Set the P2P Address and x25519 Key

How validator operators publish their x25519 public key and P2P address in the stake table, for Mainnet and Decaf.

Validators connect over an authenticated, encrypted mesh. Each validator publishes two values in the stake table:

• x25519 public key: used to encrypt connections between validators.

• P2P address (host:port): the address other validators dial to reach this node.

Requirements for the P2P address:

• Use the node's public IP address or DNS name, not a private or loopback address.

• It must be reachable over TCP from the public internet and route to the node's P2P bind port (ESPRESSO_NODE_CLIQUENET_BIND_ADDRESS, default 9977). Behind NAT, a firewall, or a load balancer, register the public address and forward that port to the node.

• If an IP address is registered, the node's outgoing connections must also originate from that same IP address. The registered address is not only a listen address: peers check the source IP of every incoming connection against it.

Registering an IP address while the node's outbound traffic leaves through a different IP breaks connectivity in one direction. This happens when ingress and egress use separate paths, for example an inbound load balancer or proxy with a separate NAT gateway for egress, or a pool of egress IPs. Peers reject those connections and log party has invalid ip addr.

Register a DNS name instead when the egress IP differs from the ingress IP or is not stable. Registering a DNS name disables the source IP check, so any source IP is accepted for the node.

1. Obtain the x25519 key

The x25519 key belongs to the node's key set, alongside the BLS and state keys. There are two options, depending on how the node's keys are configured:

• Option 1: the node is configured with a node key mnemonic (ESPRESSO_NODE_KEY_MNEMONIC).

• Option 2: the node is configured with explicit private keys, or with a key file that has no x25519 key. This applies to most validators registered before the V3 stake table.

Option 1: node configured with a node key mnemonic

The x25519 key is derived deterministically from the mnemonic, so no node change is needed. Print the public key using the same mnemonic (and --index if the node sets one):

docker run -e ESPRESSO_NODE_KEY_MNEMONIC ghcr.io/espressosystems/espresso-network/espresso-node:main \
    pub-key --scheme x25519 --index $KEY_INDEX

Option 2: node configured with explicit private keys or a key file without an x25519 key

Generate a keypair, add the private key to the node config, and restart.

docker run ghcr.io/espressosystems/espresso-network/espresso-node:main keygen --scheme x25519

Output:

ESPRESSO_NODE_PUBLIC_X25519_KEY=X25519_PK~...
ESPRESSO_NODE_PRIVATE_X25519_KEY=X25519_SK~...

Where the generated private key goes depends on how the node's other keys are configured. Again there are two options:

• Option 2a: the node uses a key file (ESPRESSO_NODE_KEY_FILE / ESPRESSO_SEQUENCER_KEY_FILE). Add the ESPRESSO_NODE_PRIVATE_X25519_KEY=... line to the key file itself.

• Option 2b: the node uses explicit private key env vars (ESPRESSO_NODE_PRIVATE_STAKING_KEY / ESPRESSO_SEQUENCER_PRIVATE_STAKING_KEY and ESPRESSO_NODE_PRIVATE_STATE_KEY / ESPRESSO_SEQUENCER_PRIVATE_STATE_KEY, no key file). Set ESPRESSO_NODE_PRIVATE_X25519_KEY as an env var alongside them.

Restart the node after setting the key. Without a persistent x25519 key the node uses a random ephemeral key on each start, which will not match the registered public key.

2. Register the public key and P2P address

docker run -e MNEMONIC -e ACCOUNT_INDEX -e L1_PROVIDER -e STAKE_TABLE_ADDRESS \
    ghcr.io/espressosystems/espresso-network/staking-cli:main \
    staking-cli update-network-config \
        --x25519-key $ESPRESSO_NODE_PUBLIC_X25519_KEY \
        --p2p-addr $PUBLIC_HOST:9977

Network-specific values:

Network	L1_PROVIDER	STAKE_TABLE_ADDRESS
Mainnet	An Ethereum endpoint	0xCeF474D372B5b09dEfe2aF187bf17338Dc704451
Decaf	An Ethereum Sepolia endpoint	0x40304fbe94d5e7d1492dd90c53a2d63e8506a037

Sign with the same Ethereum wallet that registered the validator. That wallet is separate from the node key mnemonic in step 1. The example above uses a mnemonic (MNEMONIC + ACCOUNT_INDEX); the staking-cli also accepts a raw private key (PRIVATE_KEY) or a Ledger device (--ledger, with --account-index), see Choose your type of wallet in the staking-cli README. This is a single invocation; the same command also rotates both values later if needed.

New validators do not need this step: register-validator takes --x25519-key and --p2p-addr directly and requires both. This step is for validators registered before the V3 stake table, which have neither value set.

For the full command reference, including rotating one value at a time with update-x25519-key and update-p2p-addr, see Configuring networking (x25519 key and p2p address) in the staking-cli README.

3. Check the node configuration

The registered values only take effect if the node itself is configured to match. Before restarting, confirm in the node's environment that:

• ESPRESSO_NODE_PRIVATE_X25519_KEY is set (as an env var or in the key file) and matches the registered public key.

• ESPRESSO_NODE_CLIQUENET_BIND_ADDRESS (default 9977) uses the same port as the registered P2P address, and that port is reachable over TCP from the public internet.

For the full environment of the network's node, see Running a Mainnet Node or Running a Decaf Node.

Related references

• Running a Mainnet Node

• Running a Decaf Node

• Networks & Contracts