Skip to main content

@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

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.
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" }.
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 merchant’s dollar claim is discharged when a payout is instructed, not when the partner confirms.The money really has left. A balance still showing it would let the same dollars pay out twice while the partner is still working.
A failure reverses the instruction exactly and the merchant is whole again — a failed payout that strands a shopkeeper’s money is the worst thing this service can do. The reversal is a new entry, not a deletion: the record shows it was attempted and why it did not land. After settlement, what remains on the partner receivable is the spread — real money the partner still owes, settled on their own remittance cycle. Leaving it visible rather than writing it off at instruction time is the difference between knowing what you are owed and hoping.

The spread is a difference, never a percentage

Both sides round down independently and the spread absorbs the remainder, so rounding cannot invent or destroy a minor unit. Quoting a merchant a better rate than the partner gives is refused loudly — that is a pricing mistake, not something to discover in a month’s revenue figures. The same principle in 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 one check that catches everything else — a missed sale, a double-posted payout, a sweep nobody recorded. Run it at close of day, and treat any drift as an incident. “Small” drift is still a transaction you cannot explain.

The partner is a declared stub

No disbursement partner has been signed. The only implementation is DeclaredStubPartner, and it is built so it cannot be mistaken for a real one:
  • fidelity: "stub" on the partner, on every quote, and on every result
  • References prefixed STUB-, unmistakable in a log, a ledger memo or a screenshot
  • assertMovesRealMoney(partner) throws for anything that is not "live"
  • Configured destinations reject, so the failure path is exercised rather than assumed — a payout that cannot fail in testing will fail for the first time in front of a merchant
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-account confirms 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_SECRET set, a delivery must carry a valid X-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.
84 tests, 45 of them for cash-outs.

@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.
Asked twice, it answers once. A voucher it has already submitted gets the same signature back while that transaction can still land. The ledger entry is written before the transaction is sent, and requests are handled one at a time. Double spends. Two vouchers at one sequence, from a till or seen by the relayer itself, are reported with 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.