| name | prefer-subxt-over-rpc |
| description | Use when fetching or decoding chain data (blocks, extrinsics, events, storage, runtime APIs) and tempted to make manual RPC calls (legacy_rpc, rpc_params!, chain_getBlock, state_call), or when writing code that branches on metadata versions |
Prefer Subxt over manual RPC
Overview
Subxt 0.50 covers ~99% of chain access — fetching and decoding blocks, extrinsics, events, storage, constants, runtime APIs and view functions — across all runtime versions back to genesis. Manual RPC (legacy_rpc, rpc_params!) is a last resort, not a default.
Quick reference
| Task | Instead of RPC, use |
|---|
| Latest finalized block | api.at_current_block().await? |
| Specific block | api.at_block(...).await? |
| Storage read (one-shot) | at_block.storage().fetch(addr, keys) / .iter(...) |
| Storage read (reusable handle) | at_block.storage().entry(addr)? then .fetch(keys) |
| Storage read that may be absent | at_block.storage().try_fetch(addr, keys) (returns Option) |
| Events | at_block.events() |
| Extrinsics | at_block.extrinsics() |
| Runtime API call | at_block.runtime_apis() |
| View functions | at_block.view_functions() |
| Constants | at_block.constants() |
| Metadata / spec version | at_block.metadata(), at_block.spec_version() |
End-to-end example — a dynamic storage read at a block, no RPC anywhere:
let at_block = api.at_block(block_hash).await?;
let addr = subxt::dynamic::storage::<(), u32>("Referenda", "ReferendumCount");
let count: u32 = at_block.storage().fetch(addr, ()).await?.decode()?;
Keyed entries take the keys as a tuple in fetch (e.g. .fetch(addr, (account_id,))). Both fetch and entry accept dynamic and static/codegen addresses alike — fetch(addr, keys) is just shorthand for entry(addr)?.fetch(keys), so choose by whether you reuse the handle, not by address kind. Note fetch errors with NoValueFound when a map entry has no value and no default; for entries that may be absent (common on account/map reads) use try_fetch, which returns Option. See the scale-decoding skill for choosing the value type parameter.
Metadata versions: don't hand-roll (for chain data)
When reading chain data (storage, events, extrinsics, runtime APIs), don't branch on metadata versions yourself. Subxt already converts every historic and modern metadata format into subxt::Metadata, and has usually already downloaded it for the block you're working at.
Pre-V14 blocks additionally need legacy type info:
PolkadotConfig ships Polkadot relay chain historic types by default (opt out with PolkadotConfig::builder().use_historic_types(false).build()).SubstrateConfig needs them provided: SubstrateConfig::builder().set_legacy_types(registry).build() (a scale_info_legacy::ChainTypeRegistry). This repo uses SubstrateConfig, and that wiring already lives in build_subxt_config (crates/server/src/state.rs), keyed by the chain-config legacy_types string — add a case there rather than building configs inline.
For chain-data access, if subxt::Metadata doesn't expose something you need, file a subxt PR to expose it rather than decoding raw metadata.
Exception: endpoints that serve version-faithful raw metadata JSON (e.g. handlers/runtime/get_metadata.rs, which emits distinct v14/v15 shapes) legitimately decode frame_metadata::RuntimeMetadata and branch on its version — normalized subxt::Metadata can't reproduce those shapes. That branching is expected there; don't "fix" it away.
Notes
- No runtime-upgrade monitoring is needed — subxt resolves the correct metadata/spec version per block automatically. Mind the cost, though: with the default config (this repo sets no spec-version ranges), each
at_block issues an extra Core_version RPC to resolve the spec version — converted metadata is cached per spec version, but that resolution is not cached per block. On hot paths, pre-seed with set_spec_version_for_block_ranges / set_metadata_for_spec_versions to drop the round-trips.
- The subxt pin lives in
crates/server/Cargo.toml (likewise frame-decode and its legacy-types feature). Before relying on version-specific behavior, check that pin against the subxt CHANGELOG — e.g. SubstrateConfigBuilder::set_genesis_hash was a no-op until 0.50.2. The VerifySignature extension-identifier rename is covered in the v5-extrinsic-signatures skill.
