Subxt Guide

Cargo.toml

@@ -86,4 +86,4 @@ subxt-macro = { version = "0.28.0", path = "macro" }
 subxt-metadata = { version = "0.28.0", path = "metadata" }
 subxt-codegen = { version = "0.28.0", path = "codegen" }
 test-runtime = { path = "testing/test-runtime" }
-substrate-runner = { path = "testing/substrate-runner" }
+substrate-runner = { path = "testing/substrate-runner" }

codegen/src/api/mod.rs

@@ -219,8 +219,13 @@ impl RuntimeGenerator {
                 // Preserve any Rust items that were previously defined in the adorned module
                 #( #rust_items ) *
 
-                // Make it easy to access the root via `root_mod` at different levels:
-                use super::#mod_ident as root_mod;
+                // Make it easy to access the root items via `root_mod` at different levels
+                // without reaching out of this module.
+                #[allow(unused_imports)]
+                mod root_mod {
+                    pub use super::*;
+                }
+
                 #types_mod
             }
         })

examples/Cargo.toml

@@ -16,9 +16,5 @@ description = "Subxt example usage"
 subxt = { workspace = true }
 tokio = { workspace = true }
 futures = { workspace = true }
-codec = { package = "parity-scale-codec", workspace = true, features = ["derive", "bit-vec"] }
 hex = { workspace = true }
 sp-keyring = { workspace = true }
-sp-core = { workspace = true }
-sp-runtime = { workspace = true }
-tracing-subscriber = { workspace = true }

examples/README.md

@@ -1,3 +1,5 @@
 # Subxt Examples
 
-Take a look in the [examples](./examples) subfolder for various `subxt` usage examples.
+Take a look in the [examples](./examples) subfolder for various `subxt` usage examples.
+
+All examples form part of the `subxt` documentation; there should be no examples without corresponding links from the docs.

examples/examples/balance_transfer_basic.rs

@@ -0,0 +1,34 @@
+use sp_keyring::AccountKeyring;
+use subxt::{tx::PairSigner, OnlineClient, PolkadotConfig};
+
+// Generate an interface that we can use from the node's metadata.
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a new API client, configured to talk to Polkadot nodes.
+    let api = OnlineClient::<PolkadotConfig>::new().await?;
+
+    // Build a balance transfer extrinsic.
+    let dest = AccountKeyring::Bob.to_account_id().into();
+    let balance_transfer_tx = polkadot::tx().balances().transfer(dest, 10_000);
+
+    // Submit the balance transfer extrinsic from Alice, and wait for it to be successful
+    // and in a finalized block. We get back the extrinsic events if all is well.
+    let from = PairSigner::new(AccountKeyring::Alice.pair());
+    let events = api
+        .tx()
+        .sign_and_submit_then_watch_default(&balance_transfer_tx, &from)
+        .await?
+        .wait_for_finalized_success()
+        .await?;
+
+    // Find a Transfer event and print it.
+    let transfer_event = events.find_first::<polkadot::balances::events::Transfer>()?;
+    if let Some(event) = transfer_event {
+        println!("Balance transfer success: {event:?}");
+    }
+
+    Ok(())
+}

examples/examples/balance_transfer_status_stream.rs

@@ -0,0 +1,54 @@
+use futures::StreamExt;
+use sp_keyring::AccountKeyring;
+use subxt::{
+    tx::{PairSigner, TxStatus},
+    OnlineClient, PolkadotConfig,
+};
+
+// Generate an interface that we can use from the node's metadata.
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api = OnlineClient::<PolkadotConfig>::new().await?;
+
+    let dest = AccountKeyring::Bob.to_account_id().into();
+    let balance_transfer_tx = polkadot::tx().balances().transfer(dest, 10_000);
+
+    let signer = PairSigner::new(AccountKeyring::Alice.pair());
+    let mut balance_transfer_progress = api
+        .tx()
+        .sign_and_submit_then_watch_default(&balance_transfer_tx, &signer)
+        .await?;
+
+    while let Some(status) = balance_transfer_progress.next().await {
+        match status? {
+            // It's finalized in a block!
+            TxStatus::Finalized(in_block) => {
+                println!(
+                    "Transaction {:?} is finalized in block {:?}",
+                    in_block.extrinsic_hash(),
+                    in_block.block_hash()
+                );
+
+                // grab the events and fail if no ExtrinsicSuccess event seen:
+                let events = in_block.wait_for_success().await?;
+                // We can look for events (this uses the static interface; we can also iterate
+                // over them and dynamically decode them):
+                let transfer_event = events.find_first::<polkadot::balances::events::Transfer>()?;
+
+                if let Some(event) = transfer_event {
+                    println!("Balance transfer success: {event:?}");
+                } else {
+                    println!("Failed to find Balances::Transfer Event");
+                }
+            }
+            // Just log any other status we encounter:
+            other => {
+                println!("Status: {other:?}");
+            }
+        }
+    }
+    Ok(())
+}

examples/examples/balance_transfer_with_params.rs

