Relayer API

The Relayer service handles fee quoting and withdrawal transaction relay. It allows users to withdraw without revealing their address as the transaction sender.

Relay Flow

API Endpoints

GET/relayer/quote

Get Fee Quote

Returns a signed fee commitment for a withdrawal. The fee is calculated based on the current gas price and the configured base fee for the asset.

Query Parameters

Param	Type	Description
chainId	number	Target chain ID
amount	string	Withdrawal amount in wei
asset	string	Asset address (or "ETH")
recipient	string	Recipient address

Response

response.json

{
  "baseFeeBPS": "200",
  "feeBPS": "291",
  "feeCommitment": {
    "expiration": 1744676669549,
    "withdrawalData": "0x...",
    "signedRelayerCommitment": "0x..."
  }
}

POST/relayer/relay

Submit Withdrawal

Submits a withdrawal transaction for relay. The relayer verifies the proof and signed fee commitment, then broadcasts the transaction on behalf of the user.

Request Body

Param	Type	Description
proof	bytes	ZK proof of valid withdrawal
withdrawalData	object	Encoded withdrawal parameters
signedRelayerCommitment	string	Signed fee commitment from /quote

Response

response.json

{
  "txHash": "0x..."
}

GET/relayer/health

Health Check

Returns the relayer status and configured chain ID. Useful for monitoring and verifying the relayer is operational.

Response

response.json

{
  "status": "ok",
  "chainId": "11155111"
}

Fee Structure

The relayer fee is composed of a base fee plus a gas cost adjustment. This ensures the relayer is compensated for on-chain transaction costs regardless of network conditions.

Base Fee

Configured per-asset in basis points. For example, 200 BPS = 2% of the withdrawal amount. This covers the relayer's operational costs and margin.

Gas Adjustment

If the estimated gas cost is high relative to the withdrawal amount, the effective fee increases to ensure the relayer doesn't operate at a loss on small withdrawals during gas spikes.

Fee Commitment

The relayer signs a fee commitment valid for 20 seconds. This binds the quoted fee so it cannot change during proof generation. The signed commitment is submitted alongside the proof when relaying.

Formula

effectiveFeeBPS = (gasCost + (amount * baseFeeBPS / 10000)) / amount * 10000

Fee Commitment Window

The relayer signs a fee commitment valid for 20 seconds. This ensures the fee you see is the fee you pay, even if gas prices change during proof generation.

Running Your Own Relayer

You can run your own relayer instance to serve withdrawals on supported chains. The relayer requires a funded signer wallet, an RPC endpoint, and a configuration file specifying supported assets and fee parameters.

Configuration

Create a config.json file with your chain settings, supported assets, and fee parameters:

config.json

{
  "feeReceiver": "0x...",
  "signerKey": "$RELAYER_SIGNER_KEY",
  "chains": {
    "11155111": {
      "rpcUrl": "$RPC_URL",
      "entrypoint": "0x...",
      "supportedAssets": ["ETH", "USDC"],
      "baseFeeBPS": {
        "ETH": 200,
        "USDC": 150
      }
    }
  }
}

Environment Variables

Variable	Description
RELAYER_SIGNER_KEY	Private key for signing fee commitments and submitting transactions
RPC_URL	JSON-RPC endpoint for the target chain
PORT	Server port (default: 3001)

Docker

terminal

docker run -d \
  --name shieldflow-relayer \
  -p 3001:3001 \
  -e RELAYER_SIGNER_KEY=$RELAYER_SIGNER_KEY \
  -e RPC_URL=$RPC_URL \
  -v ./config.json:/app/config.json \
  shieldflow/relayer:latest

Signer Wallet Funding

The relayer signer wallet must be funded with enough ETH to cover gas costs for relaying withdrawal transactions. Monitor the balance and set up alerts to avoid failed relays.