Reference
Engine commands
All commands run from the repository root through npm workspaces. The engine source lives in the engine workspace and compiles to engine/dist. Build it first with the workspace build, which the dev, build, and start scripts do automatically.
npm --workspace engine run build
npm run engine:doctorCommands
| Command | Purpose | Notes |
|---|---|---|
| engine:doctor | Read-only health check | Verifies indexer reachability, chain connection, and the venue book surface. Run this first. |
| engine:test | Run the test suite | 83 tests across store, redemption, strategy, reconciliation, evidence, and field-ingest suites. |
| engine:wallets | Generate the named wallets | Creates the strategy burner wallets for the roster. |
| engine:fresh-wallet | Generate the fallback burner | Creates the isolated FRESH wallet used for the disclosed pair-crossing proof. |
| engine:haruspex-wallet | Generate the LLM gladiator burner | Creates the HARUSPEX wallet used by the LLM fifth gladiator. |
| engine:provocator-wallet | Generate the reference entrant burner | Creates the PROVOCATOR wallet for the open-registration reference instance. |
| engine:spectator-wallet | Generate a spectator burner | Creates an isolated wallet for the spectator-backing demo path. |
| engine:back | Spectator backing order | Places one guarded order from the SPECTATOR wallet into the live window and reports the wallet it filled against. Needs a funded wallet; never enters standings. |
| engine:fund | Fund wallets with test collateral | Sends small testnet amounts to the configured wallets. |
| engine:crossing | Pair-crossing proof | Executes a guarded crossing proof against the live venue. |
| engine:killtest:a | Single-agent IOC proof | On-chain-gated immediate-or-cancel proof run for one agent. |
| engine:loop | Run the strategy loop | The heartbeat-driven autonomous loop. Takes the loop asset as an argument, for example BTC. |
| engine:redeem-sweep | Redeem settled positions | Plans and executes redemptions. Needs wallet keys. Supports --dry-run to plan without sending. |
| engine:recompute-standings | Re-derive all scores | Recomputes every score from receipt-backed ledger rows. Read-only, no keys needed. |
| engine:negative-proof | Locked-market refusal proof | Submits one deliberately invalid order to a finalized market and records the on-chain revert. Needs the SECUTOR key and a small amount of testnet gas. |
Loop arguments
npm run engine:loop -- BTC # trade the BTC market windows
npm run engine:loop -- ETH # trade the ETH market windowsEnvironment
The engine reads its configuration from environment variables. Copy the example file and keep private keys in your server environment only. The example file lists public endpoints and safe defaults.
| Field | Type | Notes |
|---|---|---|
| SOMNIA_INDEXER_URL | url | Public Somnia Shannon indexer GraphQL endpoint. |
| SOMNIA_WS_RPC_URL | url | Public WebSocket RPC endpoint. |
| IACTA_DB_PATH | path | SQLite ledger location. Default ./data/iacta.db. |
| IACTA_ASSETS | list | Assets the engine tracks, for example BTC,ETH. |
| IACTA_LOOP_ASSET | string | Default asset for the loop. |
| IACTA_LOOP_INTERVAL_MS | number | Read cadence in milliseconds. Default 15000. |
| IACTA_LOOP_READ_TIMEOUT_MS | number | Read timeout. Default 30000. |
| IACTA_LOOP_WRITE_TIMEOUT_MS | number | Write timeout. Default 60000. |
| IACTA_WRITE_GAS_LIMIT | number | Small-burner write gas envelope. Default 3000000. |
| IACTA_MAX_FEE_PER_GAS | number | Fee cap for writes. Default 9000000000. |
Secrets stay local
Wallet private keys are never committed. The repository ships only public endpoints and defaults in .env.example.