@@ -1,52 +1,28 @@
-// Copyright 2019-2023 Parity Technologies (UK) Ltd.
-// This file is dual-licensed as Apache-2.0 or GPL-3.0.
-// see LICENSE for license details.
-
-//! To run this example, a local polkadot node should be running. Example verified against polkadot v0.9.28-9ffe6e9e3da.
-//!
-//! E.g.
-//! ```bash
-//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.28/polkadot" --output /usr/local/bin/polkadot --location
-//! polkadot --dev --tmp
-//! ```
-
 use sp_keyring::AccountKeyring;
-use subxt::{
-    config::{
-        polkadot::{Era, PlainTip, PolkadotExtrinsicParamsBuilder as Params},
-        PolkadotConfig,
-    },
-    tx::PairSigner,
-    OnlineClient,
-};
+use subxt::config::polkadot::{Era, PlainTip, PolkadotExtrinsicParamsBuilder as Params};
+use subxt::{tx::PairSigner, OnlineClient, PolkadotConfig};
 
 #[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
 pub mod polkadot {}
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    tracing_subscriber::fmt::init();
-
-    let signer = PairSigner::new(AccountKeyring::Alice.pair());
-    let dest = AccountKeyring::Bob.to_account_id().into();
-
-    // Create a client to use:
+    // Create a new API client, configured to talk to Polkadot nodes.
     let api = OnlineClient::<PolkadotConfig>::new().await?;
 
-    // Create a transaction to submit:
-    let tx = polkadot::tx()
-        .balances()
-        .transfer(dest, 123_456_789_012_345);
+    // Build a balance transfer extrinsic.
+    let dest = AccountKeyring::Bob.to_account_id().into();
+    let tx = polkadot::tx().balances().transfer(dest, 10_000);
 
-    // Configure the transaction tip and era:
+    // Configure the transaction parameters; for Polkadot the tip and era:
     let tx_params = Params::new()
-        .tip(PlainTip::new(20_000_000_000))
+        .tip(PlainTip::new(1_000))
         .era(Era::Immortal, api.genesis_hash());
 
     // submit the transaction:
-    let hash = api.tx().sign_and_submit(&tx, &signer, tx_params).await?;
-
-    println!("Balance transfer extrinsic submitted: {hash}");
+    let from = PairSigner::new(AccountKeyring::Alice.pair());
+    let hash = api.tx().sign_and_submit(&tx, &from, tx_params).await?;
+    println!("Balance transfer extrinsic submitted with hash : {hash}");
 
     Ok(())
 }

examples/examples/subscribe_blocks.rs → examples/examples/blocks_subscribing.rs

@@ -1,15 +1,3 @@
-// Copyright 2019-2023 Parity Technologies (UK) Ltd.
-// This file is dual-licensed as Apache-2.0 or GPL-3.0.
-// see LICENSE for license details.
-
-//! To run this example, a local polkadot node should be running. Example verified against polkadot 0.9.29-41a9d84b152.
-//!
-//! E.g.
-//! ```bash
-//! curl "https://github.com/paritytech/polkadot/releases/download/v0.9.29/polkadot" --output /usr/local/bin/polkadot --location
-//! polkadot --dev --tmp
-//! ```
-
 use futures::StreamExt;
 use subxt::{OnlineClient, PolkadotConfig};
 
@@ -18,14 +6,13 @@ pub mod polkadot {}
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    tracing_subscriber::fmt::init();
-
     // Create a client to use:
     let api = OnlineClient::<PolkadotConfig>::new().await?;
 
     // Subscribe to all finalized blocks:
     let mut blocks_sub = api.blocks().subscribe_finalized().await?;
 
+    // For each block, print a bunch of information about it:
     while let Some(block) = blocks_sub.next().await {
         let block = block?;
 
@@ -36,6 +23,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         println!("  Hash: {block_hash}");
         println!("  Extrinsics:");
 
+        // Log each of the extrinsic with it's associated events:
         let body = block.body().await?;
         for ext in body.extrinsics() {
             let idx = ext.index();
@@ -51,8 +39,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
                 let pallet_name = evt.pallet_name();
                 let event_name = evt.variant_name();
+                let event_values = evt.field_values()?;
 
                 println!("        {pallet_name}_{event_name}");
+                println!("          {}", event_values);
             }
         }
     }

examples/examples/constants_dynamic.rs

@@ -0,0 +1,17 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a client to use:
+    let api = OnlineClient::<PolkadotConfig>::new().await?;
+
+    // A dynamic query to obtain some contant:
+    let constant_query = subxt::dynamic::constant("System", "BlockLength");
+
+    // Obtain the value:
+    let value = api.constants().at(&constant_query)?;
+
+    println!("Constant bytes: {:?}", value.encoded());
+    println!("Constant value: {}", value.to_value()?);
+    Ok(())
+}

examples/examples/constants_static.rs

@@ -0,0 +1,19 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata.scale")]
+pub mod polkadot {}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a client to use:
+    let api = OnlineClient::<PolkadotConfig>::new().await?;
+
+    // A query to obtain some contant:
+    let constant_query = polkadot::constants().system().block_length();
+
+    // Obtain the value:
+    let value = api.constants().at(&constant_query)?;
+
+    println!("Block length: {value:?}");
+    Ok(())
+}