Configuration

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

Source src/config.ts#L109-L172 · loadConfigsrc/index.ts#L246-L348 · capabilitiesFromEnvscripts/main.ts#L139-L205 · productionExternals.env.example

How configuration is read

economy-lab reads the environment in exactly one place, at startup. The library modules never touch process.env themselves. Instead the edge calls loadConfig once, gets back a plain Config object, and passes it in. A misconfigured deploy therefore 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 handful of variables — the signing secrets, the CREDIT↔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 loadConfig throw a single CONFIG.INVALID fault listing every missing key at once. Outside production a blank secret is tolerated so a local run needs no setup.

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 maturity in the lifecycle for why the holding period exists.

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.

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 pick adapters rather than tune policy, so the edge reads them when it wires the ports — not loadConfig. In production, productionExternals (scripts/main.ts) fails fast with one message if any rate or the provider URL 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↔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 and messaging, read by capabilitiesFromEnv in src/index.ts.

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.