@xyo-network/xl1-cli 3.0.0 → 3.0.2

package/README.md

@@ -76,50 +76,51 @@ Starts only the Producer Node, which is responsible for block production.
 
 Use `xl1 --help` for available options and configuration flags.
 
-### Configuration
+## Configuration
 
-Certainly! Here’s a brief and well-organized section describing the three ways to configure your xl1 CLI tool:
+You can configure `xl1` using CLI flags, environment variables, or a configuration file. CLI flags override environment variables, which override config file values.
 
-⸻
-
-Configuration
-
-You can configure xl1 using CLI flags, environment variables, or a configuration file. All methods are optional and can be combined—CLI flags override environment variables, which override config file values.
-
-#### CLI Flags
-
-Pass options directly when running a command. For example:
+### CLI flags
 
 ```sh
-xl1 --logLevel=info --api.port=8080
+xl1 --log.logLevel=info start api
 ```
 
-#### Environment Variables
+### Environment variables
 
-Set configuration via environment variables before running the command:
+`XL1_*` variables map to the config shape with double-underscore nesting (`XL1_CONNECTIONS__LOCAL_STORE__ROOT`, etc.; see `.env.example`).
 
 ```sh
-export XL1_LOG_LEVEL=info
-export XL1_API__PORT=8080
-xl1
+export XL1_LOG__LOG_LEVEL=info
+export XL1_ACTORS__0__NAME=api
+export XL1_ACTORS__0__PORT=8080
+xl1 start api
 ```
 
-#### Config File
+### Config file
 
-Create a `xyo.config.json` (or .js, .yaml) file in the working directory to define default settings:
+Create a `xyo.config.json` (cosmiconfig also accepts `xyo.yaml`, `xyo.toml`, `xyo.js`, etc.) with an `xl1` section. Omit `-c` to search the current directory, or pass `-c <path>` explicitly.
 
 ```json
 {
-  "logLevel": "info",
-  "api": {
-    "port": 8080
+  "xl1": {
+    "connections": {
+      "local-store": { "type": "lmdb", "root": ".store" }
+    },
+    "actors": [
+      { "name": "api", "host": "localhost", "port": 8080 },
+      { "name": "producer" },
+      { "name": "finalizer" }
+    ]
   }
 }
 ```
 
-## Deployment configurations
+Runnable `xyo.json`-style configs for XL1 3.0 declare every backing store, RPC endpoint, EVM RPC, and S3 bucket under `connections`. The pre-3.0 `storage`, `remote`, `transports`, and `evm.jsonRpc` / `evm.infura` fields are no longer supported. A remote API is reached with a `default-rpc` connection of `type: "rpc"`, not the old `remote.rpc`.
 
-`xl1` actors can be assembled into many physical layouts: one process running everything, one process per actor, or grouped processes sharing one config. This section covers the actors, the dimensions you choose between, and a copy-paste recipe for each supported topology.
+## Deployment guide
+
+`xl1` actors can be assembled into many physical layouts: one process running everything, one process per actor, or grouped processes sharing one config.
 
 ### Actors
 
@@ -137,125 +138,458 @@ Create a `xyo.config.json` (or .js, .yaml) file in the working directory to defi
 
 ### Dimensions
 
-You make four independent choices when deploying:
-
 1. **Process layout** — mono (everything in one process), split (one actor per process), or grouped (custom).
 2. **Storage backing** — `memory` (single-process only, ephemeral), `lmdb` (single-host, persistent, multi-process safe via shared root), or `mongodb` (multi-host, persistent, multi-process safe).
 3. **Provider tier** — `simple` (in-process tier 1, requires the corresponding backing), or `jsonrpc` (tier 3 proxy to another `xl1` process). The CLI picks `jsonrpc` automatically when a global `default-rpc` connection is configured; otherwise it picks `simple` when the backing is available.
 4. **Config layout** — single file shared across all processes (each `xl1 start <subset>` filters which actors it activates), one file per process, or pure environment variables.
 
-### Recipes
+### Launch patterns
 
-Every recipe shows a JSON config file and the command(s) to launch it. Configs use `xyo.json` (cosmiconfig also accepts `xyo.yaml`, `xyo.toml`, `xyo.js`, etc.); the CLI auto-discovers a `xyo.*` file in the current directory or accepts an explicit `-c <path>`.
+Copy any example from [Development examples](#development-examples) or [Per-actor production deployment](#per-actor-production-deployment) into `xyo.json`, then:
 
-#### Single process, in-memory (dev)
+```sh
+# Single process
+xl1 -c ./xyo.json start api producer finalizer mempool
 
-Fastest path for local development. Everything runs in one node process; state is lost when the process exits.
+# Multi-process (one OS process per actor, same config file)
+xl1 -c ./xyo.json start api
+xl1 -c ./xyo.json start producer
+xl1 -c ./xyo.json start finalizer
+xl1 -c ./xyo.json start mempool
+
+# One config file per process
+xl1 -c ./xyo.api.json start api
+xl1 -c ./xyo.producer.json start producer
+```
+
+```sh
+# Inspect resolved config (secrets redacted)
+xl1 --dump-config -c ./xyo.json start api producer finalizer
+
+# Inspect provider wiring without starting actors
+xl1 --dump-providers -c ./xyo.json start api producer finalizer
+
+# Non-interactive dev boot (skip insecure-mnemonic prompt)
+xl1 --skip-insecure-confirm -c ./xyo.json start
+```
+
+## Connections model
+
+Named **connections** describe where providers read/write state:
+
+| Connection | Type | Purpose |
+|------------|------|---------|
+| `local-store` | `lmdb` | On-disk LMDB chain authority store |
+| `chain-mongo` | `mongo` | MongoDB chain authority store |
+| `dlq-store` | `lmdb` / `mongo` | Dead-letter queue backing (dev: aliases to chain store when omitted) |
+| `mempool-store` | `lmdb` / `mongo` | Mempool backing (dev: aliases to chain store when omitted) |
+| `indexer-store` | `lmdb` / `mongo` | Indexer-local store when split from chain authority |
+| `default-rpc` | `rpc` | HTTP JSON-RPC to another XL1 API |
+| `default-evm-rpc` | `evm-rpc` | EVM JSON-RPC for staking/contracts |
+| `s3-finalized` / `s3-chain-state` / `s3-index` | `s3` | Object storage publish targets |
+| `rest-finalized` / `rest-chain-state` / `rest-index` | `rest` | CDN / HTTP read URLs for published static files |
+| `memory` | `memory` | In-process stubs (injected at boot) |
+
+**providerBindings** map each provider moniker to a connection. When omitted, bindings are synthesized per connection name (chain monikers → `local-store` / `chain-mongo`, DLQ → `dlq-store` or dev-aliased chain store, mempool → `mempool-store` or dev-aliased chain store, viewers → `default-rpc` when present, EVM monikers → `default-evm-rpc` when declared, otherwise memory fallback at plan time).
+
+**S3 write + REST read:** The finalizer writes finalized blocks and the chain-state head to S3 (`BlockPublishRunner`, `ChainStatePublishRunner`). The indexer reads the published head and blocks over REST (`ChainStateViewer`, `BlockViewer`) and writes the index bucket via `IndexPublishRunner` → `s3-index`. Because `BlockViewer` must stay on the authority store for finalization, use split per-actor configs ([Finalizer](#finalizer-per-actor) + [Indexer](#indexer-per-actor)) or override `providerBindings` explicitly as in [S3 write + REST read](#s3-write--rest-read).
+
+## Development examples
+
+### In-memory dev
+
+Single process, ephemeral in-memory chain (fastest local dev). Omits `connections` — the boot preset injects an in-memory store.
 
-`xyo.json`:
 ```json
 {
   "xl1": {
     "actors": [
-      { "name": "api", "host": "localhost", "port": 8080 },
-      { "name": "mempool" },
-      { "name": "finalizer" }
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "blockProductionCheckInterval": 100,
+        "heartbeatInterval": 100
+      },
+      {
+        "name": "finalizer",
+        "finalizationCheckInterval": 50,
+        "minCandidates": 1
+      }
     ]
   }
 }
 ```
 
-```sh
-xl1 start api mempool finalizer
+### LMDB local
+
+Single process with on-disk LMDB at `.store`.
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      }
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      },
+      {
+        "name": "mempool"
+      }
+    ]
+  }
+}
 ```
 
-The `api + mempool + finalizer` subset is the canary combo: the CLI builds a single shared provider registry for the three actors so each provider is instantiated exactly once, with no cross-actor duplication.
+### LMDB + EVM JSON-RPC
+
+LMDB plus contract-backed chain via `default-evm-rpc` (local Hardhat/Ganache).
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "http://127.0.0.1:8545",
+        "chainId": "0xaa36a7"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      },
+      {
+        "name": "mempool"
+      }
+    ]
+  }
+}
+```
 
-#### Single process, LMDB (single-host persistent)
+### LMDB + EVM Infura
 
-Persistent state on one machine. LMDB writes are multi-process safe via the LMDB lockfile, so you can later split actors across processes against the same `local-store` connection.
+LMDB plus Sepolia EVM RPC URL.
 
-`xyo.json`:
 ```json
 {
   "xl1": {
-    "connections": { "local-store": { "type": "lmdb", "root": "/var/xl1/data" } },
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
     "actors": [
-      { "name": "api", "host": "localhost", "port": 8080 },
-      { "name": "producer", "heartbeatInterval": 1000 },
-      { "name": "finalizer" },
-      { "name": "mempool" }
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      }
     ]
   }
 }
 ```
 
-```sh
-xl1 start api producer finalizer mempool
+### Explicit connections
+
+Explicit `connections` + `providerBindings` overrides.
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "http://127.0.0.1:8545",
+        "chainId": "0xaa36a7"
+      }
+    },
+    "providerBindings": {
+      "BlockViewer": {
+        "connection": "local-store"
+      },
+      "MempoolRunner": {
+        "connection": "local-store"
+      },
+      "ChainContractViewer": {
+        "connection": "default-evm-rpc"
+      },
+      "StakeViewer": {
+        "connection": "default-evm-rpc"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      }
+    ]
+  }
+}
 ```
 
-#### Single process, MongoDB (single-host with shared DB)
+### Stateless API
 
-Same as the LMDB variant but with a MongoDB-backed archivist. Use this when state needs to outlive any one host or be shared with off-chain tooling that already speaks Mongo.
+Read-only API proxying a remote chain RPC.
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "default-rpc": {
+        "type": "rpc",
+        "protocol": "https",
+        "url": "https://chain.example.com/rpc"
+      }
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "0.0.0.0",
+        "port": 8080,
+        "stateless": true
+      }
+    ]
+  }
+}
+```
+
+### MongoDB
+
+MongoDB-backed archivist via `chain-mongo`.
 
