Towns Relayer

Cloudflare Worker that relays signed intents to the blockchain. Manages a pool of signers derived from an HD wallet mnemonic for high-throughput transaction processing.

Quick Start

# Install dependencies
bun install

# Copy environment variables
cp .dev.vars.example .dev.vars

# Start local development
bun run dev

Scripts

bun run dev              # Local development server
bun run build            # Type check and build
bun run test             # Run tests
bun run deploy --env stage   # Deploy to stage
bun run deploy --env prod    # Deploy to prod

Configuration

Required Secrets

Set these via wrangler secret put <NAME> --env <stage|prod>:

| Name | Description | | ------------------ | -------------------------------------------------------------------- | | RPC_URL | JSON-RPC endpoint (e.g. https://base-sepolia.g.alchemy.com/v2/...) | | RELAYER_MNEMONIC | HD wallet mnemonic for deriving signer keys | | CHAIN_IDS | Comma-separated chain IDs (e.g. 8453,137) |

Optional: Multi-Chain RPC Configuration

For cross-chain operations, configure RPC URLs per chain using the RPC_<chainId> pattern:

| Name | Description | | ----------- | ------------------------------------------ | | RPC_84532 | RPC URL for Base Sepolia (chain ID 84532) | | RPC_8453 | RPC URL for Base Mainnet (chain ID 8453) | | RPC_137 | RPC URL for Polygon Mainnet (chain ID 137) |

Chain-specific RPCs (RPC_<chainId>) take precedence over RPC_URL for that chain.

See src/config/chains.json for supported chains and their metadata.

Optional: Pool Configuration

| Name | Default | Description | | ------------------------ | ------- | ---------------------------------- | | RELAYER_COUNT | 1 | Number of signers (max 100) | | MAX_PENDING_PER_SIGNER | 16 | Max pending txs per signer | | MAX_PENDING_TOTAL | 1000 | Max pending txs across all signers | | MIN_SIGNER_BALANCE | 0.01 | Min balance in ETH before pause | | TARGET_SIGNER_BALANCE | 0.01 | Target balance after refill (ETH) |

Optional: Contract Addresses

Auto-loaded from @towns-labs/contracts for known chains. Override for custom deployments. Names match @towns-labs/contracts env var keys (no _ADDRESS suffix):

| Name | Description | | --------------- | -------------------------------------------------------------- | | ORCHESTRATOR | Required if chain not in deployments | | TOWNS_ACCOUNT | Towns Account contract | | ACCOUNT_PROXY | Account Proxy contract | | SIMPLE_FUNDER | SimpleFunder contract | | SIMULATOR | Simulator contract | | CONTEXT | Deployment context: prod|stage|local (default: prod) |

Optional: Fee Configuration

| Name | Default | Description | | --------------------------- | ------- | --------------------------------- | | FEE_RECIPIENT | signer | Address to receive fees | | INTENT_GAS_BUFFER_PERCENT | 10 | Gas estimate buffer % | | TX_GAS_OVERHEAD | 21000 | Fixed gas overhead per tx | | PRIORITY_FEE_PERCENTILE | 50 | Fee percentile from block history | | QUOTE_TTL_SECONDS | 300 | Fee quote validity (seconds) |

Optional: Validation

| Name | Default | Description | | ------------------------------ | ------- | ------------------------------------- | | INTENT_EXPIRY_BUFFER_SECONDS | 30 | Buffer before expiry to reject intent |

Deployment

First-time Setup

1. Create the queues:

wrangler queues create relayer-monitor-queue-stage
wrangler queues create relayer-monitor-queue-prod

2. Set secrets:

# Stage
wrangler secret put RPC_URL --env stage
wrangler secret put RELAYER_MNEMONIC --env stage
wrangler secret put CHAIN_IDS --env stage
wrangler secret put CONTEXT --env stage
wrangler secret put SETTLER_OWNER_KEY --env stage
wrangler secret put SIMPLE_FUNDER_OWNER_KEY --env stage
wrangler secret put RPC_84532 --env stage
wrangler secret put RPC_137 --env stage

# Prod
wrangler secret put RPC_URL --env prod
wrangler secret put RELAYER_MNEMONIC --env prod
wrangler secret put CHAIN_IDS --env prod
wrangler secret put CONTEXT --env prod
wrangler secret put SETTLER_OWNER_KEY --env prod
wrangler secret put SIMPLE_FUNDER_OWNER_KEY --env prod
wrangler secret put RPC_8453 --env prod
wrangler secret put RPC_137 --env prod

3. Deploy:

wrangler deploy --env stage
wrangler deploy --env prod

Updating

wrangler deploy --env stage   # Deploy to stage
wrangler deploy --env prod    # Deploy to prod

Logs

wrangler tail --env stage
wrangler tail --env prod

Architecture

• SignerDO - Individual signer state and transaction signing (SQLite-backed)
• SignerPoolDO - Distributes transactions across signers (SQLite-backed)
• IntentNonceDO - Intent deduplication and ordering (SQLite-backed)
• BundleStatusDO - Transaction bundle status tracking (SQLite-backed)
• MONITOR_QUEUE - Processes transaction monitoring jobs

Endpoints

• stage: https://relayer-worker-stage.johnhntlabs.workers.dev/
• prod: