@nelo/settle
The record of who is owed what. An auditor, a payout partner and a merchant with a complaint all read this, and all three must see the same number — so the rules are enforced in the ledger rather than trusted to its callers.
Three rules, each a test
Every transaction balances, per currency
Every transaction balances, per currency
A payout touches USDC and naira in the same economic event. A ledger that balanced them together would net a dollar against a naira and call it square.Each currency balances on its own. Debits are positive, credits negative, and the check is “these sum to zero” — which is impossible to fudge.
Posting is idempotent
Posting is idempotent
Retries are the normal case, not the edge one: a partner webhook arrives twice, a relay resends, an operator re-runs a batch.Every transaction carries an id the outside world already made unique — an on-chain signature, a partner reference. A generated id defeats the point, because a retry generates a different one. Re-posting an id changes nothing and returns
{ posted: false, reason: "duplicate" }.The journal is append-only
The journal is append-only
Nothing is edited or deleted. A mistake is corrected by posting its reversal, so the history of what was believed, and when, survives.
The chart of accounts
Declared, not inferred. A ledger that opens an account whenever it sees a new string will happily balance a typo against itself and report a clean trial balance with the money in the wrong place.
Sub-accounts inherit their parent’s type:
liabilities:payable:m1 is a liability because liabilities:payable is.
The payout lifecycle
The spread is a difference, never a percentage
splitSale: net is computed by subtraction, not by its own percentage, so fee and merchant share always add back to exactly what the customer paid.
Reconciliation
The partner is a declared stub
Swapping in a licensed partner is a constructor change. That is deliberate: it pre-takes the project’s declared fork — “stub the settlement leg and say so, or settle merchant to merchant in USDC” — so the decision costs a line rather than a week.Cash-outs through paj.cash
PajPartner implements the same interface against paj.cash’s v2 API, with one credential, the business API key, sent as x-api-key. paj.cash has no staging environment, so fidelity is "live": every cash-out is real, in mainnet USDC, while offline payments, vaults and redemptions stay on devnet. It is tested against a fake of the documented API and has not yet sent a payout.
paj.cash is paid by a transfer: an order gives a one-off deposit address, and the bank is paid about 20 seconds after the USDC arrives, 24/7. The merchant’s wallet sends it on mainnet, and the relayer pays the fee.
- Orders, not the standing address. v2 can give a bank account a permanent deposit address, but paj.cash sends no webhook and keeps no readable record for deposits there, so the till could never confirm a payout. An order has an id, a status, a signed webhook and a record.
- The name enquiry is registration.
POST /pub/v2/bank-accountconfirms the account with the bank and returns the holder’s name; it is idempotent and slow (a live bank call), so the client allows 35 s. - paj.cash’s limits, before any order: $0.50 to $10,000 per payout. Below the minimum, money sent only comes back by a manual refund, so it is refused up front.
- Banks by paj.cash’s own code. NIBSS codes today, CBN 3-digit codes later. A code is matched exactly against paj.cash’s list; one it no longer lists is refused with a reason, never guessed.
- One cash-out id, one order, one transfer. paj.cash takes no idempotency key, so the record is written before it is asked, and again with the deposit address before the app is told where to send.
- A deposit address is not kept past its life. paj.cash returns an unfunded order’s address to its pool after two hours. A cash-out still unfunded after 90 minutes is closed, unless paj.cash’s record shows the USDC arrived; a transfer reported inside the two hours is still followed.
- paj.cash’s numbers are decimals. They are read through their text, exact both ways, and refused rather than rounded when a JSON number cannot carry them. Every request body is built field by field: paj.cash rejects unknown fields.
- Webhooks are signed and still only a prompt. With
PAJ_WEBHOOK_SECRETset, a delivery must carry a validX-PAJ-Signature(HMAC-SHA256 over{timestamp}.{raw body}, five-minute window) or it is refused. A verified body still only names an order; the service asks paj.cash’s API about it. The path carries a secret too. - States:
INIT→ awaiting funds,PROCESSING→ paying the bank,COMPLETED→ paid,ERROR→ failed, with the order id to quote, since paj.cash refunds or retries a failed payout on request. State only moves forward, and “paid” is final. - A refused key is the operator’s problem, not a refusal: the app says cash-outs are paused and the same cash-out goes through once the key is fixed.
@nelo/relay
Submits a merchant’s offline vouchers and pays their fees, so the merchant needs no SOL and signs nothing. redeem_voucher pays exactly the merchant the voucher names, so the relayer can submit a voucher but cannot redirect it.
report_conflict. A sweep every minute then cranks slash on each frozen vault that still holds stake.
Cash-out transfers. POST /v1/cashout/prepare builds the merchant’s transfer to a paj.cash deposit address with the relayer as fee payer; POST /v1/cashout/submit co-signs it only if it is exactly that message with the merchant’s valid signature. It never parses a transaction someone else wrote. Bounded by mint, a daily count per merchant, the shared budget, and rent for a deposit account that has none (on by default for mainnet USDC). It signs as fee payer before the wallet does, and sets its own priority fee, so wallets leave the message as built. Cash-outs run on their own cluster: with RELAY_CASHOUT_RPC_URL set they are built and sent on mainnet in mainnet USDC (RELAY_CASHOUT_MINT), while redemptions stay on devnet. The same fee payer signs both, so it needs a little mainnet SOL.
No durable nonces, since it signs each redemption fresh. RPC failover through @nelo/rpc: RELAY_RPC_FALLBACK_URLS are tried in order when RELAY_RPC_URL does not answer. Running it: the relayer runbook.
63 tests, against a fake network.