move examples to main repo so we can include_str them for publishing (#993)

* move exampels to main repo so we can include_str them for publishing

* update CI to not break examples

subxt/examples/blocks_subscribing.rs

@@ -0,0 +1,56 @@
+use futures::StreamExt;
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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?;
+
+    // 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?;
+
+        let block_number = block.header().number;
+        let block_hash = block.hash();
+
+        println!("Block #{block_number}:");
+        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().iter() {
+            let ext = ext?;
+            let idx = ext.index();
+            let events = ext.events().await?;
+            let bytes_hex = format!("0x{}", hex::encode(ext.bytes()));
+
+            // See the API docs for more ways to decode extrinsics:
+            let decoded_ext = ext.as_root_extrinsic::<polkadot::Call>();
+
+            println!("    Extrinsic #{idx}:");
+            println!("      Bytes: {bytes_hex}");
+            println!("      Decoded: {decoded_ext:?}");
+            println!("      Events:");
+
+            for evt in events.iter() {
+                let evt = evt?;
+
+                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);
+            }
+        }
+    }
+
+    Ok(())
+}

subxt/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(())
+}

subxt/examples/constants_static.rs

@@ -0,0 +1,19 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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(())
+}

subxt/examples/events.rs

@@ -0,0 +1,47 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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?;
+
+    // Get events for the latest block:
+    let events = api.events().at_latest().await?;
+
+    // We can dynamically decode events:
+    println!("Dynamic event details:");
+    for event in events.iter() {
+        let event = event?;
+
+        let pallet = event.pallet_name();
+        let variant = event.variant_name();
+        let field_values = event.field_values()?;
+
+        println!("{pallet}::{variant}: {field_values}");
+    }
+
+    // Or we can attempt to statically decode them into the root Event type:
+    println!("Static event details:");
+    for event in events.iter() {
+        let event = event?;
+
+        if let Ok(ev) = event.as_root_event::<polkadot::Event>() {
+            println!("{ev:?}");
+        } else {
+            println!("<Cannot decode event>");
+        }
+    }
+
+    // Or we can look for specific events which match our statically defined ones:
+    let transfer_event = events.find_first::<polkadot::balances::events::Transfer>()?;
+    if let Some(ev) = transfer_event {
+        println!("  - Balance transfer success: value: {:?}", ev.amount);
+    } else {
+        println!("  - No balance transfer event found in this block");
+    }
+
+    Ok(())
+}

subxt/examples/runtime_apis_dynamic.rs

@@ -0,0 +1,32 @@
+use sp_keyring::AccountKeyring;
+use subxt::dynamic::Value;
+use subxt::{config::PolkadotConfig, OnlineClient};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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?;
+
+    // Create a dynamically runtime API payload that calls the
+    // `AccountNonceApi_account_nonce` function.
+    let account = AccountKeyring::Alice.to_account_id();
+    let runtime_api_call = subxt::dynamic::runtime_api_call(
+        "AccountNonceApi",
+        "account_nonce",
+        vec![Value::from_bytes(account)],
+    );
+
+    // Submit the call to get back a result.
+    let nonce = api
+        .runtime_api()
+        .at_latest()
+        .await?
+        .call(runtime_api_call)
+        .await?;
+
+    println!("Account nonce: {:#?}", nonce.to_value());
+    Ok(())
+}

subxt/examples/runtime_apis_raw.rs

@@ -0,0 +1,22 @@
+use subxt::ext::codec::Compact;
+use subxt::ext::frame_metadata::RuntimeMetadataPrefixed;
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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?;
+
+    // Use runtime APIs at the latest block:
+    let runtime_apis = api.runtime_api().at_latest().await?;
+
+    // Ask for metadata and decode it:
+    let (_, meta): (Compact<u32>, RuntimeMetadataPrefixed) =
+        runtime_apis.call_raw("Metadata_metadata", None).await?;
+
+    println!("{meta:?}");
+    Ok(())
+}

subxt/examples/runtime_apis_static.rs

@@ -0,0 +1,27 @@
+use sp_keyring::AccountKeyring;
+use subxt::{config::PolkadotConfig, OnlineClient};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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?;
+
+    // Create a runtime API payload that calls into
+    // `AccountNonceApi_account_nonce` function.
+    let account = AccountKeyring::Alice.to_account_id().into();
+    let runtime_api_call = polkadot::apis().account_nonce_api().account_nonce(account);
+
+    // Submit the call and get back a result.
+    let nonce = api
+        .runtime_api()
+        .at_latest()
+        .await?
+        .call(runtime_api_call)
+        .await;
+
+    println!("AccountNonceApi_account_nonce for Alice: {:?}", nonce);
+    Ok(())
+}

subxt/examples/setup_client_custom_config.rs

