annon
Reference · Relayer

Annon relayer

An HTTP front for relay from @defdone/annon. It sends register, unlock, claim_key, reopen, reopen_seller, stop_sales and fund_file_storage to an Annon contract and pays the NEAR gas and storage, for people and agents without a NEAR account. An optional keeper, with its own account and key, calls the permissionless settle so recipients get paid.

Sponsorship decisions, admissions, quotas, storage allocations and pending operations live in a durable ledger under RELAYER_STATE_DIR and survive restarts. Additional HTTP request throttles are kept in memory. Run one relayer instance per signing key and per state directory.

Shell
docker build -f apps/relayer/Dockerfile -t annon-relayer .     # from the repository root
docker run -p 8080:8080 -v relayer-state:/data --env-file relayer.env annon-relayer

With that volume, set RELAYER_STATE_DIR (and KEEPER_STATE_DIR) to directories under /data. Without Docker: pnpm --filter @defdone/annon-relayer start (Node.js 22.22.2 or newer).

Route Answer
POST /v1/relay A relay request as JSON. 200 {txHash, signer}; 202 {txHash, signer, uncertain: true} when NEAR's answer was lost (read the outcome by hash); 202 {pending: true, retryAfterSeconds} while the same request is being signed; or {error, message}
GET /v1/capabilities What this relayer sponsors: network, contract, methods, fee and treasuries, sponsorship allocations, minimum price, acceptingNewBasePayments
POST /v1/base-eligibility {fileId, termsHash} in; whether this relayer will unlock a Base purchase of that file
GET /healthz {"ok":true}

The caller reads every transaction's outcome through its own NEAR RPC: a relayer cannot fake one.

Required settings

Startup stops on a missing or invalid setting.

Variable Meaning
CONTRACT_ID The Annon contract, for example v1.annon.defdone.near
RELAYER_ACCOUNT The NEAR account that sends and pays
RELAYER_KEY Secret. A function-call key of that account, restricted to the contract and the methods register,unlock,claim_key,reopen,reopen_seller,stop_sales,fund_file_storage
RELAYER_STATE_DIR A private directory on durable storage, writable by the container's node user. Holds the ledger and the alert state
DEMO_HOST_ORIGIN The HTTPS origin of the file host whose hosting reservations this relayer accepts, for example https://demo.annon.dev. Fixed in configuration, never taken from a request
SELLERS Required while OPEN_POOL_ENABLED=1 (the default). Comma-separated kind:id identities of listed sellers, who get their own allowance and need no hosting reservation. Keep the list private
TREASURY_EVM Required while BASE_SPONSORSHIP=1 (the default). The EVM identity that receives the fee share on Base listings, as evm:0x… or a bare address

Fees above zero need a treasury: TREASURY_EVM, TREASURY_NEAR, or both. The relay account needs prepaid storage on the contract (storage_deposit).

Network and service settings

Variable Default Meaning
NEAR_RPC https://rpc.mainnet.fastnear.com NEAR RPC. Use an endpoint with an API key for a keeper that polls often
BASE_RPC https://mainnet.base.org Base RPC. Use an endpoint with an API key: the public one rate-limits the reads made during unlocking
NEAR_ARCHIVAL_RPC unset Archival NEAR RPC for historical file reads. Without it, startup raises historical_unavailable
NETWORK near:mainnet Must match the contract's configuration
NEAR_USDC, USDC The canonical USDC on NEAR and on Base Must match the contract's configuration; startup checks both
DEMO_RESERVATION_PUBLIC_KEY unset The host's Ed25519 public key (64 hex characters) that signs hosting reservations. Without it, only listed sellers are sponsored
CORS_ALLOW_ORIGINS https://annon.dev,https://www.annon.dev Exact browser origins allowed to call the relayer
CORS_PREVIEW_ORIGINS empty Extra exact origins, for preview deployments
CORS_MAX_AGE_SECONDS 600 Preflight cache, at most 600
IP_HEADER unset The single-value header your proxy overwrites with the client IP (for example x-client-ip). Never an appending header like x-forwarded-for. Without it, the connection's address is used
DISABLED 0 1 answers 503 and sends nothing
PORT 8080

Sponsorship and fees

On defdone's relayer the fee pays for the infrastructure it provides: sponsored registration and storage, relayed transactions and the settlement keeper. We set it at cost plus a small margin. A seller who registers directly with their own NEAR account pays no protocol fee.

