Skip to main content
A relayer is a small HTTP service holding a funded key, and the reason a fresh wallet can receive from the pool without ever paying gas. Users prove in their own browser and send only the finished transaction; the relayer submits it to the pool and pays the gas. It is never paid in public: its fee is output slot 2 of the relayed transaction, a note owned by the relayer’s own shielded address, whose keys derive from RELAYER_PRIVATE_KEY exactly as a web wallet’s derive from the user’s. Because the proof binds every output, a relayer can only refuse to submit; it cannot redirect a payout or change its fee. See Fees and referrals for why fee notes work this way. Fluton runs the relayer the hosted wallet uses. You can run your own from the same Docker image; clients reach it through the SDK’s relayer client (Deposits, withdrawals and transfers).
The public Docker image, and the proving artifacts that fee collection needs, are not published yet. They will be. Until then the relayer behind the hosted wallet is the one in service, and this page is the reference for the image when it ships.
Use a separate, small-balance key for the relayer.

Endpoints

Every response is JSON, CORS is open by default (RELAYER_CORS_ORIGIN), and OPTIONS ends with 204. Logs name transaction hashes only: for a hidden transfer the relayer is the one outside party that knows the asset and the fee, and it does not write them down. GET /status is what a wallet reads before it offers to relay:
address
The EOA that signs and pays gas.
string
The shielded address (pp-addr:…) that fee notes must be paid to.
number
The chain this relayer serves.
address
The pool this relayer serves.
object
Asset id to fixed minimum fee, in that asset’s note units, as decimal strings. Only assets with a non-zero minimum appear, and only those are relayed.
GET /fees quotes every served asset at once, so asking reveals nothing about the spend. It returns at (the time of the quote), gasPrice (what the relayer would bid now) and fees, keyed by asset id and then by job kind, transfer or withdraw:
string
The job’s gas times the price the relayer would bid now, plus the margin, in the asset’s note units. This is what the web app pays.
string
The job’s gas times the lowest price that still lands in the next block: the least the relayer accepts right now.
POST /relay takes the payload the SDK produces, proof and extData, and answers { "hash": "0x…" }. GET /relay/:nullifier takes one of the transaction’s input nullifiers and answers a status of unknown, pending, mined or failed, with the hash of the transaction it last broadcast. Submissions are held in memory, so a restart forgets them and the chain stays the final word.

What it refuses

Cheap checks run first, and each refusal is a 400 with a reason:
  • a payload whose shape is wrong: it relays only transactions with 2 nullifiers, 3 commitments and 3 ciphertexts of exactly 168 bytes. The 16-input circuit is valid on-chain but not relayed, because it costs about 35% more gas than the minimum fees are set for;
  • deposits, which would pull tokens from the relayer, and deposit finalizations, which only the depositor may send;
  • a referrer on anything but a deposit, since only a deposit may name one;
  • a payload whose domain fields name another chain, pool or format, or that names an asset without moving value, or moves value without naming one;
  • a slot-2 output that is not a fee note to this relayer: the ciphertext must decrypt with its key to a canonical opening that hashes to that slot’s commitment under its spend public key;
  • an asset it does not serve, a fee below that asset’s fixed minimum, or a withdrawal whose named asset is not the fee note’s;
  • a fee that no longer pays for the gas, and, while the ETH price is unavailable, anything paid in a USD-priced token.
A different payload that spends notes already in flight gets 409; the same payload twice returns the first hash, so a retry never broadcasts twice. A body over 256 KiB gets 413.

Fee quoting

