Run a Parachain RPC Node

Markdown for LLMs

Copy page View page in Markdown Download page in Markdown Open in ChatGPT Open in Claude

Introduction

A parachain RPC node provides direct access to a specific parachain on the Polkadot network, enabling developers and applications to interact with its assets, governance, cross-chain messages, and more. Running your own node also supports essential infrastructure tasks, such as block indexing and compatibility with Polkadot SDK tools.

Through the parachain RPC (port 9944, serving both WebSocket and HTTP), your node acts as the bridge between the parachain and applications. This page walks through setting up a node from scratch, covering hardware requirements and deployment options using Docker or systemd.

Prerequisites

Hardware Requirements

RPC nodes serving production traffic require robust hardware:

• CPU: 8+ cores; 16+ cores for high traffic
• Memory: 64 GB RAM minimum; 128 GB recommended for high traffic
• Storage: Total required storage is the size of the pruned relay chain state plus the size of the parachain state. Snapshots may be available. Fast NVMe I/O is critical for RPC query performance
  • Pruned Polkadot Relay Chain: ~40 GB using warp sync
  • System parachains:
    • Archive node (complete history): Using snapshots, expected storage requirements are:
      • Asset Hub: ~1.2 TB
      • People Chain: ~400 GB
      • Bridge Hub: ~400 GB
      • Coretime: ~200 GB
    • Pruned node (recent state): Snapshots are not available. A pruned node uses warp sync instead and requires far less disk space than an archive node.
  • Non-system parachains: Consult the parachain team or documentation
• Network:
  • Public IP address
  • Stable internet connection with sufficient bandwidth
  • 1 Gbps connection for high traffic scenarios
  • Consider DDoS protection and rate limiting for production deployments
  • Open ports:
    • 30333: Parachain P2P
    • 30334: Relay chain P2P
    • 9944: Polkadot SDK RPC (WebSocket and HTTP)
    • 8545: Ethereum JSON-RPC (if running eth-rpc adapter)

Note

For development or low-traffic scenarios, you can reduce these requirements proportionally. Consider using a reverse proxy (nginx, Caddy) for production deployments.

Software Requirements

Required software:

• Operating system: Ubuntu 22.04 LTS (recommended) or similar Linux distribution
• Docker: Required for obtaining binaries and running containers
• rclone: (Optional but recommended) Command-line program for managing files on cloud storage

Obtain the Chain Specification

To run an RPC node for a parachain, you need its chain specification file. This JSON file defines the network parameters, genesis state, and bootnodes. The process for obtaining the chain spec may differ depending on whether you’re running a system parachain or a regular parachain.

System Parachains

Obtain the chain specification for your target system parachain using one of the following options:

Download from Chainspec Collection (Recommended)Download from the Polkadot SDK repository

Download the chain specification directly using curl. For example, to download the Asset Hub Polkadot chain spec:

curl -sL -o chain-spec.json \
  https://paritytech.github.io/chainspecs/polkadot/parachain/asset-hub/chainspec.json

For other system parachains, find the correct URL in the Chainspec Collection under the List of Chainspecs.

Download the chain specification directly using curl. For example, to download the Asset Hub Polkadot chain spec:

curl -sL -o chain-spec.json \
  https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/cumulus/parachains/chain-specs/asset-hub-polkadot.json

Other Parachains

For non-system parachains, check the parachain's documentation for official chain specification files.

Spin Up a Node

Choose the deployment option that fits your project, and follow the steps in the appropriate tab to complete setup:

• Docker: Best for simpler set up and maintenance
• systemd: Best for production environments requiring more control

This guide uses Polkadot Asset Hub as an example. To set up a different parachain, replace the chain spec file, snapshot path, and chain name with the corresponding values for your target parachain.

System parachain details:

System Parachain	Para ID	Chain Spec File	Snapshot Path
Asset Hub	1000	asset-hub-polkadot.json	polkadot-asset-hub-rocksdb-archive
People Chain	1004	people-polkadot.json	polkadot-people-rocksdb-archive
Bridge Hub	1002	bridge-hub-polkadot.json	polkadot-bridge-hub-paritydb-archive
Coretime Chain	1005	coretime-polkadot.json	polkadot-coretime-rocksdb-archive

Dockersystemd

1. Download your parachain's chain specification as described in Obtain the Chain Specification.

