@towns-labs/relayer 2.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +161 -0
  2. package/dist/README.md +1 -0
  3. package/dist/index.js +47482 -0
  4. package/dist/index.js.map +8 -0
  5. package/package.json +53 -0
  6. package/src/rpc/schema/getCallsStatus.ts +21 -0
  7. package/src/rpc/schema/getCapabilities.ts +91 -0
  8. package/src/rpc/schema/getKeys.ts +40 -0
  9. package/src/rpc/schema/prepareCalls.ts +173 -0
  10. package/src/rpc/schema/sendPreparedCalls.ts +23 -0
  11. package/src/rpc/schema/upgradeAccount.ts +172 -0
  12. package/src/rpc/schema/verifySignature.ts +27 -0
package/README.md ADDED
@@ -0,0 +1,161 @@
1
+ # Towns Relayer
2
+
3
+ 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.
4
+
5
+ ## Quick Start
6
+
7
+ ```bash
8
+ # Install dependencies
9
+ bun install
10
+
11
+ # Copy environment variables
12
+ cp .dev.vars.example .dev.vars
13
+
14
+ # Start local development
15
+ bun run dev
16
+ ```
17
+
18
+ ## Scripts
19
+
20
+ ```bash
21
+ bun run dev # Local development server
22
+ bun run build # Type check and build
23
+ bun run test # Run tests
24
+ bun run deploy --env stage # Deploy to stage
25
+ bun run deploy --env prod # Deploy to prod
26
+ ```
27
+
28
+ ## Configuration
29
+
30
+ ### Required Secrets
31
+
32
+ Set these via `wrangler secret put <NAME> --env <stage|prod>`:
33
+
34
+ | Name | Description |
35
+ | ------------------ | -------------------------------------------------------------------- |
36
+ | `RPC_URL` | JSON-RPC endpoint (e.g. `https://base-sepolia.g.alchemy.com/v2/...`) |
37
+ | `RELAYER_MNEMONIC` | HD wallet mnemonic for deriving signer keys |
38
+ | `CHAIN_IDS` | Comma-separated chain IDs (e.g. `8453,137`) |
39
+
40
+ ### Optional: Multi-Chain RPC Configuration
41
+
42
+ For cross-chain operations, configure RPC URLs per chain using the `RPC_<chainId>` pattern:
43
+
44
+ | Name | Description |
45
+ | ----------- | ------------------------------------------ |
46
+ | `RPC_84532` | RPC URL for Base Sepolia (chain ID 84532) |
47
+ | `RPC_8453` | RPC URL for Base Mainnet (chain ID 8453) |
48
+ | `RPC_137` | RPC URL for Polygon Mainnet (chain ID 137) |
49
+
50
+ Chain-specific RPCs (`RPC_<chainId>`) take precedence over `RPC_URL` for that chain.
51
+
52
+ See `src/config/chains.json` for supported chains and their metadata.
53
+
54
+ ### Optional: Pool Configuration
55
+
56
+ | Name | Default | Description |
57
+ | ------------------------ | ------- | ---------------------------------- |
58
+ | `RELAYER_COUNT` | `1` | Number of signers (max 100) |
59
+ | `MAX_PENDING_PER_SIGNER` | `16` | Max pending txs per signer |
60
+ | `MAX_PENDING_TOTAL` | `1000` | Max pending txs across all signers |
61
+ | `MIN_SIGNER_BALANCE` | `0.01` | Min balance in ETH before pause |
62
+ | `TARGET_SIGNER_BALANCE` | `0.01` | Target balance after refill (ETH) |
63
+
64
+ ### Optional: Contract Addresses
65
+
66
+ Auto-loaded from `@towns-labs/contracts` for known chains. Override for custom deployments.
67
+ Names match `@towns-labs/contracts` env var keys (no `_ADDRESS` suffix):
68
+
69
+ | Name | Description |
70
+ | --------------- | -------------------------------------------------------------- |
71
+ | `ORCHESTRATOR` | Required if chain not in deployments |
72
+ | `TOWNS_ACCOUNT` | Towns Account contract |
73
+ | `ACCOUNT_PROXY` | Account Proxy contract |
74
+ | `SIMPLE_FUNDER` | SimpleFunder contract |
75
+ | `SIMULATOR` | Simulator contract |
76
+ | `CONTEXT` | Deployment context: `prod`\|`stage`\|`local` (default: `prod`) |
77
+
78
+ ### Optional: Fee Configuration
79
+
80
+ | Name | Default | Description |
81
+ | --------------------------- | ------- | --------------------------------- |
82
+ | `FEE_RECIPIENT` | signer | Address to receive fees |
83
+ | `INTENT_GAS_BUFFER_PERCENT` | `10` | Gas estimate buffer % |
84
+ | `TX_GAS_OVERHEAD` | `21000` | Fixed gas overhead per tx |
85
+ | `PRIORITY_FEE_PERCENTILE` | `50` | Fee percentile from block history |
86
+ | `QUOTE_TTL_SECONDS` | `300` | Fee quote validity (seconds) |
87
+
88
+ ### Optional: Validation
89
+
90
+ | Name | Default | Description |
91
+ | ------------------------------ | ------- | ------------------------------------- |
92
+ | `INTENT_EXPIRY_BUFFER_SECONDS` | `30` | Buffer before expiry to reject intent |
93
+
94
+ ## Deployment
95
+
96
+ ### First-time Setup
97
+
98
+ 1. Create the queues:
99
+
100
+ ```bash
101
+ wrangler queues create relayer-monitor-queue-stage
102
+ wrangler queues create relayer-monitor-queue-prod
103
+ ```
104
+
105
+ 2. Set secrets:
106
+
107
+ ```bash
108
+ # Stage
109
+ wrangler secret put RPC_URL --env stage
110
+ wrangler secret put RELAYER_MNEMONIC --env stage
111
+ wrangler secret put CHAIN_IDS --env stage
112
+ wrangler secret put CONTEXT --env stage
113
+ wrangler secret put SETTLER_OWNER_KEY --env stage
114
+ wrangler secret put SIMPLE_FUNDER_OWNER_KEY --env stage
115
+ wrangler secret put RPC_84532 --env stage
116
+ wrangler secret put RPC_137 --env stage
117
+
118
+ # Prod
119
+ wrangler secret put RPC_URL --env prod
120
+ wrangler secret put RELAYER_MNEMONIC --env prod
121
+ wrangler secret put CHAIN_IDS --env prod
122
+ wrangler secret put CONTEXT --env prod
123
+ wrangler secret put SETTLER_OWNER_KEY --env prod
124
+ wrangler secret put SIMPLE_FUNDER_OWNER_KEY --env prod
125
+ wrangler secret put RPC_8453 --env prod
126
+ wrangler secret put RPC_137 --env prod
127
+ ```
128
+
129
+ 3. Deploy:
130
+
131
+ ```bash
132
+ wrangler deploy --env stage
133
+ wrangler deploy --env prod
134
+ ```
135
+
136
+ ### Updating
137
+
138
+ ```bash
139
+ wrangler deploy --env stage # Deploy to stage
140
+ wrangler deploy --env prod # Deploy to prod
141
+ ```
142
+
143
+ ### Logs
144
+
145
+ ```bash
146
+ wrangler tail --env stage
147
+ wrangler tail --env prod
148
+ ```
149
+
150
+ ## Architecture
151
+
152
+ - **SignerDO** - Individual signer state and transaction signing (SQLite-backed)
153
+ - **SignerPoolDO** - Distributes transactions across signers (SQLite-backed)
154
+ - **IntentNonceDO** - Intent deduplication and ordering (SQLite-backed)
155
+ - **BundleStatusDO** - Transaction bundle status tracking (SQLite-backed)
156
+ - **MONITOR_QUEUE** - Processes transaction monitoring jobs
157
+
158
+ ## Endpoints
159
+
160
+ - stage: https://relayer-worker-stage.johnhntlabs.workers.dev/
161
+ - prod:
package/dist/README.md ADDED
@@ -0,0 +1 @@
1
+ This folder contains the built output assets for the worker "relayer-worker" generated at 2026-02-10T14:35:42.453Z.