@xyo-network/xl1-cli 1.22.0 → 1.23.0

package/README.md

@@ -115,6 +115,257 @@ Create a `xyo.config.json` (or .js, .yaml) file in the working directory to defi
 }
 ```
 
+## Deployment configurations
+
+`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.
+
+### Actors
+
+| Actor | Role |
+|---|---|
+| `api` | JSON-RPC gateway. Serves block / balance / transaction queries and accepts transfers. |
+| `producer` | Block producer. Drives heartbeat blocks and packages mempool transactions. |
+| `finalizer` | Selects a chain head from competing producer candidates and writes finalizations. |
+| `mempool` | Holds pending transactions until the producer pulls them. |
+| `bridge` | EVM bridge — relays deposits / withdrawals between XL1 and an EVM chain. |
+| `rewardRedemption` | Claims block rewards for the producer's account. |
+
+`xl1 start <actor> [actor ...]` runs any subset in one process. With no positional args it defaults to `api producer finalizer`.
+
+### 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 the global `remote.rpc` is set; 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
+
+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>`.
+
+#### Single process, in-memory (dev)
+
+Fastest path for local development. Everything runs in one node process; state is lost when the process exits.
+
+`xyo.json`:
+```json
+{
+  "xl1": {
+    "actors": [
+      { "name": "api", "host": "localhost", "port": 8080 },
+      { "name": "mempool" },
+      { "name": "finalizer" }
+    ]
+  }
+}
+```
+
+```sh
+xl1 start api mempool finalizer
+```
+
+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.
+
+#### Single process, LMDB (single-host persistent)
+
+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 `storage.root`.
+
+`xyo.json`:
+```json
+{
+  "xl1": {
+    "storage": { "root": "/var/xl1/data" },
+    "actors": [
+      { "name": "api", "host": "localhost", "port": 8080 },
+      { "name": "producer", "heartbeatInterval": 1000 },
+      { "name": "finalizer" },
+      { "name": "mempool" }
+    ]
+  }
+}
+```
+
+```sh
+xl1 start api producer finalizer mempool
+```
+
+#### Single process, MongoDB (single-host with shared DB)
+
+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.
+
+`xyo.json`:
+```json
+{
+  "xl1": {
+    "storage": {
+      "mongo": {
+        "connectionString": "mongodb://user:pass@db.internal:27017",
+        "database": "xl1",
+        "domain": "internal"
+      }
+    },
+    "actors": [
+      { "name": "api", "host": "localhost", "port": 8080 },
+      { "name": "producer", "heartbeatInterval": 1000 },
+      { "name": "finalizer" },
+      { "name": "mempool" }
+    ]
+  }
+}
+```
+
+```sh
+xl1 start api producer finalizer mempool
+```
+
+#### Multi-process, shared LMDB (one host, role-isolated)
+
+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.
+
+`xyo.json` (single file, all processes load it):
+```json
+{
+  "xl1": {
+    "storage": { "root": "/var/xl1/data" },
+    "actors": [
+      { "name": "api", "host": "localhost", "port": 8080 },
+      { "name": "producer", "heartbeatInterval": 1000 },
+      { "name": "finalizer" },
+      { "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
+```
+
+#### Multi-process, shared MongoDB (multi-host, durable)
+
+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.
+
+`xyo.json`:
+```json
+{
+  "xl1": {
+    "storage": {
+      "mongo": {
+        "connectionString": "mongodb://user:pass@db.internal:27017",
+        "database": "xl1",
+        "domain": "internal"
+      }
+    },
+    "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 }
+    ]
+  }
+}
+```
+
+```sh
+# On host A
+xl1 start api
+
+# On host B
+xl1 start producer
+
+# On host C
+xl1 start finalizer mempool
+```
+
+#### Stateless API client (read-only proxy to a remote chain)
+
+The API actor in `stateless: true` mode owns no local store. All viewer providers resolve to JsonRpc proxies pointed at `remote.rpc`. Run several stateless API instances behind a load balancer to scale read traffic without duplicating state.
+
+`xyo.json`:
+```json
+{
+  "xl1": {
+    "remote": { "rpc": { "protocol": "https", "url": "https://chain.example.com/rpc" } },
+    "actors": [
+      { "name": "api", "host": "0.0.0.0", "port": 8080, "stateless": true }
+    ]
+  }
+}
+```
+
+```sh
+xl1 start api
+```
+
+#### Pure environment variables (no config file)
+
+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.
+
+```sh
+export XL1_STORAGE__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
+```
+
+#### 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`.
+
+`xyo.api.json`:
+```json
+{ "xl1": { "storage": { "root": "/var/xl1/data" }, "actors": [{ "name": "api", "host": "localhost", "port": 8080 }] } }
+```
+
+`xyo.producer.json`:
+```json
+{ "xl1": { "storage": { "root": "/var/xl1/data" }, "actors": [{ "name": "producer", "heartbeatInterval": 1000 }] } }
+```
+
+```sh
+xl1 -c ./xyo.api.json      start api
+xl1 -c ./xyo.producer.json start producer
+```
+
+### 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.
+
+```json
+{
+  "xl1": {
+    "mnemonic": "edit hill neutral usage share kite knee abandon slim open lottery abandon",
+    "actors": [
+      { "name": "producer", "accountPath": "0" },
+      { "name": "finalizer", "accountPath": "1" }
+    ]
+  }
+}
+```
+
+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
+
+Two CLI flags help you verify what the chain *would* do without actually starting it:
+
+- `xl1 --dump-config start <actors>` — prints the fully resolved config (file + env + CLI flags merged, defaults applied) to stdout, then exits. Secret-bearing fields are redacted by default; pass `--with-secrets` on a developer box to see raw values.
+- `xl1 --dump-providers start <actors>` — runs the locator construction up to the point where actor runners would start, then prints a per-actor tree of every registered provider (implementation class, scope, dependencies). Cross-actor duplicates are flagged with `⚠ also in: ...`. Use this to confirm that, e.g., your stateless API actually picked the JsonRpc tier-3 viewers.
+
+```sh
+xl1 -c ./xyo.json --dump-providers start api producer
+```
+
 ## License
 
 See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).