-`xyo.json`:
 ```json
 {
   "xl1": {
     "connections": {
       "chain-mongo": {
         "type": "mongo",
-        "connectionString": "mongodb://user:pass@db.internal:27017",
-        "database": "xl1",
-        "domain": "internal"
+        "connectionString": "mongodb://root:example@localhost:27017/?retryWrites=true&w=majority",
+        "database": "chain",
+        "domain": "localhost",
+        "username": "root",
+        "password": "example"
       }
     },
     "actors": [
-      { "name": "api", "host": "localhost", "port": 8080 },
-      { "name": "producer", "heartbeatInterval": 1000 },
-      { "name": "finalizer" },
-      { "name": "mempool" }
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      },
+      {
+        "name": "mempool"
+      }
     ]
   }
 }
 ```
 
-```sh
-xl1 start api producer finalizer mempool
+### Multi-process LMDB
+
+Shared LMDB; run one process per `xl1 start <actor>`.
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      }
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer"
+      },
+      {
+        "name": "mempool",
+        "host": "localhost",
+        "port": 8081
+      }
+    ]
+  }
+}
 ```
 
-#### Multi-process, shared LMDB (one host, role-isolated)
+### Mempool remote API
 
-Each actor runs as its own OS process. Useful when you want to restart one role independently or pin different actors to different cores. Every process loads the same config file and uses `xl1 start <name>` to activate just its slice.
+Standalone mempool over JsonRpc to a remote API.
 
-`xyo.json` (single file, all processes load it):
 ```json
 {
   "xl1": {
-    "connections": { "local-store": { "type": "lmdb", "root": "/var/xl1/data" } },
+    "connections": {
+      "default-rpc": {
+        "type": "rpc",
+        "protocol": "http",
+        "url": "http://localhost:8080/rpc"
+      }
+    },
+    "providerBindings": {
+      "MempoolRunner": {
+        "connection": "default-rpc"
+      },
+      "MempoolViewer": {
+        "connection": "default-rpc"
+      },
+      "BlockViewer": {
+        "connection": "default-rpc"
+      },
+      "WindowedBlockViewer": {
+        "connection": "default-rpc"
+      },
+      "TransactionValidationViewer": {
+        "connection": "default-rpc"
+      }
+    },
     "actors": [
-      { "name": "api", "host": "localhost", "port": 8080 },
-      { "name": "producer", "heartbeatInterval": 1000 },
-      { "name": "finalizer" },
-      { "name": "mempool", "host": "localhost", "port": 8081 }
+      {
+        "name": "mempool",
+        "host": "localhost",
+        "port": 8081
+      }
     ]
   }
 }
 ```
 
-```sh
-# Each line is a separate process (e.g., one systemd unit per actor)
-xl1 start api
-xl1 start producer
-xl1 start finalizer
-xl1 start mempool
+### Mixed local + remote
+
+Local LMDB runners + JsonRpc viewers.
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "local-store": {
+        "type": "lmdb",
+        "root": ".store"
+      },
+      "default-rpc": {
+        "type": "rpc",
+        "protocol": "http",
+        "url": "http://localhost:8080/rpc"
+      }
+    },
+    "providerBindings": {
+      "MempoolRunner": {
+        "connection": "local-store"
+      },
+      "BlockViewer": {
+        "connection": "default-rpc"
+      },
+      "MempoolViewer": {
+        "connection": "default-rpc"
+      },
+      "FinalizationViewer": {
+        "connection": "default-rpc"
+      },
+      "TransactionViewer": {
+        "connection": "default-rpc"
+      },
+      "AccountBalanceViewer": {
+        "connection": "default-rpc"
+      }
+    },
+    "actors": [
+      {
+        "name": "api",
+        "host": "localhost",
+        "port": 8080
+      },
+      {
+        "name": "mempool"
+      }
+    ]
+  }
+}
 ```
 
-#### Multi-process, shared MongoDB (multi-host, durable)
+### Finalizer + indexer S3
 
-Same as above but with MongoDB as the shared store. Now each process can run on a different host, since MongoDB takes care of cross-host coordination.
+Mongo store plus S3 publish connections for finalizer and indexer in one process.
 