2. (Archive nodes only, optional but recommended) Download a pre-synced parachain snapshot to cut initial sync time from days to hours:

   Note

   Archive snapshots are available for system parachains. For other parachains, check with the parachain team for snapshot availability or sync from genesis. Skip this step for a pruned node, which uses warp sync instead. The relay chain does not need a snapshot because it always uses warp sync in this guide.

   1. Create a new directory:

      mkdir -p my-node-data/chains/asset-hub-polkadot/db
      

   2. Download and save the archive parachain snapshot:

      # Check https://snapshots.polkadot.io/ for the latest snapshot URL
      export SNAPSHOT_URL_PARACHAIN="https://snapshots.polkadot.io/polkadot-asset-hub-rocksdb-archive/INSERT_LATEST"
      
      rclone copyurl $SNAPSHOT_URL_PARACHAIN/files.txt files.txt
      rclone copy --progress --transfers 20 \
        --http-url $SNAPSHOT_URL_PARACHAIN \
        --no-traverse --http-no-head --disable-http2 \
        --inplace --no-gzip-encoding --size-only \
        --retries 6 --retries-sleep 10s \
        --files-from files.txt :http: my-node-data/chains/asset-hub-polkadot/db/
      
      rm files.txt
      

      rclone parameters

      • --transfers 20: Uses 20 parallel transfers for faster download
      • --retries 6: Automatically retries failed transfers up to 6 times
      • --retries-sleep 10s: Waits 10 seconds between retry attempts
      • --size-only: Only transfers if sizes differ (prevents unnecessary re-downloads)

3. Launch the parachain node using the official Parity Docker image:

   ArchivePruned

   docker run -d --name polkadot-hub-rpc --restart unless-stopped \
     -p 9944:9944 \
     -p 9615:9615 \
     -p 30334:30334 \
     -p 30333:30333 \
     -v $(pwd)/chain-spec.json:/chain-spec.json \
     -v $(pwd)/my-node-data:/data \
     parity/polkadot-parachain:stable2603-1 \
     --name=PolkadotHubRPC \
     --base-path=/data \
     --chain=/chain-spec.json \
     --prometheus-external \
     --prometheus-port 9615 \
     --rpc-external \
     --rpc-port=9944 \
     --rpc-cors=all \
     --rpc-methods=safe \
     --rpc-max-connections=1000 \
     --state-pruning=archive \
     --blocks-pruning=archive \
     -- \
     --base-path=/data \
     --chain=polkadot \
     --sync=warp \
     --state-pruning=256 \
     --blocks-pruning=256 \
     --rpc-port=0
   

   docker run -d --name polkadot-hub-rpc --restart unless-stopped \
     -p 9944:9944 \
     -p 9615:9615 \
     -p 30334:30334 \
     -p 30333:30333 \
     -v $(pwd)/chain-spec.json:/chain-spec.json \
     -v $(pwd)/my-node-data:/data \
     parity/polkadot-parachain:stable2603-1 \
     --name=PolkadotHubRPC \
     --base-path=/data \
     --chain=/chain-spec.json \
     --prometheus-external \
     --prometheus-port 9615 \
     --rpc-external \
     --rpc-port=9944 \
     --rpc-cors=all \
     --rpc-methods=safe \
     --rpc-max-connections=1000 \
     --sync=warp \
     --state-pruning=1000 \
     --blocks-pruning=1000 \
     -- \
     --base-path=/data \
     --chain=polkadot \
     --sync=warp \
     --state-pruning=256 \
     --blocks-pruning=256 \
     --rpc-port=0
   

   Note

   The parity/polkadot-parachain image works for system parachains and parachains built with standard Cumulus templates. For parachains with custom runtimes, check the parachain's documentation for their specific Docker image or binary.

   Refer to the Port Mappings and Node Configuration Parameters sections for details on the command's configurations.

1. Download the polkadot-parachain binary from the latest stable Polkadot SDK release:

   # Download the latest stable release (check releases page for current version)
   wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2603-1/polkadot-parachain
   
   # Make it executable and move to system path
   chmod +x polkadot-parachain
   sudo mv polkadot-parachain /usr/local/bin/
   
   # Verify installation
   polkadot-parachain --version
   

2. Download your parachain's chain specification as described in Obtain the Chain Specification.

3. Create user and directory structures:

   # Create a dedicated user
   sudo useradd -r -s /bin/bash polkadot
   
   # Create data directory
   sudo mkdir -p /var/lib/polkadot-hub-rpc
   
   # Copy the chain spec to the directory
   sudo cp chain-spec.json /var/lib/polkadot-hub-rpc/
   
   # Set permissions
   sudo chown -R polkadot:polkadot /var/lib/polkadot-hub-rpc
   

4. Create a systemd service file for the Polkadot SDK RPC node:

   sudo nano /etc/systemd/system/polkadot-hub-rpc.service
   

5. Open the new service file and add the configuration for either an archive (complete history) or pruned (recent state) node:

   ArchivePruned

   [Unit]
   Description=Polkadot Hub RPC Node
   After=network.target
   
   [Service]
   Type=simple
   User=polkadot
   Group=polkadot
   WorkingDirectory=/var/lib/polkadot-hub-rpc
   
   ExecStart=/usr/local/bin/polkadot-parachain \
     --name=PolkadotHubRPC \
     --chain=/var/lib/polkadot-hub-rpc/chain-spec.json \
     --base-path=/var/lib/polkadot-hub-rpc \
     --port=30333 \
     --rpc-port=9944 \
     --rpc-external \
     --rpc-cors=all \
     --rpc-methods=safe \
     --rpc-max-connections=1000 \
     --prometheus-port=9615 \
     --prometheus-external \
     --state-pruning=archive \
     --blocks-pruning=archive \
     -- \
     --chain=polkadot \
     --base-path=/var/lib/polkadot-hub-rpc \
     --port=30334 \
     --sync=warp \
     --state-pruning=256 \
     --blocks-pruning=256 \
     --rpc-port=0
   
   Restart=always
   RestartSec=10
   LimitNOFILE=65536
   
   [Install]
   WantedBy=multi-user.target
   

   [Unit]
   Description=Polkadot Hub RPC Node
   After=network.target
   
   [Service]
   Type=simple
   User=polkadot
   Group=polkadot
   WorkingDirectory=/var/lib/polkadot-hub-rpc
   
   ExecStart=/usr/local/bin/polkadot-parachain \
     --name=PolkadotHubRPC \
     --chain=/var/lib/polkadot-hub-rpc/chain-spec.json \
     --base-path=/var/lib/polkadot-hub-rpc \
     --port=30333 \
     --rpc-port=9944 \
     --rpc-external \
     --rpc-cors=all \
     --rpc-methods=safe \
     --rpc-max-connections=1000 \
     --prometheus-port=9615 \
     --prometheus-external \
     --sync=warp \
     --state-pruning=1000 \
     --blocks-pruning=1000 \
     -- \
     --chain=polkadot \
     --base-path=/var/lib/polkadot-hub-rpc \
     --port=30334 \
     --sync=warp \
     --state-pruning=256 \
     --blocks-pruning=256 \
     --rpc-port=0
   
   Restart=always
   RestartSec=10
   LimitNOFILE=65536
   
   [Install]
   WantedBy=multi-user.target
   

   Refer to the Port Mappings and Node Configuration Parameters sections for details on the command's configurations.

6. Start the service:

   # Reload systemd
   sudo systemctl daemon-reload
   
   # Enable service to start on boot
   sudo systemctl enable polkadot-hub-rpc
   
   # Start the Polkadot SDK node:
   sudo systemctl start polkadot-hub-rpc
   

Port Mappings

• 9944: Polkadot SDK RPC endpoint (WebSocket/HTTP)
• 9615: Prometheus metrics endpoint
• 30333/30334: P2P networking ports

Node Configuration Parameters

• --rpc-external: Listens for RPC connections on all network interfaces instead of only on localhost. Combine it with --rpc-methods=safe and, for production, a reverse proxy with rate limiting.
• --unsafe-rpc-external: Behaves like --rpc-external but skips the check that rejects external RPC access on validator nodes. An RPC node does not need it.
• --rpc-cors=all: Allows all origins for CORS.
• --rpc-methods=safe: Only allows safe RPC methods.
• --sync=warp: Downloads the latest finalized state with a finality proof instead of executing every block since genesis. When --blocks-pruning is set to a number, the node then backfills only the headers and justifications of older blocks. Warp sync only applies when the database is empty and cannot be combined with --state-pruning=archive or --state-pruning=archive-canonical.
• --state-pruning: archive keeps the state of all blocks, archive-canonical keeps the state of finalized blocks only, and [NUMBER] keeps the state of the last specified number of finalized blocks. Defaults to 256.
• --blocks-pruning: archive keeps all block bodies, archive-canonical keeps the bodies of finalized blocks only, and [NUMBER] keeps the bodies of the last specified number of finalized blocks. Defaults to archive-canonical, so set a number explicitly on pruned nodes. Block headers are always kept.
• --prometheus-external: Exposes metrics externally.
• --: Separates parachain flags from relay chain flags. Flags after -- configure the embedded Polkadot relay chain node.

Warning

The state pruning mode is stored in the database when the node first starts. Later runs fail if --state-pruning does not match the stored mode, except that [NUMBER] can change. To switch between a pruned node and an archive node, delete the database and sync again.

Monitor Node Synchronization

Monitor the node synchronization status:

curl -H "Content-Type: application/json" \
-d '{"id":1, "jsonrpc":"2.0", "method": "system_syncState", "params":[]}' \
http://localhost:9944

When synchronization is complete, currentBlock will be equal to highestBlock:

curl -H "Content-Type: application/json" \ -d '{"id":1, "jsonrpc":"2.0", "method": "system_syncState", "params":[]}' \ http://localhost:9944

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "startingBlock":0,
    "currentBlock":3394816,
    "highestBlock":3394816
  }
}
  

Tip

You can use the system_health command to verify your node is running properly.

curl -H "Content-Type: application/json" \
-d '{"id":1, "jsonrpc":"2.0", "method": "system_health", "params":[]}' \
http://localhost:9944

Commands for Managing Your Node

Use the following commands to manage your node:

Dockersystemd

• View node logs:

  docker logs -f polkadot-hub-rpc
  

• Stop container:

  docker stop polkadot-hub-rpc
  

• Start container:

  docker start polkadot-hub-rpc
  

• Remove container:

  docker rm polkadot-hub-rpc
  

• Check status:

  sudo systemctl status polkadot-hub-rpc
  

• View node logs:

  sudo journalctl -u polkadot-hub-rpc -f
  

• Stop service:

  sudo systemctl stop polkadot-hub-rpc
  

• Enable service:

  sudo systemctl enable polkadot-hub-rpc
  

• Start service:

  sudo systemctl start polkadot-hub-rpc
  

Ethereum RPC Compatibility

Note

Ethereum RPC compatibility is supported only on some chains, such as Polkadot Hub.

Ethereum RPC compatibility is provided through the eth-rpc adapter, which is part of pallet-revive. This adapter translates Ethereum JSON-RPC calls into Polkadot SDK-compatible requests, enabling integration with Ethereum tools like MetaMask, Hardhat, and Ethers.js.

Prerequisites

Before starting the Ethereum RPC adapter:

• Node synchronization: Let your Polkadot Hub node finish syncing before you start the adapter. On startup, the eth-rpc adapter reads pallet-revive configuration from the node's latest block and fails to start if that block predates pallet-revive, for example, early in the initial sync.
• Archive node recommended: For full Ethereum RPC compatibility, run an archive node (--state-pruning=archive). The eth-rpc adapter may fail to query historical state on pruned nodes.
• RPC accessibility: The Polkadot SDK-based RPC endpoint must be accessible (default: ws://127.0.0.1:9944).

Run the Ethereum RPC Adapter

You can run the Ethereum RPC adapter using Docker or as a systemd service.

Dockersystemd

Start the adapter using the official Parity eth-rpc Docker image:

docker run -d --name eth-rpc --restart unless-stopped \
  --network=host \
  -v /var/lib/eth-rpc:/data \
  parity/eth-rpc:stable2606-2 \
  --node-rpc-url=ws://127.0.0.1:9944 \
  --rpc-port=8545 \
  --base-path=/data \
  --rpc-external \
  --rpc-cors=all

Note

The -v flag maps the host directory /var/lib/eth-rpc to /data inside the container. The --base-path flag references this container path to persist the eth-rpc.db database across restarts.

Note

Check the Docker Hub tags page for newer releases. Tags follow the Polkadot SDK release naming, such as stable2606-2.

1. Build the eth-rpc binary from the Polkadot SDK source:

   git clone https://github.com/paritytech/polkadot-sdk.git
   cd polkadot-sdk
   cargo build -p pallet-revive-eth-rpc --bin eth-rpc --release
   
   # Move to system path
   sudo mv target/release/eth-rpc /usr/local/bin/
   

   Note

   Pre-built binaries may not be available for all platforms. Building from source ensures compatibility with your system.

2. Create a systemd service file:

   sudo nano /etc/systemd/system/eth-rpc.service
   

3. Add the following configuration:

   [Unit]
   Description=Ethereum RPC Adapter for Polkadot Hub
   After=network.target polkadot-hub-rpc.service
   
   [Service]
   Type=simple
   User=polkadot
   Group=polkadot
   
   ExecStart=/usr/local/bin/eth-rpc \
     --node-rpc-url=ws://127.0.0.1:9944 \
     --rpc-port=8545 \
     --base-path=/var/lib/eth-rpc \
     --rpc-external \
     --rpc-cors=all
   
   Restart=always
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
   

   Warning

   The --rpc-external flag exposes your RPC endpoint publicly. For production deployments, consider using a reverse proxy with authentication and rate limiting, or bind to a specific interface.

4. Start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable eth-rpc
   sudo systemctl start eth-rpc
   

Ethereum RPC Configuration

The adapter accepts the following key parameters:

Parameter	Description	Default
--node-rpc-url	Polkadot SDK-based node WebSocket URL	ws://127.0.0.1:9944
--rpc-port	Ethereum RPC server port	8545
--rpc-external	Listen for RPC connections on all network interfaces instead of only on localhost	Disabled
--rpc-cors	CORS allowed origins	None
--eth-pruning	Block storage strategy: archive for persistent on-disk DB with full historical sync, or <N> for in-memory DB keeping latest N blocks	archive
--base-path	Directory for persistent database storage (eth-rpc.db is created inside this directory)	OS default data directory
--dev	Use temporary on-disk directory, deleted on exit	Disabled

Warning

The --rpc-external flag exposes your RPC endpoint publicly. For production deployments, use a reverse proxy with proper authentication and rate limiting.

Migrating from previous CLI flags

As of PR #11153, the following flags have been removed and replaced:

Previous Flag	Replacement
--cache-size N	--eth-pruning=<N>
--database-url sqlite::memory:	--eth-pruning=<N>
--database-url /path/to/db	--base-path=/path/to/dir
--index-last-n-blocks N	--eth-pruning=archive
--earliest-receipt-block N	Removed — the adapter now auto-discovers the first EVM block

API Endpoints

Your node setup provides two distinct API interfaces:

Interface	Port	Protocol	Use Cases
Polkadot SDK RPC	9944	WebSocket/HTTP	Polkadot SDK-native applications, parachain-specific operations, governance
Ethereum RPC	8545	HTTP	EVM libraries, Ethereum tools, EVM-compatible dApps

Verify the Ethereum RPC Adapter

To verify the Ethereum RPC adapter is working correctly, you can test standard Ethereum JSON-RPC methods like eth_chainId, eth_blockNumber, and eth_getBlockByNumber. For a complete list of supported methods and example queries, see the JSON-RPC APIs reference.

Manage the Ethereum RPC Adapter

Dockersystemd

• View logs:

  docker logs -f eth-rpc
  

• Stop container:

  docker stop eth-rpc
  

• Start container:

  docker start eth-rpc
  

• Check status:

  sudo systemctl status eth-rpc
  

• View logs:

  sudo journalctl -u eth-rpc -f
  

• Stop service:

  sudo systemctl stop eth-rpc
  

Conclusion

Running a parachain RPC node provides critical infrastructure for accessing Polkadot network services. By following this guide, you have set up a production-ready RPC node that:

• Provides reliable access to parachain functionality for applications and users.
• Supports flexible deployment with both Docker and systemd options.
• Implements comprehensive monitoring, security, and maintenance practices.
• Can be adapted for any parachain by substituting the appropriate chain specification.
• Optionally enables Ethereum RPC compatibility for integration with EVM tools and wallets.

Whether you're running a node for system parachains (Asset Hub, People Chain, Bridge Hub, Coretime Chain) or other parachains in the ecosystem, regular maintenance and monitoring will ensure your RPC node continues to provide reliable service. Stay updated with the latest releases and best practices to keep your infrastructure secure and performant.

Last update: October 7, 2026
| Created: January 14, 2026