economy-lab / docs
GitHub

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.

Source src/economy.ts#L73 · createEconomysrc/index.ts#L41README.md

economy-lab is the application layer of a credits economy — wallets, a marketplace, payouts, subscriptions, and digital ownership — built as one library over a single double-entry ledger.

You drive it through one submit entry point and read its state through read. Every action is one Operation that posts a balanced transaction and returns an Outcome.

Balances aren't stored and mutated. Every action becomes a balanced posting in an append-only, hash-chained ledger, and balances are folded back from those postings.

What the project is really about is a handful of invariants: value is conserved, no account overdrafts, every spendable credit is backed by real cash, and history can't be silently rewritten. A prover re-checks all of them after every operation.

How it fits together

A submit is synchronous. It validates and authorizes the request first. Then it posts one balanced transaction to the ledger, writing a matching event to an outbox in the same transaction. The Economy API walks that request path step by step.

Anything that outlives a request happens off that path. A background worker drains the outbox and runs the recurring sweeps — advancing payouts, billing subscriptions, expiring promos, realizing fees, and sealing checkpoints.

A lab, not a product

economy-lab is a runnable study of an application layer, not a deployable money system. The ledger invariants are enforced to a production standard: pushed down into the database, and proven by an adversarial suite that attacks the tables directly.

The operational edges are deliberately stubbed or simplified. That covers the payout Processor, the FX Rates source, schema migrations, and concurrency at scale.

A real deployment also needs the regulated plumbing a money transmitter provides — KYC, AML and sanctions screening, and the payout rails. economy-lab is the layer that sits on top: wallets, entitlements, marketplace logic, and the invariants that bind them.

It runs entirely in memory with zero runtime dependencies, and the same logic runs on Postgres, MySQL, Redis, and SQS through swappable adapters. What's intentionally out of scope has its own page: scope and non-goals.

Where to go next