Skip to content

Running a validator node locally

Jump to bottom
Guilherme Dantas edited this page Jun 17, 2025 · 21 revisions

Prerequisites

  • A Unix-based system (like Linux, macOS, or WSL)
  • A wallet with some Ether for submitting transactions (see Creating a wallet)
  • An Ethereum JSON-RPC provider (either self-hosted or third-party)

Important

We advise validators not to use Alchemy's free-tier account because of their block-range limit on eth_getLogs calls. Instead, we suggest either Infura's free-tier account or subscribing to Alchemy's pay-as-you-go model, both of which have been proven more reliable. Other third-party providers are also available.

Docker setup (recommended)

Running the Cartesi Rollups PRT Node inside a container is our recommended option for several reasons:

  • Isolation: Your host environment is protected against any unintended behavior
  • Control: You can adjust the amount of memory and disk space used by the node
  • Reproducibility: Your node is expected to behave similarly to other nodes validating Honeypot

Enderson Maia, a Cartesi core contributor, was kind enough to create a gist going through the process of setting up a container. It encompasses both x86-64 and arm64 architectures and verifies the checksum of every binary distributed through GitHub. It only supports private key wallets, but AWS KMS wallets can also be supported by defining the correct environment variables.

Local setup

  1. Create a directory to store the Cartesi Rollups PRT Node and its state.
mkdir -p cartesi-honeypot
cd cartesi-honeypot
mkdir -p bin machine snapshots state
  1. Install the pre-built Cartesi Rollups PRT Node (code below) or build it from source (follow instructions on the README).
VERSION='v1.0.0'
ARCH=$(uname -m | sed 's/^aarch64$/arm64/')
FILENAME="cartesi-rollups-prt-node-Linux-gnu-$ARCH.tar.gz"
DOWNLOAD_PREFIX='https://github.com/cartesi/dave/releases/download'
wget -qO- "$DOWNLOAD_PREFIX/$VERSION/$FILENAME" | tar -C bin -xz cartesi-rollups-prt-node
  1. Download the pre-built Honeypot machine snapshot (code below) or build it from source (follow instructions on the README). The code below downloads the pre-built snapshot used in the Sepolia deployment. For the Mainnet deployment, set the NETWORK variable to mainnet.
VERSION='v2.0.0'
NETWORK='sepolia'
FILENAME="honeypot-snapshot-$NETWORK.tar.gz"
DOWNLOAD_PREFIX='https://github.com/cartesi/honeypot/releases/download'
wget -qO- "$DOWNLOAD_PREFIX/$VERSION/$FILENAME" | tar -C machine -xz
  1. Define the Ethereum JSON-RPC URL to be used by the node to communicate with the blockchain.
export WEB3_RPC_URL="https://sepolia.infura.io/v3/$API_KEY"
  1. Define the application contract address, which you can find in the Deployments page.
export APP_ADDRESS='0xccEbaA7E541BcaA99dE39ca248f0aa6CD33f9e3E'
  1. Define the following environment variables.
export WEB3_CHAIN_ID=$(cast chain-id --rpc-url "$WEB3_RPC_URL")
export MACHINE_PATH=$(pwd)/machine
export STATE_DIR=$(pwd)/state

  1. Now, let's define how the node is going to sign transactions to the blockchain. The node currently supports two options: private keys and AWS Key Management Service (KMS) wallets.

  2. For private-key wallets, you can provide it through an environment variable. Then, run the node executable with the argument pk.

export WEB3_PRIVATE_KEY='0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
./bin/cartesi-rollups-prt-node pk
  1. For AWS KMS wallets, you can define the following environment variables and provide the positional argument awk-kms to the node executable.
export AWS_KMS_KEY_ID=
export AWS_KMS_KEY_ID_FILE=
export AWS_ENDPOINT_URL=
export AWS_REGION=
./bin/cartesi-rollups-prt-node aws-kms

Clone this wiki locally