subxt/book/setup/
client.rs

1// Copyright 2019-2025 Parity Technologies (UK) Ltd.
2// This file is dual-licensed as Apache-2.0 or GPL-3.0.
3// see LICENSE for license details.
4
5//! # The Subxt client.
6//!
7//! The client forms the entry point to all of the Subxt APIs. Every client implements one or
8//! both of [`crate::client::OfflineClientT`] and [`crate::client::OnlineClientT`].
9//!
10//! Subxt ships with three clients which implement one or both of traits:
11//! - An [online client](crate::client::OnlineClient).
12//! - An [offline client](crate::client::OfflineClient).
13//! - A light client (which is currently still unstable).
14//!
15//! In theory it's possible for users to implement their own clients, although this isn't generally
16//! expected.
17//!
18//! The provided clients are all generic over the [`crate::config::Config`] that they accept, which
19//! determines how they will interact with the chain.
20//!
21//! In the case of the [`crate::OnlineClient`], we have various ways to instantiate it:
22//!
23//! - [`crate::OnlineClient::new()`] to connect to a node running locally. This uses the default Subxt
24//!   backend, and the default RPC client.
25//! - [`crate::OnlineClient::from_url()`] to connect to a node at a specific URL. This uses the default Subxt
26//!   backend, and the default RPC client.
27//! - [`crate::OnlineClient::from_rpc_client()`] to instantiate the client with a [`crate::backend::rpc::RpcClient`].
28//! - [`crate::OnlineClient::from_backend()`] to instantiate Subxt using a custom backend. Currently there
29//!   is just one backend, [`crate::backend::legacy::LegacyBackend`]. This backend can be instantiated from
30//!   a [`crate::backend::rpc::RpcClient`].
31//!
32//! [`crate::backend::rpc::RpcClient`] can itself be instantiated from anything that implements the low level
33//! [`crate::backend::rpc::RpcClientT`] trait; this allows you to decide how Subxt will attempt to talk to a node
34//! if you'd prefer something other default client. We use this approach under the hood to implement the light client.
35//!
36//! ## Examples
37//!
38//! Most of the other examples will instantiate a client. Here are a couple of examples for less common
39//! cases.
40//!
41//! ### Writing a custom [`crate::backend::rpc::RpcClientT`] implementation:
42//!
43//! ```rust,ignore
44#![doc = include_str!("../../../examples/setup_client_custom_rpc.rs")]
45//! ```
46//!
47//! ### Creating an [`crate::OfflineClient`]:
48//!
49//! ```rust,ignore
50#![doc = include_str!("../../../examples/setup_client_offline.rs")]
51//! ```
52//!
subxt/book/setup/client.rs

subxt/book/setup/
client.rs
