Polkadot Omni Node¶

Introduction¶

The polkadot-omni-node crate is a versatile, pre-built binary designed to simplify running parachains in the Polkadot ecosystem. Unlike traditional node binaries that are tightly coupled to specific runtime code, the polkadot-omni-node operates using an external chain specification file, allowing it to adapt dynamically to different parachains.

This approach enables it to act as a white-labeled node binary, capable of running most parachains that do not require custom node-level logic or extensions. Developers can leverage this flexibility to test, deploy, or operate parachain nodes without maintaining a dedicated codebase for each network.

This guide provides step-by-step instructions for installing the polkadot-omni-node, obtaining a chain specification, and spinning up a parachain node.

Prerequisites¶

Before getting started, ensure you have the following prerequisites:

Rust: Required to build and install the polkadot-omni-node binary.

Ensure Rust's cargo command is available in your terminal by running:

cargo --version

Install Polkadot Omni Node¶

To install polkadot-omni-node globally using cargo, run:

cargo install --locked polkadot-omni-node@0.7.0

This command downloads and installs version 0.7.0 of the binary, making it available system-wide.

To confirm the installation, run:

polkadot-omni-node --version

You should see the installed version number printed to the terminal, confirming a successful installation.

Obtain Chain Specifications¶

The polkadot-omni-node binary uses a chain specification file to configure and launch a parachain node. This file defines the parachain's genesis state and network settings.

The most common source for official chain specifications is the paritytech/chainspecs repository. These specifications are also browsable in a user-friendly format via the Chainspec Collection website.

To obtain a chain specification:

Visit the Chainspec Collection website.
Find the parachain you want to run.
Click the chain spec to open it.
Copy the JSON content and save it locally as a .json file, e.g., chain_spec.json.

Run a Parachain Full Node¶

Once you've installed polkadot-omni-node and saved the appropriate chain specification file, you can start a full node for your chosen parachain.

To see all available flags and configuration options, run:

polkadot-omni-node --help

To launch the node, run the following command, replacing ./INSERT_PARACHAIN_CHAIN_SPEC.json with the actual path to your saved chain spec file.

This command will:

Load the chain specification.
Initialize the node using the provided network configuration.
Begin syncing with the parachain network.

polkadot-omni-node --chain ./INSERT_PARACHAIN_CHAIN_SPEC.json --sync warp

The --chain flag tells the polkadot-omni-node which parachain to run by pointing to its chain specification file.
The --sync warp flag enables warp sync, allowing the node to quickly catch up to the latest finalized state. Historical blocks are fetched in the background as the node continues operating.

Once started, the node will begin connecting to peers and syncing with the network. You’ll see logs in your terminal reflecting its progress.

Interact with the Node¶

By default, polkadot-omni-node exposes a WebSocket endpoint at ws://localhost:9944, which you can use to interact with the running node. You can connect using:

Polkadot.js Apps: A web-based interface for exploring and interacting with Polkadot SDK-based chains.
Custom scripts using compatible libraries.

Once connected, you can review blocks, call extrinsics, inspect storage, and interact with the runtime.

Parachain Compatibility¶

The polkadot-omni-node is designed to work with most parachains out of the box; however, your parachain's runtime must meet specific requirements and follow certain conventions to be compatible. This section outlines what your runtime needs to implement and configure to work seamlessly with the polkadot-omni-node:

Your runtime must implement the required runtime APIs (see below).
Your runtime must include and configure the required pallets.

The parachain-template provides a complete reference implementation that is fully compatible with the polkadot-omni-node. You can use it as a starting point or reference for ensuring your runtime meets all compatibility requirements.

Required Runtime APIs¶

Your parachain runtime must implement the following runtime APIs for the polkadot-omni-node to function properly:

GetParachainInfo Runtime API: The omni-node requires the GetParachainInfo runtime API to identify and configure the parachain correctly. This API provides the parachain ID to the node.

runtime/src/apis.rs

impl cumulus_primitives_core::GetParachainInfo<Block> for Runtime {
    fn parachain_id() -> cumulus_primitives_core::ParaId {
        // Return your parachain ID
        ParachainInfo::parachain_id()
    }
}

Aura Runtime API: For consensus, the polkadot-omni-node expects the Aura runtime API to be implemented.

runtime/src/apis.rs

impl sp_consensus_aura::AuraApi<Block, AuraId> for Runtime {
    fn slot_duration() -> sp_consensus_aura::SlotDuration {
        sp_consensus_aura::SlotDuration::from_millis(SLOT_DURATION)
    }

    fn authorities() -> Vec<AuraId> {
        Aura::authorities().into_inner()
    }
}

Required Pallets¶

Your runtime must include and properly configure the following pallets:

System Pallet: The System pallet (frame-system) is fundamental and must be configured with appropriate types.

runtime/src/lib.rs

#[frame_support::runtime]
impl frame_system::Config for Runtime {
    type Block = Block;
    type BlockNumber = BlockNumber;
    // ... other configurations
}

// Must be named "System" for omni-node compatibility
pub type System = frame_system::Pallet<Runtime>;

ParachainSystem Pallet: This pallet (cumulus-pallet-parachain-system) enables parachain functionality and handles low-level details of being a parachain.

runtime/src/lib.rs

impl cumulus_pallet_parachain_system::Config for Runtime {
    type RuntimeEvent = RuntimeEvent;
    type OnSystemEvent = ();
    // ... other configurations
}

// Must be named "ParachainSystem" for omni-node compatibility  
pub type ParachainSystem = cumulus_pallet_parachain_system::Pallet<Runtime>;

Aura Pallet: For block authoring consensus (pallet-aura).

runtime/src/lib.rs

impl pallet_aura::Config for Runtime {
    type AuthorityId = AuraId;
    type DisabledValidators = ();
    type MaxAuthorities = MaxAuthorities;
    type AllowMultipleBlocksPerSlot = ConstBool<false>;
}

pub type Aura = pallet_aura::Pallet<Runtime>;

ParachainInfo Pallet: Provides parachain metadata (parachain-info).

runtime/src/lib.rs

impl parachain_info::Config for Runtime {}

pub type ParachainInfo = parachain_info::Pallet<Runtime>;

If you're migrating an existing parachain to use the polkadot-omni-node, you may need to perform runtime upgrades to add the required runtime APIs and pallets. Follow the standard parachain runtime upgrade procedures to implement these changes on your live network.

Last update: August 15, 2025
| Created: May 28, 2025