Docs

SubstrateClient

This section explains how to initialize SubstrateClient, which is used to communicate with RPC nodes.

SubstrateClient will allow you to:

make queries
submit extrinsics
listen to events

Scaffolding with Substrate.NET.Toolchain

I recommend scaffolding the SubstrateClient first with Substrate.NET.Toolchain.

You can find the latest docs for the scaffolding process here: https://github.com/SubstrateGaming/Substrate.NET.Toolchain.

Install our .NET template with the following command:

dotnet new install Substrate.DotNet.Template

which makes dotnet new substrate available.

Using a terminal of your choice, create a new directory for your project and execute the following command in that directory:

dotnet new sln
dotnet new substrate \
   --sdk_version 0.4.4 \
   --rest_service Substrate.NetApi.RestService \
   --net_api Substrate.NetApi.NetApiExt \
   --rest_client Substrate.NetApi.RestClient \
   --metadata_websocket <websocket_url> \
   --generate_openapi_documentation false \
   --force \
   --allow-scripts yes

which generates a new solution and a couple of .NET projects in your project directory. (A description for all command parameters can be found here)

Replace the websocket_url with either ws://127.0.0.1:9944 to connect to a local chain or any other url to connect to an RPC node, e.g. wss://rpc.polkadot.io to connect to Polkadot relay chain.

Initialize SubstrateClient

I will assume that you will use the SubstrateClientExt that was generated by the Toolchain instead of the barebones SubstrateClient.

using Substrate.NetApi.Model.Extrinsics;
using Substrate.NetApi.NetApiExt.Generated;

var client = new SubstrateClientExt(
    new Uri("wss://rpc.polkadot.io"),
    ChargeTransactionPayment.Default());

await client.ConnectAsync();

You can also ensure that the client is connected like this:

if (!client.IsConnected)
{
    // Ensure that the client connects
}

Account

To interact with Substrate chains, you will need an Account. Currently, there are 3 ways to getting the account

Mnemonics

Unless you are building a crypto wallet, I do not recommend using this in the production. It is not User friendly and is the least secure out of all of the options.

Generate a new mnemonic:

var random = RandomNumberGenerator.Create(); // Cryptographically secure RNG

var entropyBytes = new byte[16];
random.GetBytes(entropyBytes);

string mnemonics = string.Join(" ", Mnemonic.MnemonicFromEntropy(entropyBytes, BIP39Wordlist.English));

// You might want to display the mnemonics
Console.WriteLine(mnemonics);

Create an Account from mnemonic:

ExpandMode expandMode = ExpandMode.Ed25519; // Currently preferred in Substrate
string password = "please_put_here_something_better_than_password123";

var secret = Mnemonic.GetSecretKeyFromMnemonic(mnemonics, password, BIP39Wordlist.English);

var miniSecret = new MiniSecret(secret, expandMode);

// Our actual Account, that will be used for signing extrinsics/messages
Account account = Account.Build(
    KeyType.Sr25519,
    miniSecret.ExpandToSecret().ToBytes(),
    miniSecret.GetPair().Public.Key);

Import JSON file

https://github.com/SubstrateGaming/Substrate.NET.Wallet/blob/master/README.md

Connecting via Plutonication

Docs currently unavailable

Substrate types

Substrate uses Rust. Rust is a strictly typed language. To be sure that you will use the right types, you need to use the Substrate types, that are either included in the Substrate.NetApi or generated by the Substrate.NET.Toolchain. These Substrate types can be easily encoded to and decoded from SCALE codec.

Primitive Types

Bool = bool
U8 = byte
U16 = ushort
U32 = uint - Very often used for indexing/ids
U64 = ulong
U128 = BigInteger - Very often used for tracking Balance
U256 = BigInteger - Almost never used
PrimChar = char
Str = string - Never used in Substrate, but is useful for correct SCALE encoding/decoding.

Composite types

I will mention a few of the compound types that are often present in Substrate

Vec<U8> - used as string in Substrate. It is equal to UTF-8 encoded/decoded string.
AccountId32 - used for representing an account address
EnumMultiAddress
BaseCom - Used for compacting types

Examples

// U128 number
U128 number = new U128(1000);

// The same 1000 number in type U128
U128 number2 = new U128();
number2.Create("0xE8030000000000000000000000000000");

