lightclient: Add support for multi-chain usecase

[lexnv]

The subxt lightclient support enforced users to spawn one smoldot instance per chain.
With this PR, users can reuse the same smoldot instance to communicate with multiple chains and parachains.

API design for multi chain usecase:

• Users are responsible for creating a low level smoldot instance, which allows complete control over registering chains (users can configure internal buffers, maximum number of subscription, add multiple chains, remove chains etc).
• Chains are also reported to the RawLightClientBuilder object in terms of chain ID and RPC object that produces method responses
• The RawLightClientBuilder is turned into a LightClient and the smoldot instance is spawned on a background task that handles requests and multiplexes responses back to the internal RPC objects of subxt
• A LightClient instance is mapped to one chain. To interact with a different chain, users can call LightClient::target_chain method. This fetches under the hood the needed info of the OnlineClient (metadata, spec, runtime) and receives a custom Config. The newly created light client communicates with the same background instance of smoldot.

// Smoldot instance.
let client = subxt_lightclient::Client::new(...);
// Raw subxt builder.
let mut builder = LightClient::raw_builder();

// Configure smoldot.
let chain = client.add_chain(...);

// Make subxt aware of the chain IFF
// - the chain has the RPC functionality enabled 
// - the chain should be used by the subxt LightClient
builder.add_chain(chain.chain_id, chain.rpc_object);

// Other configuration ...

// Spawn the smoldot on the background task and target chain x
let api_chain_x = builder.build(client, chian_x_id).await?;

// Target chain Y (if prior added).
let api_chain_y = api_chain_x.target_chain(chian_y_id).await?;

// Use subxt clients api_chain_x and api_chain_y

The changes include:

• Adding support for building a light client instance from a smoldot instance via RawLightClientBuilder
• Ability to target different chains / parachains (and reuse the same smoldot instance) via target_chain API
• Extend internal the frontend - backend protocol to support multiple chains and multiplex smoldot responses accordingly
• Created a low level example which subscribes to finalized blocks of polkadot relay chain and asset hub parachain
• Added 2 demo chain specs to reach Polkadot and PolkadotAssetHub
• Improved the readability and added granular detail for tracing logs

Review notes:

• I would suggest looking first at the example to get a feel of the API subxt/examples/unstable_light_client_parachains.rs then at the background implementation for multichain use-cases lightclient/src/background.rs

Next steps (possibly in another PR):

• Add subxt book entry about the raw light client
• Maybe expose the subxt_lightclient::fetch_spec via a ChainSpecBuilder to avoid demo-chain-specs artifacts and the need to keep them in sync (currently taken from smoldot)
• Extend the low-level raw client builder with easier to use API, but more restrictive (maybe abstract the smoldot instance entirely)

Closes: #1213.

[jsdw]

I wonder if it's possible to obtain a more condensed version of this file; there's one here for polkadot which is much smaller:

https://github.com/paritytech/substrate-connect/blob/main/projects/extension/assets/chainspecs/polkadot.json

It'd be great to know how to programmatically get hold of the smallest ones possible!

[lexnv]

I have created this issue that I ll tackle shortly 👍

• cli: Command to fetch chainSpec and optimise its size #1263

[jsdw]

As a nit, I think I'd find the example a little easier to follow if all of the builder stuff was in one place, like:

let polkadot_api = builder
    .add_chain(polkadot_chain_id, polkadot_json_rpc_responses)
    .add_chain(parachain_chain_id, parachain_json_rpc_responses)
    .build(client, polkadot_chain_id)
    .await?;

I guess that client is used to make requests, but we also need to hold onto those json_rpc_responses for each chain, but looking at this I do wonder if it's possible to do any better here, eg avoid those .add_chain steps because that information can be extracted from the client on the .build step or something (I guess I'll know better when I read the rest of the PR :D)

[jsdw]

Client can be indexed on a chain Id for instance to get some stuff (I didn't check what); I wonder if that helps at all:

https://docs.rs/smoldot-light/latest/src/smoldot_light/lib.rs.html#1097

[lexnv]

I believe regarding the json_rpc_responses object, if the user drops this object, than the backend might not provide any responses:

pub struct JsonRpcResponses {
    /// Receiving side for responses.
    ///
    /// As long as this object is alive, the JSON-RPC service will continue running. In order
    /// to prevent that from happening, we destroy it as soon as the
    /// [`JsonRpcResponses::public_api_chain_destroyed`] is notified of the destruction of
    /// the sender.
    inner: Option<json_rpc_service::Frontend>,

    /// Notified when the [`PublicApiChain`] is destroyed.
    public_api_chain_destroyed: pin::Pin<Box<event_listener::EventListener>>,
}

Extracted from smolodot.

Wrt https://docs.rs/smoldot-light/latest/src/smoldot_light/lib.rs.html#1097, I believe that returns the user data that we provided as () for default purposes. I couldn't dig anything that's related to the frontend channel that gets responses back

[niklasad1]

nice and great to have this for sure

as I said in the review, this API is low-level and would be nice with
some high-level API because one would need understand some configurations
from smoldot to use it.

[jsdw]

I wonder if there's any sensible way to hide tokio, so that users don't need to care, and we can potentially remove it as a dependency in the future. Possibly not though; nothing comes to mind offhand!

[jsdw]

Just to check, is this a smoldot instance or specifically just a smoldot_lightclient::Client instance?

[lexnv]

The subxt_lightclient::Client in this case is a re-export of smoldot_light::Client. Will modify the docs to say client instead of instance here and everywhere else, thanks!

[jsdw]

See my other comment re renaming exports a bit (#1238 (comment)) :)

[jsdw]

I'm generally thinking if it's better to expose all of the smoldot things behind it's own name; when reading the PR I wasn't sure which of the types actually came from smoldot and which were our own.

I think the ideal place to be here is:

• subxt_lightclient doesn't need to ever be explicitly depended on; it's just internal logic that Subxt leans on and re-exports as needed.
• It's easy to tell which types are from smoldot_lightclient and which types are from our crates (this way, it's super obvious in the example for instance that the RawLightClientBuilder is taking smoldot args for instance).

So maybe here we could expose all of the smoldot stuff via a subxt_lightclient::smoldot::... and perhaps in subxt we expose our own types in subxt::client::light_client, and maybe the smoldot types via either subxt::ext::smoldot (or smoldot_light.. not sure which makes more sense) or maybe subxt::client::light_client::smoldot (or smoldot_light) if we prefer to export specific types only and want to namespace them into the light client stuff.

[lexnv]

Yep that makes sense to have different exports.

I modified the exports as:

• subxt_lightclient::smoldot { .. } where smoldot and smoldot_light objects are exported
• then I exported this in subxt::client::light_client::smoldot

[jsdw]

Does it make more sense now to save just the actual chain_id in LightClient instead of the raw_rpc thing now?

[jsdw]

Same comment as others :)

[lexnv]

Think this should be updated now 🤔 Might be a github race somewhere

[jsdw]

This looks great! Nice clean code :)

I left some comments, mostly small and one regarding jigging some exports around a bit but happy to approve and let you merge when you're happy with everything!

[niklasad1]

@lexnv

I just realized that creating a "connection" to the same chain more than twice might end up in weird race-conditions because the background task has a HashMap<(request_id, ChainId)> which may overwrite a previous request with "the same (request_id; ChainId)" but a different sender...

I don't know whether it makes sense restrict that one can only the connect to the same chain once or refactor that work with several connections....

EDIT: nvm, the request ID will just be incremented for every request so the same request ID shouldn't be used anyway.