Skip to main content
Everything here is pure and testable off-device. That is the point: it is the arithmetic that would otherwise hide inside a phone or a validator, where nobody could check it.

@nelo/voucher

The 202-byte wire format, and the two conversions between Android and Solana.
The layout is a contract with the on-chain program — bytes 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.
The only package with a runtime dependency (@noble/curves), so it is the one suite that needs pnpm install before it runs.
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

Finding a transaction that names your reference is not proof of payment. Anyone can build a transaction naming any account. Every payment is validated against what was asked — right payee, right mint, enough money, transaction did not fail. Underpayment is refused, and the merchant is told “that was not enough” rather than left looking at a spinner.
Validation works off the token-balance deltas in transaction metadata rather than by decoding instructions: the metadata carries the account owner, so it needs no associated-token-address derivation and is indifferent to whether the wallet used transfer, transferChecked, batched, or routed through several instructions.

The oracle guard

A quote is not a number — it is a number plus “how old?” and “how sure?”, and both are refused rather than displayed. Defaults: stale past 30s, confidence band wider than 50 bps. Also refuses a quote from the future (that is a clock problem, and just as untrustworthy), a non-positive price, and a negative confidence. Provider-agnostic: Pyth and Switchboard publish the same shape.

Balance

Reads via 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.
The timezone offset is passed in rather than read from the environment, so it is deterministic under test — including non-whole-hour offsets like Chatham Islands (UTC+12:45). Close of day counts offline payments too. The day-book holds money that has arrived, but offline, goods go before the money. 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.
It never falls back to a software key. setIsStrongBoxBacked(true) throws on a handset with no secure element, and that exception is deliberately not retried without the flag.A silent fallback would keep the app working while destroying the entire security argument. A handset without StrongBox degrades to online-only instead.
StrongBox is API 28+ and absent on much budget hardware — which is the hardware this product targets. Treat 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.
Never compiled. Requires a JDK and Android SDK; it compiles for the first time during an EAS build. See Testing.

@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:
Colon-delimited because no field can contain a colon, which makes the parse unambiguous rather than usually-right. Tested as a round trip, and 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. So flow.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.
The NUBAN check digit is advisory and must stay that way. It is implemented because it catches transposed digits, and it is non-blocking because it has not been validated against real account numbers. Refusing a merchant’s actual account on an unverified algorithm is a lost merchant; accepting a typo is a payout the partner bounces with a clear reason.
60 tests.

@nelo/reserve

The insurance line, modelled. Exposure → reserve requirement → what the SKR premium can be.
Run the report:
It prints its unsourced assumptions first, deliberately — every figure below them inherits that uncertainty. 17 tests. See The reserve model.

@nelo/redeem

The transaction a merchant broadcasts on reconnect to turn a voucher into USDC. Two instructions, in this order:
The objects are @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.
Resumable because every step is idempotent. The phone makes the cash-out’s id once and keeps it; run again after any interruption, the flow picks up where it stopped. A test interrupts it at each step in turn and checks the USDC moves once. A message signer’s signature is checked before use. A transaction signature is a signature over its message bytes, so Privy’s message signing can sign one, but only if it signed exactly those bytes. The result is verified against the owner’s key, trying each encoding, and anything that does not verify is refused. 6 tests.

@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.
It moves on only when an endpoint did not answer: a network error, a timeout (8 s), HTTP 401 or 403 (the endpoint refused its own API key), HTTP 429 or 5xx, or a JSON-RPC error about the node (-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.
SKR needs the disclosure accepted, as it reads now. 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.
It holds vouchers, not transactions, so it needs no durable nonces. Each redemption is built and signed when it is sent, with a fresh blockhash. The only deadline is the voucher’s own 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.