mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-22 10:18:01 +00:00
Andrew Jones
3bca39c0a7
* Remove health warning * Update cargo-contract link * Add example of initializing the api client * Explain RuntimeApi parameterization * Add storage query example * Add basic extrinsic example
123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# subxt ·  [](https://crates.io/crates/subxt) [](https://docs.rs/subxt)
|
|
|
|
A library to **sub**mit e**xt**rinsics to a [substrate](https://github.com/paritytech/substrate) node via RPC.
|
|
|
|
## Usage
|
|
|
|
Take a look in the [examples](./examples/examples) folder for various `subxt` usage examples.
|
|
|
|
### Downloading metadata from a Substrate node
|
|
|
|
Use the [`subxt-cli`](./cli) tool to download the metadata for your target runtime from a node.
|
|
|
|
1. Install:
|
|
```bash
|
|
cargo install subxt-cli
|
|
```
|
|
2. Save the encoded metadata to a file:
|
|
```bash
|
|
subxt metadata -f bytes > metadata.scale
|
|
```
|
|
|
|
This defaults to querying the metadata of a locally running node on the default `http://localhost:9933/`. If querying
|
|
a different node then the `metadata` command accepts a `--url` argument.
|
|
|
|
### Generating the runtime API from the downloaded metadata
|
|
|
|
Declare a module and decorate it with the `subxt` attribute which points at the downloaded metadata for the
|
|
target runtime:
|
|
|
|
```rust
|
|
#[subxt::subxt(runtime_metadata_path = "metadata.scale")]
|
|
pub mod node_runtime { }
|
|
```
|
|
|
|
**Important:** `runtime_metadata_path` resolves to a path relative to the directory where your crate's `Cargo.toml`
|
|
resides ([`CARGO_MANIFEST_DIR`](https://doc.rust-lang.org/cargo/reference/environment-variables.html)), *not* relative to the source file.
|
|
|
|
### Initializing the API client
|
|
|
|
```rust
|
|
use subxt::{ClientBuilder, DefaultConfig, DefaultExtra};
|
|
|
|
let api = ClientBuilder::new()
|
|
.set_url("wss://rpc.polkadot.io:443")
|
|
.build()
|
|
.await?
|
|
.to_runtime_api::<node_runtime::RuntimeApi<DefaultConfig, DefaultExtra<DefaultConfig>>>();
|
|
```
|
|
|
|
The `RuntimeApi` type is generated by the `subxt` macro from the supplied metadata. This can be parameterized with user
|
|
supplied implementations for the `Config` and `Extra` types, if the default implementations differ from the target
|
|
chain.
|
|
|
|
### Querying Storage
|
|
|
|
Call the generated `RuntimeApi::storage()` method, followed by the `pallet_name()` and then the `storage_item_name()`.
|
|
|
|
So in order to query `Balances::TotalIssuance`:
|
|
|
|
```rust
|
|
let total_issuance = api
|
|
.storage()
|
|
.balances()
|
|
.total_issuance(None)
|
|
.await
|
|
.unwrap()
|
|
```
|
|
|
|
### Submitting Extrinsics
|
|
|
|
Submit an extrinsic, returning success once the transaction is validated and accepted into the pool:
|
|
|
|
```rust
|
|
use sp_keyring::AccountKeyring;
|
|
use subxt::PairSigner;
|
|
|
|
let signer = PairSigner::new(AccountKeyring::Alice.pair());
|
|
let dest = AccountKeyring::Bob.to_account_id().into();
|
|
|
|
let tx_hash = api
|
|
.tx()
|
|
.balances()
|
|
.transfer(dest, 10_000)
|
|
.sign_and_submit(&signer)
|
|
.await?;
|
|
```
|
|
|
|
For more advanced usage, which can wait for block inclusion and return any events triggered by the extrinsic, see the
|
|
[balance transfer example](./examples/examples/balance_transfer.rs).
|
|
|
|
## Integration Testing
|
|
|
|
Most tests require a running substrate node to communicate with. This is done by spawning an instance of the
|
|
substrate node per test. It requires an executable binary `substrate` at [`polkadot-v0.9.10`](https://github.com/paritytech/substrate/releases/tag/polkadot-v0.9.10) on your path.
|
|
|
|
This can be installed from source via cargo:
|
|
|
|
```bash
|
|
cargo install --git https://github.com/paritytech/substrate node-cli --tag=polkadot-v0.9.10 --force
|
|
```
|
|
|
|
## Real world usage
|
|
|
|
Please add your project to this list via a PR.
|
|
|
|
- [cargo-contract](https://github.com/paritytech/cargo-contract/) CLI for interacting with Wasm smart contracts.
|
|
- [xcm-cli](https://github.com/ascjones/xcm-cli) CLI for submitting XCM messages.
|
|
- [phala-pherry](https://github.com/Phala-Network/phala-blockchain/tree/master/standalone/pherry) The relayer between Phala blockchain and the off-chain Secure workers.
|
|
- [crunch](https://github.com/turboflakes/crunch) CLI to claim staking rewards in batch every Era or X hours for substrate-based chains.
|
|
- [interbtc-clients](https://github.com/interlay/interbtc-clients) Client implementations for the interBTC parachain; notably the Vault / Relayer and Oracle.
|
|
|
|
**Alternatives**
|
|
|
|
[substrate-api-client](https://github.com/scs/substrate-api-client) provides similar functionality.
|
|
|
|
#### License
|
|
|
|
<sup>
|
|
The entire code within this repository is licensed under the <a href="LICENSE">GPLv3</a>.
|
|
Please <a href="https://www.parity.io/contact/">contact us</a> if you have questions about the licensing of our
|
|
products.
|
|
</sup>
|