README.md

substrate-api-client

substrate-api-client a library written in Rust for connecting to the substrate's RPC interface via WebSockets allowing to

• Compose extrinsics, send them and subscribe to updates (synchronously).
• supportsno_std builds. Only the rpc-client is std only. For no_std builds, a custom rpc client needs to be implemented.
• Watch events and execute code upon events.
• Parse and print the node metadata.

Prerequisites

In order to build the substrate-api-client and the examples, Rust and the wasm target are needed. For Linux:

curl https://sh.rustup.rs -sSf | sh
# Install the rust toolchain specified in rust-toolchain.toml
rustup show

For more information, please refer to the substrate repository.

Substrate node

To execute the examples, a running substrate node is needed. You can download a node artifact from substrate directly: https://github.com/paritytech/substrate or run the kitchensink-node with docker:

docker run -p 9944:9944 -p 9933:9933 -p 30333:30333 parity/substrate:latest --dev --ws-external --rpc-external

Examples

To run an example, clone the substrate-api-client repository and run the desired example directly with the cargo command:

git clone https://github.com/scs/substrate-api-client.git
cd substrate-api-client
cargo run -p ac-examples --example get_storage

or download the already built binaries from Github Actions: https://github.com/scs/substrate-api-client/actions and run them without any building:

chmod +x <example>
./<example>

Set the output verbosity by prepending RUST_LOG=info or RUST_LOG=debug.

The following examples can be found in the examples folder:

• batch_payout: Batch reward payout for validator.
• benchmark_bulk_xt: Float the node with a series of transactions.
• compose_extrinsic_offline: Compose an extrinsic without interacting with the node.
• custom_nonce: Compose an with a custom nonce.
• contract_instantiate_with_code: Instantiate a contract on the chain.
• event_callback: Subscribe and react on events.
• event_error_details: Listen to error events from the node to determine if an extrinsic was successful or not.
• get_account_identity: Create an custom Unchecked Extrinsic to set an account identity and retrieve it afterwards with a getter.
• get_block: Read header, block and signed block from storage.
• get_storage: Read storage values.
• print_metadata: Print the metadata of the node in a readable way.
• sudo: Create and send a sudo wrapped call.
• transfer_with_tungstenite_client: Transfer tokens by using a wrapper of compose_extrinsic with an account generated with a seed.
• transfer_with_ws_client: Transfer tokens by using a wrapper of compose_extrinsic with an account generated with a seed.

Alternatives

Parity offers a Rust client with similar functionality: https://github.com/paritytech/subxt

Acknowledgements

The development of substrate-api-client is financed by web3 foundation's grant programme.

We also thank the teams at

• Parity Technologies for building substrate and supporting us during development.

Projects using substrate-api-client

If you intend to or are using substrate-api-client, please add your project here

In alphabetical order

• Ajuna Network
• Encointer
• Integritee Network
• Litentry
• Polkadex