Add more docs, pass over README, logo

Author: jsdw

README.md

@@ -1,54 +1,73 @@
-# subxt · [![build](https://github.com/paritytech/subxt/actions/workflows/rust.yml/badge.svg)](https://github.com/paritytech/subxt/actions/workflows/rust.yml) [![Latest Version](https://img.shields.io/crates/v/subxt.svg)](https://crates.io/crates/subxt) [![Documentation](https://docs.rs/subxt/badge.svg)](https://docs.rs/subxt)
+<p align="center">
+  <img src="./logo.svg" alt="subxt logo" width="420" />
+</p>
 
-Subxt is a library for interacting with [Substrate](https://github.com/paritytech/polkadot-sdk) based nodes in Rust and WebAssembly. It can:
+<p align="center">
+  <a href="https://github.com/paritytech/subxt/actions/workflows/rust.yml"><img src="https://github.com/paritytech/subxt/actions/workflows/rust.yml/badge.svg" alt="build"></a>
+  <a href="https://crates.io/crates/subxt"><img src="https://img.shields.io/crates/v/subxt.svg" alt="Latest Version"></a>
+  <a href="https://docs.rs/subxt"><img src="https://docs.rs/subxt/badge.svg" alt="Documentation"></a>
+</p>
+
+Subxt is a library for interacting with chains in the [Polkadot](https://github.com/paritytech/polkadot-sdk) network. It can:
 
 - Submit Extrinsics (this is where the name comes from).
-- Subscribe to blocks, reading the extrinsics and associated events from them.
-- Read and iterate over storage values.
-- Read constants and custom values from the metadata.
-- Call runtime APIs, returning the results.
-- Do all of the above via a safe, statically typed interface or via a dynamic one when you need the flexibility.
-- Compile to WASM and run entirely in the browser.
-- Do a bunch of things in a `#[no_std]` environment via the `subxt-core` crate.
-- Use a built-in light client (`smoldot`) to interact with chains.
+- Access information at any block (eg storage values, constants, Runtime APIs, View Functions).
+- Subscribe to new blocks (and then do the above at them).
+- Do all of the above via a safe, statically typed interface or via a flexible dynamic interface.
+- Do most of the above via a built-in light client to interact with chains trustlessly.
+- Compile to WASM and run [entirely in the browser](./examples/wasm-example), or be [called via FFI](./examples/ffi-example) in many other languages.
 
 ## Usage
 
-Take a look in the [examples](./subxt/examples) folder or the [examples](./examples) folder for various smaller or
-larger `subxt` usage examples, or [read the guide](https://docs.rs/subxt/latest/subxt/book/index.html) to learn more.
-
-### 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.
-
-## Subxt Documentation
-
-For more details regarding utilizing subxt, please visit the [documentation](https://docs.rs/subxt/latest/subxt/).
-
-## 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 up-to-date `substrate` executable on your path.
-
-This can be installed from source via cargo:
-
-```bash
-cargo install --git https://github.com/paritytech/polkadot-sdk staging-node-cli --force
+Take a look at the [single-file examples](./subxt/examples) folder or the [project based examples](./examples) folder for various smaller or
+larger `subxt` usage examples, or [read the docs](https://docs.rs/subxt/latest/subxt) to learn more.
+
+## Example
+
+The "hello world" example of Subxt is submitting a transaction. This is what it looks like:
+
+```rust
+use subxt::{Error, OnlineClient, PolkadotConfig};
+use subxt_signer::sr25519::dev;
+
+// Generate an interface that we can use from the node's metadata.
+#[subxt::subxt(runtime_metadata_path = "/path/to/polkadot_rc_metadata.scale")]
+mod polkadot {}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    // Create a new API client, configured to talk to Polkadot nodes.
+    let api = OnlineClient::<PolkadotConfig>::new().await?;
+
+    // Almost all actions are performed at an explicit block. Here we use
+    // the current block at the time of running this.
+    let at_block = api.at_current_block().await?;
+
+    // Build a balance transfer extrinsic.
+    let dest = dev::bob().public_key().into();
+    let balance_transfer_tx = polkadot::transactions()
+        .balances()
+        .transfer_allow_death(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 = dev::alice();
+    let events = at_block
+        .transactions()
+        .sign_and_submit_then_watch_default(&balance_transfer_tx, &from)
+        .await?
+        .wait_for_finalized_success()
+        .await?;
+
+    // (Optional) we can look for a specific event to learn more about 
+    // the submission.
+    if let Some(event) = events.find_first::<polkadot::balances::events::Transfer>() {
+        println!("Balance transfer success: {event:?}");
+    }
+
+    Ok(())
+}
 ```
 
 ## Real world usage
@@ -68,9 +87,9 @@ Please add your project to this list via a PR.
 - [Hyperbridge](https://github.com/polytope-labs/hyperbridge) A hyperscalable coprocessor for verifiable cross-chain interoperability.
 - [pop CLI](https://github.com/r0gue-io/pop-cli) The all-in-one tool for Polkadot development.
 
-**Alternatives**
+## Alternatives
 
-[substrate-api-client](https://github.com/scs/substrate-api-client) provides similar functionality.
+If you're working in TypeScript / JavaScript, [polkadot-api](https://github.com/polkadot-api/polkadot-api) is an excellent and actively developed alternative.
 
 #### License
 

artifacts/polkadot_assethub_metadata_small.scale

@@ -0,0 +1,89 @@
+//! Configuring Subxt to talk to AssetHub.
+use subxt::Error;
+use subxt::config::{
+    Config, DefaultExtrinsicParams, DefaultExtrinsicParamsBuilder, PolkadotConfig, SubstrateConfig,
+};
+use subxt_signer::sr25519::dev;
+
+#[subxt::subxt(
+    runtime_metadata_path = "../artifacts/polkadot_assethub_metadata_small.scale",
+    derive_for_type(
+        path = "staging_xcm::v5::location::Location",
+        derive = "Clone, codec::Encode",
+        recursive
+    )
+)]
+pub mod assethub {}
+use assethub::runtime_types::staging_xcm::v5::junctions::Junctions;
+use assethub::runtime_types::staging_xcm::v5::location::Location;
+
+/// Our AssetHub configuration wraps SubstrateConfig and
+/// tweaks it in a couple of places.
+#[derive(Debug, Clone, Default)]
+pub struct AssetHubConfig(SubstrateConfig);
+
+impl Config for AssetHubConfig {
+    // AssetHub, like Polkadot, has no account index on its address type:
+    type Address = <PolkadotConfig as Config>::Address;
+
+    // Configure the asset location to be our generated Location type.
+    type AssetId = Location;
+
+    // Just copy the default SubstrateConfig for these:
+    type AccountId = <SubstrateConfig as Config>::AccountId;
+    type Signature = <SubstrateConfig as Config>::Signature;
+    type Hasher = <SubstrateConfig as Config>::Hasher;
+    type Header = <SubstrateConfig as Config>::Header;
+    type ExtrinsicParams = DefaultExtrinsicParams<AssetHubConfig>;
+
+    // Forward these methods to the default SubstrateConfig:
+    fn genesis_hash(&self) -> Option<subxt::config::HashFor<Self>> {
+        self.0.genesis_hash()
+    }
+    fn legacy_types_for_spec_version<'this>(
+        &'this self,
+        spec_version: u32,
+    ) -> Option<scale_info_legacy::TypeRegistrySet<'this>> {
+        self.0.legacy_types_for_spec_version(spec_version)
+    }
+    fn metadata_for_spec_version(&self, spec_version: u32) -> Option<subxt::ArcMetadata> {
+        self.0.metadata_for_spec_version(spec_version)
+    }
+    fn set_metadata_for_spec_version(&self, spec_version: u32, metadata: subxt::ArcMetadata) {
+        self.0.set_metadata_for_spec_version(spec_version, metadata);
+    }
+    fn spec_and_transaction_version_for_block_number(
+        &self,
+        block_number: u64,
+    ) -> Option<(u32, u32)> {
+        self.0
+            .spec_and_transaction_version_for_block_number(block_number)
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    // With the config defined, we can create a Subxt client using it:
+    let client = subxt::OnlineClient::<AssetHubConfig>::new().await?;
+
+    // Build some extrinsic to submit:
+    let tx_payload = assethub::tx().system().remark(b"Hello".to_vec());
+
+    // Build extrinsic params using an asset at some location as a tip:
+    let location = Location {
+        parents: 3,
+        interior: Junctions::Here,
+    };
+    let tx_config = DefaultExtrinsicParamsBuilder::<AssetHubConfig>::new()
+        .tip_of(1234, location)
+        .build();
+
+    // And provide the extrinsic params including the tip when submitting a transaction:
+    let _ = client
+        .tx()
+        .await?
+        .sign_and_submit_then_watch(&tx_payload, &dev::alice(), tx_config)
+        .await;
+
+    Ok(())
+}

logo.svg

@@ -0,0 +1,53 @@
+//! Configuring Subxt to talk to AssetHub.
+use subxt::Error;
+use subxt::config::{Config, DefaultExtrinsicParams, SubstrateConfig};
+
+/// Our EthConfig wraps SubstrateConfig and configures the
+/// account ID / address / signature to be based on 20 byte IDs.
+#[derive(Debug, Clone, Default)]
+pub struct EthConfig(SubstrateConfig);
+
+impl Config for EthConfig {
+    // AssetHub, like Polkadot, has no account index on its address type:
+    type Address = subxt::utils::AccountId20;
+    type AccountId = subxt::utils::AccountId20;
+    type Signature = subxt_signer::eth::Signature;
+
+    // Just copy the default SubstrateConfig for these:
+    type AssetId = <SubstrateConfig as Config>::AssetId;
+    type Hasher = <SubstrateConfig as Config>::Hasher;
+    type Header = <SubstrateConfig as Config>::Header;
+    type ExtrinsicParams = DefaultExtrinsicParams<EthConfig>;
+
+    // Forward these methods to the default SubstrateConfig:
+    fn genesis_hash(&self) -> Option<subxt::config::HashFor<Self>> {
+        self.0.genesis_hash()
+    }
+    fn legacy_types_for_spec_version<'this>(
+        &'this self,
+        spec_version: u32,
+    ) -> Option<scale_info_legacy::TypeRegistrySet<'this>> {
+        self.0.legacy_types_for_spec_version(spec_version)
+    }
+    fn metadata_for_spec_version(&self, spec_version: u32) -> Option<subxt::ArcMetadata> {
+        self.0.metadata_for_spec_version(spec_version)
+    }
+    fn set_metadata_for_spec_version(&self, spec_version: u32, metadata: subxt::ArcMetadata) {
+        self.0.set_metadata_for_spec_version(spec_version, metadata);
+    }
+    fn spec_and_transaction_version_for_block_number(
+        &self,
+        block_number: u64,
+    ) -> Option<(u32, u32)> {
+        self.0
+            .spec_and_transaction_version_for_block_number(block_number)
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    // With the eth config defined, we can create a Subxt client using it:
+    let _client = subxt::OnlineClient::<EthConfig>::new().await?;
+
+    Ok(())
+}

subxt/examples/config_assethub.rs

@@ -9,6 +9,8 @@
 //! via something like [`OnlineClient::at_block`] or [`OfflineClient::at_block`].
 //! These hand back [`OnlineClientAtBlock`] or [`OfflineClientAtBlock`], which expose
 //! various methods available online or offline at the given block.
+//!
+//! See the docs for [`ClientAtBlock`] to see what it's possible to do at a given block.
 
 mod offline_client;
 mod online_client;

subxt/examples/config_eth.rs

@@ -11,6 +11,39 @@
 //! - A [`PolkadotConfig`] implementation is provided which is specialized towards the Polkadot
 //!   Relay Chain, and comes pre-configured to work against historic Polkadot RC blocks.
 //!
+//! # Creating custom configuration
+//!
+//! Some chains require this configuration to be customized. In many cases, you can perform most
+//! interactions on these chains using the default [`SubstrateConfig`], but may need small
+//! customizations to enable all interactions to work properly.
+//!
+//! ## Asset Hub
+//!
+//! One chain that needs custom configuration to completely work is Asset Hub. For the most part
+//! you can just use [`SubstrateConfig`], but if you want to add a tip to a transaction in anything
+//! other than DOT, you'll need to change the [`Config::AssetId`] property to allow for this.
+//! This involves creating a new [`Config`] instance for Asset Hub, which looks like this:
+//!
+//! ```rust,no_run
+#![doc = include_str ! ("../examples/config_assethub.rs")]
+//! ```
+//!
+//! ## Ethereum based chains
+//!
+//! If you're interacting with an Ethereum based chain, you'll need to configure Subxt to work with
+//! 20 byte account IDs instead of the default 32 byte ones, and a corresponding `Signature` type.
+//! This would look something like this:
+//!
+//! ```rust,no_run
+#![doc = include_str ! ("../examples/config_eth.rs")]
+//! ```
+//!
+//! # Other chains
+//!
+//! If you find that [`SubstrateConfig`] doesn't work, and neither of the above is applicable, then
+//! the next step is to look at how the runtime for the chain you'd like to interact with is
+//! configured. Please open an issue in the Subxt repository and we can help to narrow down what
+//! the problem might be.
 
 mod default_extrinsic_params;
 
@@ -56,7 +89,7 @@ pub trait Config: Clone + Debug + Sized + Send + Sync + 'static {
     type ExtrinsicParams: ExtrinsicParams<Self>;
 
     /// This is used to identify an asset in the `ChargeAssetTxPayment` signed extension.
-    type AssetId: Debug + Clone + Encode + DecodeAsType + EncodeAsType + Send;
+    type AssetId: AssetId;
 
     /// The hashing system (algorithm) being used in the runtime (e.g. Blake2).
     /// This is created on demand with the relevant metadata for a given block, and
@@ -129,7 +162,11 @@ pub type HashFor<T> = <<T as Config>::Hasher as Hasher>::Hash;
 /// given some [`Config`], this return the other params needed for its `ExtrinsicParams`.
 pub type ParamsFor<T> = <<T as Config>::ExtrinsicParams as ExtrinsicParams<T>>::Params;
 
-/// Block hashes must conform to a bunch of things to be used in Subxt.
+/// AssetId types must conform to this trait.
+pub trait AssetId: Debug + Clone + Encode + DecodeAsType + EncodeAsType + Send {}
+impl<T> AssetId for T where T: Debug + Clone + Encode + DecodeAsType + EncodeAsType + Send {}
+
+/// Block hash types must conform to this trait.
 pub trait Hash:
     Debug
     + Display