// string message
BaseVec<U8> message = new BaseVec<U8>();
message.Create(new Str("Hello Substrate").Encode());

// account id
AccountId32 accountId = new AccountId32();
accountId.Create(Utils.GetPublicKeyFrom("5EU6EyEq6RhqYed1gCYyQRVttdy6FC9yAtUUGzPe3gfpFX8y"));

SCALE Encode() and Decode()

All Substrate types support .Encode() and .Decode(byte[] byteArray, ref int p) methods.

Encode() encodes the Substrate type and returns a SCALE encoded byte[]
Decode(byte[] byteArray, ref int p) decodes a SCALE encoded byte[] into the desired Substrate type. The p variable is used for tracking the current index of the byte array. It may be handy when decoding Composite types.

Utils

Utils class is useful when working with byte[]. It is not only useful for translating strings to byte[] and back, but it can also help you when working with addresses. Here are a few methods that you should be on a lookout.

Bytes2HexString(byte[] bytes, HexStringFormat format = HexStringFormat.Prefixed) - Converts byte[] to hexadecimal string. Useful when wanting to display the hex values.
HexToByteArray(string hex, bool evenLeftZeroPad = false) - Converts hexadecimal string to byte array.
SizePrefixedByteArray(List<byte> list) - Converts List<byte> to byte[] with a CompactInteger encoded value at the start, indicating the length of the list.
GetPublicKeyFrom(string address, out short network) - returns the hex value of SS58 encoded address, which is handy when creating AccountId object. This method also gives SS58 prefix (network variable), which might indicate the chain the user might be using.
GetAddressFrom(byte[] bytes, short ss58Prefix = 42) - Encodes a hex public key into an SS58 encoded one.

Building a method

Substrate.NetApi has got a Method type which describes the actions you want to do in a submitted extrinsic.

Luckily, Substrate.NET.Toolchain has generated helper classes that help us get the Method, that will be called.

To get the Method, you will use <name-of-the-pallet>Calls.<name-of-the-call>(<params>). Here is an example for System.remark("Hello Remark"), which takes as a parameter BaseVec<U8>:

// Creating the parameter message
BaseVec<U8> message = new BaseVec<U8>();
message.Create(Encoding.UTF8.GetBytes("Hello Remark"));

// Getting the actual Method
Method vote = SystemCalls.Remark(message);

Submit Extrinsics

Interacting with the chain requires the signing and submission of extrinsics (akin to transactions).

To effectively submit an extrinsic, you must be familiar with:

Acquiring an Account
Constructing a Method

Below is an example of the Balances.transferKeepAlive extrinsic:

// For details on acquiring an account, see: https://github.com/SubstrateGaming/Substrate.NET.API/wiki/Docs#account
Account account = <way_to_get_your_account>;

var accountId = new AccountId32();
accountId.Create(Utils.GetPublicKeyFrom("5EU6EyEq6RhqYed1gCYyQRVttdy6FC9yAtUUGzPe3gfpFX8y"));

var multiAddress = new EnumMultiAddress();
multiAddress.Create(0, accountId);

var amount = new BaseCom<U128>(10000000000); // This is equivalent to 1 DOT (10^10 planks)

// Building the transferKeepAlive Method
Method transfer = BalancesCalls.TransferKeepAlive(multiAddress, amount);

// The charge determines the tip you wish to pay (and its currency)
ChargeType charge = true ? ChargeTransactionPayment.Default() : ChargeAssetTxPayment.Default();

uint lifeTime = 64; // For details, refer to: https://polkadot.js.org/docs/api/FAQ/#how-long-do-transactions-live

CancellationToken token = CancellationToken.None; // Consider using a CancellationToken if needed

await client.Author.SubmitExtrinsicAsync(transfer, account, charge, lifeTime, token);

SubmitAndWatch

SubmitAndWatch is a specialized function within the Substrate RPC calls. It lets users submit an extrinsic and then track its inclusion within the blockchain. Upon invoking this function, a subscription ID is returned. This ID is crucial for monitoring the block inclusion trajectory of the extrinsic, facilitated through callbacks.

Callbacks provide information on the block inclusion status, which is structured using the ExtrinsicStatus model. The sequence for a successful callback is as follows:

None
Ready
None + InBlock(Hash)
None + Finalized(Hash)

A critical point to remember is that SubmitAndWatch only informs if the extrinsic was processed and added to a block. It doesn't convey the result of the extrinsic's execution (i.e., success or failure).

Query chain State

To get the chain state, like what is the balance of an account.

Fortunately, Substrate.NET.Toolchain has generated helper classes that live in the client. To use them, just type client.<pallet-name>Storage.<storage-name>(<params>). Just like this:

var accountId = new AccountId32();
accountId.Create(Utils.GetPublicKeyFrom("5EU6EyEq6RhqYed1gCYyQRVttdy6FC9yAtUUGzPe3gfpFX8y"));

// Query chain state
var accountBalance = await client.SystemStorage.Account(accountId, token);

// Polkadot has got 10 decimals
// Do not forget to check if the accountBalance is not null
double assetBalance = accountBalance != null ? (double)accountBalance.Data.Free.Value / Math.Pow(10, 10) : 0;

// You might want to show the balance
Console.WriteLine(String.Format("Account balance: {0:0.00} DOT", assetBalance));

Instead of using "5EU6..pFX8y", you can use account.Value to get an address of your account.

accountBalance variable is of type AccountInfo, which is a rust struct translated to c# class by Substrate.NET.Toolchain.

Also, bear in mind that if nothing is saved at that Storage position, await client.SystemStorage.Account(accountId, token) will return null.

Query StorageMaps

Querying data over a StorageMap is a little bit more difficult. To get a full understanding how StorageMaps work in Substrate, I recommend reading this blog post by Shawn: https://www.shawntabrizi.com/substrate/transparent-keys-in-substrate/.

The will need to:

Get the Storage prefix
Get List of all of the keys starting with the Storage prefix
Query the List of keys to get the Storage changes.
Decode Storage changes to the desired type.

The following code shows how to query balances of all Accounts:

List<AccountInfo> accounts = await GetSystemAccountsAsync(client, CancellationToken.None);

foreach(var a in accounts)
{
    // Polkadot has got 10 decimals
    double aBalance = (double)a.Data.Free.Value / Math.Pow(10, 10);

    // You might want to show the balance
    Console.WriteLine(String.Format("Account balance: {0:0.00} DOT", aBalance));
}

/// <summary>
/// Helper method that queries all System.Account values
/// </summary>
/// <param name="client">Your SubstrateClient</param>
/// <param name="token">CancellationToken</param>
/// <returns>List<AccountInfo></returns>
static async Task<List<AccountInfo>> GetSystemAccountsAsync(SubstrateClientExt client, CancellationToken token)
{
    // Get the Storage prefix
    byte[] prefix = RequestGenerator.GetStorageKeyBytesHash("System", "Account");

    // First startKey is unknown
    byte[] startKey = null;

    List<string[]> storageChanges = new List<string[]>();

    while (true)
    {
        // Get List of all of the keys starting with the Storage prefix
        var keysPaged = await client.State.GetKeysPagedAtAsync(prefix, 1000, startKey, string.Empty, token);

        if (keysPaged == null || !keysPaged.Any())
        {
            break;
        }
        else
        {
            // temp variable
            var tt = await client.State.GetQueryStorageAtAsync(keysPaged.Select(p => Utils.HexToByteArray(p.ToString())).ToList(), string.Empty, token);

            storageChanges.AddRange(new List<string[]>(tt.ElementAt(0).Changes));

            // update the startKey to query next keys
            startKey = Utils.HexToByteArray(tt.ElementAt(0).Changes.Last()[0]);
        }
    }

    // Result list
    var accountInfoList = new List<AccountInfo>();

    if (storageChanges != null)
    {
        foreach (var storageChangeSet in storageChanges)
        {
            // Decoding Storage changes to the desired type.
            AccountInfo accountInfo = new AccountInfo();
            accountInfo.Create(storageChangeSet[1]);

            accountInfoList.Add(accountInfo);
        }
    }

    return accountInfoList;
}

Also keep in mind that you might query thousands of storage keys - this might take a while or may not complete at all.

Query DoubleStorageMaps and StorageNMaps

Querying over a DoubleStorageMap is very similar to the StorageMap. The only difference is that you do not have to query all of the keys, but you can just query data under a certain key.