Ledger

Backed by: @pithy-sh/ledger. Scopes: ledger:accounts:read · ledger:transactions:read · ledger:accounts:adjust.

What it shows

Ledger is the capability it reads, holds and settlement is what held means, currencies and minor units is why an amount is a whole number, and users is the person behind a player id.

Your players’ balances, and the entry log behind each one, read live from your Worker. It appears in the rail when your Worker composes the ledger, at whatever path you mounted it.

The index lists accounts, a page at a time. One row per player per currency, because each is its own account: the player id, and the balance in that currency. More reads the next page; End of the list. says there is none.

Currency is sent to your Worker, so it answers over every account, and offers the currencies the accounts read hold. Held funds (some held, or none) and Balance (zero, or not zero) narrow this page only. The overview is how the filter panel works.

The record is one player, in every currency they hold. Each currency shows three figures: the balance, the part of it open holds reserve, and what is available to spend.

The player id links to their user record when the Users pane is there to open it. Without auth composed, or without the scope to read users, it is a bare id.

An amount is drawn as sent

The whole number your Worker stored, grouped for reading, and the currency’s own name: 1,250 chips.

No decimal point and no symbol. The ledger carries no exponent and the currency is a name from your own catalog, so either one drawn here would be money we invented.

The entry log is a second scope

A balance is a number. An entry log is a behavioral record: every wager, payout and purchase in order, with whatever memo your own code wrote on it.

So the log sits behind ledger:transactions:read, and the balance behind ledger:accounts:read. Both are reads, so both are in the default grant. A connection narrowed to balances alone shows every balance, and each currency’s log names the scope it was not granted and sends nothing.

A log is read only when you open it, one currency at a time, newest entry first and a page at a time. Each entry shows what moved and by how much, its ref, the entry it answers (a hold, the other side of a transfer, or the entry a reversal reversed), and its memo, drawn as text.

Correcting a ledger

Four acts, on the player the record shows: credit and debit a balance, reverse an entry, and release a hold. Each one opens a form that previews the balance and what is available before and after, asks why, and confirms once.

ActWhere it is offeredWhat it does
CreditOn each currency’s balanceAdds the whole number you type
DebitOn each currency’s balanceTakes away the whole number you type
ReverseOn a credit or a debit in the log that is not itself a reversal and has not been reversedWrites the opposite entry for the same amount
ReleaseOn a hold in the log that nothing has released or capturedFrees what the hold reserved, so it is available again. The balance does not move

An amount is a positive whole number, typed as digits, and a reason is required, up to 500 characters. The reason is kept as the entry’s memo. While one form is open on a currency, no other act on that currency can be pressed.

Each opening of a credit or a debit mints one idempotency key, sent as the entry’s ref, so a second press or a retry moves the money once. A reversal and a release are keyed by the entry and the hold they name.

What is shown after an act is your Worker’s answer. A write that lands closes the form, and the account and its log read again. A refusal your Worker names stays in the form, in plain words: no such currency, account, entry or hold, not enough available, a hold already released or captured, an amount that is not a positive whole number, an entry that cannot be reversed, or a key another entry already holds.

A write whose answer was lost may have landed. The form stays open with the amount it was sent with, the account and its log read again, and it closes only once you tick I have checked the account against that later answer. Dropping the key is a choice made with the balance in view.

On every plan, and on Team

The reads render on every plan. Seeing balances and entry logs costs nothing.

The four acts are Team. Below it they are drawn locked, saying what Team buys.

The acts are a third scope

ledger:accounts:adjust is all four acts, and your Worker declares it charges, because it moves money. So it is never in the default grant, and the acts are an owner’s: an admin sees them locked and marked for the owner, as roles and permissions sets out. A connection without the scope shows the acts unavailable, with the scope they need. Scopes has how to add one to a connection made before it existed.

An act your Worker declares no route for is not drawn.

It keeps nothing

Nothing here is kept. Balances and entries are fetched from your Worker for this screen and held in no Pithy table.

ESC