Courier
The optional service that rides the Arbitrum fallback and sweeps envelopes: states, environment, HTTP API and deployment.
The courier is one Node process in courier/. HOOZ works without it: the direct rail pays you or your envelope, and anyone can call sweep. Run the courier to get two extras: the Arbitrum fallback when no solver quotes Robinhood Chain, and automatic sweeps after launch.
One key, two jobs
The courier key receives NEAR Intents settlements on Arbitrum One (fallback only) and sends the Relay deposit toward your envelope. On Robinhood Chain it signs sweep and, when the vault is funded, deliver. It needs a little ETH on both chains for gas. It never holds $WHOZ.
Storage
DATA_DIR/orders.json, written atomically (temp file, then rename) after every change. No database. Terminal orders older than thirty days are pruned on start.
States
| From | To | Condition |
|---|---|---|
| request | waiting | validation passed and 1Click returned a deposit address |
| waiting | seen | 1Click reports KNOWN_DEPOSIT_TX or INCOMPLETE_DEPOSIT |
| seen | settling | 1Click reports PROCESSING |
| any open | settled | 1Click reports SUCCESS |
| settled | bridging | fallback order: Relay deposit sent with recipient = envelope |
| bridging | landed | Relay reports success |
| landed | sorting | token set, Sorter not paused, sweep sent |
| sorting | delivered | sweep receipt succeeded |
| any open | refunded, failed | 1Click refund or failure, or a reverted transaction |
The courier writes each transaction hash before it awaits the receipt, so a crash never resends. On restart it resumes from the hash.
Environment
| Variable | Default | Meaning |
|---|---|---|
| COURIER_PK | required | the courier key |
| HOOZ_SORTER | empty | Sorter address; sweeps start once set |
| ROBINHOOD_RPC | https://rpc.mainnet.chain.robinhood.com | |
| ARBITRUM_RPC | https://arb1.arbitrum.io/rpc | |
| DATA_DIR | ./data | where orders.json lives |
| PORT | 8080 | |
| TICK_MS | 20000 | loop period |
| ONECLICK_JWT | empty | partner key; removes the unauthenticated 1Click surcharge |
HTTP API
| Method and path | Returns |
|---|---|
| POST /orders | {amountZec, beneficiary, refundTo} in, the new order out |
| GET /orders/:id | the order with its events |
| POST /envelopes | {beneficiary}: watch this envelope and sweep it when ETH lands |
| GET /health | {ok, tick, openOrders} |
Set RELAYER_URL on the site to the courier's URL and the site forwards orders to it whenever the direct rail refuses a quote.