Numary
Numary Technical Briefing
Published November 9, 2021
Overview
Clément of Numary demos Numary\'s open-source ledger and Numscript — a DSL purpose-built to model the hidden money-flow complexity of marketplaces and platforms (where customer payments, commission splits, and seller payouts quickly become an operational mess). The demo clones a DoorDash-style marketplace in Numscript: a "world" account injects funds, a coupon account funds a $15k FALL21 marketing campaign with a $10-per-redemption metadata value, an order\'s payment account pulls first from the user\'s wallet and falls back to world, and a single atomic Numscript splits the order payment four ways — 85% to the restaurant, a delivery amount to the rider, platform fees, and VAT-applicable taxes. Each step produces a transaction with clean source/destination postings in the Numary ledger, which the fintech later reconciles against Stripe, Wise, or their payment provider of record. The closing rider payout demonstrates the reconciliation handoff between Numary\'s internal ledger and the external payment system — the Numscript repo is open-sourced on GitHub at github.com/numary.
0:00 Introduction to Numary and Numscript
Clément (Numary) demos Numary's open-source ledger and Numscript, the DSL designed to model complex money flows in marketplaces and platforms — where inflows, outflows, and commission splits quickly create a hidden mess in the back office.
1:30 Modeling the DoorDash money flow
The "blue part" of a marketplace flowchart — decoupling customer payments from seller payouts — is where ledgers become necessary. The demo clones DoorDash-style flows with riders, restaurants, a platform commission, and marketing coupons.
2:30 Numscript basics — world account and postings
Numscript moves assets between accounts. The "world" account is the only one allowed to spend money it doesn't have, letting developers inject funds into the ledger. A simple send from world → user_01 creates a single-posting transaction.
4:00 Multiple destinations with percentages
Numscript supports multiple destinations in one transaction — e.g. 10% to user_01 and the remainder to user_02 — producing a transaction with two postings. This is the primitive behind every split in the demo.
4:30 Funding marketing coupons
The first real Numscript models a coupon: $15k budget set aside for code "FALL21", with every redemption worth $10. The coupon is a first-class account in the ledger with metadata for per-use value — so the platform can never overspend the marketing budget.
7:30 Redeeming a coupon into a user wallet
When a user enters the coupon code, a Numscript reads the coupon's per-use value from metadata and credits the user's wallet. This produces a second transaction — 10 moved from the FALL21 coupon account to user_42's wallet.
9:30 Order payment — pull from wallet, then from world
Order payments use Numscript's source chaining: pull first from the user's wallet, then fall back to the world account to synthesize the remainder (reconciled later with Stripe). Two postings record both source flows into a single payment account per order.
11:30 Split an order across rider, restaurant, platform, taxes, fees
A final Numscript splits the payment account into four postings: restaurant (85%), delivery rider, platform (with 20% of that going to taxes on VAT-applicable items), and platform fees — all in one atomic transaction.
13:30 Paying out the rider
A closing Numscript registers the actual payout to the rider's external account — a transaction that would later be reconciled against the upstream payment system (Stripe, Wise, etc.).
Presented by Clément Salaün — Numary · LinkedIn · website
Topics: Payments, Developer Tools
