Subxt Guide (#890)

* WIP Starting to write book; extrinsics first pass done

* cargo fmt

* Ongoing work; events, constants, wip blocks

* at_latest() and wip blocks

* remove need to import parity-scale-codec crate with Subxt for macro to work

* More docs; expanding on setup guide and finish pass of main sections

* Tidy and remove example section for now

* format book lines to 100chars

* Fix example code

* cargo fmt

* cargo fmt

* fix example

* Fix typos

* fix broken doc links, pub mods

* Update Subxt macro docs

* can't link to Subxt here

* move macro docs to Subxt to make linking better and fix example code

* note on macro about docs

* cargo fmt

* document the no_default_derives macro feature

* Address feedback and remove redundant text

* address review comments; minor tweaks

* WIP add Runtime calls to book

* Improve Runtime API docs

* expose thing we forgot to expose and doc link fixes

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

@@ -225,8 +225,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(())
+}