XRPL EVM

Setup your XRPL EVM Mainnet or Testnet node.

Prerequisites

• MacOS or Ubuntu 18.04+
• Build-essential packages
• Golang 1.17+
• Official Documentation

Install

To get started with the node setup.

1. Install the latest binary from the official XRPL EVM node repo
2. Move the binary to your preferred directory
3. Make the binary executable

chmod +x exrpd

4. Confirm if exrpd successfully installed by running version command

 exrpd version

Node Configuration

1. Create the .exrpd directory in your user’s home directory:

mkdir -p ~/.exrpd

Inside it, you will eventually see two subfolders. The first is ~/.exrpd/config. The second is ~/.exrpd/data.

2. Set the chain id

exrpd config set client chain-id exrp_1440002-1

exrpd config set client chain-id xrplevm_1449000-1

exrpd config set client chain-id xrplevm_1440000-1

3. Initialize the node Make sure to replace <your_moniker> with a short ASCII-only name for your node (e.g., my-node).

exrpd init <your_moniker> --chain-id exrp_1440002-1

exrpd init <your_moniker> --chain-id xrplevm_1449000-1

exrpd init <your_moniker> --chain-id xrplevm_1440000-1

This step populates the aforementioned ~/.exrpd directory with the config and data directories.

Download genesis file

wget https://raw.githubusercontent.com/Peersyst/xrp-evm-archive/main/poa-devnet/genesis.json -O ~/.exrpd/config/genesis.json

 wget https://raw.githubusercontent.com/xrplevm/networks/main/testnet/genesis.json \ -O ~/.exrpd/config/genesis.json

wget https://raw.githubusercontent.com/xrplevm/networks/main/mainnet/genesis.json \ -O ~/.exrpd/config/genesis.json

Download Snapshot

You can download Peersyst's snapshot.

This may take a few hours to complete and will require about ~142gb of storage. Once completed, extract the file into your ~/.exrpd/data folder.

Add Peers

You need peers so that your node can sync with the devnet. The XRPL EVM Devnet provides a text file listing known peers:

Grab 10

PEERS=$(curl -sL https://raw.githubusercontent.com/Peersyst/xrp-evm-archive/main/poa-devnet/peers.txt \
  | sort -R \
  | head -n 10 \
  | awk '{print $1}' \
  | paste -s -d, -)

Inject the peers into your config.toml file (persistent_peers):

sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PEERS\"/" \
  ~/.exrpd/config/config.toml

Ethereum JSON RPC Compatibility

The XRP EVM node is a CometBFT Node. The ampd daemon however will be attempting to interact with your node as an Ethereum JSON RPC compatible node. To configure your CometBFT Node to support Ethereum JSON RPC functionality you need to update your app.toml file. In the JSON RPC section of the app.toml update the enable flag to true.

###############################################################################
###                           JSON RPC Configuration                        ###
###############################################################################

[json-rpc]

# Enable defines if the JSONRPC server should be enabled.
enable = true

Run Node

At this point your ~/.exrpd file should have a config and data file. The config should be wired up with various configurations including the

1. addrbook.json
2. app.toml
3. client.toml
4. config.toml
5. config.toml.bak
6. genesis.json
7. node_key.json
8. priv_validator_key.json

The data directory should contain the data that you extraced from the snpashot you installed before.

Run the following command to start the node

exrpd start

You should see logs similar to

INF starting ABCI with CometBFT module=server
...
INF finalized block block_app_hash=... height=13242560 ...

Common Observations in Logs

1. “ERR failed to add block ... got an already committed block #XXXX”. This just means your node already processed the block from a faster peer.
2. Periodic connect/disconnect messages (e.g., SendTimeout, error with peer ...) This is normal. Tendermint/CometBFT will drop slow or unresponsive peers and reconnect if needed.
3. “catching_up”: true This means your node thinks there are more blocks to fetch. If the Devnet is actively producing blocks, this will remain true until you fully sync. If the network is paused or slow, it may stay true indefinitely, but you’ll still be at the latest block.

Common Issues

1. No peers

• Make sure you updated persistent_peers.
• If you see repeated “No addresses to dial,” your node has zero connections. Re-run the peer script or check the docs for seed nodes.

2. Genesis or config file errors

• Ensure the chain ID and all fields (like initial_height) are in the correct format (typically string in Cosmos).
• Re-download the official genesis.json if in doubt.

3. Port collisions

• If something else is using 26657, you may need to open ~/.exrpd/config/config.toml and change your RPC ports.

4. Minimum gas price error

• If you receive an error that says Error: set min gas price in app.toml or flag or env variable: error in app.toml. Set the minimum-gas-prices field in app.toml to a value for example 0.25axrp

Configure ampd

This assumes you have set up ampd as per Become an Amplifier verifier.

Add the chain to your ampd config (~/.ampd/config.toml):

[[grpc.blockchain_service.chains]]
chain_name="xrpl-evm"
voting_verifier="axelar1q8kn9t39ddpce42atk0d6wpdudr6djqxmz689m3nxy92ck0nnftqxfsuyk"
multisig_prover="axelar198xehj5htckk75s8wcamxerxtdc45669zdqjmr69guveqntj9f6s5rqq55"
multisig="axelar14a4ar5jh7ue4wg28jwsspf23r8k68j7g5d6d3fsttrhp42ajn4xq6zayy5"

[[grpc.blockchain_service.chains]]
chain_name="xrpl-evm"
voting_verifier="axelar1q8kn9t39ddpce42atk0d6wpdudr6djqxmz689m3nxy92ck0nnftqxfsuyk"
multisig_prover="axelar198xehj5htckk75s8wcamxerxtdc45669zdqjmr69guveqntj9f6s5rqq55"
multisig="axelar14a4ar5jh7ue4wg28jwsspf23r8k68j7g5d6d3fsttrhp42ajn4xq6zayy5"

Create a config directory for the evm-handler, pointing it at your node:

ampd_url = "http://127.0.0.1:9090"
chain_name = "xrpl-evm"

rpc_url = "<your node's RPC URL>"
finalization = "RPCFinalizedBlock"

Start the handler:

evm-handler --config-dir ~/.ampd/xrpl-evm/

See Set up handlers for running handlers with Docker or as services.

Register chain support

Once the handler is running, register your verifier's support for the chain:

ampd register-chain-support amplifier xrpl-evm