aluro-selected-systems

Two subsystems, extracted and sanitized, from a merchant-of-record payments platform I designed and built solo. The platform issued invoices, collected fiat (Stripe, PayPal, P2P rails), and settled suppliers in USDC on Ethereum. It ran in production and has since been wound down; these are the parts worth reading on their own.

Provenance. Lifted from a private codebase. Business logic is intact; wallet addresses, contract addresses, key ids, and internal wiring are removed or abstracted. No secrets, no network calls in the tested path.

1. Payment matching — src/paymentMatching.ts

Fiat arrives out-of-band: a payer sends a Zelle/Cash App transfer and we learn about it from a parsed notification, not a webhook tied to an invoice. So an observed payment has to be attributed to one of several open expectations.

The engine scores each candidate on a 100-point scale — amount (40), time window (30), reference memo (20), and a uniqueness bonus (10) applied once all candidates are known — then decides whether the top match is safe to confirm automatically or must be held for a human. The parts I'd point at:

• Transposition detection (checkTransposition) — catches the common fat-finger error where a payer swaps two adjacent digits ($150.21 for $150.12). It compares the amounts in integer cents to dodge floating-point noise, and treats an overpaid swap as a near-match but blocks a materially underpaid one.
• Ambiguity gap (canAutoConfirm) — a high score is necessary but not sufficient. If the second-best candidate is within 15 points of the best, the match is ambiguous and never auto-confirms, however high the top score is.
• Cross-currency tolerance — a non-USD payment matches on its converted amount within an FX spread tolerance, flagged as such.

Pure functions, no I/O. See the tests for the behavior in full.

2. KMS-signed settlement — src/kmsSettlement.ts

Paying suppliers means holding a hot wallet, which means holding a private key — the thing you least want in application memory or an env var. Here the operating wallet's key lives in an AWS KMS HSM and never leaves it; signing is a kms:Sign API call. viem sees an ordinary Account, so the rest of the code is ordinary viem.

Two details carry the design:

• Address assertion on load (loadKmsAccount) — a wrong key id yields a perfectly valid wallet that simply isn't ours. Deriving the address from the key and asserting it equals the expected address turns a silent wrong-wallet-signing bug into a startup error.
• Receipt-based verification (verifyUsdcTransfer) — after a payout, the amount credited is re-derived by decoding the ERC-20 Transfer logs on the mined receipt and summing those to the recipient, rather than trusting the arguments we submitted.

This file is illustrative — it depends on viem and a KMS signer package and is meant to be read, not run against mainnet.

Running

Only the matching engine has tests, and they need nothing but vitest — no keys, no network:

pnpm install
pnpm test        # vitest
pnpm typecheck   # tsc --noEmit

License

MIT — see LICENSE.