Skip to main content
The relayer is why a merchant needs no SOL and never signs anything. redeem_voucher’s only signer is whoever pays the fee, and the program pays exactly the merchant the voucher names. So the relayer submits the voucher and pays, and it cannot redirect the money. It runs as one small Node process. Until hosting (next on the roadmap) it runs on a single machine — a Mac in the commands below — behind a tunnel, because the phones are on mobile data and cannot reach a laptop on a home network.
For release APKs, use the stable address in Release builds: ngrok’s fixed domain in front of pnpm gateway, which serves the relayer and the settlement service from one https address that never changes. The quick tunnel and LAN set-ups below are for development builds only: a release APK compiles its addresses in and Android refuses plain http outside development.

What it will pay for

A refusal on budget or the per-vault cap tells the till to retry later; any other refusal is held for a person to look at.

Run it on the Mac

1

Set up every setting, once

This writes the relayer’s settings to ~/.config/nelo/relay.env and the settlement service’s to ~/.config/nelo/settle.env, both owner-only, and creates apps/merchant/.env and apps/payer/.env from their examples if they are missing. It generates the tokens and copies them into the apps, so the two ends always match. Then it lists what is still blank.It never changes a value you have set, and it keeps the tokens it generated, so run it again whenever you like.
2

Fill in the keys it asks for

Open the files it names and paste in:
  • RELAY_RPC_URL in ~/.config/nelo/relay.env: your Helius devnet URL. If one of the apps’ .env already has one, it is copied across for you.
  • PAJ_API_KEY and PAJ_WEBHOOK_SECRET (whsec_…) in ~/.config/nelo/settle.env: Nelo’s paj.cash business key and its signing secret. Production only; paj.cash has no staging.
  • RELAY_CASHOUT_RPC_URL in ~/.config/nelo/relay.env: a mainnet RPC (your Helius mainnet URL), for cash-outs. It is copied to the merchant app too.
3

A fee-payer key, funded with devnet SOL

If the airdrop is rate-limited, use faucet.solana.com with that address. This key pays fees and nothing else: it has no authority over the program or anyone’s funds. Keep it out of the repo like every other keypair.
4

Rehearse the gate on devnet

Before the phones, prove the whole path on devnet: an offline sale, settling through a relayer, the replay refused, a double spend frozen and slashed. It uses the RPC in relay.env and pays from ~/.config/solana/id.json if that exists, otherwise from the fee-payer key; pass --keypair <file> to choose. It needs about 0.2 SOL, runs its own relayer with its own throwaway fee payer, and sends what is left back. It ends with GATE REHEARSAL PASSED or names the step that failed. See the gate rehearsal.
5

Start it, and put a tunnel in front of it

It listens on 127.0.0.1:8787 and needs Node 22.18 or later. Keep the ledger file it writes: it is how a retried voucher gets the same answer, so it must survive restarts. Check the tunnel from a phone’s browser: open the address cloudflared printed, with /v1/health on the end. It should show the fee payer’s address. If cloudflared’s precheck says Allow outbound TCP on port 7844, the network blocks tunnels altogether. With the phones on the Mac’s Wi-Fi, skip the tunnel: add export RELAY_HOST=0.0.0.0 to relay.env, restart the relay, and run pnpm setup:env --relay-url http://<the Mac's Wi-Fi address>:8787 (System Settings → Wi-Fi → Details shows it). A development build allows plain http, as it does for Metro.
6

Point the apps at it

This writes the address into both apps’ .env. A quick tunnel’s address changes whenever cloudflared restarts, so run this again each time. Then restart Metro with npx expo start --dev-client --clear; no new native build is needed.

Keeping it up

Until the services are hosted, the machine running them must be awake whenever a till settles. caffeinate -i in a spare terminal stops it sleeping. If the relayer is down, nothing is lost: the till treats it as offline, keeps the vouchers queued, and tries again on the next round.

Why it never submits a voucher twice

The till records the signature only after the relayer answers. A till that crashes in between asks again, so the relayer answers a voucher it has already submitted with the same signature, for as long as that transaction can still land. It builds a new one only once the old one is not on chain and its blockhash has expired. Otherwise the till would see “already redeemed” on the second transaction and report its own payment as a double spend. The submission is written to the ledger before the transaction is sent, and requests are handled one at a time. services/relay/test/ pins both, with a control test that shows the duplicate send happening without them.

