Skip to content

Running a validator node locally

Jump to bottom
Guilherme Dantas edited this page Nov 7, 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 service because of their block-range limit on eth_getLogs calls. Instead, we suggest either Infura's free-tier service or subscribing to Alchemy's pay-as-you-go pricing model, both of which have been proven more reliable. Self-hosting methods and other third-party providers are also available.

Docker setup (recommended)

Running the Cartesi Rollups PRT Node inside a container has several benefits:

  • 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 guide for setting up a container using Docker compose. It encompasses both x86-64 and arm64 architectures and verifies the checksum of artifacts distributed via GitHub releases. It currently only supports private-key wallets, although AWS KMS wallets are also supported by the prototype node. See AWS KMS 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 state
  1. Install the pre-built Cartesi Rollups PRT Node (code below) or build it from source (follow instructions on the README).
VERSION='v2.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 Mainnet deployment. For the Sepolia deployment, set the NETWORK variable to sepolia.
VERSION='v3.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://$NETWORK.infura.io/v3/$API_KEY"

Note: It's recommended to have a payed Infura API key for reliability and privacy, but you could try a public free RPC endpoint from ChainList for quick testing. Be aware that most public free RPC endpoints will have a block-range limit, although some might work.

  1. Define the application contract address, which you can find in the Deployments page. The following is the address of the Honeypot v3 app on Ethereum Sepolia.
export APP_ADDRESS='0xb72d7AfbE7afd35C82D1d0B3D9C714944ff5B7d8'
  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 positional argument pk.

export WEB3_PRIVATE_KEY='0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
./bin/cartesi-rollups-prt-node pk

Note: You could use any wallet to reconstruct the latest state of the application. However you will need a funded wallet in order to participate in disputes.

  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