lightclient: Add support for multi-chain usecase

lightclient/src/client.rs

@@ -2,6 +2,8 @@
 // This file is dual-licensed as Apache-2.0 or GPL-3.0.
 // see LICENSE for license details.
 
+use std::iter;
+
 use super::{
     background::{BackgroundTask, FromSubxt, MethodResponse},
     LightClientRpcError,
@@ -11,14 +13,38 @@ use tokio::sync::{mpsc, mpsc::error::SendError, oneshot};
 
 use super::platform::build_platform;
 
-pub const LOG_TARGET: &str = "light-client";
+pub const LOG_TARGET: &str = "subxt-light-client";
+
+/// A raw light-client RPC implementation that can connect to multiple chains.
+#[derive(Clone)]
+pub struct RawLightClientRpc {
+    /// Communicate with the backend task that multiplexes the responses
+    /// back to the frontend.
+    to_backend: mpsc::UnboundedSender<FromSubxt>,
+}
+
+impl RawLightClientRpc {
+    /// Construct a [`LightClientRpc`] that can communicated with the provided chain.
+    ///
+    /// # Note
+    ///
+    /// This uses the same underlying instance created by [`LightClientRpc::new_from_client`].
+    pub fn for_chain(&self, chain_id: smoldot_light::ChainId) -> LightClientRpc {
+        LightClientRpc {
+            to_backend: self.to_backend.clone(),
+            chain_id,
+        }
+    }
+}
 
 /// The light-client RPC implementation that is used to connect with the chain.
 #[derive(Clone)]
 pub struct LightClientRpc {
     /// Communicate with the backend task that multiplexes the responses
     /// back to the frontend.
     to_backend: mpsc::UnboundedSender<FromSubxt>,
+    /// The chain ID to target for requests.
+    chain_id: smoldot_light::ChainId,
 }
 
 impl LightClientRpc {
@@ -31,7 +57,16 @@ impl LightClientRpc {
     ///
     /// ## Panics
     ///
-    /// Panics if being called outside of `tokio` runtime context.
+    /// The panic behaviour depends on the feature flag being used:
+    ///
+    /// ### Native
+    ///
+    /// Panics when called outside of a `tokio` runtime context.
+    ///
+    /// ### Web
+    ///
+    /// If smoldot panics, then the promise created will be leaked. For more details, see
+    /// https://docs.rs/wasm-bindgen-futures/latest/wasm_bindgen_futures/fn.future_to_promise.html.
     pub fn new(
         config: smoldot_light::AddChainConfig<'_, (), impl Iterator<Item = smoldot_light::ChainId>>,
     ) -> Result<LightClientRpc, LightClientRpcError> {
@@ -46,22 +81,61 @@ impl LightClientRpc {
             .add_chain(config)
             .map_err(|err| LightClientRpcError::AddChainError(err.to_string()))?;
 
-        let (to_backend, backend) = mpsc::unbounded_channel();
-
-        // `json_rpc_responses` can only be `None` if we had passed `json_rpc: Disabled`.
         let rpc_responses = json_rpc_responses.expect("Light client RPC configured; qed");
 
+        let raw_client = Self::new_from_client(
+            client,
+            iter::once(AddedChain {
+                chain_id,
+                rpc_responses,
+            }),
+        );
+        Ok(raw_client.for_chain(chain_id))
+    }
+
+    /// Constructs a new [`RawLightClientRpc`] from the raw smoldot client.
+    ///
+    /// Receives a list of RPC objects as a result of calling `smoldot_light::Client::add_chain`.
+    /// This [`RawLightClientRpc`] can target different chains using [`RawLightClientRpc::for_chain`] method.
+    ///
+    /// ## Panics
+    ///
+    /// The panic behaviour depends on the feature flag being used:
+    ///
+    /// ### Native
+    ///
+    /// Panics when called outside of a `tokio` runtime context.
+    ///
+    /// ### Web
+    ///
+    /// If smoldot panics, then the promise created will be leaked. For more details, see
+    /// https://docs.rs/wasm-bindgen-futures/latest/wasm_bindgen_futures/fn.future_to_promise.html.
+    pub fn new_from_client<TPlat>(
+        client: smoldot_light::Client<TPlat>,
+        chains: impl Iterator<Item = AddedChain>,
+    ) -> RawLightClientRpc
+    where
+        TPlat: smoldot_light::platform::PlatformRef + Clone,
+    {
+        let (to_backend, backend) = mpsc::unbounded_channel();
+        let chains = chains.collect();
+
         let future = async move {
-            let mut task = BackgroundTask::new(client, chain_id);
-            task.start_task(backend, rpc_responses).await;
+            let mut task = BackgroundTask::new(client);
+            task.start_task(backend, chains).await;
         };
 
         #[cfg(feature = "native")]
         tokio::spawn(future);
         #[cfg(feature = "web")]
         wasm_bindgen_futures::spawn_local(future);
 
-        Ok(LightClientRpc { to_backend })
+        RawLightClientRpc { to_backend }
+    }
+
+    /// Returns the chain ID of the current light-client.
+    pub fn chain_id(&self) -> smoldot_light::ChainId {
+        self.chain_id
     }
 
     /// Submits an RPC method request to the light-client.
@@ -79,6 +153,7 @@ impl LightClientRpc {
             method,
             params,
             sender,
+            chain_id: self.chain_id,
         })?;
 
         Ok(receiver)
@@ -107,8 +182,17 @@ impl LightClientRpc {
             params,
             sub_id,
             sender,
+            chain_id: self.chain_id,
         })?;
 
         Ok((sub_id_rx, receiver))
     }
 }
