Run a Local Node on opBNB

Setting up your own local node on opBNB is a powerful step for developers building decentralized applications (dApps), validators, or infrastructure providers who need reliable, low-latency access to blockchain data. While public RPC endpoints are available, running a private node enhances performance, security, and control over your development environment.

This comprehensive guide walks you through the process of deploying a local opBNB node—whether for Testnet or Mainnet—using Docker, binaries, or snapshots. We’ll cover hardware requirements, setup procedures, synchronization checks, and troubleshooting tips to ensure a smooth deployment.

Why Run Your Own opBNB Node?

Running your own node gives you:

• Full control over RPC availability and request limits
• Improved reliability compared to shared public endpoints
• Enhanced privacy by eliminating third-party data exposure
• Support for advanced operations like debugging, tracing, and custom indexing

Whether you're testing smart contracts or preparing for mainnet deployment, a self-hosted node is essential for serious blockchain development.

👉 Get started with reliable blockchain infrastructure today.

Hardware Requirements

To run an opBNB node efficiently, your system must meet minimum hardware specifications:

• RAM: At least 16 GB (32 GB recommended for archive/full nodes)
• Storage: 500+ GB SSD (preferably NVMe; space grows over time in archive mode)
• CPU: Multi-core processor (4+ cores)
• Network: Stable broadband connection with high upload/download throughput

💡 For production environments, use dedicated servers or cloud instances optimized for I/O performance.

Fast Node Option

For developers who don’t require full historical state data or debugging capabilities, opBNB supports a fast node configuration that significantly reduces sync time and resource usage.

Key Features of Fast Nodes:

• Uses snapshots instead of full Merkle Patricia Trie (MPT) state calculations
• Lower disk and memory footprint
• Faster initial synchronization
• Sufficient for most dApp use cases

To enable fast mode, start op-geth with the --allow-insecure-no-tries flag and set --gcmode=full (not archive). Note that this sacrifices some security guarantees but improves efficiency.

Deployment Methods

You can deploy an opBNB node using one of three methods: Docker, pre-built binaries, or snapshots. Each has its advantages depending on your technical expertise and operational needs.

Run with Docker

Docker simplifies deployment by containerizing all components. Official images are hosted on GitHub Container Registry:

• op-node
• op-geth

A ready-to-use docker-compose.yml example is available in the opbnb-node-docker repository. This allows you to spin up both op-node and op-geth services with a single command:

git clone https://github.com/bnb-chain/opbnb-node-docker
cd opbnb-node-docker
# Modify configuration as needed (e.g., network selection)
docker-compose up -d

This method is ideal for quick testnet setups or CI/CD pipelines.

👉 Accelerate your node deployment with optimized tools.

Run with Binaries

For greater control and customization, compile and run op-node and op-geth from source.

Prerequisites

Ensure these tools are installed:

• Go 1.20+
• Make
• Git
• GCC
• libc-dev

Build Instructions

export OPBNB_WORKSPACE=/tmp/opbnb
mkdir -p $OPBNB_WORKSPACE
cd $OPBNB_WORKSPACE

# Clone and build op-node
git clone https://github.com/bnb-chain/opbnb.git
cd opbnb/op-node
git checkout develop
make op-node
mkdir -p $OPBNB_WORKSPACE/op-node-data
cp ./bin/op-node $OPBNB_WORKSPACE/op-node-data

# Clone and build op-geth
cd $OPBNB_WORKSPACE
git clone https://github.com/bnb-chain/op-geth.git
cd op-geth
git checkout develop
make geth
mkdir -p $OPBNB_WORKSPACE/op-geth-data
cp ./build/bin/geth $OPBNB_WORKSPACE/op-geth-data/op-geth

Prepare Configuration Files

cd $OPBNB_WORKSPACE

# Select network: testnet or mainnet
cp $OPBNB_WORKSPACE/opbnb/assets/testnet/genesis.json $OPBNB_WORKSPACE/op-geth-data

# Generate JWT secret for authentication
openssl rand -hex 32 > jwt.txt
cp jwt.txt $OPBNB_WORKSPACE/op-geth-data
cp jwt.txt $OPBNB_WORKSPACE/op-node-data

# Initialize genesis block
cd $OPBNB_WORKSPACE/op-geth-data
mkdir datadir
./op-geth --datadir ./datadir init genesis.json

Start op-geth

Configure environment variables based on your network:

export CHAIN_ID=5611  # Testnet
export L2_RPC=https://opbnb-testnet-rpc.bnbchain.org
export P2P_BOOTNODES="enr:-KO4QKFOBDW--pF4pFwv3Al_jiLOITj_Y5mr1Ajyy2yxHpFtNcBfkZEkvWUxAKXQjWALZEFxYHooU88JClyzA00e8YeGAYtBOOZig2V0aMfGhE0ZYGqAgmlkgnY0gmlwhDREiqaJc2VjcDI1NmsxoQM8pC_6wwTr5N2Q-yXQ1KGKsgz9i9EPLk8Ata65pUyYG4RzbmFwwIN0Y3CCdl-DdWRwgnZf,..."