A relayed job costs the relayer gas: roughly 1.3M for a private transfer and 2.2 to 3M for a withdrawal, plus the keeper’s follow-ups (confirming the payout, about 80k, and for a TOKEN withdrawal the claim, 110k). Gas per kind starts at RELAYER_GAS, which defaults to transfer=1500000,withdraw=3500000, measured with headroom, and rises on its own when a relay’s estimate is higher: the service remembers the gas limits of recent attempts and quotes from the largest. The follow-up budget is 200,000 gas for a withdrawal and nothing for a transfer. The fee in a quote includes the margin, RELAYER_FEE_MARGIN_BPS, which defaults to 2000 (20%). The margin is the relayer’s profit and the room gas prices have to rise between a quote and the relay. Both fee and min are at least the asset’s fixed minimum fee, and a quote is reused for a few seconds. When a transaction arrives, the relayer values its fee note in ETH and divides by the transaction’s estimated gas (the estimate plus 10%, which also simulates the call) plus the follow-ups. That is the cap: the most it may ever pay per gas for this job. It never bids above the cap, neither at the first broadcast nor when replacing a stuck transaction. If the cap is below the price that still lands in the next block, nothing is signed at all: the answer is a 400 reading relayer fee too low for current gas prices, with the least acceptable fee in note units, so the user asks GET /fees again and proves afresh. So congestion can delay or refuse a job, but a relayed transaction never costs more than its fee is worth.

Token prices

Each asset is valued in one of two ways.
  • A fixed ETH price per whole token (ethPrice in the deployment, or RELAYER_ETH_PRICES) needs nothing else. WETH is 1.
  • A USD price per whole token (usdPrice, or RELAYER_USD_PRICES) is converted at the live ETH/USD price, which the relayer reads from a Chainlink AggregatorV3 feed through its own RPC: no API key, and every answer carries its update time. RELAYER_ETH_USD_FEED names the feed; by default the relayer uses Chainlink’s own ETH/USD feed on Arbitrum One, Ethereum, Sepolia and Arbitrum Sepolia. A reading is reused for a minute before the feed is read again.
An answer older than RELAYER_PRICE_MAX_AGE_S (default 7200 seconds, twice the longest heartbeat among those feeds, measured in chain time against the latest block’s timestamp), or zero, or negative, is never used, and the relayer never falls back to an older reading instead. While the price is unavailable, USD-priced assets are left out of GET /fees and refused at POST /relay before anything is signed, and fixed-price assets carry on as normal. A failing RPC, as opposed to a stale feed, keeps the last reading only while its age is still within the maximum. Each outage and each recovery is logged once. An asset with neither price is relayed at its fixed minimum fee, with no cap, whatever gas costs; the service warns about it at startup. Naming one asset in both RELAYER_ETH_PRICES and RELAYER_USD_PRICES is a configuration error and the service refuses to start; in the deployment file, an ethPrice simply wins over a usdPrice.

Sending and re-sending

Every send goes through one serial queue (one nonce at a time) shared with the keeper, and is simulated against the latest state right before it is signed, so a job made stale by someone else is dropped instead of sent. Each broadcast is then watched until its nonce is used, and the submission’s status always ends at mined or failed, never pending after a drop:
  1. A transaction still unmined three minutes after its last broadcast was outbid, or dropped by the node, which would also hold back every later nonce. It is re-sent at the same nonce with fees 25% higher, up to three times, as long as it still simulates. A capped job bids the cap itself while that still replaces the stuck transaction.
  2. Then, or at once if the call would now revert or a higher bid would exceed the cap, the relayer cancels it: a 0 ETH transfer to itself at that nonce, 21,000 gas, the only cost the fee does not cover. The submission is failed, the user’s notes were not spent, and the same payload may be sent again.
  3. A nonce taken by a transaction this relayer did not send also ends as failed, after a few polls confirm it.
A wallet waiting for a receipt follows a re-send to its receipt. After a cancel it reports an unknown outcome and asks GET /relay/:nullifier and the chain before offering to send from the wallet, because re-sending from the wallet could land first and name the user as the sender.

The keeper

