@xyo-network/xl1-cli 4.0.6 → 4.2.1

package/README.md

@@ -191,6 +191,8 @@ Named **connections** describe where providers read/write state:
 
 **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).
 
+Set the root option **`strictDependencies: true`** to disable implicit in-memory provider creation. In strict mode, every memory-backed dependency must have an explicit `providerBindings.<Moniker>.connection` pointing to a declared memory connection. An unbound required dependency fails configuration, while an unbound optional dependency is omitted. The option defaults to `false`; config-less runs retain the in-memory development preset and implicit memory fallback.
+
 **Index summaries** use two monikers (not one provider per family):
 
 | Moniker | Typical connection | Role |
@@ -198,6 +200,15 @@ Named **connections** describe where providers read/write state:
 | `IndexViewer` | `rest-index` (CDN) or `memory` (local dev) | Read step-summary families: `balances`, `blocks`, `schemas`, `transfers` |
 | `IndexPublishRunner` | `s3-index` | Publish those families to the index bucket |
 
+**Finalized EVM contract events** reuse the index bucket under an address-scoped `evm/events/` layout:
+
+| Moniker | Typical connection | Role |
+|---|---|---|
+| `EvmEventIndexPublishRunner` | `s3-index` | Read all logs for `chain.id` through Ethereum's `finalized` head and publish resumable range frames |
+| `StakeEventsViewer` | `rest-index` | Decode the published raw logs with the staking ABI; no historical `eth_getLogs` calls |
+
+The EVM index is optional. Bind `EvmChainViewer → default-evm-rpc` and `EvmEventIndexPublishRunner → s3-index` on the indexer to enable it. Bind `StakeEventsViewer → rest-index` on reward/staking consumers. Without the REST binding, `EvmStakeEventsViewer` remains the direct-RPC fallback.
+
 Local dev omits `IndexViewer` — `AccountBalanceViewer` computes summaries on demand from `BlockViewer`. Bind `IndexViewer` → `memory` (`SimpleIndexViewer`) when you want in-process summary memoization without S3.
 
 **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).
