Complementary Examples¶

Prerequisites¶

Before we get started we need to make sure that all of the required dependencies are installed. These dependencies are the Crypto SDK and Client SDK. You can head on over to their documentations to read more about them but for now we are only concerned with installing them to get up and running.

Open your project and execute the following commands to install both SDKs. Make sure that those complete without any errors. If you encounter any errors, please open an issue with as much information as you can provide so that our developers can have a look and get to the bottom of the issue.

pnpm ¶

pnpm add @solar-network/crypto
pnpm add @solar-network/client

npm ¶

npm install @solar-network/crypto
npm install @solar-network/client

yarn ¶

yarn add @solar-network/crypto
yarn add @solar-network/client

Now that we're setup and ready to go we'll look into some examples for the most common tasks you'll encounter when wanting to interact with the SXP Blockchain.

Persisting your transaction on the blockchain¶

The process of getting your transaction verified and persisted on the SXP Blockchain involves a few steps with which our SDKs will help you but lets break them down to get a better idea of what is happening.

Install the Client SDK and configure it to use a node of your choosing to broadcast your transactions to. Always make sure that you have a fallback node that you can use for broadcasting in case your primary node goes offline or acts strange otherwise.
Install the Crypto SDK and configure it to match the configuration of the network. This is the most important part as misconfiguration can lead to a myriad of issues as Core will reject your transactions.
Retrieve the nonce of the sender wallet and increase it by 1. You can read about what a sequential nonce is and why it is important here.
Create an instance of the builder for the type of transaction you want to create. This is the step where we actually create a transaction and sign it so that the SXP Blockchain can later on verify it and decide if it will be accepted and finally forged.
Turn the newly created transaction into JSON and broadcast it to the network through the Client SDK.
Process the API response and verify that your transaction was accepted. If the network rejects your transaction you'll receive the reason as to why that is the case in the response which might mean that you need to create a new transaction and broadcast it.

Troubleshooting¶

A common issue when trying to get your transaction onto the blockchain is that you'll receive an error to the effect of Transaction Version 2 is not supported which indicates that your Crypto SDK configuration might be wrong.

The solution to this is to make sure that your Crypto SDK instance is properly configured. This includes both the network preset and the height it's configured to assume the network has passed, if any of those don't match up you'll encounter the aforementioned issue with the version of your transactions.

Mainnet¶

Managers.configManager.setFromPreset("mainnet");
Managers.configManager.setHeight("2400000);

Testnet¶

Managers.configManager.setFromPreset("testnet");
Managers.configManager.setHeight(1000000);

Creating and broadcasting a transfer transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {

    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(1000000);


    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.transfer()
        .nonce(senderNonce.toFixed())
        .fee("30000000")
        .addTransfer("Address of Recipient 1", "100000000")
        .addTransfer("Address of Recipient 2", "100000000")
        .memo("Hello World") // Memo is optional
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

Info

The memo is optional and limited to a length of 255 characters. It can be a good idea to add a memo to your transactions if you want to be able to easily track or identify them in the future or include a personal message to the transaction's recipient(s).

Creating and broadcasting a second signature transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {

    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(1000000);

    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.secondSignature()
        .nonce(senderNonce.toFixed())
        .signatureAsset("this is a top secret second passphrase")
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

Creating and broadcasting a delegate registration transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {
    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(1000000);

    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.delegateRegistration()
        .nonce(senderNonce.toFixed())
        .usernameAsset("johndoe")
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

Creating and broadcasting a vote transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {
    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(1000000);

    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.vote()
        .nonce(senderNonce.toFixed())
        .votesAsset({delegate1: 40, delegate2: 60}) // The sum has to be 100
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

Info

Note the numbers in the object that is passed on the votesAsset function represent the percentage of the wallet balance you want to vote towards the related delegate. This implies that the sum of all of them must be 100 or the object has to be empty to cancel an existing vote.

Creating and broadcasting an IPFS transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {
    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(100000);

    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.ipfs()
        .nonce(senderNonce.toFixed())
        .ipfsAsset("QmR45FmbVVrixReBwJkhEKde2qwHYaQzGxu4ZoDeswuF9w")
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

Creating and broadcasting a delegate resignation transaction¶

import { Transactions, Managers, Utils } from "@solar-network/crypto";
import { Connection } from "@solar-network/client";

// Configure our API client
const client = new Connection("https://tapi.solar.org/api");

(async () => {
    // Get current height
    const height = (await client.api("blockchain").blockchain()).body.data.block.height;

    // Set the chain's presets and height
    Managers.configManager.setFromPreset("testnet");
    Managers.configManager.setHeight(1000000);

    // Step 1: Retrieve the incremental nonce of the sender wallet
    const senderWallet = await client.api("wallets").get("YOUR_SENDER_WALLET_ADDRESS");
    const senderNonce = Utils.BigNumber.make(senderWallet.body.data.nonce).plus(1);

    // Step 2: Create the transaction
    const transaction = Transactions.BuilderFactory.delegateResignation()
        .resignationTypeAsset(0)
        .nonce(senderNonce.toFixed())
        .sign("this is a top secret passphrase");

    // Step 4: Broadcast the transaction
    const broadcastResponse = await client.api("transactions").create({ transactions: [transaction.build().toJson()] });

    // Step 5: Log the response
    console.log(JSON.stringify(broadcastResponse.body.data, null, 4))
})();

A delegate resignation must be sent from the corresponding delegate's wallet in order to verify their identity.

Resignation can be of 2 types:

0 - meaning the resignation is only temporary and can be undone
1 - meaning the resignation is permanent