Rework Subxt API to support offline and dynamic transactions (#593)

* WIP API changes * debug impls * Get main crate compiling with first round of changes * Some tidy up * Add WithExtrinsicParams, and have SubstrateConfig + PolkadotConfig, not DefaultConfig * move transaction into extrinsic folder * Add runtime updates back to OnlineClient * rework to be 'client first' to fit better with storage + events * add support for events to Client * tidy dupe trait bound * Wire storage into client, but need to remove static reliance * various tidy up and start stripping codegen to remove bits we dont need now * First pass updating calls and constants codegen * WIP storage client updates * First pass migrated runtime storage over to new format * pass over codegen to generate StorageAddresses and throw other stuff out * don't need a Call trait any more * shuffle things around a bit * Various proc_macro fixes to get 'cargo check' working * organise what's exposed from subxt * Get first example working; balance_transfer_with_params * get balance_transfer example compiling * get concurrent_storage_requests.rs example compiling * get fetch_all_accounts example compiling * get a bunch more of the examples compiling * almost get final example working; type mismatch to look into * wee tweaks * move StorageAddress to separate file * pass Defaultable/Iterable info to StorageAddress in codegen * fix storage validation ne, and partial run through example code * Remove static iteration and strip a generic param from everything * fix doc tests in subxt crate * update test utils and start fixing frame tests * fix frame staking tests * fix the rest of the test compile issues, Borrow on storage values * cargo fmt * remove extra logging during tests * Appease clippy and no more need for into_iter on events * cargo fmt * fix dryRun tests by waiting for blocks * wait for blocks instead of sleeping or other test hacks * cargo fmt * Fix doc links * Traitify StorageAddress * remove out-of-date doc comments * optimise decoding storage a little * cleanup tx stuff, trait for TxPayload, remove Err type param and decode at runtime * clippy fixes * fix doc links * fix doc example * constant address trait for consistency * fix a typo and remove EncodeWithMetadata stuff * Put EventDetails behind a proper interface and allow decoding into top level event, too * fix docs * tweak StorageAddress docs * re-export StorageAddress at root for consistency * fix clippy things * Add support for dynamic values * fix double encoding of storage map key after refactor * clippy fix * Fixes and add a dynamic usage example (needs new scale_value release) * bump scale_value version * cargo fmt * Tweak event bits * cargo fmt * Add a test and bump scale-value to 0.4.0 to support this * remove unnecessary vec from dynamic example * Various typo/grammar fixes Co-authored-by: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> * Address PR nits * Undo accidental rename in changelog * Small PR nits/tidyups * fix tests; codegen change against latest substrate * tweak storage address util names * move error decoding to DecodeError and expose * impl some basic traits on the extrinsic param builder Co-authored-by: Alexandru Vasile <60601340+lexnv@users.noreply.github.com>
2026-06-13 22:11:06 +00:00 · 2022-08-08 11:55:20 +01:00
parent 7a09ac6cd7
commit e48f0e3b1d
84 changed files with 23097 additions and 35863 deletions
@@ -0,0 +1,21 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! This module provides two clients that can be used to work with
+//! transactions, storage and events. The [`OfflineClient`] works
+//! entirely offline and can be passed to any function that doesn't
+//! require network access. The [`OnlineClient`] requires network
+//! access.
+
+mod offline_client;
+mod online_client;
+
+pub use offline_client::{
+    OfflineClient,
+    OfflineClientT,
+};
+pub use online_client::{
+    OnlineClient,
+    OnlineClientT,
+};
@@ -0,0 +1,140 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+use crate::{
+    constants::ConstantsClient,
+    events::EventsClient,
+    rpc::RuntimeVersion,
+    storage::StorageClient,
+    tx::TxClient,
+    Config,
+    Metadata,
+};
+use derivative::Derivative;
+use std::sync::Arc;
+
+/// A trait representing a client that can perform
+/// offline-only actions.
+pub trait OfflineClientT<T: Config>: Clone + Send + Sync + 'static {
+    /// Return the provided [`Metadata`].
+    fn metadata(&self) -> Metadata;
+    /// Return the provided genesis hash.
+    fn genesis_hash(&self) -> T::Hash;
+    /// Return the provided [`RuntimeVersion`].
+    fn runtime_version(&self) -> RuntimeVersion;
+
+    /// Work with transactions.
+    fn tx(&self) -> TxClient<T, Self> {
+        TxClient::new(self.clone())
+    }
+
+    /// Work with events.
+    fn events(&self) -> EventsClient<T, Self> {
+        EventsClient::new(self.clone())
+    }
+
+    /// Work with storage.
+    fn storage(&self) -> StorageClient<T, Self> {
+        StorageClient::new(self.clone())
+    }
+
+    /// Access constants.
+    fn constants(&self) -> ConstantsClient<T, Self> {
+        ConstantsClient::new(self.clone())
+    }
+}
+
+/// A client that is capable of performing offline-only operations.
+/// Can be constructed as long as you can populate the required fields.
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""), Clone(bound = ""))]
+pub struct OfflineClient<T: Config> {
+    inner: Arc<Inner<T>>,
+}
+
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""), Clone(bound = ""))]
+struct Inner<T: Config> {
+    genesis_hash: T::Hash,
+    runtime_version: RuntimeVersion,
+    metadata: Metadata,
+}
+
+impl<T: Config> OfflineClient<T> {
+    /// Construct a new [`OfflineClient`], providing
+    /// the necessary runtime and compile-time arguments.
+    pub fn new(
+        genesis_hash: T::Hash,
+        runtime_version: RuntimeVersion,
+        metadata: Metadata,
+    ) -> OfflineClient<T> {
+        OfflineClient {
+            inner: Arc::new(Inner {
+                genesis_hash,
+                runtime_version,
+                metadata,
+            }),
+        }
+    }
+
+    /// Return the genesis hash.
+    pub fn genesis_hash(&self) -> T::Hash {
+        self.inner.genesis_hash
+    }
+
+    /// Return the runtime version.
+    pub fn runtime_version(&self) -> RuntimeVersion {
+        self.inner.runtime_version.clone()
+    }
+
+    /// Return the [`Metadata`] used in this client.
+    pub fn metadata(&self) -> Metadata {
+        self.inner.metadata.clone()
+    }
+
+    // Just a copy of the most important trait methods so that people
+    // don't need to import the trait for most things:
+
+    /// Work with transactions.
+    pub fn tx(&self) -> TxClient<T, Self> {
+        <Self as OfflineClientT<T>>::tx(self)
+    }
+
+    /// Work with events.
+    pub fn events(&self) -> EventsClient<T, Self> {
+        <Self as OfflineClientT<T>>::events(self)
+    }
+
+    /// Work with storage.
+    pub fn storage(&self) -> StorageClient<T, Self> {
+        <Self as OfflineClientT<T>>::storage(self)
+    }
+
+    /// Access constants.
+    pub fn constants(&self) -> ConstantsClient<T, Self> {
+        <Self as OfflineClientT<T>>::constants(self)
+    }
+}
+
+impl<T: Config> OfflineClientT<T> for OfflineClient<T> {
+    fn genesis_hash(&self) -> T::Hash {
+        self.genesis_hash()
+    }
+    fn runtime_version(&self) -> RuntimeVersion {
+        self.runtime_version()
+    }
+    fn metadata(&self) -> Metadata {
+        self.metadata()
+    }
+}
+
+// For ergonomics; cloning a client is deliberately fairly cheap (via Arc),
+// so this allows users to pass references to a client rather than explicitly
+// cloning. This is partly for consistency with OnlineClient, which can be
+// easily converted into an OfflineClient for ergonomics.
+impl<'a, T: Config> From<&'a OfflineClient<T>> for OfflineClient<T> {
+    fn from(c: &'a OfflineClient<T>) -> Self {
+        c.clone()
+    }
+}
@@ -0,0 +1,234 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+use super::{
+    OfflineClient,
+    OfflineClientT,
+};
+use crate::{
+    constants::ConstantsClient,
+    error::Error,
+    events::EventsClient,
+    rpc::{
+        Rpc,
+        RpcClient,
+        RuntimeVersion,
+    },
+    storage::StorageClient,
+    tx::TxClient,
+    Config,
+    Metadata,
+};
+use derivative::Derivative;
+use futures::future;
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+/// A trait representing a client that can perform
+/// online actions.
+pub trait OnlineClientT<T: Config>: OfflineClientT<T> {
+    /// Return an RPC client that can be used to communicate with a node.
+    fn rpc(&self) -> &Rpc<T>;
+}
+
+/// A client that can be used to perform API calls (that is, either those
+/// requiriing an [`OfflineClientT`] or those requiring an [`OnlineClientT`]).
+#[derive(Derivative)]
+#[derivative(Clone(bound = ""))]
+pub struct OnlineClient<T: Config> {
+    inner: Arc<RwLock<Inner<T>>>,
+    rpc: Rpc<T>,
+}
+
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""))]
+struct Inner<T: Config> {
+    genesis_hash: T::Hash,
+    runtime_version: RuntimeVersion,
+    metadata: Metadata,
+}
+
+impl<T: Config> std::fmt::Debug for OnlineClient<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Client")
+            .field("rpc", &"<Rpc>")
+            .field("inner", &self.inner)
+            .finish()
+    }
+}
+
+impl<T: Config> OnlineClient<T> {
+    /// Construct a new [`OnlineClient`] using default settings which
+    /// point to a locally running node on `ws://127.0.0.1:9944`.
+    pub async fn new() -> Result<OnlineClient<T>, Error> {
+        let url = "ws://127.0.0.1:9944";
+        OnlineClient::from_url(url).await
+    }
+
+    /// Construct a new [`OnlineClient`], providing a URL to connect to.
+    pub async fn from_url(url: impl AsRef<str>) -> Result<OnlineClient<T>, Error> {
+        let client = crate::rpc::ws_client(url.as_ref()).await?;
+        OnlineClient::from_rpc_client(client).await
+    }
+
+    /// Construct a new [`OnlineClient`] by providing the underlying [`RpcClient`]
+    /// to use to drive the connection.
+    pub async fn from_rpc_client(
+        rpc_client: impl Into<RpcClient>,
+    ) -> Result<OnlineClient<T>, Error> {
+        let rpc = Rpc::new(rpc_client.into());
+
+        let (genesis_hash, runtime_version, metadata) = future::join3(
+            rpc.genesis_hash(),
+            rpc.runtime_version(None),
+            rpc.metadata(),
+        )
+        .await;
+
+        Ok(OnlineClient {
+            inner: Arc::new(RwLock::new(Inner {
+                genesis_hash: genesis_hash?,
+                runtime_version: runtime_version?,
+                metadata: metadata?,
+            })),
+            rpc,
+        })
+    }
+
+    /// Create an object which can be used to keep the runtime uptodate
+    /// in a separate thread.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// use subxt::{ OnlineClient, PolkadotConfig };
+    ///
+    /// let client = OnlineClient::<PolkadotConfig>::new().await.unwrap();
+    ///
+    /// let update_task = client.subscribe_to_updates();
+    /// tokio::spawn(async move {
+    ///     update_task.perform_runtime_updates().await;
+    /// });
+    /// # }
+    /// ```
+    pub fn subscribe_to_updates(&self) -> ClientRuntimeUpdater<T> {
+        ClientRuntimeUpdater(self.clone())
+    }
+
+    /// Return the [`Metadata`] used in this client.
+    pub fn metadata(&self) -> Metadata {
+        let inner = self.inner.read();
+        inner.metadata.clone()
+    }
+
+    /// Return the genesis hash.
+    pub fn genesis_hash(&self) -> T::Hash {
+        let inner = self.inner.read();
+        inner.genesis_hash
+    }
+
+    /// Return the runtime version.
+    pub fn runtime_version(&self) -> RuntimeVersion {
+        let inner = self.inner.read();
+        inner.runtime_version.clone()
+    }
+
+    /// Return an RPC client to make raw requests with.
+    pub fn rpc(&self) -> &Rpc<T> {
+        &self.rpc
+    }
+
+    /// Return an offline client with the same configuration as this.
+    pub fn offline(&self) -> OfflineClient<T> {
+        let inner = self.inner.read();
+        OfflineClient::new(
+            inner.genesis_hash,
+            inner.runtime_version.clone(),
+            inner.metadata.clone(),
+        )
+    }
+
+    // Just a copy of the most important trait methods so that people
+    // don't need to import the trait for most things:
+
+    /// Work with transactions.
+    pub fn tx(&self) -> TxClient<T, Self> {
+        <Self as OfflineClientT<T>>::tx(self)
+    }
+
+    /// Work with events.
+    pub fn events(&self) -> EventsClient<T, Self> {
+        <Self as OfflineClientT<T>>::events(self)
+    }
+
+    /// Work with storage.
+    pub fn storage(&self) -> StorageClient<T, Self> {
+        <Self as OfflineClientT<T>>::storage(self)
+    }
+
+    /// Access constants.
+    pub fn constants(&self) -> ConstantsClient<T, Self> {
+        <Self as OfflineClientT<T>>::constants(self)
+    }
+}
+
+impl<T: Config> OfflineClientT<T> for OnlineClient<T> {
+    fn metadata(&self) -> Metadata {
+        self.metadata()
+    }
+    fn genesis_hash(&self) -> T::Hash {
+        self.genesis_hash()
+    }
+    fn runtime_version(&self) -> RuntimeVersion {
+        self.runtime_version()
+    }
+}
+
+impl<T: Config> OnlineClientT<T> for OnlineClient<T> {
+    fn rpc(&self) -> &Rpc<T> {
+        &self.rpc
+    }
+}
+
+/// Client wrapper for performing runtime updates. See [`OnlineClient::subscribe_to_updates()`]
+/// for example usage.
+pub struct ClientRuntimeUpdater<T: Config>(OnlineClient<T>);
+
+impl<T: Config> ClientRuntimeUpdater<T> {
+    fn is_runtime_version_different(&self, new: &RuntimeVersion) -> bool {
+        let curr = self.0.inner.read();
+        &curr.runtime_version != new
+    }
+
+    /// Performs runtime updates indefinitely unless encountering an error.
+    ///
+    /// *Note:* This will run indefinitely until it errors, so the typical usage
+    /// would be to run it in a separate background task.
+    pub async fn perform_runtime_updates(&self) -> Result<(), Error> {
+        // Obtain an update subscription to further detect changes in the runtime version of the node.
+        let mut update_subscription = self.0.rpc.subscribe_runtime_version().await?;
+
+        while let Some(new_runtime_version) = update_subscription.next().await {
+            // The Runtime Version obtained via subscription.
+            let new_runtime_version = new_runtime_version?;
+
+            // Ignore this update if there is no difference.
+            if !self.is_runtime_version_different(&new_runtime_version) {
+                continue
+            }
+
+            // Fetch new metadata.
+            let new_metadata = self.0.rpc.metadata().await?;
+
+            // Do the update.
+            let mut writable = self.0.inner.write();
+            writable.metadata = new_metadata;
+            writable.runtime_version = new_runtime_version;
+        }
+
+        Ok(())
+    }
+}