B7.5.2 · dive 2 of 3 · module B7.5
The transactional wallet.
Balances live in a wallet keyed by the USR account; the balance is the running total of an append-only TXN ledger, and every move is a debit and a credit applied together in one all-or-nothing transaction.
The idea
codemojex · the transactional walletA player’s balances live in a wallet keyed by their USR account, one wallet per account across every room they play. The wallet is not a number that is edited in place; it is the running total of a ledger. Every credit and debit is a TXN entry, and the balance is what the entries sum to, so the history is always there to audit.
Money moves only through the economy, and only inside a transaction. Charging a guess, crediting a purchase, paying a prize — each is a debit and a credit applied together, all-or-nothing, so a balance is never left half-changed by a crash between two steps. The reference implementation composes these as a single database transaction, which either commits whole or leaves the wallet exactly as it was.
Because the ledger is the truth and the balance is derived, the economy reconciles. A disputed charge is a row to read, not a mystery; a wallet can be rebuilt from its entries; and the same discipline that keeps a guess from charging twice keeps a payout from paying twice. The wallet sits on the Postgres floor, the record of truth, with the rest of the game’s record.
The doors
the sibling coursesEchoMQ — the protocol, in depth
The bus B3 narrates, taught rung by rung: the keyspace, the Lua inventory, and the 3.0 Stream Tier — XADD, XREADGROUP, XACK — with conformance on Valkey.
Redis Patterns Applied
The substrate patterns under the bus: sorted sets, atomic Lua moves, locks, and streams — the judgement layer.
/echo-persistenceEcho Persistence — the durable floor
Beneath the volatile tiers: the Graft page engine built twice, the commit-LSN loop, and the stream archive on Tigris. Where Part I says state lives somewhere, this says where it lives durably.
References
sources · relatedSources
- Ecto.Multi — composable, single-transaction database operationsthe one transaction a debit and a credit are applied in together
- Kreps — The Log: real-time data’s unifying abstractionthe ledger as an append-only log whose entries the balance is derived from
- Helland — Life Beyond Distributed Transactions (CIDR 2007)a wallet and a bank as durable entities, the ledger as the record of truth
Related
- BCS — the course homethe law, the id anatomy, the chapter map
- Echo Persistencethe durable floor beneath the bus