Docs/Run your own relay

One relay, one bundler, one deposit.

The one-bundler-per-deposit rule#

Co-signed ops never go to a third-party bundler, not even as a fallback. Only your bundler can land them: the relay never returns the co-signature to the client, and the chain has no public mempool.

JSON-RPC API#

ERC-7769 method names where they exist, plus stamp_* and pow_* methods. CORS allows only the web origin. The full description is the OpenRPC document, /openrpc.json.

Check order for a send#

eth_sendUserOperation and pow_sendUserOperation take a mined stamp, stamp_sendUserOperation a prepaid one; the paymasterData version must match the method.

1. EntryPoint v0.9, op.paymaster is this paymaster, size limits; the version matches the method.
2. The epoch exists and is current, or the previous one within STALE_GRACE after a roll (EPOCH_STALE); at least 60 s left before validUntil (EPOCH_EXPIRED); a prepaid stamp needs the epoch's STAMPS flag (STAMP_LANE_CLOSED).
3. EntryPoint nonce key 0 (NONCE_KEY).
4. Authorization shape (AUTH_INVALID).
5. Recompute userOpHash locally, including the authorization. A client-supplied hash is never trusted.
6. Mined stamp: verify the 8 PoW hashes (POW_INVALID). Prepaid stamp: verify the stamp under its window's derived key and its expiry (STAMP_INVALID, STAMP_EXPIRED), that the op's nullifier is the stamp's, and that the stamp is not in flight (STAMP_IN_FLIGHT). Then mirror every on-chain soft check (fees, cost, gas caps, paymaster gas).
7. The account signature and the authorization's signer, then the delegation state read from the chain (SIGNATURE_INVALID, AUTH_INVALID, DELEGATE_MISMATCH).
8. Template, allowlist, exact gas profile, PVG bounds and fees; the recipient rule for ETH sends.
9. At most 4 pending ops per sender; a prepaid stamp must not be cancelled on chain yet (cancelledAt, STAMP_SPENT).
10. Admission: a mined stamp against headroom, the free budget and pacing (BUDGET_EXHAUSTED, PACING, with retryAt); a prepaid stamp against the deposit's headroom only.
11. Co-sign cosignDigest(userOpHash), or stampDigest(userOpHash, nullifier), with the epoch's co-signer key and replace the stub in paymasterSignature.
12. Add the op to the ledger and forward it to the bundler, or hold it. If the bundler rejects it, remove it and return the bundler's reason.

No bundler or provider call happens before the proof or the stamp is verified, so sends are protected by the postage itself, and refused sends cost the client tokens of its invalidSend budget.

Issuance#

stamp_issue reads the purchase's receipt, requires STAMP_CONFIRMATIONS, finds StampsBought from the PostOffice, checks that the count and keccak256(keccak256(info) ‖ blinded…) are the ones paid for and that the purchase's block time falls in the window info names (plus STAMP_ISSUE_GRACE_S), then blind-signs under that window's key. The relay stores nothing; asking again returns the same signatures. Generate the master keys with pnpm relay:issuer-key: the private key goes to the keyring file only, and the public part is the pin to publish in contracts/deployments/<chainId>.json under stamps.issuers. Clients refuse any key or window that is not pinned.

Configuration#

The keeper checks every 10 s and calls roll() from its EOA once an epoch is over (on mainnet, only while clients use the relay). It refreshes the PVG quotes with the relay's own dummy accounts, never a user's. Every POSTAL_INTERVAL_S it also runs the postal jobs, each skipped when its contract is not configured: it re-prices the PostOffice when the gas quote drifts, burns the DeadLetterOffice's balance into $STAMP at 0x…dEaD with a minimum output, and calls CreatorFeeSink.collect() once enough creator fees are pending.

The bundler#

Self-hosted Alto 0.0.21, reachable only from the relay. The non-secret flags live in a config file; the secrets come from the environment (Alto reads ALTO_<OPTION> variables), so no key is ever on a command line:

{
  "entrypoints": "0x433709009B8330FDa32311DF1C2AFA402eD8D009",
  "chain-type": "arbitrum",
  "safe-mode": false,
  "deploy-simulations-contract": true,
  "min-entity-stake": 0,
  "min-entity-unstake-delay": 86400,
  "ceiling-max-priority-fee-per-gas": "0.001",
  "gas-price-expiry": 1200,
  "default-api-version": "v2",
  "bundle-mode": "manual",
  "enable-debug-endpoints": true,
  "enable-cors": false,
  "min-executor-balance": "5000000000000000",
  "port": 4337
}

ALTO_RPC_URL="$RH_RPC" ALTO_EXECUTOR_PRIVATE_KEYS="$EXECUTOR_PK" ALTO_UTILITY_PRIVATE_KEY="$UTILITY_PK" \
  npx -y @pimlico/alto@0.0.21 --config infra/alto/alto.mainnet.json

• ceiling-max-priority-fee-per-gas is read in gwei: 0.001 is 1e6 wei, the epoch's priority cap.
• min-entity-stake must be an integer number of ETH and is read only by the safe-mode reputation manager: 0 here.
• chain-type arbitrum lets Alto price the L1 data part of each op through the NodeInterface; the executor gets each bundle's compensation back, and the utility account refills it below min-executor-balance (0.005 ETH).
• Use a provider RPC for the bundler and the relay; the public RPC is rate-limited and has no debug API, which is why the bundler runs in unsafe mode. Prefer an endpoint that authenticates by header or allowlist over one with the API key in its path: Alto's error text quotes the URL it called (the relay never forwards it, but logs and other tools might).
• The executor must be a plain EOA (EntryPoint v0.9 handleOps is non-reentrant and requires one). Give its address to the relay as BUNDLER_EXECUTORS: after a restart, the relay accepts sends only once no bundle transaction is in flight.
• Debug endpoints stay on the private network between the relay and the bundler.

Privacy posture#

• No IP logging and no request-body logging. Metrics are aggregated only.
• Zero retention: the ledger holds hashes and amounts, dropped when the op resolves. The issuer stores no blinded message, no serial and no signature.
• Put it behind a reverse proxy that keeps X-Forwarded-For out of its logs.
• Rate limits live in memory and are never written anywhere: one bucket per client network (IPv4 address or IPv6 /64) and method class.
• Bundler and provider error text is never returned to clients; refusals carry a fixed message and a reason.
• The internal admin listener refuses browser requests (any Origin) and foreign Host names; set ADMIN_TOKEN to require a bearer token for the drain switch.
• The issuer keyring never enters the repository or a log line; errors name keyring entries by position only.

Point the web app at it#

The app only connects to the endpoints its Content-Security-Policy allows. To use your relay from the app, build your own copy with NEXT_PUBLIC_RELAY_URL (and optionally NEXT_PUBLIC_RPC_URL and NEXT_PUBLIC_ALLOWED_ENDPOINTS) set; the privacy options in the app then offer it. SDK users just pass the URL to createRelayClient. Your relay issues its own stamps under its own keys: stamps bought from one relay are redeemed by that relay.