-`xyo.json`:
 ```json
 {
   "xl1": {
@@ -265,87 +599,539 @@ Same as above but with MongoDB as the shared store. Now each process can run on
         "connectionString": "mongodb://user:pass@db.internal:27017",
         "database": "xl1",
         "domain": "internal"
+      },
+      "s3-finalized": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-chain",
+        "readUrl": "https://chain.xl1.example"
+      },
+      "s3-chain-state": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-chain-state",
+        "readUrl": "https://chain-state.xl1.example"
+      },
+      "s3-index": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-index",
+        "readUrl": "https://index.xl1.example"
       }
     },
     "actors": [
-      { "name": "api", "host": "0.0.0.0", "port": 8080 },
-      { "name": "producer", "heartbeatInterval": 1000 },
-      { "name": "finalizer" },
-      { "name": "mempool", "host": "0.0.0.0", "port": 8081 }
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      },
+      {
+        "name": "finalizer",
+        "publishOnFinalize": true,
+        "publishContentEncoding": "br",
+        "publishProgressInterval": 100
+      },
+      {
+        "name": "indexer",
+        "publishSyncInterval": 5000,
+        "publishContentEncoding": "br",
+        "publishProgressInterval": 100
+      }
     ]
   }
 }
 ```
 
-```sh
-# On host A
-xl1 start api
+### S3 write + REST read
 
-# On host B
-xl1 start producer
+Indexer: `s3-index` publish + REST CDN viewers.
 
-# On host C
-xl1 start finalizer mempool
+```json
+{
+  "xl1": {
+    "connections": {
+      "s3-index": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-index",
+        "readUrl": "https://index.xl1.example"
+      },
+      "rest-finalized": {
+        "type": "rest",
+        "baseUrl": "https://chain.xl1.example"
+      },
+      "rest-chain-state": {
+        "type": "rest",
+        "baseUrl": "https://chain-state.xl1.example"
+      },
+      "rest-index": {
+        "type": "rest",
+        "baseUrl": "https://index.xl1.example"
+      }
+    },
+    "providerBindings": {
+      "BlockViewer": {
+        "connection": "rest-finalized"
+      },
+      "ChainStateViewer": {
+        "connection": "rest-chain-state"
+      },
+      "IndexViewer": {
+        "connection": "rest-index"
+      },
+      "IndexPublishRunner": {
+        "connection": "s3-index"
+      }
+    },
+    "actors": [
+      {
+        "name": "indexer",
+        "publishSyncInterval": 5000,
+        "publishContentEncoding": "br",
+        "publishProgressInterval": 100
+      }
+    ]
+  }
+}
 ```
 
-#### Stateless API client (read-only proxy to a remote chain)
+## Per-actor production deployment
 
-The API actor in `stateless: true` mode owns no local store. All viewer providers resolve to JsonRpc proxies pointed at the `default-rpc` connection. Run several stateless API instances behind a load balancer to scale read traffic without duplicating state.
+One config per actor **process** — the shape a real multi-host deployment runs, where each actor is its own container/pod (see `.k8s/` and the `deploy-prod-*` workflows). The read layer is served from S3/R2 object storage behind a CDN, so only the finalizer and indexer write to S3; everyone else reads the published blocks / chain-state / index over REST and keeps MongoDB only for the authority/write path.
+
+| Actor | Backing connections | Writes to S3 | Reads |
+|-------|---------------------|--------------|-------|
+| `api` | `chain-mongo` (mempool + tx submission) | — | blocks / state / index over REST |
+| `producer` | `chain-mongo` authority + `default-evm-rpc` + `producer-wallet` | — | authority store + EVM staking contract |
+| `finalizer` | `chain-mongo` authority | `s3-finalized` (blocks), `s3-chain-state` (head) | authority store |
+| `indexer` | none (reads over REST) | `s3-index` | finalized blocks + chain-state over REST |
+| `mempool` | `chain-mongo` | — | authority store |
+| `bridge` | `chain-mongo` + `default-evm-rpc` + `bridge-wallet` + Redis | — | authority store + remote EVM chain |
+| `rewardRedemption` | `chain-mongo` + `default-evm-rpc` + `rewardRedemption-wallet` | — | authority store + EVM staking contract |
+
+- **One writer per bucket.** The finalizer owns `s3-finalized` + `s3-chain-state`; the indexer owns `s3-index`. No other actor writes object storage.
+- **`BlockViewer` is not auto-bound to REST.** When a process declares a local store, `BlockViewer` defaults to it, so the API and indexer configs bind `BlockViewer → rest-finalized` explicitly to read finalized blocks from the CDN. `ChainStateViewer` / `IndexViewer` bind to their REST connections automatically when those connections are declared (the explicit bindings here are for clarity).
+- **Staking.** `chain.id` (the staking contract address on the backing EVM) plus `evm.chainId` and a `default-evm-rpc` connection enable the EVM-backed stake/contract viewers. Actors that only read published data (`api`, `indexer`) omit them; the stake viewers fall back to their chain-state-derived implementations.
+- **Wallets.** Wallet connections (`<actor>-wallet`) and the `XyoSigner` binding are auto-synthesized for signing actors (`producer`, `bridge`, `rewardRedemption`); they are shown explicitly here for clarity. `bridge` and `rewardRedemption` cannot be co-located in one process (they share `XyoSigner`).
+- **Secrets.** `YOUR_*` placeholders (R2 keys, Mongo credentials, Infura project id) and wallet mnemonics should be supplied via `XL1_*` env vars / your secret store in production — do not commit real credentials.
+
+### API (per-actor)
 
-`xyo.json`:
 ```json
 {
   "xl1": {
     "connections": {
-      "default-rpc": { "type": "rpc", "protocol": "https", "url": "https://chain.example.com/rpc" }
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      },
+      "rest-finalized": {
+        "type": "rest",
+        "baseUrl": "https://chain.xl1.example"
+      },
+      "rest-chain-state": {
+        "type": "rest",
+        "baseUrl": "https://chain-state.xl1.example"
+      },
+      "rest-index": {
+        "type": "rest",
+        "baseUrl": "https://index.xl1.example"
+      }
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "rest-finalized" },
+      "ChainStateViewer": { "connection": "rest-chain-state" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "IndexViewer": { "connection": "rest-index" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
     },
     "actors": [
-      { "name": "api", "host": "0.0.0.0", "port": 8080, "stateless": true }
+      {
+        "name": "api",
+        "host": "0.0.0.0",
+        "port": 8080
+      }
     ]
   }
 }
 ```
 
-```sh
-xl1 start api
-```
+### Producer (per-actor)
 
-#### Pure environment variables (no config file)
+```json
+{
+  "xl1": {
+    "connections": {
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
+      "producer-wallet": {
+        "type": "wallet",
+        "accountPath": "0"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "chain-mongo" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "StakeEventsViewer": { "connection": "default-evm-rpc" },
+      "StakeTotalsViewer": { "connection": "default-evm-rpc" },
+      "StakeViewer": { "connection": "default-evm-rpc" },
+      "TimeSyncViewer": { "connection": "default-evm-rpc" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
+    },
+    "actors": [
+      {
+        "name": "producer",
+        "heartbeatInterval": 1000
+      }
+    ]
+  }
+}
+```
 
-Every config key has a `XL1_*` env var equivalent. Use double-underscore for nested keys and numeric indices for array entries — useful in container orchestration where you'd rather not mount a file.
+### Finalizer (per-actor)
 
-```sh
-export XL1_CONNECTIONS__LOCAL_STORE__TYPE=lmdb
-export XL1_CONNECTIONS__LOCAL_STORE__ROOT=/var/xl1/data
-export XL1_ACTORS__0__NAME=api
-export XL1_ACTORS__0__HOST=localhost
-export XL1_ACTORS__0__PORT=8080
-export XL1_ACTORS__1__NAME=producer
-export XL1_ACTORS__1__HEARTBEAT_INTERVAL=1000
-export XL1_ACTORS__2__NAME=finalizer
-xl1 start api producer finalizer
+```json
+{
+  "xl1": {
+    "connections": {
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      },
+      "s3-finalized": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-chain",
+        "readUrl": "https://chain.xl1.example"
+      },
+      "s3-chain-state": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-chain-state",
+        "readUrl": "https://chain-state.xl1.example"
+      }
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockPublishRunner": { "connection": "s3-finalized" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "chain-mongo" },
+      "ChainStatePublishRunner": { "connection": "s3-chain-state" },
+      "ChainStateViewer": { "connection": "s3-chain-state" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
+    },
+    "actors": [
+      {
+        "name": "finalizer",
+        "finalizationCheckInterval": 500,
+        "publishOnFinalize": true,
+        "publishContentEncoding": "br",
+        "publishProgressInterval": 100
+      }
+    ]
+  }
+}
 ```
 
-#### One config file per process
-
-When per-process config needs to live in different config-management systems (Kubernetes secrets vs ConfigMaps, separate Vault paths, etc.), give each process its own file with `-c`.
+### Indexer (per-actor)
 
-`xyo.api.json`:
 ```json
-{ "xl1": { "connections": { "local-store": { "type": "lmdb", "root": "/var/xl1/data" } }, "actors": [{ "name": "api", "host": "localhost", "port": 8080 }] } }
+{
+  "xl1": {
+    "connections": {
+      "rest-finalized": {
+        "type": "rest",
+        "baseUrl": "https://chain.xl1.example"
+      },
+      "rest-chain-state": {
+        "type": "rest",
+        "baseUrl": "https://chain-state.xl1.example"
+      },
+      "rest-index": {
+        "type": "rest",
+        "baseUrl": "https://index.xl1.example"
+      },
+      "s3-index": {
+        "type": "s3",
+        "accountId": "YOUR_R2_ACCOUNT_ID",
+        "accessKeyId": "YOUR_ACCESS_KEY_ID",
+        "secretAccessKey": "YOUR_SECRET_ACCESS_KEY",
+        "prefix": "xl1/",
+        "bucket": "xl1-index",
+        "readUrl": "https://index.xl1.example"
+      }
+    },
+    "providerBindings": {
+      "BlockViewer": {
+        "connection": "rest-finalized"
+      },
+      "ChainStateViewer": {
+        "connection": "rest-chain-state"
+      },
+      "IndexViewer": {
+        "connection": "rest-index"
+      },
+      "IndexPublishRunner": {
+        "connection": "s3-index"
+      }
+    },
+    "actors": [
+      {
+        "name": "indexer",
+        "publishSyncInterval": 5000,
+        "publishContentEncoding": "br",
+        "publishProgressInterval": 100
+      }
+    ]
+  }
+}
 ```
 
-`xyo.producer.json`:
+### Mempool (per-actor)
+
 ```json
-{ "xl1": { "connections": { "local-store": { "type": "lmdb", "root": "/var/xl1/data" } }, "actors": [{ "name": "producer", "heartbeatInterval": 1000 }] } }
+{
+  "xl1": {
+    "connections": {
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      }
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "chain-mongo" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
+    },
+    "actors": [
+      {
+        "name": "mempool",
+        "host": "0.0.0.0",
+        "port": 8081
+      }
+    ]
+  }
+}
 ```
 
-```sh
-xl1 -c ./xyo.api.json      start api
-xl1 -c ./xyo.producer.json start producer
+### Bridge (per-actor)
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
+      "rest-datalake": {
+        "type": "rest",
+        "baseUrl": "https://api.archivist.xyo.network/dataLake"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "chain-mongo" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
+      "DataLakeRunner": { "connection": "rest-datalake" },
+      "DataLakeViewer": { "connection": "rest-datalake" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "StakeEventsViewer": { "connection": "default-evm-rpc" },
+      "StakeTotalsViewer": { "connection": "default-evm-rpc" },
+      "StakeViewer": { "connection": "default-evm-rpc" },
+      "TimeSyncViewer": { "connection": "default-evm-rpc" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
+    },
+    "actors": [
+      {
+        "name": "bridge",
+        "accountPath": "0",
+        "redisHost": "redis.internal",
+        "redisPort": 6379,
+        "scannerIntervalMs": 30000
+      }
+    ]
+  }
+}
 ```
 
-### S3 object storage (finalized / chain-state / index publishing)
+### Reward redemption (per-actor)
+
+```json
+{
+  "xl1": {
+    "connections": {
+      "chain-mongo": {
+        "type": "mongo",
+        "connectionString": "mongodb://YOUR_MONGO_USER:YOUR_MONGO_PASSWORD@db.internal:27017/?retryWrites=true&w=majority",
+        "database": "xl1",
+        "domain": "internal"
+      },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      }
+    },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
+    "providerBindings": {
+      "AccountBalanceViewer": { "connection": "chain-mongo" },
+      "BlockRunner": { "connection": "chain-mongo" },
+      "BlockValidationViewer": { "connection": "chain-mongo" },
+      "BlockViewer": { "connection": "chain-mongo" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
+      "DeadLetterQueueRunner": { "connection": "chain-mongo" },
+      "DeadLetterQueueViewer": { "connection": "chain-mongo" },
+      "FinalizationRunner": { "connection": "chain-mongo" },
+      "FinalizationViewer": { "connection": "chain-mongo" },
+      "MempoolRunner": { "connection": "chain-mongo" },
+      "MempoolViewer": { "connection": "chain-mongo" },
+      "StakeEventsViewer": { "connection": "default-evm-rpc" },
+      "StakeTotalsViewer": { "connection": "default-evm-rpc" },
+      "StakeViewer": { "connection": "default-evm-rpc" },
+      "TimeSyncViewer": { "connection": "default-evm-rpc" },
+      "TransactionValidationViewer": { "connection": "chain-mongo" },
+      "TransactionViewer": { "connection": "chain-mongo" },
+      "WindowedBlockViewer": { "connection": "chain-mongo" },
+      "XyoConnection": { "connection": "chain-mongo" },
+      "XyoGateway": { "connection": "chain-mongo" },
+      "XyoGatewayRunner": { "connection": "chain-mongo" },
+      "XyoRunner": { "connection": "chain-mongo" },
+      "XyoViewer": { "connection": "chain-mongo" }
+    },
+    "actors": [
+      {
+        "name": "rewardRedemption",
+        "accountPath": "0",
+        "host": "0.0.0.0",
+        "port": 8082
+      }
+    ]
+  }
+}
+```
+## S3 object storage (finalized / chain-state / index publishing)
 
 Beyond the authority store (`lmdb` / `mongodb`), the chain can publish a static, HTTP-servable copy of itself to S3-compatible object storage (e.g. Cloudflare R2). This is what serves cheap, CDN-cached reads to [`@xyo-network/xl1-rest-block-viewer`](https://www.npmjs.com/package/@xyo-network/xl1-rest-block-viewer) and the wallet / explorer clients — no RPC server in the read path. It layers on top of any backing; it does not replace it.
 
@@ -411,7 +1197,7 @@ export XL1_ACTORS__1__PUBLISH_ON_FINALIZE=true
 export XL1_ACTORS__2__PUBLISH_SYNC_INTERVAL=5000
 ```
 
-### Mnemonics & wallets
+## Mnemonics & wallets
 
 The root `mnemonic` field (or `XL1_MNEMONIC`) defines the wallet from which every actor derives an account at `accountPath`. Per-actor `mnemonic` fields are rejected — use `accountPath` to give each actor a distinct derivation.
 
@@ -429,7 +1215,7 @@ The root `mnemonic` field (or `XL1_MNEMONIC`) defines the wallet from which ever
 
 If you omit `mnemonic` entirely, the CLI falls back to a built-in dev mnemonic and pauses for an interactive RETURN before starting. Pass `--skip-insecure-confirm` to bypass the prompt in non-interactive deployments — but never deploy production traffic against the dev mnemonic.
 
-### Inspecting a configuration
+## Inspecting a configuration
 
 Two CLI flags help you verify what the chain *would* do without actually starting it: