@nelo/voucher
The 202-byte wire format, and the two conversions between Android and Solana.
0..105 must match VoucherArgs::signed_message() byte for byte. vectors/voucher-v1.json is the frozen proof: generated by Rust (the chain is authoritative), asserted by both sides.
38 tests. See Voucher format.
@nelo/pay
Solana Pay requests, payment validation, currency arithmetic, the oracle guard, and balance reads.
Currency arithmetic
The rounding directions are opposite, and both are deliberate:A fraction of a cent per sale is a reconciliation problem by the end of the week. When charging, the remainder lands in the merchant’s favour; when displaying, it never claims more than is held.
Payment validation
transfer, transferChecked, batched, or routed through several instructions.
The oracle guard
Balance
getTokenAccountsByOwner, so there is no ATA derivation to get wrong. The mint is re-checked on the way back — trusting a filter you did not verify is how someone ends up looking at a balance denominated in something else.
64 tests.
@nelo/ledger
The day-book: sale records, day boundaries, close-of-day totals.
A merchant’s day is their local day. A sale at 23:50 belongs to that day, not to tomorrow because UTC has already rolled over. Get this wrong and the close-of-day total silently disagrees with the cash in the tin.
reconcileDay sorts everything sold on a day into received (on the spot, or offline and settled), still coming, needs a look, and lost, and the four always add up to what was sold. An offline sale belongs to the day the goods changed hands, not the day it settled. What is still coming from earlier days is shown apart from the day’s figures.
It also checks the till’s two records against each other. A settled offline payment is in both the queue and the day-book, and it is counted once. A payment settled but missing from the day-book, a day-book row the queue says has not settled or never took, and a disagreement on the amount are each reported rather than resolved by picking one.
22 tests.
@nelo/attest
Expo native module wrapping Android StrongBox.
isStrongBoxAvailable() === false as an ordinary case, not an error.
The Kotlin side does one conversion it cannot delegate: BigInteger.toByteArray() is signed and variable-width, so affine coordinates are pinned to exactly 32 bytes before they leave. Everything else is done in TypeScript, in @nelo/voucher, so it is covered by tests that run without a handset.
@nelo/onboard
The checkable half of merchant onboarding: what a merchant types, and whether it can be paid.
Not a libphonenumber reimplementation
Global numbering is a large, frequently-changing dataset. A half-remembered subset of it would reject real merchants while looking authoritative — so the launch markets are explicit table rows, and anything outside them is refused rather than guessed.Adding a market is a row in
MARKETS plus its tests. If the table ever becomes the problem, that is the point to take the dependency.Two things that fell out of building it
The markets overlap.0917… is a real Nigerian prefix and a real Philippine one. The same typed string is a different person depending on market, and no digit inspection can tell you which — which is why market is a required parameter rather than something inferred.
SMS is the whole login mechanism, so a non-mobile line cannot complete onboarding. The refusal says exactly that, and deliberately does not say “landline”: a 10-digit number on a non-mobile prefix is not a landline either, since real landlines in both markets are shorter and fail on length. Claiming more would be a guess dressed as a diagnosis.
The canonical form
DisburseRequest.destination in @nelo/settle is a single string, but a bank payout needs two facts — institution and account. So the string carries both and parses back:
parseCanonical re-validates rather than trusting the string — it may have come off a phone, out of a database, or from a partner callback, and a destination that is wrong is money going somewhere else.
The flow is a state machine, and that is why it is here
The Privy wiring — SMS code, embedded wallet — needs an app ID, a development build and a handset. What it does not need is any of the deciding: which step the merchant is on, whether what they typed is acceptable, whether a tap is allowed yet, what a failure means. Soflow.ts holds all of that as reduce(state, event, now) returning the next state and at most one effect for the caller to perform, and apps/merchant/src/privy.ts is left with: call the SDK, report back.
A result is only accepted while the effect that produces it is in flight, and only in the step that could have asked for it. A late promise, a remount or a double tap then cannot advance the flow twice.
busy alone is not sufficient, and the difference is not hypothetical: an effect that starts the next effect leaves busy set across the handover, so a duplicate logged-in sails through a busy-only guard and creates a second wallet — the one failure in this flow with no undo, because the merchant ends up holding an address the day-book has never seen. Two tests pin it shut.Whose problem is it?
explain() labels every failure merchant or operator, and the screen renders them differently.
“That code is not right” is fixable by the person holding the phone. “SMS login is not enabled for this Privy app” is a dashboard setting — showing it as though they mistyped something has them retype a perfectly good number until they give up. The codes are Privy’s own, read off PrivyApiError.code and PrivyClientError.code; anything unrecognised is passed through rather than replaced, because a reassuring “something went wrong” on a first development build is how a configuration problem stays invisible for an afternoon.
60 tests.
@nelo/reserve
The insurance line, modelled. Exposure → reserve requirement → what the SKR premium can be.
@nelo/redeem
The transaction a merchant broadcasts on reconnect to turn a voucher into USDC. Two instructions, in this order:
@solana/kit’s instruction shape, so they drop into a kit transaction message.
Nothing may come before the precompile. redeem_voucher reads it at instruction index 0. Some wallets prepend a ComputeBudget instruction for priority fees when they sign; that would move the precompile to index 1 and fail every redemption. Compute-budget instructions work from any position, so append them after these two.
Pinned to the program, not to a reading of it. programs/nelo_vault/tests/tx_vectors.rs generates vectors/redeem-v1.json from Anchor’s own instruction::RedeemVoucher and accounts::RedeemVoucher, anchor_spl’s ATA derivation, and the crate’s precompile_instruction_data. The LiteSVM suite uses that same writer to submit vouchers to the real precompile, so the layout both sides share is one the chain has accepted.
PDAs without crypto.subtle. @solana/addresses derives addresses through WebCrypto, which Hermes lacks and neither app polyfills. This package derives them synchronously with SHA-256 and an on-curve check written to match curve25519-dalek, which is what the runtime runs, rather than stricter RFC 8032 decoding. The two differ on non-canonical encodings, and one disagreement would be a PDA the program does not recognise. The vectors carry dalek’s verdict on those encodings, and the tests compare against @solana/addresses on 400 random points and 120 derivations.
High-S signatures are folded here too. A high-S signature verifies offline, so a merchant takes the voucher, but the precompile then rejects it. Folding needs no key, so the builder does it.
Double spends too. checkConflict(a, b) says whether two packets prove one: same vault, same sequence, different messages, same key, and both signatures valid. reportConflictInstructions(a, b, reporter) returns the two precompile instructions and report_conflict, in the order the program reads them. slashInstruction builds the permissionless crank that moves a frozen vault’s stake to the reserve. All three are pinned to vectors the program generates.
The cash-out transfer too. buildCashout is the merchant’s USDC to a payout partner’s deposit address, with the relayer as fee payer, and checkOwnerSigned accepts only the exact message with the merchant’s valid signature. transfer_checked and the deposit account’s create_idempotent are pinned to vectors generated by the SPL crates themselves.
45 tests. Broadcast on devnet by the offline rehearsal and, for cash-outs, on mainnet.
@nelo/cashout
The phone’s side of cashing out to a bank: open the order with the settlement service, have the relayer build the transfer, sign it, submit it, report it.
@nelo/rpc
RPC failover. One endpoint is one point of failure for every till, every payer and the relayer, and a rate limit looks, from a till, exactly like a customer who has not paid.
-32005, or a rate limit). Everything else is an answer and is returned as it is. A simulation failure asked of a second node gets the same answer and hides the bug.
Resending a transaction is safe. It carries the same signed bytes, so it is the same transaction, and the chain runs it at most once.
An endpoint that failed rests for 30 s so it is not asked first on every request. If all are resting, all are still tried. Error messages name hosts, never URLs, so an API key in a query string is never logged.
10 tests.
@nelo/rebate
The merchant’s monthly choice of how their rebate is paid: cash, the default, or SKR at a premium, already staked.
DISCLOSURE is one plain sentence about price risk, with a version. An acknowledgement is of a particular wording, so changing it makes every merchant accept again before choosing SKR.
A choice applies from next month. Choosing mid-month, after seeing SKR’s price, would let a merchant pick the winner in hindsight at the platform’s cost.
The premium is labelled until it is priced. ILLUSTRATIVE_PREMIUM is BUILD.md’s 1.5× placeholder and says so. @nelo/reserve’s premiumCeiling is where the real number has to come from.
9 tests.
@nelo/queue
The merchant’s offline queue: vouchers taken and not yet paid, and what to do about each one when the network comes back.
expiresAt, and the queue keeps trying for five minutes past it, because the chain’s clock is the one that counts.
Every chain answer means one of four things:
The codes come from
vectors/program-errors-v1.json, which the program generates from NeloError. Inserting an error variant mid-list fails that test before it can make the queue misread the chain.
It never mistakes its own success for fraud. A signature is stored before its transaction is sent. An entry with an attempt in flight is looked up with searchTransactionHistory, never resent. And “already redeemed” is believed only once every attempt of the merchant’s own is known not to have landed.
Signing is injected. SettleDeps.prepare builds with @nelo/redeem, signs, and returns the signature without sending. In the merchant app the relayer does it, so the merchant signs nothing. A relayer decline marked conflict is refused as paid to someone else.
standing(entry) puts an entry in the four words close of day uses: settled, owed, held or lost, with why in words a merchant can act on.
relayPrepare, reportConflict and rpcStatuses are the network half of settling, shared by the merchant’s till and a customer who was paid by another: the relayer builds, pays for and sends each redemption. fetch is injected, so they are tested as they run.
63 tests, against a fake network. Wired into the merchant app and the payer app, and running in their release builds.
@nelo/till
What a phone that takes vouchers needs, whether it is a merchant’s till or a customer being paid by another customer. A voucher does not know what a merchant is.
voucherDb is written against the four calls expo-sqlite and Node’s node:sqlite share, and tested on the second, including a close and reopen. The merchant app’s schema is unchanged by the move.
17 tests, including the two-phone sale and the two-customer transfer end to end.