Local Development Node

Introduction

A local development node provides an isolated blockchain environment where you can deploy, test, and debug smart contracts without incurring network fees or waiting for block confirmations. This guide demonstrates how to set up a local Polkadot SDK-based node with smart contract capabilities.

By the end of this guide, you'll have:

• A running Substrate node with smart contract support
• An ETH-RPC adapter for Ethereum-compatible tooling integration accessible at http://localhost:8545

Prerequisites

Before getting started, ensure you have done the following:

• Completed the Install Polkadot SDK Dependencies guide and successfully installed Rust and the required packages to set up your development environment

Install the Substrate Node and ETH-RPC Adapter

The Polkadot SDK repository contains both the Substrate node implementation and the ETH-RPC adapter required for Ethereum compatibility. Start by cloning the repository and navigating to the project directory:

git clone https://github.com/paritytech/polkadot-sdk.git
cd polkadot-sdk

Next, you need to compile the two essential components for your development environment. The Substrate node provides the core blockchain runtime with smart contract support, while the ETH-RPC adapter enables Ethereum JSON-RPC compatibility for existing tooling:

cargo build --bin substrate-node --release
cargo build -p pallet-revive-eth-rpc --bin eth-rpc --release

The compilation process may take some time depending on your system specifications, potentially up to 30 minutes. Release builds are optimized for performance but take longer to compile than debug builds. After successful compilation, you can verify the binaries are available in the target/release directory:

• Substrate node path - polkadot-sdk/target/release/substrate-node
• ETH-RPC adapter path - polkadot-sdk/target/release/eth-rpc

Run the Local Node

With the binaries compiled, you can now start your local development environment. The setup requires running two processes.

Start the Substrate node first, which will initialize a local blockchain with the dev chain specification. This configuration includes pallet-revive for smart contract functionality and uses pre-funded development accounts for testing:

./target/release/substrate-node --dev

The node will begin producing blocks immediately and display initialization logs:

./target/release/substrate-node --dev
2025-05-29 10:42:35 Substrate Node 2025-05-29 10:42:35 ✌️ version 3.0.0-dev-38b7581fc04 2025-05-29 10:42:35 ❤️ by Parity Technologies <admin@parity.io>, 2017-2025 2025-05-29 10:42:35 📋 Chain specification: Development 2025-05-29 10:42:35 🏷 Node name: annoyed-aunt-3163 2025-05-29 10:42:35 👤 Role: AUTHORITY 2025-05-29 10:42:35 💾 Database: RocksDb at /var/folders/x0/xl_kjddj3ql3bx7752yr09hc0000gn/T/substrate2P85EF/chains/dev/db/full 2025-05-29 10:42:40 🔨 Initializing Genesis block/state (state: 0xfc05…482e, header-hash: 0x1ae1…b8b4) 2025-05-29 10:42:40 Creating transaction pool txpool_type=SingleState ready=Limit { count: 8192, total_bytes: 20971520 } future=Limit { count: 819, total_bytes: 2097152 } 2025-05-29 10:42:40 👴 Loading GRANDPA authority set from genesis on what appears to be first startup. 2025-05-29 10:42:40 👶 Creating empty BABE epoch changes on what appears to be first startup. 2025-05-29 10:42:40 Using default protocol ID "sup" because none is configured in the chain specs 2025-05-29 10:42:40 🏷 Local node identity is: 12D3KooWAH8fgJv3hce7Yv4yKG4YXQiRqESFu6755DBnfZQU8Znm 2025-05-29 10:42:40 Running libp2p network backend 2025-05-29 10:42:40 local_peer_id=12D3KooWAH8fgJv3hce7Yv4yKG4YXQiRqESFu6755DBnfZQU8Znm 2025-05-29 10:42:40 💻 Operating system: macos 2025-05-29 10:42:40 💻 CPU architecture: aarch64 2025-05-29 10:42:40 📦 Highest known block at #0 2025-05-29 10:42:40 Error binding to '127.0.0.1:9615': Os { code: 48, kind: AddrInUse, message: "Address already in use" } 2025-05-29 10:42:40 Running JSON-RPC server: addr=127.0.0.1:63333,[::1]:63334 2025-05-29 10:42:40 🏁 CPU single core score: 1.24 GiBs, parallelism score: 1.08 GiBs with expected cores: 8 2025-05-29 10:42:40 🏁 Memory score: 49.42 GiBs 2025-05-29 10:42:40 🏁 Disk score (seq. writes): 1.91 GiBs 2025-05-29 10:42:40 🏁 Disk score (rand. writes): 529.02 MiBs 2025-05-29 10:42:40 👶 Starting BABE Authorship worker 2025-05-29 10:42:40 🥩 BEEFY gadget waiting for BEEFY pallet to become available... 2025-05-29 10:42:40 Failed to trigger bootstrap: No known peers. 2025-05-29 10:42:42 🙌 Starting consensus session on top of parent 0x1ae19030b13592b5e6fd326f26efc7b31a4f588303d348ef89ae9ebca613b8b4 (#0) 2025-05-29 10:42:42 🎁 Prepared block for proposing at 1 (5 ms) hash: 0xe046f22307fba58a3bd0cc21b1a057843d4342da8876fd44aba206f124528df0; parent_hash: 0x1ae1…b8b4; end: NoMoreTransactions; extrinsics_count: 2 2025-05-29 10:42:42 🔖 Pre-sealed block for proposal at 1. Hash now 0xa88d36087e7bf8ee59c1b17e0003092accf131ff8353a620410d7283657ce36a, previously 0xe046f22307fba58a3bd0cc21b1a057843d4342da8876fd44aba206f124528df0. 2025-05-29 10:42:42 👶 New epoch 0 launching at block 0xa88d…e36a (block slot 582842054 >= start slot 582842054). 2025-05-29 10:42:42 👶 Next epoch starts at slot 582842254 2025-05-29 10:42:42 🏆 Imported #1 (0x1ae1…b8b4 → 0xa88d…e36a)