The relayer also runs the keeper (RELAYER_KEEPER=1, the default; KEEPER_INTERVAL_MS sets the tick period, default 5000 ms). It only ever calls permissionless functions: It never finalizes or cancels a deposit: those are the depositor’s alone. It resolves each asset’s wrapper from the pool’s registry and caches it, so it follows assets listed after it started. Jobs are rebuilt from chain state. Events are scanned from a cursor persisted in a file (one per chain and pool, under a .keeper directory by default, or wherever KEEPER_CURSOR_FILE points), written to a temporary file and renamed so a crash never leaves a torn cursor, and every job re-reads its on-chain status immediately before acting. When the deployment file names an indexer, or KEEPER_INDEXER_URL does, the keeper takes its new jobs from that indexer’s GET /events instead of reading logs, so an idle keeper makes no RPC calls between its own chain scans, which it still runs every KEEPER_CHAIN_SCAN_MS. The indexer is untrusted here as everywhere: every id it names is read on-chain before anything is done with it, a claim is kept only once its attempt on-chain names it, and the chain scan finds whatever it left out. While the indexer is unreachable, stale or serving another pool, the keeper scans the chain on every tick, as it does with no indexer at all. Correctness never depends on the keeper: the pool rejects stale confirmations, replays and concurrent retries, and the wrapper rejects a double claim, so a crashed, restarted or duplicated keeper can at worst waste gas on a reverting transaction.

Run it from the Docker image

The relayer ships as a Docker image, fluton-relayer. It contains the relayer and the SDK it needs, exposes port 8787 and binds 0.0.0.0. It reads the pool’s addresses from a deployment file: the same JSON the hosted wallet publishes as deployment.json, whose contents are listed under deployments. Mount a directory holding that file, saved as arbitrum.json, at /app/deployments, name it in DEPLOYMENT_FILE, and give the container a key and an RPC:
The service then answers on :8787 and serves every asset it has a minimum fee for; with none it warns and runs the keeper only. Fund the key with a little ETH on Arbitrum One, keep it small and separate from any key that holds funds, and host the container anywhere that runs Docker. Clients that want to use your relayer point the SDK’s relayer client at its public URL.

Configuration

Everything is set through environment variables. RELAYER_PRIVATE_KEY is the only required one; the rest have the defaults below. A malformed KEY=value list, a key that names no listed token, a token with both prices, a non-positive price, or a non-integer margin or maximum age fails at startup. A token with a minimum fee but no price is relayed at that fixed minimum and the relayer warns about it.

Collect the fee notes

Income accumulates as fee notes, one per relayed transaction, which the relayer finds by scanning the chain with its own note key. The fees command runs in the same image, in place of the service, with the same environment and volumes:
The first form lists the fee-note balance per asset. fees withdraw <SYMBOL> merges the notes and withdraws them to the relayer’s address as eTOKEN (add --public for TOKEN). Stop the service first: both send from the same key, and the command refuses to run while a relayer answers on the port with that key. Collecting uses the 16-input circuit. Each merge spends 16 fee notes into one with a private transfer to the relayer itself, which names no asset, and the final withdrawal spends up to 16 notes in full. Collecting N notes therefore takes one transaction for up to 16 notes and one more for every 15 beyond that: 100 notes take 7 transactions instead of 99. A 16-input merge costs 1.71M gas against 1.26M for a 2-input transfer, so collecting a fee note costs about 115k gas, a small part of the transaction that paid it. The withdrawal shows that asset’s total income since the last one and pays the pool’s withdrawal fee like any other withdrawal, so the relayer receives the total minus that fee. Notes below the asset’s minimum fee are dust (anyone can send notes to a published shielded address) and are left alone. The proving artifacts are not in the image. fees withdraw needs the four circuit files of the deployed pool (transaction.wasm, transaction_final.zkey, transaction16.wasm, transaction16_final.zkey) in the directory CIRCUIT_DIR names; the 16-input proving key alone is about 61 MB. A key from another build produces proofs the deployed verifier rejects; fees simulates every transaction first, so that costs nothing. Without the 16-input artifacts it warns and can still withdraw at most two notes.