@@ -0,0 +1,30 @@
+use subxt::{
+    config::{substrate::SubstrateExtrinsicParams, Config, SubstrateConfig},
+    OnlineClient,
+};
+
+/// Define a custom config type (see the `subxt::config::Config` docs for
+/// more information about each type):
+enum MyConfig {}
+impl Config for MyConfig {
+    // This is different from the default `u32`:
+    type Index = u64;
+    // We can point to the default types if we don't need to change things:
+    type Hash = <SubstrateConfig as Config>::Hash;
+    type Hasher = <SubstrateConfig as Config>::Hasher;
+    type Header = <SubstrateConfig as Config>::Header;
+    type AccountId = <SubstrateConfig as Config>::AccountId;
+    type Address = <SubstrateConfig as Config>::Address;
+    type Signature = <SubstrateConfig as Config>::Signature;
+    // ExtrinsicParams makes use of the index type, so we need to tweak it
+    // too to align with our modified index type, above:
+    type ExtrinsicParams = SubstrateExtrinsicParams<Self>;
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create a client which uses the custom config:
+    let _api = OnlineClient::<MyConfig>::new().await?;
+
+    Ok(())
+}

subxt/examples/setup_client_custom_rpc.rs

@@ -0,0 +1,79 @@
+use std::{
+    fmt::Write,
+    pin::Pin,
+    sync::{Arc, Mutex},
+};
+use subxt::{
+    rpc::{RawValue, RpcClientT, RpcFuture, RpcSubscription},
+    OnlineClient, PolkadotConfig,
+};
+
+// A dummy RPC client that doesn't actually handle requests properly
+// at all, but instead just logs what requests to it were made.
+struct MyLoggingClient {
+    log: Arc<Mutex<String>>,
+}
+
+// We have to implement this fairly low level trait to turn [`MyLoggingClient`]
+// into an RPC client that we can make use of in Subxt. Here we just log the requests
+// made but don't forward them to any real node, and instead just return nonsense.
+impl RpcClientT for MyLoggingClient {
+    fn request_raw<'a>(
+        &'a self,
+        method: &'a str,
+        params: Option<Box<RawValue>>,
+    ) -> RpcFuture<'a, Box<RawValue>> {
+        writeln!(
+            self.log.lock().unwrap(),
+            "{method}({})",
+            params.as_ref().map(|p| p.get()).unwrap_or("[]")
+        )
+        .unwrap();
+
+        // We've logged the request; just return garbage. Because a boxed future is returned,
+        // you're able to run whatever async code you'd need to actually talk to a node.
+        let res = RawValue::from_string("[]".to_string()).unwrap();
+        Box::pin(std::future::ready(Ok(res)))
+    }
+
+    fn subscribe_raw<'a>(
+        &'a self,
+        sub: &'a str,
+        params: Option<Box<RawValue>>,
+        unsub: &'a str,
+    ) -> RpcFuture<'a, RpcSubscription> {
+        writeln!(
+            self.log.lock().unwrap(),
+            "{sub}({}) (unsub: {unsub})",
+            params.as_ref().map(|p| p.get()).unwrap_or("[]")
+        )
+        .unwrap();
+
+        // We've logged the request; just return garbage. Because a boxed future is returned,
+        // and that will return a boxed Stream impl, you have a bunch of flexibility to build
+        // and return whatever type of Stream you see fit.
+        let res = RawValue::from_string("[]".to_string()).unwrap();
+        let stream = futures::stream::once(async move { Ok(res) });
+        let stream: Pin<Box<dyn futures::Stream<Item = _> + Send>> = Box::pin(stream);
+        // This subscription does not provide an ID.
+        Box::pin(std::future::ready(Ok(RpcSubscription { stream, id: None })))
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Instantiate our replacement RPC client.
+    let log = Arc::default();
+    let rpc_client = MyLoggingClient {
+        log: Arc::clone(&log),
+    };
+
+    // Pass this into our OnlineClient to instantiate it. This will lead to some
+    // RPC calls being made to fetch chain details/metadata, which will immediately
+    // fail..
+    let _ = OnlineClient::<PolkadotConfig>::from_rpc_client(Arc::new(rpc_client)).await;
+
+    // But, we can see that the calls were made via our custom RPC client:
+    println!("Log of calls made:\n\n{}", log.lock().unwrap().as_str());
+    Ok(())
+}

subxt/examples/setup_client_offline.rs

