Relayer Infrastructure

The Ghost Protocol relies on relayer services to maintain the commitment tree and update Merkle roots on-chain.

Services Overview

Service	Purpose
Root Updater	Updates Merkle roots on-chain after new commitments
Commitment Relayer	Listens for commits, maintains off-chain tree
Faucet	Distributes testnet GHOST

How Root Updates Work

┌──────────────────────────────────────────────────────────────────┐
│  1. User calls commit() on GhostVault                            │
│     └──► CommitmentAdded event emitted                           │
│                                                                  │
│  2. Commitment Relayer detects event                             │
│     └──► Updates off-chain Merkle tree                           │
│                                                                  │
│  3. Root Updater periodically checks                             │
│     └──► Calls updateRoot() on CommitmentTree contract           │
│                                                                  │
│  4. New root becomes valid for proofs                            │
│     └──► User can now generate proof with this root              │
└──────────────────────────────────────────────────────────────────┘

Trust Model

Important

The relayer is trusted for liveness, not correctness.

• If the relayer goes down: Root updates pause. Users cannot reveal until it returns.
• If the relayer submits wrong roots: Proof verification will fail. Your funds cannot be stolen.

The relayer cannot:

• Steal committed funds
• Generate valid proofs for commitments it doesn't own
• Change your commitment's dataHash

The relayer can only:

• Delay root updates (denial of service)
• Update roots (which must be mathematically valid)

Root Staleness

Roots are valid for the last 100 updates. If your root is older:

InvalidRoot revert

Solution: Generate a new proof with a recent root.

Infrastructure Services

Avalanche Validator

Service	Type	Purpose
avalanchego.service	systemd	Avalanche L1 validator node
caddy.service	systemd	Reverse proxy for RPC endpoints

Relayer Server

Service	Type	Purpose
ghost-root-updater.service	systemd	Updates Merkle roots on-chain
ghost-commitment-relayer.service	systemd	Listens for commits, updates tree
faucet-relayer	PM2	Testnet GHOST distribution

Faucet API

• Endpoint: https://portal.ghostcoin.com/faucet (proxied via Vercel)
• Rate limit: 1 request per address per 24 hours
• Amount: 100 GHOST per request

Checking Relayer Status

You can verify the relayer is functioning by checking:

# Check commitment count (should increase after commits)
cast call 0xe382a7C7a5CE3B9250D73aE6ab97931E5798e6F7 "leafCount()(uint256)" \
  --rpc-url https://testnet-rpc.umbraline.com

# Check current root (should update after new commitments)
cast call 0xe382a7C7a5CE3B9250D73aE6ab97931E5798e6F7 "currentRoot()(bytes32)" \
  --rpc-url https://testnet-rpc.umbraline.com

If leafCount increases but currentRoot doesn't change, the root updater may be paused.