@@ -617,6 +628,11 @@ Mongo store plus S3 publish connections for finalizer and indexer in one process
         "database": "xl1",
         "domain": "internal"
       },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
       "s3-finalized": {
         "type": "s3",
         "accountId": "YOUR_R2_ACCOUNT_ID",
@@ -648,8 +664,11 @@ Mongo store plus S3 publish connections for finalizer and indexer in one process
     "providerBindings": {
       "BlockViewer": { "connection": "chain-mongo" },
       "BlockPublishRunner": { "connection": "s3-finalized" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
       "ChainStatePublishRunner": { "connection": "s3-chain-state" },
       "ChainStateViewer": { "connection": "s3-chain-state" },
+      "EvmChainViewer": { "connection": "default-evm-rpc" },
+      "EvmEventIndexPublishRunner": { "connection": "s3-index" },
       "FinalizationRunner": { "connection": "chain-mongo" },
       "FinalizationViewer": { "connection": "chain-mongo" },
       "IndexPublishRunner": { "connection": "s3-index" },
@@ -694,6 +713,11 @@ Indexer: `s3-index` publish + REST CDN viewers.
         "bucket": "xl1-index",
         "readUrl": "https://index.xl1.example"
       },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
       "rest-finalized": {
         "type": "rest",
         "baseUrl": "https://chain.xl1.example"
@@ -714,6 +738,12 @@ Indexer: `s3-index` publish + REST CDN viewers.
       "ChainStateViewer": {
         "connection": "rest-chain-state"
       },
+      "EvmChainViewer": {
+        "connection": "default-evm-rpc"
+      },
+      "EvmEventIndexPublishRunner": {
+        "connection": "s3-index"
+      },
       "IndexViewer": {
         "connection": "rest-index"
       },
@@ -742,14 +772,14 @@ One config per actor **process** — the shape a real multi-host deployment runs
 | `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 |
+| `indexer` | `default-evm-rpc` (when event indexing is enabled) | `s3-index` | finalized blocks + chain-state over REST; finalized contract logs from EVM |
 | `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.
+- **Staking.** `chain.id` is the staking contract address on the backing EVM. The indexer needs `default-evm-rpc` only when `EvmEventIndexPublishRunner` is enabled. Staking/reward consumers can bind `StakeEventsViewer → rest-index` for indexed finalized history while retaining EVM bindings for mutating calls and point-in-time contract state.
 - **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.
 
@@ -883,6 +913,11 @@ One config per actor **process** — the shape a real multi-host deployment runs
         "database": "xl1",
         "domain": "internal"
       },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
       "s3-finalized": {
         "type": "s3",
         "accountId": "YOUR_R2_ACCOUNT_ID",
@@ -902,12 +937,16 @@ One config per actor **process** — the shape a real multi-host deployment runs
         "readUrl": "https://chain-state.xl1.example"
       }
     },
+    "chain": {
+      "id": "dd381fbb392c85160d8b0453e446757b12384046"
+    },
     "providerBindings": {
       "AccountBalanceViewer": { "connection": "chain-mongo" },
       "BlockPublishRunner": { "connection": "s3-finalized" },
       "BlockRunner": { "connection": "chain-mongo" },
       "BlockValidationViewer": { "connection": "chain-mongo" },
       "BlockViewer": { "connection": "chain-mongo" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
       "ChainStatePublishRunner": { "connection": "s3-chain-state" },
       "ChainStateViewer": { "connection": "s3-chain-state" },
       "DeadLetterQueueRunner": { "connection": "chain-mongo" },
@@ -956,6 +995,11 @@ One config per actor **process** — the shape a real multi-host deployment runs
         "type": "rest",
         "baseUrl": "https://index.xl1.example"
       },
+      "default-evm-rpc": {
+        "type": "evm-rpc",
+        "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID",
+        "chainId": "0xaa36a7"
+      },
       "s3-index": {
         "type": "s3",
         "accountId": "YOUR_R2_ACCOUNT_ID",
@@ -973,6 +1017,12 @@ One config per actor **process** — the shape a real multi-host deployment runs
       "ChainStateViewer": {
         "connection": "rest-chain-state"
       },
+      "EvmChainViewer": {
+        "connection": "default-evm-rpc"
+      },
+      "EvmEventIndexPublishRunner": {
+        "connection": "s3-index"
+      },
       "IndexViewer": {
         "connection": "rest-index"
       },
@@ -1168,18 +1218,21 @@ Beyond the authority store (`lmdb` / `mongodb`), the chain can publish a static,
 |---|---|---|
 | `finalized` | `finalizer` (when `publishOnFinalize` is set) | finalized blocks, payloads, `manifest.json` |
 | `chainState` | `finalizer` (when `publishOnFinalize` is set) | the mutable head pointer (`head.json`) |
-| `index` | `indexer` | the step-summary families (`blocks`, `balances`, `schemas`, `transfers`), `manifest.json`, `head.json` watermark |
+| `index` | `indexer` | step-summary families plus optional address-scoped finalized EVM event frames and their manifests/head pointers |
 
 The `indexer` is gated at the finalized head the `finalizer` has published, so `publishOnFinalize` must be enabled on the finalizer for the index to advance.
 
 Configure the buckets as named `connections` (`s3-finalized`, `s3-chain-state`, `s3-index`). Credentials and `prefix` can be set per connection; each bucket sets its own `bucket` name and public `readUrl` — the CDN base URL anonymous reads go through, so they hit the CDN rather than the (per-operation billed) S3 API.
 
+The `chainState` bucket also carries the chain-contract manifest (`minWithdrawalBlocks`, `rewardsContract`, `stakingTokenAddress`), read from `ChainContractViewer` when the publisher starts — so a chain-state-publishing finalizer must bind `ChainContractViewer` to an `evm-rpc` connection (config compilation rejects the plan otherwise; an explicit memory binding opts into dev placeholder values instead).
+
 `xyo.json`:
 ```json
 {
   "xl1": {
     "connections": {
       "chain-mongo": { "type": "mongo", "connectionString": "mongodb://user:pass@db.internal:27017", "database": "xl1", "domain": "internal" },
+      "default-evm-rpc": { "type": "evm-rpc", "url": "https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID", "chainId": "0xaa36a7" },
       "s3-finalized": { "type": "s3", "accountId": "…", "accessKeyId": "…", "secretAccessKey": "…", "prefix": "", "bucket": "xl1-chain", "readUrl": "https://chain.xl1.example" },
       "s3-chain-state": { "type": "s3", "bucket": "xl1-chain-state", "readUrl": "https://chain-state.xl1.example" },
       "s3-index": { "type": "s3", "bucket": "xl1-index", "readUrl": "https://index.xl1.example" }
@@ -1187,8 +1240,11 @@ Configure the buckets as named `connections` (`s3-finalized`, `s3-chain-state`,
     "providerBindings": {
       "BlockViewer": { "connection": "chain-mongo" },
       "BlockPublishRunner": { "connection": "s3-finalized" },
+      "ChainContractViewer": { "connection": "default-evm-rpc" },
       "ChainStatePublishRunner": { "connection": "s3-chain-state" },
       "ChainStateViewer": { "connection": "s3-chain-state" },
+      "EvmChainViewer": { "connection": "default-evm-rpc" },
+      "EvmEventIndexPublishRunner": { "connection": "s3-index" },
       "FinalizationRunner": { "connection": "chain-mongo" },
       "FinalizationViewer": { "connection": "chain-mongo" },
       "IndexPublishRunner": { "connection": "s3-index" },