Skip to content
TxPipe Docs

Substrate RPC

The Substrate RPC source connects to a Substrate-based blockchain node via WebSocket RPC to subscribe to new blocks and retrieve complete block data. It works with any Substrate-based network including Polkadot, Kusama, and parachains.

Configuration

The following snippet shows an example of how to set up a Substrate WebSocket source:

[source]
type = "substrate-rpc"
url = "ws://localhost:9944"

Section source:

  • type: this field must be set to the literal value substrate-rpc.
  • url: the WebSocket URL of the Substrate RPC endpoint (required). Must use ws:// or wss:// protocol.

Supported Networks

The Substrate source works with any Substrate-based blockchain, including:

  • Polkadot - The main relay chain
  • Kusama - Polkadot’s canary network
  • Westend - Polkadot’s testnet
  • Parachains - Any parachain connected to Polkadot or Kusama
  • Solo chains - Independent Substrate-based blockchains
  • Local development nodes - For testing and development

Examples

Local Substrate Node

[source]
type = "substrate-rpc"
url = "ws://localhost:9944"

Polkadot Mainnet via OnFinality

[source]
type = "substrate-rpc"
url = "wss://polkadot.api.onfinality.io/public-ws"

Kusama Network

[source]
type = "substrate-rpc"
url = "wss://kusama-rpc.polkadot.io"

Westend Testnet

[source]
type = "substrate-rpc"
url = "wss://westend-rpc.polkadot.io"

Astar Parachain

[source]
type = "substrate-rpc"
url = "wss://rpc.astar.network"

How It Works

The Substrate source operates using Subxt library for Substrate interaction:

  1. Connection: Connects to the Substrate node via WebSocket using the Subxt client.

  2. Subscription: Subscribes to the best block stream to receive notifications when new blocks are finalized.

  3. Block Processing: For each new block:

    • Retrieves the complete block header information
    • Parses all extrinsics (transactions) in the block
    • Extracts signature information for signed extrinsics
    • Calculates block and extrinsic hashes

  4. Event Generation: Converts the block data into Oura’s internal ChainEvent::Apply format for processing by filters and sinks.

Output Events

The Substrate source produces ChainEvent::Apply events containing parsed Substrate block data. Each event includes:

Block Header

  • Block number and hash
  • Parent block hash
  • State root and extrinsics root
  • Block timestamp and other metadata

Extrinsics

For each extrinsic in the block:

  • Extrinsic index and hash
  • Raw bytes (hex-encoded)
  • Signature information (for signed extrinsics):
    • Signer address
    • Signature data
    • Signed extensions metadata

Additional Information

  • Total extrinsics count
  • Block processing metrics
  • Chain tip information

Data Structure

The parsed block follows this structure:

ParsedBlock {
    header: BlockHeader {
        number: u64,
        hash: String,
        parent_hash: String,
        state_root: String,
        extrinsics_root: String,
    },
    extrinsics: Vec<Extrinsic>,
    extrinsics_count: usize,
}


Extrinsic {
    index: u32,
    hash: String,
    bytes: Option<String>,
    signature: Option<SignatureInfo>,
}


SignatureInfo {
    address: String,
    signature: String,
    extra: Option<String>,
}

Substrate Runtime Compatibility

The source is designed to work with any Substrate runtime without requiring specific runtime metadata knowledge. It focuses on the core block structure that is consistent across all Substrate chains:

  • Block headers follow the standard Substrate format
  • Extrinsics use the SCALE codec for encoding
  • Signature extraction works with standard Substrate transaction formats

This makes the source compatible with both current and future Substrate networks without requiring updates for new runtime versions.

Performance Considerations

  • The source subscribes to the best blocks only, ensuring reliable block ordering
  • Block processing is done asynchronously to maintain good throughput
  • Extrinsic parsing includes detailed signature extraction which may add some processing overhead
  • WebSocket connections are automatically managed and reconnected if needed

The events follow the same pattern as other Oura sources, allowing them to be processed by standard filters and sinks in the pipeline.