Config
Refusals carry an error code, not a sentence.
ledger({
currencies: [
{ code: "chips", name: "Casino Chips" },
{ code: "gold", name: "Gold", decimals: 2 },
],
})| Key | Default | |
|---|---|---|
currencies | — | Required, non-empty. Duplicate codes refused |
currencies[].decimals | 0 | Display only. Storage is always integer minor units |
adminScope | ledger:admin | The scope the credit and debit routes stack |
database | DB | |
basePath | /ledger |
The in-process API
const ledger = openLedger(env.DB);| Call | |
|---|---|
credit(userId, currency, amount, ref, { memo? }) | Opens the account if absent |
debit(userId, currency, amount, ref, { memo? }) | Fails if the available balance cannot cover it |
reverse(ref, { memo? }) | The opposite of a credit or a debit, as a new entry <ref>:reverse. The original stays |
transfer(from, to, currency, amount, ref, { memo? }) | Atomic |
hold(userId, currency, amount, ref) | Reserves. Balance unchanged |
capture(ref, { amount?, memo? }) | The stake is spent. amount captures part of it, never more than was held |
release(ref, { memo? }) | The stake returns |
balance(userId, currency) | { balance, held, available } |
reverse is idempotent by its derived ref: a second reversal of one entry moves nothing. It refuses any kind but a credit or a debit, and a reversal of a reversal, with ledger/entry_not_reversible. Reversing a credit the account can no longer cover is ledger/insufficient_funds, naming the shortfall, and a <ref>:reverse an unrelated entry already holds is ledger/ref_conflict rather than a replay.
Tables
Every constraint below is one of the three invariants written down.
pithy_ledger_accounts
userId, currency | UNIQUE together — one account per player per currency |
balance, held | Integers, minor units |
CHECK | balance >= 0 AND held >= 0 AND held <= balance |
pithy_ledger_transactions — append-only.
ref | UNIQUE across the whole ledger. The idempotency anchor |
userId, currency, kind, amount | |
relatedRef | Ties the halves of a transfer, a payout to its wager, or a reversal to the entry it reverses |
memo | Yours, or an operator’s reason on a management write |
pithy_ledger_holds — status is open, captured or released.
Routes
| Route | Verified by |
|---|---|
GET /ledger/:currency | user |
GET /ledger/:currency/transactions | user |
POST /ledger/:currency/credit | user + admin scope |
POST /ledger/:currency/debit | user + admin scope |
GET /ledger/admin/accounts | control-plane |
GET /ledger/admin/accounts/:userId | control-plane |
GET /ledger/admin/accounts/:userId/:currency/transactions | control-plane |
POST /ledger/admin/accounts/:userId/:currency/credit | control-plane |
POST /ledger/admin/accounts/:userId/:currency/debit | control-plane |
POST /ledger/admin/accounts/:userId/:currency/reverse | control-plane |
POST /ledger/admin/accounts/:userId/:currency/release | control-plane |
A player’s read is always scoped to the authenticated caller — never a user id in a request body. Your own code moves balances in-process: Using Ledger has the calls, and holds and settlement covers the three-call shape. The four control-plane writes are how a person corrects an account from a console.
Management writes
Each carries every guarantee the in-process ledger gives, and two a console needs. The body is { amount, ref, reason } for a credit or a debit and { ref, reason } for a reversal or a release. The account is the path, never the body, and a body naming a field of its own is a 400.
| Rule | |
|---|---|
| An idempotency key | The client chooses ref, written as the entry’s ref, so a double-click moves the balance once. A replay answers 200 with the balance as it stands and applied: false |
| A required reason | Refused when blank, before anything is written. Stored as the entry’s memo and carried verbatim on the audit event. At most 500 characters |
Never below available | A debit, and a reversal of a credit, are refused with ledger/insufficient_funds, naming the shortfall in params |
| Nothing is updated or deleted | A reversal is the opposite movement under <ref>:reverse, with the original as its relatedRef. Two reversals of one entry sent at once post one |
| Reserved suffixes | A client ref never ends in :reverse, :resolve, :out or :in, which the ledger writes itself |
| One account | A reversal or a release names an entry or a hold on the account the path names, or it is not found and never touched |
applied: false means only a replay — the same write sent again. The same key sent for another account, for the other act, for another amount or naming a hold is ledger/ref_conflict, and so is a reversal or a release whose derived ref an unrelated entry holds. Nothing moves.
Every write that moved money writes one warning audit event — ledger/account_credited, ledger/account_debited, ledger/entry_reversed or ledger/hold_released — naming the connection, the account, the ref it wrote, the amount, the reason and the balance before and after. A replay or a refusal writes none. The response is the account as the write left it: userId, currency, ref, applied, balance, held and available.
Scopes
| Scope | Discloses or does |
|---|---|
ledger:accounts:read | A number |
ledger:transactions:read | Every wager, payout and purchase in order |
ledger:accounts:adjust | Moves money. Credit, debit, reverse, release. Reads nothing |
Three rather than one admin flag, because those are different things. Matching is exact, so neither read confers the write. ledger:accounts:adjust gates only POSTs, so pithy dashboard connect never grants it unless you pick it.
Every management call is audited, the reads included. A read records identifiers and counts, never a balance, a memo or a ref.
Error codes
| Code | |
|---|---|
ledger/insufficient_funds | From the CHECK, not from a handler — so it holds under concurrency |
ledger/invalid_amount | |
ledger/account_not_found | |
ledger/currency_not_found | Not in your configured set |
ledger/hold_not_found | |
ledger/hold_not_open | Already captured or released |
ledger/entry_not_found | No entry with that ref on the account named (404) |
ledger/entry_not_reversible | Only a credit or a debit reverses, and never a reversal. params.kind names the kind (409) |
ledger/ref_conflict | The ref belongs to a different entry. Nothing moved (409) |
What is deliberately absent
No exchange between currencies. A rate is a business decision. Build it as a debit and a credit under one ref prefix.
No hold expiry. A hold that timed out on its own would release a stake the game may still be settling.
License
MIT. The root license covers it.