Skip to main content

Immutable Geth

View the node software source code
 Immutable Chain supports two types of nodes for connecting to the network:
TypeDescriptionAccess
PublicFor partners wanting to run a node in the networkPermissionless
PrivateFor critical infrastructure partners with direct Immutable relationshipRequires allowlisting

​
Public Nodes

Public nodes do not participate in txpool gossiping—they forward all transactions directly to the Immutable RPC endpoint. This manages gossiping load while processing all transactions normally.

​
Requirements

  • Hardware: 2 AWS vCPU, 4GB RAM, 100GB free storage
  • OS: Ubuntu 22.04.1 (tested)
  • Software: Docker

​
Setup Instructions

1. Create data directory 
mkdir /opt/immutable-zkevm
2. Pull the Docker image 
docker pull ghcr.io/immutable/immutable-geth/immutable-geth:latest
docker tag ghcr.io/immutable/immutable-geth/immutable-geth:latest geth
3. Initialize the node 
docker run \
  --rm \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  geth immutable bootstrap rpc \
  --zkevm testnet \
  --datadir /mnt/geth
4. Start the node as a service 
docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm testnet \
  --config /etc/geth/testnet-public.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0" \
  --gossipdefault \
  --disabletxpoolgossip \
  --rpcproxy

​
Verify Deployment

Check logs 
docker logs geth
You should see output indicating the node is syncing: 
INFO [12-04|04:54:26.754] Chain ID:  13473 (unknown)
INFO [12-04|04:54:26.754] Consensus: Clique (proof-of-authority)
INFO [12-04|04:54:36.978] Block synchronisation started
INFO [12-04|04:54:37.205] Imported new chain segment number=1,343,079
Verify chain ID 
curl http://localhost:8545 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_chainId","params":[],"id":1,"jsonrpc":"2.0"}'
Expected responses:
  • Testnet: {"jsonrpc":"2.0","id":1,"result":"0x34a1"} (13473)
  • Mainnet: {"jsonrpc":"2.0","id":1,"result":"0x343b"} (13371)

​
Private Nodes

Private nodes are for partners providing critical infrastructure with a direct relationship with Immutable. They require allowlisting via WireGuard or static IP.
Most node operators should use the permissionless public node setup. Contact your Immutable representative if you need private node access.

​
Access Methods

WireGuard: Generate keys and provide your public key to Immutable: 
sudo apt-get install wireguard
umask 077
wg genkey > wg-privatekey
wg pubkey < wg-privatekey > wg-publickey
After receiving your WireGuard config, update PrivateKey and start: 
# Save config to /etc/wireguard/wg0.conf
wg-quick up wg0
Static IP: Provide your static IP to your Immutable contact for allowlisting.

​
Private Node Startup

Running private nodes is the same as the process for public nodes described above, with the exception of step 4, “Start the node as a service”: 
docker run \
  -d \
  --restart=always \
  -v /opt/immutable-zkevm:/mnt/geth \
  --name geth \
  -p 8545:8545 \
  geth \
  --zkevm testnet \
  --config /etc/geth/testnet.toml \
  --datadir /mnt/geth \
  --http \
  --http.port "8545" \
  --http.addr "0.0.0.0"