From 037d5178b8d167ba1a2779dc3b5a0a351b568d9f Mon Sep 17 00:00:00 2001 From: James Wilson Date: Mon, 3 Mar 2025 12:07:48 +0000 Subject: [PATCH] Document generating interface from Runtime WASM and change feature to `runtime-wasm-path` (#1936) * runtime_metadata_path => runtime_wasm_path and document this feature * fix doc --- macro/Cargo.toml | 2 +- macro/src/lib.rs | 14 ++++----- subxt/Cargo.toml | 2 +- subxt/src/lib.rs | 62 +++++++++++++++++++++++++++---------- testing/ui-tests/Cargo.toml | 2 +- 5 files changed, 55 insertions(+), 27 deletions(-) diff --git a/macro/Cargo.toml b/macro/Cargo.toml index 01fc86b6f9..3add41d9df 100644 --- a/macro/Cargo.toml +++ b/macro/Cargo.toml @@ -15,7 +15,7 @@ description = "Generate types and helpers for interacting with Substrate runtime [features] web = ["subxt-codegen/web"] -runtime-metadata-path = ["sc-executor", "sc-executor-common", "sp-maybe-compressed-blob", "sp-io", "sp-state-machine"] +runtime-wasm-path = ["sc-executor", "sc-executor-common", "sp-maybe-compressed-blob", "sp-io", "sp-state-machine"] runtime-metadata-insecure-url = ["subxt-utils-fetchmetadata/url"] [lib] diff --git a/macro/src/lib.rs b/macro/src/lib.rs index 5f41806d5a..a8137880ee 100644 --- a/macro/src/lib.rs +++ b/macro/src/lib.rs @@ -16,7 +16,7 @@ use scale_typegen::typegen::{ use subxt_codegen::{CodegenBuilder, CodegenError, Metadata}; use syn::{parse_macro_input, punctuated::Punctuated}; -#[cfg(feature = "runtime-metadata-path")] +#[cfg(feature = "runtime-wasm-path")] mod wasm_loader; #[derive(Clone, Debug)] @@ -56,7 +56,7 @@ struct RuntimeMetadataArgs { no_default_substitutions: bool, #[darling(default)] unstable_metadata: darling::util::Flag, - #[cfg(feature = "runtime-metadata-path")] + #[cfg(feature = "runtime-wasm-path")] #[darling(default)] runtime_path: Option, } @@ -206,7 +206,7 @@ fn fetch_metadata(args: &RuntimeMetadataArgs) -> Result Result { abort_call_site!( "At least one of 'runtime_metadata_path', 'runtime_metadata_insecure_url' or 'runtime_path` can be provided" ) } - #[cfg(not(feature = "runtime-metadata-path"))] + #[cfg(not(feature = "runtime-wasm-path"))] (None, None) => { abort_call_site!( "At least one of 'runtime_metadata_path', 'runtime_metadata_insecure_url' can be provided" ) } - #[cfg(feature = "runtime-metadata-path")] + #[cfg(feature = "runtime-wasm-path")] _ => { abort_call_site!( "Only one of 'runtime_metadata_path', 'runtime_metadata_insecure_url' or 'runtime_path` can be provided" ) } - #[cfg(not(feature = "runtime-metadata-path"))] + #[cfg(not(feature = "runtime-wasm-path"))] _ => { abort_call_site!( "Only one of 'runtime_metadata_path' or 'runtime_metadata_insecure_url' can be provided" diff --git a/subxt/Cargo.toml b/subxt/Cargo.toml index a490c9f3dd..7caf8df4d0 100644 --- a/subxt/Cargo.toml +++ b/subxt/Cargo.toml @@ -71,7 +71,7 @@ unstable-metadata = [] unstable-light-client = ["subxt-lightclient", "subxt-rpcs/unstable-light-client"] # Activate this to expose the ability to generate metadata from Wasm runtime files. -runtime-metadata-path = ["subxt-macro/runtime-metadata-path"] +runtime-wasm-path = ["subxt-macro/runtime-wasm-path"] [dependencies] async-trait = { workspace = true } diff --git a/subxt/src/lib.rs b/subxt/src/lib.rs index e15bf45b71..1dc11a78ac 100644 --- a/subxt/src/lib.rs +++ b/subxt/src/lib.rs @@ -110,7 +110,7 @@ pub mod ext { } } -/// Generate a strongly typed API for interacting with a Substrate runtime from its metadata. +/// Generate a strongly typed API for interacting with a Substrate runtime from its metadata of WASM. /// /// # Metadata /// @@ -128,7 +128,19 @@ pub mod ext { /// /// # Basic usage /// -/// Annotate a Rust module with the `subxt` attribute referencing the aforementioned metadata file. +/// We can generate an interface to a chain given either: +/// - A locally saved SCALE encoded metadata file (see above) for that chain, +/// - The Runtime WASM for that chain, or +/// - A URL pointing at the JSON-RPC interface for a node on that chain. +/// +/// In each case, the `subxt` macro will use this data to populate the annotated module with all of the methods +/// and types required for interacting with the chain that the Runtime/metadata was loaded from. +/// +/// Let's look at each of these: +/// +/// ## Using a locally saved metadata file +/// +/// Annotate a Rust module with the `subxt` attribute referencing a metadata file like so: /// /// ```rust,no_run /// #[subxt::subxt( @@ -137,8 +149,37 @@ pub mod ext { /// mod polkadot {} /// ``` /// -/// The `subxt` macro will populate the annotated module with all of the methods and types required -/// for interacting with the runtime that the metadata is in via Subxt. +/// ## Using a WASM runtime via `runtime_path = "..."` +/// +/// This requires the `runtime-wasm-path` feature flag. +/// +/// Annotate a Rust module with the `subxt` attribute referencing some runtime WASM like so: +/// +/// ```rust,no_run +/// #[subxt::subxt( +/// runtime_path = "../artifacts/westend_runtime.wasm", +/// )] +/// mod polkadot {} +/// ``` +/// +/// ## Connecting to a node to download metadata via `runtime_metadata_insecure_url = "..."` +/// +/// This will, at compile time, connect to the JSON-RPC interface for some node at the URL given, +/// download the metadata from it, and use that. This can be useful in CI, but is **not recommended** +/// in production code, because: +/// +/// - The compilation time is increased since we have to download metadata from a URL each time. If +/// the node we connect to is unresponsive, this will be slow or could fail. +/// - The metadata may change from what is expected without notice, causing compilation to fail if +/// it leads to changes in the generated interfaces that are being used. +/// - The node that you connect to could be malicious and provide incorrect metadata for the chain. +/// +/// ```rust,ignore +/// #[subxt::subxt( +/// runtime_metadata_insecure_url = "wss://rpc.polkadot.io:443" +/// )] +/// mod polkadot {} +/// ``` /// /// # Configuration /// @@ -251,19 +292,6 @@ pub mod ext { /// mod polkadot {} /// ``` /// -/// ## `runtime_metadata_insecure_url = "..."` -/// -/// This attribute can be used instead of `runtime_metadata_path` and will tell the macro to download metadata from a node running -/// at the provided URL, rather than a node running locally. This can be useful in CI, but is **not recommended** in production code, -/// since it runs at compile time and will cause compilation to fail if the node at the given address is unavailable or unresponsive. -/// -/// ```rust,ignore -/// #[subxt::subxt( -/// runtime_metadata_insecure_url = "wss://rpc.polkadot.io:443" -/// )] -/// mod polkadot {} -/// ``` -/// /// ## `generate_docs` /// /// By default, documentation is not generated via the macro, since IDEs do not typically make use of it. This attribute diff --git a/testing/ui-tests/Cargo.toml b/testing/ui-tests/Cargo.toml index 58641779ab..6582f45ed1 100644 --- a/testing/ui-tests/Cargo.toml +++ b/testing/ui-tests/Cargo.toml @@ -14,6 +14,6 @@ hex = { workspace = true } scale-info = { workspace = true, features = ["bit-vec"] } frame-metadata = { workspace = true } codec = { package = "parity-scale-codec", workspace = true, features = ["derive", "bit-vec"] } -subxt = { workspace = true, features = ["native", "jsonrpsee", "runtime-metadata-path"] } +subxt = { workspace = true, features = ["native", "jsonrpsee", "runtime-wasm-path"] } subxt-metadata = { workspace = true } generate-custom-metadata = { path = "../generate-custom-metadata" }