+
+/// The added chain of the light-client.
+pub struct AddedChain {
+    /// The id of the chain.
+    pub chain_id: smoldot_light::ChainId,
+    /// Producer of RPC responses for the chain.
+    pub rpc_responses: smoldot_light::JsonRpcResponses,
+}

lightclient/src/lib.rs

@@ -33,8 +33,13 @@ mod platform;
 #[allow(unused_imports)]
 pub use getrandom as _;
 
-pub use client::LightClientRpc;
-pub use smoldot_light::{AddChainConfig, AddChainConfigJsonRpc, ChainId};
+pub use client::{AddedChain, LightClientRpc, RawLightClientRpc};
+pub use smoldot_light::{
+    platform::PlatformRef, AddChainConfig, AddChainConfigJsonRpc, ChainId, Client, JsonRpcResponses,
+};
+
+#[cfg(feature = "native")]
+pub use smoldot_light::platform::default::DefaultPlatform;
 
 /// Light client error.
 #[derive(Debug, thiserror::Error)]

subxt/Cargo.toml

@@ -114,3 +114,8 @@ tracing-subscriber = { workspace = true }
 name = "unstable_light_client_tx_basic"
 path = "examples/unstable_light_client_tx_basic.rs"
 required-features = ["unstable-light-client", "jsonrpsee"]
+
+[[example]]
+name = "unstable_light_client_parachains"
+path = "examples/unstable_light_client_parachains.rs"
+required-features = ["unstable-light-client", "jsonrpsee", "native"]

subxt/examples/unstable_light_client_parachains.rs

@@ -0,0 +1,100 @@
+use futures::StreamExt;
+use std::{iter, num::NonZeroU32};
+use subxt::{
+    client::{LightClient, RawLightClient},
+    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 {}
+
+const POLKADOT_SPEC: &str = include_str!("../../artifacts/demo_chain_specs/polkadot.json");
+const ASSET_HUB_SPEC: &str =
+    include_str!("../../artifacts/demo_chain_specs/polkadot_asset_hub.json");
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // The smoldot logs are informative:
+    tracing_subscriber::fmt::init();
+
+    // Connecting to a parachain is a multi step process.
+
+    // Step 1. Construct a new smoldot client.
+    let mut client = subxt_lightclient::Client::new(subxt_lightclient::DefaultPlatform::new(
+        "subxt-example-light-client".into(),
+        "version-0".into(),
+    ));
+
+    // Step 2. Connect to the relay chain of the parachain. For this example, the Polkadot relay chain.
+    let polkadot_connection = client
+        .add_chain(subxt_lightclient::AddChainConfig {
+            specification: POLKADOT_SPEC,
+            json_rpc: subxt_lightclient::AddChainConfigJsonRpc::Enabled {
+                max_pending_requests: NonZeroU32::new(128).unwrap(),
+                max_subscriptions: 1024,
+            },
+            potential_relay_chains: iter::empty(),
+            database_content: "",
+            user_data: (),
+        })
+        .expect("Light client chain added with valid spec; qed");
+    let polkadot_json_rpc_responses = polkadot_connection
+        .json_rpc_responses
+        .expect("Light client configured with json rpc enabled; qed");
+    let polkadot_chain_id = polkadot_connection.chain_id;
+
+    // Step 3. Connect to the parachain. For this example, the Asset hub parachain.
+    let assethub_connection = client
+        .add_chain(subxt_lightclient::AddChainConfig {
+            specification: ASSET_HUB_SPEC,
+            json_rpc: subxt_lightclient::AddChainConfigJsonRpc::Enabled {
+                max_pending_requests: NonZeroU32::new(128).unwrap(),
+                max_subscriptions: 1024,
+            },
+            // The chain specification of the asset hub parachain mentions that the identifier
+            // of its relay chain is `polkadot`.
+            potential_relay_chains: [polkadot_chain_id].into_iter(),
+            database_content: "",
+            user_data: (),
+        })
+        .expect("Light client chain added with valid spec; qed");
+    let parachain_json_rpc_responses = assethub_connection
+        .json_rpc_responses
+        .expect("Light client configured with json rpc enabled; qed");
+    let parachain_chain_id = assethub_connection.chain_id;
+
+    // Step 4. Turn the smoldot client into a raw client.
+    let raw_light_client = RawLightClient::builder()
+        .add_chain(polkadot_chain_id, polkadot_json_rpc_responses)
+        .add_chain(parachain_chain_id, parachain_json_rpc_responses)
+        .build(client)
+        .await?;
+
+    // Step 5. Obtain a client to target the relay chain and the parachain.
+    let polkadot_api: LightClient<PolkadotConfig> =
+        raw_light_client.for_chain(polkadot_chain_id).await?;
+    let parachain_api: LightClient<PolkadotConfig> =
+        raw_light_client.for_chain(parachain_chain_id).await?;
+
+    // Step 6. Subscribe to the finalized blocks of the chains.
+    let polkadot_sub = polkadot_api
+        .blocks()
+        .subscribe_finalized()
+        .await?
+        .map(|block| ("Polkadot", block));
+    let parachain_sub = parachain_api
+        .blocks()
+        .subscribe_finalized()
+        .await?
+        .map(|block| ("AssetHub", block));
+    let mut stream_combinator = futures::stream::select(polkadot_sub, parachain_sub);
+
+    while let Some((chain, block)) = stream_combinator.next().await {
+        let block = block?;
+
+        println!("     Chain {:?} hash={:?}", chain, block.hash());
+    }
+
+    Ok(())
+}