Ledger reference

Config

Refusals carry an error code, not a sentence.

ledger({
  currencies: [
    { code: "chips", name: "Casino Chips" },
    { code: "gold", name: "Gold", decimals: 2 },
  ],
})
KeyDefault
currencies—Required, non-empty. Duplicate codes refused
currencies[].decimals0Display only. Storage is always integer minor units
adminScopeledger:adminThe scope the credit and debit routes stack
databaseDB
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, currencyUNIQUE together — one account per player per currency
balance, heldIntegers, minor units
CHECKbalance >= 0 AND held >= 0 AND held <= balance

pithy_ledger_transactions — append-only.

refUNIQUE across the whole ledger. The idempotency anchor
userId, currency, kind, amount
relatedRefTies the halves of a transfer, a payout to its wager, or a reversal to the entry it reverses
memoYours, or an operator’s reason on a management write

pithy_ledger_holds — status is open, captured or released.

Routes

RouteVerified by
GET /ledger/:currencyuser
GET /ledger/:currency/transactionsuser
POST /ledger/:currency/credituser + admin scope
POST /ledger/:currency/debituser + admin scope
GET /ledger/admin/accountscontrol-plane
GET /ledger/admin/accounts/:userIdcontrol-plane
GET /ledger/admin/accounts/:userId/:currency/transactionscontrol-plane
POST /ledger/admin/accounts/:userId/:currency/creditcontrol-plane
POST /ledger/admin/accounts/:userId/:currency/debitcontrol-plane
POST /ledger/admin/accounts/:userId/:currency/reversecontrol-plane
POST /ledger/admin/accounts/:userId/:currency/releasecontrol-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 keyThe 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 reasonRefused 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 availableA debit, and a reversal of a credit, are refused with ledger/insufficient_funds, naming the shortfall in params
Nothing is updated or deletedA 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 suffixesA client ref never ends in :reverse, :resolve, :out or :in, which the ledger writes itself
One accountA 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

ScopeDiscloses or does
ledger:accounts:readA number
ledger:transactions:readEvery wager, payout and purchase in order
ledger:accounts:adjustMoves 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_fundsFrom the CHECK, not from a handler — so it holds under concurrency
ledger/invalid_amount
ledger/account_not_found
ledger/currency_not_foundNot in your configured set
ledger/hold_not_found
ledger/hold_not_openAlready captured or released
ledger/entry_not_foundNo entry with that ref on the account named (404)
ledger/entry_not_reversibleOnly a credit or a debit reverses, and never a reversal. params.kind names the kind (409)
ledger/ref_conflictThe 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.

ESC