Configuration

Every environment variable economy-lab reads, with its meaning and default.

Source src/config.ts#L303-L318loadConfigsrc/index.ts#L656openPortssrc/from-env.ts#L145resolveExternals.env.example

API Config

How configuration is read

economy-lab reads the environment once, at startup: the edge calls loadConfig, gets a plain Config object, and passes it in — the library modules never touch process.env. A misconfigured deploy fails at startup, not deep inside a request.

That single read also means defaults live in one file. Every tunable below is parsed by loadConfig with a fallback, so an unset or malformed value lands on the documented default rather than leaving the config half-applied. These are the same defaults the operation and background-worker pages cite.

A config override passed to openPorts (or defaultConfig) applies last-wins per knob, except the record-valued knobs — maturityHorizonMs and payoutSla — which merge one level deep: overriding one funding source or one SLA step keeps the others rather than replacing the whole record.

A handful of variables (the signing secrets, the CREDIT-to-USD rates, the payout provider, and the infrastructure URLs) are read outside loadConfig, when the edge wires up the Economy and its ports. Those are grouped separately at the end, because they pick adapters rather than tune policy.

Required secrets

Two secrets have no honest default. In production (NODE_ENV=production) a blank value for either makes loadSecrets throw a single CONFIG.INVALID fault listing every missing key at once.

Payouts

These tune when a payout is too small, too frequent, or too old to proceed. The minimums are counted in CREDIT minor units; see the money model for what a minor unit is.

The payout rate and the per-state payout SLAs also feed the saga; the SLAs live under the worker group below, and the rate under externals.

Worker queues

The background worker retries deferred work, then gives up after a cap so a poison message can’t wedge a queue. Each cap below is a number of attempts; the worker dead-letters once attempts reaches it.

The payout SLAs are per-state staleness thresholds the reconcile sweep folds over. A step stuck past its threshold is overdue. DEFAULT covers any state not named.

Maturity horizons

Topped-up funds wait before they can be spent or paid out, keyed by funding source. An unlisted source falls back to the default entry. See credit maturity for why the holding period exists.

The horizons split by environment. Outside production every unset horizon is 0 — funds clear instantly, so the zero-config quickstart’s top-up can be spent in the next line. In production MATURITY_HORIZON_CARD_MS is required (startup fails fast naming it, like the secrets): a real deployment states its chargeback window rather than inheriting a silent policy number.

Fees and the risk gate

PLATFORM_FEE_BPS is the platform’s cut on a sale, in basis points, where 10000 is 100%. The velocity variables bound how fast one subject may spend before the risk check steps in; see risk and velocity for the actor side of that gate.

The velocity ceiling splits by environment the same way the maturity anchor does. Outside production the default is 1,000 credits per window — sized so the velocity examples can trip the gate. In production VELOCITY_LIMIT_MINOR is required (startup fails fast naming it, like the secrets): a per-user hourly ceiling is a risk decision each deployment states for itself.

Subscriptions

The price band bounds what a subscription may charge per period, so a typo’d price cannot silently bind a buyer to it. A price outside the band is refused at subscribe time as a wiring error.

The purchase catalog

Unset, top-up accepts any positive CREDIT amount. Set, TOP_UP_BUNDLES_MINOR names the only amounts a top-up may carry — the platform’s purchase bundles — and any other amount faults OP.MALFORMED, since a store client that offers an off-catalog amount is miswired.

Platform sharding

A hot platform account (REVENUE, STORED_VALUE, TRUST_CASH, …) is one row, and concurrent postings of the same kind queue on its lock. PLATFORM_SHARDS splits each one across several rows so those postings spread out; platform sharding covers which accounts shard and how a posting picks its row.

Raising the count on a live ledger is safe: shard 0 keeps the bare account id, so existing balances already sit on shard 0 and new postings fan out from there. Lowering it is the careful direction. A smaller count reroutes every key, so rows that still hold balance can drop out of the rotation. Readers keep summing them and totals stay right, but nothing ever posts to them again, so drain before dropping the count back to 1.

The accrual split

Sharding relieves the platform accounts; a hot seller’s earned row needs the accrual split. With the flag on, spend and subscribe park seller shares on a SETTLEMENT_ACCRUAL shard and the worker’s drain sweep moves them to earned in batches. Meant to run with PLATFORM_SHARDS at 2 or more, so the parking shards don’t queue like the row they replace.

Replay window and the maintenance pause

REPLAY_WINDOW_MS bounds how stale a signed request may be before it’s rejected as a possible replay; see integrity. The two pause bounds open an optional maintenance window.

The pause is active only when both bounds parse as integers and start <= now < end. While it holds, end-user discretionary writes are declined with ECONOMY_PAUSED; settlement (actor system) and operator fixes still flow, and reads never reach the gate.

Production externals

These choose which adapter fills each port, so the edge reads them at wiring time rather than through loadConfig. In production, openPorts fails fast with one preflight message naming every rate or provider URL that is missing or malformed, so a prod process never runs on the 1:1 dev rate or an auto-approve payout stub. Outside production these fall back to dev stubs, and a local run needs none of them.

The six rate variables configure the fixed-point CREDIT-to-USD conversions for the rates port: usd_minor = floor(credit_minor × rate / 10^scale). The gap between buy and par is the platform spread.

Infrastructure adapters

DATABASE_URL picks the storage backend, and the cache and dispatcher URLs pick their transports. Each is optional: unset means the dependency-free in-memory adapter. These belong to storage, read by openPorts in src/index.ts.

Three of the optional ports — the dispatcher, the payee directory, and the checkpoint anchor — production refuses to lose silently: leaving one unwired without a word is a preflight error. Each has a decline flag (1 or true) that declares the deployment runs without that port on purpose.

HTTP server and worker loop

The serve and worker entry point reads four more variables directly. They control the HTTP service port, shutdown grace, and the worker’s tick cadence and batch size.

The package bridges

Two optional bridges in the host entry point (scripts/main.ts) compose the sibling packages in. Each is off until its gate variable is set, and neither is read by the library itself; the seams they wire are owned by the packages.