For debugging purposes or to monitor low-level operations, you can enable detailed logging by setting environment variables before running the command:

RUST_LOG="error,evm=debug,sc_rpc_server=info,runtime::revive=debug" ./target/release/substrate-node --dev

Once the Substrate node is running, open a new terminal window and start the ETH-RPC adapter. This component translates Ethereum JSON-RPC calls into Substrate-compatible requests, allowing you to use familiar Ethereum tools like MetaMask, Hardhat, or Ethers.js:

./target/release/eth-rpc --dev

You should see logs indicating that the adapter is ready to accept connections:

./target/release/eth-rpc --dev
2025-05-29 10:48:48 Running in --dev mode, RPC CORS has been disabled. 2025-05-29 10:48:48 Running in --dev mode, RPC CORS has been disabled. 2025-05-29 10:48:48 🌐 Connecting to node at: ws://127.0.0.1:9944 ... 2025-05-29 10:48:48 🌟 Connected to node at: ws://127.0.0.1:9944 2025-05-29 10:48:48 💾 Using in-memory database, keeping only 256 blocks in memory 2025-05-29 10:48:48 〽️ Prometheus exporter started at 127.0.0.1:9616 2025-05-29 10:48:48 Running JSON-RPC server: addr=127.0.0.1:8545,[::1]:8545 2025-05-29 10:48:48 🔌 Subscribing to new blocks (BestBlocks) 2025-05-29 10:48:48 🔌 Subscribing to new blocks (FinalizedBlocks)

Similar to the Substrate node, you can enable detailed logging for the ETH-RPC adapter to troubleshoot issues:

RUST_LOG="info,eth-rpc=debug" ./target/release/eth-rpc --dev

Your local development environment is now active and accessible at http://localhost:8545. This endpoint accepts standard Ethereum JSON-RPC requests, enabling seamless integration with existing Ethereum development tools and workflows.

You can connect wallets, deploy contracts using Remix or Hardhat, and interact with your smart contracts as you would on any Ethereum-compatible network.

Last update: May 29, 2025
| Created: May 29, 2025