Cash-outs through paj.cash

The settlement service (services/settle) opens payout orders with paj.cash, and the relayer pays the fee on the merchant’s transfer to the order’s deposit address. It runs on the same Mac, behind pnpm gateway at <address>/settle (Release builds), or behind its own tunnel in development. This is real money. paj.cash’s v2 API is production only and settles in mainnet USDC. Offline payments stay on devnet; a cash-out moves mainnet USDC from the merchant’s wallet, and the relayer pays its fee in mainnet SOL.
1

Tell the setup where it is

This writes the address to SETTLE_PUBLIC_URL, which paj.cash’s webhook uses, and to the merchant app’s .env. PAJ_API_KEY and PAJ_WEBHOOK_SECRET must be in ~/.config/nelo/settle.env by now. There is no login step: v2 uses the API key alone.
2

Fetch the webhook signing secret

The dashboard does not always show the key’s whsec_… secret. This points the key’s order webhook at this service, saves the secret paj.cash returns to settle.env as PAJ_WEBHOOK_SECRET (never printed), and asks paj.cash for a test delivery. It moves no money. Optional: without the secret, webhooks are not signature-checked, and the till asks paj.cash directly anyway.
3

Give the fee payer mainnet SOL

Send about 0.01 SOL to that address on mainnet from any wallet (there is no airdrop on mainnet). Each cash-out costs it about 0.000005 SOL.
4

Start it

It warns if the mint is not mainnet USDC, or if there is no signing secret. Restart Metro with --clear. The till then shows paj.cash’s naira rate, and the balance opens Cash out.
5

Fund the merchant's wallet

The cash-out screen reads the merchant wallet’s mainnet USDC. Send it at least $0.50 of mainnet USDC: paj.cash pays out $0.50 to $10,000 at a time, and money sent below the minimum only comes back by a manual refund.
Cash-outs per merchant a day are unlimited by default; set RELAY_CASHOUTS_PER_DAY to cap them, counted when the relayer signs one. paj.cash’s pooled deposit addresses may never have held USDC, so on mainnet the relayer opens the token account when one is missing (about 0.002 SOL rent, RELAY_SPONSOR_DEPOSIT_ACCOUNTS=false to stop it). The relayer signs each cash-out before the wallet sees it and sets its own priority fee (RELAY_CASHOUT_PRIORITY, default 100000 micro-lamports per unit on mainnet), because wallets add one to an unsigned transaction and the relayer refuses a message it did not build. The settlement service counts funded cash-outs toward SETTLE_CASHOUTS_PER_DAY (default unlimited); when it is set, orders opened and never funded have a separate cap of four times that. USDC sent to the fee payer by mistake goes back with cd services/relay && pnpm withdraw --to <wallet> --amount <n> (add --yes to send). If a payout fails (ERROR), paj.cash refunds or retries it on request: the till shows the order id to quote. An unfunded order’s address goes back to paj.cash’s pool after two hours, so the service closes a cash-out still unfunded after 90 minutes; the merchant starts a new one.

Every setting

pnpm setup:env writes all of these; this is what each one is. Every EXPO_PUBLIC_ value is compiled into the app and readable by anyone holding the APK. The RPC URL and the two tokens are fine there; PAJ_API_KEY, PAJ_WEBHOOK_SECRET and the fee-payer key are not, and live only on the Mac.

Double spends

Two different vouchers from one vault with the same sequence number are proof that the payer spent the same money twice. The relayer acts on that proof in two steps:
  1. Report. It sends report_conflict, which freezes the vault for good. The proof can come from two places:
    • a till that scanned both vouchers posts the pair to POST /v1/conflict with { "a": "<base64>", "b": "<base64>" };
    • the relayer sees it itself when a second till submits a different voucher at a sequence it already submitted. That till’s voucher is declined with conflict: true, and the report goes out at once.
  2. Slash. Every minute, a sweep looks at each reported vault. Once the vault is frozen and still holds stake, the sweep sends slash, which moves the stake to the reserve. The log shows slashed <vault>: <signature>.
The relayer checks both signatures before it pays for anything. It sends nothing for a vault that is already frozen, and a repeated report gets the same transaction back. Reports are kept in the ledger file with everything else.