Concepts
The ideas the economy is built on — read top to bottom for the full picture.
Overview
What economy-lab is (and isn't): a double-entry credit economy, provably solvent and tamper-evident, built as a library rather than a product.
The money model
A dual-rate credit economy (buy ≥ par ≥ payout) where the platform spread is the only fee and every value carries an explicit currency and scale.
Accounts & double-entry
Every operation is a balanced double-entry posting across a fixed chart of accounts: spendable, earned, promo, and the system accounts.
Solvency
Provably solvent: real USD held in trust covers users' spendable credits at par, and the backing check reports any shortfall.
Actors & authorization
Who can do what: every request names an actor (user, system, or operator) and passes a central authorization gate before any work runs.
Idempotency & retries
Every operation carries an idempotency key. The first call claims it, runs, and records its outcome; a retry with the same key replays that outcome without running again.
The payout saga
A payout reaches an external rail that answers in its own time, so it runs as a stored state machine: reserve, submit, settle — every transition a compare-and-set that posts its money in the same transaction.
Subscriptions
A subscription is a stored record the worker renews period by period: a one-charge-per-period claim keeps overlapping sweeps from double-billing, and a retry cap lapses a subscription that can no longer pay.
Credit maturity
Funds clear on a delay: spends drain oldest-first, so the matured balance is the cleared part of the newest run of lots, never money still in its settlement wait.
Integrity
Tamper-evidence: a per-account hash chain plus signed checkpoints make any altered entry detectable, atop conservation and no-overdraft invariants.
The proof
The independent prover: one report that re-derives conservation, backing, no-overdraft, and chain integrity from the ledger itself.
Spend velocity
A per-subject cap on how much value one account can move within a rolling window.
Concurrency
Two operations touching the same account at once stay correct through one app-side rule and one database constraint: every operation locks its accounts in one global order, and a unique index makes a forked hash chain impossible.
Platform sharding
An account can only commit as fast as its one lock turns over, and every operation meets the same few platform accounts. PLATFORM_SHARDS splits each hot account into rows: routing is deterministic per operation, and readers sum the rows.
The accrual split
Concurrent buyers of one seller all credit that seller's earned row, and serialize on its lock. With ACCRUAL_DRAIN on, a charge parks the seller's share on a settlement-accrual shard and records an accrual row; the worker's drain sweep moves parked shares to earned in batches, one posting per seller.
Session netting
A netting session accepts thousands of small balanced movements into a durable, hash-chained journal and settles the net against the ledger in one posting. The journal is the source of truth, a session settles exactly once, and a long-lived scope rotates epochs.
The instance economy
The opt-in fast lane for in-world product purchases, layered on session netting. A purchase grants ownership immediately and durably; the money rides the journal and nets to the ledger at settle. The lane lives in the economy service — game servers stay unprivileged callers.
Cluster nodes
A session is single-writer, so every caller must send a given scope to the same economy node for the scope's life. scopeRouter computes that assignment by rendezvous hashing, and openClusterNode binds it to a node identity with shared reservations, ownership-gated sessions, crash recovery, and the orphan sweep.