@@ -0,0 +1,35 @@
+use subxt::ext::codec::Decode;
+use subxt::metadata::Metadata;
+use subxt::utils::H256;
+use subxt::{config::PolkadotConfig, OfflineClient};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // We need to obtain the following details for an OfflineClient to be instantiated:
+
+    // 1. Genesis hash (RPC call: chain_getBlockHash(0)):
+    let genesis_hash = {
+        let h = "91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3";
+        let bytes = hex::decode(h).unwrap();
+        H256::from_slice(&bytes)
+    };
+
+    // 2. A runtime version (system_version constant on a Substrate node has these):
+    let runtime_version = subxt::rpc::types::RuntimeVersion {
+        spec_version: 9370,
+        transaction_version: 20,
+        other: Default::default(),
+    };
+
+    // 3. Metadata (I'll load it from the downloaded metadata, but you can use
+    //    `subxt metadata > file.scale` to download it):
+    let metadata = {
+        let bytes = std::fs::read("./artifacts/polkadot_metadata_small.scale").unwrap();
+        Metadata::decode(&mut &*bytes).unwrap()
+    };
+
+    // Create an offline client using the details obtained above:
+    let _api = OfflineClient::<PolkadotConfig>::new(genesis_hash, runtime_version, metadata);
+
+    Ok(())
+}

subxt/examples/storage_fetch.rs

@@ -0,0 +1,29 @@
+use sp_keyring::AccountKeyring;
+use subxt::{OnlineClient, PolkadotConfig};
+
+// Generate an interface that we can use from the node's metadata.
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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 storage query to access account information.
+    let account = AccountKeyring::Alice.to_account_id().into();
+    let storage_query = polkadot::storage().system().account(&account);
+
+    // Use that query to `fetch` a result. This returns an `Option<_>`, which will be
+    // `None` if no value exists at the given address. You can also use `fetch_default`
+    // where applicable, which will return the default value if none exists.
+    let result = api
+        .storage()
+        .at_latest()
+        .await?
+        .fetch(&storage_query)
+        .await?;
+
+    println!("Alice has free balance: {}", result.unwrap().data.free);
+    Ok(())
+}

subxt/examples/storage_fetch_dynamic.rs

@@ -0,0 +1,27 @@
+use sp_keyring::AccountKeyring;
+use subxt::dynamic::{At, Value};
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[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 dynamic storage query to access account information.
+    let account = AccountKeyring::Alice.to_account_id();
+    let storage_query =
+        subxt::dynamic::storage("System", "Account", vec![Value::from_bytes(account)]);
+
+    // Use that query to `fetch` a result. Because the query is dynamic, we don't know what the result
+    // type will be either, and so we get a type back that can be decoded into a dynamic Value type.
+    let result = api
+        .storage()
+        .at_latest()
+        .await?
+        .fetch(&storage_query)
+        .await?;
+    let value = result.unwrap().to_value()?;
+
+    println!("Alice has free balance: {:?}", value.at("data").at("free"));
+    Ok(())
+}

subxt/examples/storage_iterating.rs

@@ -0,0 +1,29 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_full.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 storage query to iterate over account information.
+    let storage_query = polkadot::storage().system().account_root();
+
+    // Get back an iterator of results (here, we are fetching 10 items at
+    // a time from the node, but we always iterate over oen at a time).
+    let mut results = api
+        .storage()
+        .at_latest()
+        .await?
+        .iter(storage_query, 10)
+        .await?;
+
+    while let Some((key, value)) = results.next().await? {
+        println!("Key: 0x{}", hex::encode(&key));
+        println!("Value: {:?}", value);
+    }
+
+    Ok(())
+}

subxt/examples/storage_iterating_dynamic.rs

@@ -0,0 +1,25 @@
+use subxt::{OnlineClient, PolkadotConfig};
+
+#[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 dynamic storage query to iterate account information.
+    let storage_query = subxt::dynamic::storage_root("System", "Account");
+
+    // Use that query to return an iterator over the results.
+    let mut results = api
+        .storage()
+        .at_latest()
+        .await?
+        .iter(storage_query, 10)
+        .await?;
+
+    while let Some((key, value)) = results.next().await? {
+        println!("Key: 0x{}", hex::encode(&key));
+        println!("Value: {:?}", value.to_value()?);
+    }
+
+    Ok(())
+}

subxt/examples/tx_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_small.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(())
+}

subxt/examples/tx_status_stream.rs

@@ -0,0 +1,58 @@
+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_small.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 then monitor the
+    // progress of it.
+    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(())
+}

subxt/examples/tx_with_params.rs

@@ -0,0 +1,28 @@
+use sp_keyring::AccountKeyring;
+use subxt::config::polkadot::{Era, PlainTip, PolkadotExtrinsicParamsBuilder as Params};
+use subxt::{tx::PairSigner, OnlineClient, PolkadotConfig};
+
+#[subxt::subxt(runtime_metadata_path = "../artifacts/polkadot_metadata_small.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 tx = polkadot::tx().balances().transfer(dest, 10_000);
+
+    // Configure the transaction parameters; for Polkadot the tip and era:
+    let tx_params = Params::new()
+        .tip(PlainTip::new(1_000))
+        .era(Era::Immortal, api.genesis_hash());
+
+    // submit the transaction:
+    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(())
+}