Variable Default Meaning
OPEN_POOL_ENABLED 1 1: unlisted EVM and Solana sellers can get sponsored registrations, with a hosting reservation from the host at DEMO_HOST_ORIGIN. 0: only listed sellers
MIN_PRICE 100000 Smallest listing price and smallest Base purchase served, in USDC base units (0.10 USDC). Cannot be lower
FEE_FIXED 30000 Fixed fee in USDC base units (0.03 USDC). Cannot be lower
FEE_BPS 100 Proportional fee in basis points (1%). At least 100, below 10000
TREASURY_NEAR unset Fee recipient on NEAR-only listings, as kind:id or a bare NEAR account. Falls back to TREASURY_EVM
TREASURY_EVM unset Fee recipient on Base listings, and on NEAR-only listings without TREASURY_NEAR
BASE_SPONSORSHIP 1 0 disables sponsored Base registrations and Base unlocks
MAX_FILE_BYTES 50000000 Largest plaintext a hosting reservation may declare. Cannot be higher
MAX_DEADLINE_SECONDS, TOPUP_MAX_DEADLINE_SECONDS 600 How far ahead a wallet signature may be valid. Cannot be higher

A sponsored registration must give the route treasury at least ceil((FEE_FIXED * 10000 + price * FEE_BPS) / price) basis points. With the defaults that is 0.03 USDC plus 1% of the price. A file with Base terms carries one EVM treasury share, the larger of the NEAR and Base requirements, and all its recipients must be EVM identities. The eight-recipient limit includes the treasury. A fee that takes the whole price is refused.

The SDK reads the fee from /v1/capabilities, adds the treasury share, scales the other shares down and gives the rounding to an original recipient. The CLI shows the resulting split before it registers. JSON, agent and MCP sales refuse a fee above maxProtocolFee; an interactive human sale can approve it explicitly.

Who gets sponsored

  • A listed seller (in SELLERS) gets sponsored registrations up to its own daily allowance and needs no hosting reservation.
  • An unlisted EVM or Solana seller gets a sponsored registration only with a hosting reservation signed by the host at DEMO_HOST_ORIGIN, and only while OPEN_POOL_ENABLED=1. Without one the request is refused with not_sponsored before anything is sent.
  • A NEAR seller registers with their own wallet and does not use the relayer for it.

Sponsored Base registration includes baseSplit: {kind, salt} outside the contract arguments. The relayer recomputes the immutable, ownerless split address from the recipients, shares, kind and salt, and refuses a different pay_to.

Registration quotas

Variable Default Meaning
SPONSORED_FILES_PER_DAY 60 Sponsored registrations per UTC day for all unlisted sellers together
SPONSORED_FILES_PER_IP_DAY 2 Sponsored registrations per IP bucket for unlisted sellers per UTC day
REGISTRATIONS_PER_SELLER_DAY 2 Sponsored registrations per unlisted seller per UTC day
LISTED_REGISTRATIONS_PER_SELLER_DAY 20 Sponsored registrations per listed seller per UTC day
SPONSORED_FILES_LISTED_RESERVED 0 Fixed at 0

These defaults are also the highest values accepted; an operator can lower them. A registration is charged when it is admitted. One that was sent and then failed on chain is not refunded, because NEAR was spent.

File storage allocations

Values in decimal NEAR, with at most 24 fractional digits. The allocation defaults are also the highest values accepted.

Variable Default Meaning
FILE_BUDGET 0.041 Purchase storage allocated to a new unlisted file at registration
LISTED_FILE_BUDGET 0.05 The same for a listed seller's file
TOPUP_PER_FILE, LISTED_TOPUP_PER_FILE 0.082, 0.15 Lifetime allocation cap per sponsored file, registration included
TOPUP_PER_FILE_DAY, LISTED_TOPUP_PER_FILE_DAY 0.041, 0.05 Additional allocation per file per UTC day
TOPUP_PER_DAY 0.5 Additional allocation across all files per UTC day
TOPUP_LISTED_RESERVED 0.25 Part of TOPUP_PER_DAY kept for listed sellers
PREPAID_UNLOCK_FLOOR 1 Prepaid contract storage kept for unlocks: other sponsored writes are refused when they would go below it. At least 1
STORAGE_PER_WRITE 0.01 Prepaid storage set aside per sponsored write

Registration sends one zero-deposit register with args.file_budget. The contract debits registration storage and that allocation from the relayer's prepaid balance in one step; too little prepaid storage rolls back the whole registration. A zero FILE_BUDGET leaves the listing unfunded.

A registered EVM or Solana seller can ask for more:

JSON
{"method":"fund_file_storage","args":{"file_id":"<file-id>","amount":"<yoctoNEAR>","nonce":"<0x-32-byte-nonce>","deadline":1794528600},"auth":{"kind":"evm","sig":"<seller-signature>"}}

The seller signs fileFundingText from the SDK over the network, contract, seller, file ID, amount, nonce and deadline (Unix seconds, at most 600 seconds ahead). Only sponsored files qualify, and every cap above applies. Retries reuse the same envelope; the same nonce returns the saved result without a second allocation. There are no automatic top-ups. NEAR sellers fund their files directly.

Keep signing credentials private and rotate a compromised key.

Admission floor

Variable Default Meaning
ADMISSION_FLOOR_NEAR 3 Decimal NEAR, positive. Liquid balance below which new listing work stops

Before each seller-side write the relayer reads its liquid balance: the account balance minus the stake for its own account storage. Below the floor it refuses sponsored register, reopen_seller, stop_sales and fund_file_storage with budget (HTTP 429) and a 30-second Retry-After.

Buyers keep working below the floor: paid unlock, claim_key and buyer reopen (recovery of a paid purchase) are still served. Crossing the floor raises one admissions_paused alert, and recovering above it raises admissions_resumed. Set the floor above the balance you need to finish the unlocks of purchases already paid.

Send pools and per-client limits

Variable Default Meaning
PER_DAY 1000 Transactions per UTC day across all methods
UNLOCK_RESERVED 500 (at most PER_DAY) Part of PER_DAY that only unlock can use
UNLOCK_LISTED_RESERVED 250 Part of the unlock pool kept for listed sellers' files
PER_DAY_REGISTER, PER_DAY_UNLOCK, PER_DAY_CLAIM_KEY, PER_DAY_REOPEN, PER_DAY_REOPEN_SELLER, PER_DAY_STOP_SALES, PER_DAY_FUND_FILE_STORAGE 100, 500, 250, 50, 50, 100, 50 Daily pool of one method, inside PER_DAY
UNLOCKS_PER_FILE_DAY, UNLOCKS_PER_SELLER_DAY 10, 20 Sponsored Base unlocks per unlisted file and seller per day
LISTED_UNLOCKS_PER_FILE_DAY, LISTED_UNLOCKS_PER_SELLER_DAY 100, 250 The same for listed sellers
CLAIMS_PER_GRANT_DAY 3 New sponsored claim_key sends per (purchase, grant) per 24 hours
REOPENS_PER_PURCHASE_DAY 10 Sponsored recoveries per wallet and file per day
PER_IP_HOUR 600 Durable admissions per client IP per UTC hour (IPv6 grouped by /48), with additional HTTP throttling in memory
REQUEST_MULTIPLIER 10 Coarse request cap per IP, as a multiple of PER_IP_HOUR. In memory
HITS_CAP 100000 In-memory client counters before the oldest are evicted
HOLD_SECONDS 900 How long a recent operation is held against duplicates
MAX_WAITING, MAX_CHECKING 32, 32 Signing queue capacity and concurrent chain preflight checks
RETRY_SECONDS 5 Short retry hint for busy or paused answers

Count settings must be whole numbers. Non-unlock methods together may use at most PER_DAY - UNLOCK_RESERVED; capacity reserved for unlock is never lent to other methods. A definite refusal before execution can release the operation's reserved counters. A registration that executes and fails on chain keeps its quota charge. An uncertain result keeps its saved evidence until reconciled.

HTTP 429, 503 and 425 answers carry Retry-After in seconds. Refusals answer {error, message} with a public error code; the SDK maps it to the same error the CLI and the MCP server report. A Base payment that is not yet final answers 425 settlement_pending: retry the same request after Retry-After.

Alerts

Variable Default Meaning
RELAYER_ALERT_WEBHOOK unset Private HTTPS webhook for relayer alerts. Each alert is a JSON POST with text (a one-line summary) and alert (the alert fields)
RELAYER_BALANCE_LOW_WATER 3 NEAR Liquid balance alert, in yoctoNEAR
RELAYER_STORAGE_LOW_WATER 0.5 NEAR Prepaid contract storage alert, in yoctoNEAR
ALERT_SAMPLE_SECONDS 60 How often balances are sampled
ALERT_POOL_PERCENT, ALERT_DISK_PERCENT 70, 70 Daily pool and disk use alerts
ALERT_KEEPER_STALLED_SECONDS, ALERT_OLDEST_DELIVERY_SECONDS 300, 1800 Keeper progress alerts
ALERT_RELAYER_429_COUNT, ALERT_RELAYER_429_WINDOW_SECONDS 20, 600 Refusal burst alert
ALERT_KEEPER_BUDGET_PERCENT 50 Keeper budget use alert

Alerts are POSTed as JSON {text, alert} with a three-second timeout and no redirects; webhook failures never stop the relayer. alert holds only its type and public numbers such as balances. Keys, webhook URLs and upstream error bodies are never included. Repeated low samples are suppressed until the value recovers.

Base purchases

For a Base unlock the relayer reads BASE_RPC and requires terms.base.pay_to to be a clone of a known 0xSplits v2.2 implementation. At one Base block it checks that splitHash() matches the registered recipients and shares with zero distribution incentive, that owner() is zero and paused() is false, and that the treasury share follows policy. Owned, paused or different splits, plain accounts and missing treasury shares are refused. RPC failures fail closed with 503 and Retry-After, so the buyer can retry without spending gas.

Clients call POST /v1/base-eligibility before signing a new Base payment and check the returned network, contract, assets and file. acceptingNewBasePayments in /v1/capabilities must be true for a new Base payment. It is false when the relayer is disabled, BASE_SPONSORSHIP=0, or the state directory has not been sealed by the one-time cutover bootstrap in cutover.ts (the relayer raises cutover_unsealed until then). An eligible answer freezes its minPrice, fee, tier, policyVersion and decidedAt, and a paid purchase keeps that decision after later configuration changes.

Claims and duplicates

A purchase and grant pair gets at most CLAIMS_PER_GRANT_DAY new sponsored claim_key sends per 24 hours. A request for a pair that is already being sent returns its pending state or its hash without another send. After HOLD_SECONDS the relayer checks the cached transaction: only a final {big_y, big_c} release keeps the hash. A final outcome without a release, or an explicit unknown transaction, allows one new send charged to the same pair. Non-final transactions, transport errors and malformed outcomes keep the cache and never justify another send.

Identity-authorized requests use {method, args, auth: {kind, sig}}; claim_key and unlock have only method and args. An omitted grant becomes 0 before signing. The call shapes are in specs/near-settlement.md section 10.

Keeper

Variable Default Meaning
KEEPER_SECONDS 0 (off) Seconds between keeper passes, for example 15
KEEPER_ACCOUNT, KEEPER_KEY required when on A dedicated account and key, different from the relay account and key, allowed to call settle and materialize_refund
KEEPER_STATE_DIR required when on A private durable directory; jobs and budgets survive restarts
KEEPER_HOURLY_BUDGET, KEEPER_DAILY_BUDGET 0.5 NEAR, 1 NEAR Spend caps in yoctoNEAR
KEEPER_GAS_PRICE 100000000 Highest yoctoNEAR per gas; higher network prices stop new signing
KEEPER_MIN_PAYOUT 100000 Smallest purchase payout the keeper settles, in USDC base units (0.10 USDC)
KEEPER_RESERVE_LOW_WATER 0.04096 NEAR Refund reserve alert, in yoctoNEAR
KEEPER_BALANCE_LOW_WATER 2 NEAR Minimum liquid keeper balance, in yoctoNEAR. Signing needs at least this and the next transaction's full cost
KEEPER_ALERT_WEBHOOK unset Private HTTPS incoming webhook for keeper alerts

Run the keeper with its dedicated account and durable state directory. Keep that state private and backed up, and fund the account before enabling it. Check saved transactions after an uncertain result. The keeper settles purchases at or above KEEPER_MIN_PAYOUT and processes refunds within its configured budgets. Supply config.keeper.refunds when embedding serve to provide a RefundSource; see the SDK README.

Tests

The production-install container test is opt-in: ANNON_TEST_CONTAINER=1 pnpm --filter @defdone/annon-relayer test. CI runs it explicitly. Ordinary pnpm test does not install packages or contact the registry for this check.

Synced from apps/relayer/README.md at commit e649de1. Also asMarkdown.