Launch the node:

./op-geth \
  --datadir="./datadir" \
  --http \
  --http.addr=0.0.0.0 \
  --http.port=8545 \
  --http.api=net,eth,engine \
  --ws \
  --ws.addr=0.0.0.0 \
  --ws.port=8545 \
  --ws.api=eth,engine \
  --syncmode=full \
  --networkid=$CHAIN_ID \
  --authrpc.addr="0.0.0.0" \
  --authrpc.port="8551" \
  --authrpc.jwtsecret=./jwt.txt \
  --gcmode=archive \
  --rollup.sequencerhttp=$L2_RPC \
  --bootnodes=$P2P_BOOTNODES

✅ Enable --state.scheme path and --db.engine pebble for better performance and reduced disk usage.

Start op-node

cd $OPBNB_WORKSPACE/op-node-data
export L2_RPC=http://localhost:8551
export P2P_PRIV_KEY=$(openssl rand -hex 32)  # Replace with your key
export L1_RPC=https://bsc-testnet.bnbchain.org

./op-node \
  --l1.trustrpc \
  --l1=${L1_RPC} \
  --l2=${L2_RPC} \
  --l2.jwt-secret=./jwt.txt \
  --rpc.addr=0.0.0.0 \
  --rpc.port=8546 \
  --metrics.enabled \
  --log.level=debug \
  --network=opBNBTestnet  # Use opBNBMainnet for mainnet

Run with Snapshots

To drastically reduce synchronization time—from days to minutes—use pre-synced snapshots provided in the opbnb-snapshot repository.

These snapshots include fully synced chain states at recent block heights. Download the latest archive, extract it into your datadir, and restart your node.

This method is ideal for:

• Rapid recovery after downtime
• Avoiding long initial syncs
• Reducing server load during peak development cycles

Verify Node Synchronization Status

Monitor logs for real-time sync progress:

INFO [11-15|10:10:05.569] Syncing beacon headers downloaded=1,762,304 left=11,403,991 eta=27m1.039s
INFO [11-15|10:10:06.440] Forkchoice requested sync to new head number=13,164,499 hash=d78cb3..a2e94d finalized=unknown

Check current block height locally:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

Compare with public RPC:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  https://opbnb-testnet-rpc.bnbchain.org

When both values align, your node is fully synchronized.

Frequently Asked Questions (FAQ)

Q: Can I run an opBNB node on a VPS?
A: Yes, popular cloud providers like AWS, Google Cloud, and DigitalOcean offer suitable configurations. Ensure sufficient SSD storage and RAM.

Q: What’s the difference between fast mode and full node mode?
A: Fast nodes skip MPT state reconstruction using snapshots, resulting in faster sync but limited historical query capability.

Q: How do I secure my node?
A: Use firewalls to restrict access to RPC ports (8545/8546), rotate JWT secrets regularly, and avoid exposing admin APIs publicly.

Q: Why does my node get stuck during sync?
A: High disk I/O due to database compaction is common. Upgrade hardware or consider snapshot-based recovery.

Q: Is pruning safe?
A: Pruning reduces disk usage but removes pre-prune state data. Only perform if you understand the risks and have backups.

Q: How often should I update my node software?
A: Regularly check for updates on GitHub. Running outdated versions may lead to chain forks or compatibility issues.

Troubleshooting Common Issues

Node Not Syncing

Ensure connectivity to both op-node and op-geth P2P networks:

# Check op-node peers
curl -X POST http://localhost:8546 -d '{"method":"opp2p_peers","params":[true],"id":1,"jsonrpc":"2.0"}'

# Check op-geth peers (admin API required)
curl -X POST http://localhost:8545 -d '{"method":"admin_peers","params":[],"id":1,"jsonrpc":"2.0"}' | jq .

Chain Fork Detected

If your block hash doesn’t match public nodes:

• Confirm you're running the latest code version (op-node -v, op-geth version)
• Use --network=opBNBTestnet instead of custom rollup.json
• Reinitialize with clean data if necessary

Database Compaction Slows Performance

Archive mode increases disk pressure. Solutions:

• Upgrade hardware (faster CPU/disk)
• Use PBSS + PebbleDB for better efficiency
• Switch to snapshot-based node or prune offline

⚠️ Always back up critical data before maintenance operations.

Final Thoughts

Running a local opBNB node empowers developers with direct blockchain access, enabling faster iteration and robust application testing. Whether using Docker for simplicity or compiling from source for control, the ecosystem provides flexible options tailored to various needs.

By following best practices in configuration, monitoring, and maintenance, you can maintain a reliable and high-performance node setup ready for any stage of development.

👉 Optimize your blockchain workflow with advanced tools and resources.