@ariestools/cli 0.1.16 → 0.1.17

package/README.md

@@ -1116,8 +1116,9 @@ aries witness pentair-schedules --json
 
 ### `aries xyo rewards <sequence|mainnet> <view>`
 
-Query finalized XL1 reward activity through the SDK REST gateway and its block
-rollup indexes.
+Query finalized XL1 **reward lifecycle** activity (pool funding → step holders →
+escrows → redemptions) through the SDK REST gateway and its multi-family block
+rollup indexes (`blocks/*`).
 
 ```sh
 aries xyo rewards sequence summary
@@ -1136,21 +1137,56 @@ aries xyo rewards sequence index verify --concurrency 8
 | `steps` | Per-step direct funding, supplemental funding, and allocation; optionally filter with `--step-level` |
 | `recipients` | Rank recipients at the `funded`, `supplemental-funding`, `allocated`, or `redeemed` stage |
 | `address <address>` | Reward lifecycle events involving an escrow, staker, or destination |
-| `index status` | Show the durable rewards-index head and its XL1/EVM source-watermark lag |
-| `index verify` | Recompute cumulative totals from every immutable reward-step record and verify the snapshot and source hashes |
+| `index status` | Show the durable **network-stake** rewards-index head and its XL1/EVM source-watermark lag |
+| `index verify` | Recompute cumulative **network-stake** totals from every immutable reward-step record and verify the snapshot and source hashes |
+
+**Two different “rewards indexes”.** Do not confuse them:
+
+| Index | Path / command | What it is for | Used by `summary` / `steps` / `recipients` / `address`? |
+|---|---|---|---|
+| Multi-family **blocks** index | `indexes.*.xyo.space` `blocks/{level}/{i}.json` | Bulk block frames for history walks | **Yes** (via `blocksByStep`) |
+| Local **lifecycle cache** | `~/.aries/xyo-rewards/<net>/lifecycle/v1/` | Client-side cumulative summary resume | **Yes** (`summary` only, from-block 0) |
+| Durable **network-stake** rewards index | `rewards/network-stake/v1/{policy}/…` + `xyo rewards … index` | Stake-reward **allocation** math (XL1 ∩ EVM watermarks) | **No** — backfilling or verifying it does **not** speed lifecycle summary |
 
 | Common option | Default | Description |
 |---|---|---|
-| `--from-block <n>` | `0` | First finalized block to include |
+| `--from-block <n>` | `0` | First finalized block to include (non-zero → range-delta lifecycle nets) |
 | `--to-block <n>` | finalized head | Last finalized block to include |
-| `--concurrency <n>` | `2` | Indexed ranges read concurrently, from 1 to 16 |
+| `--recent-blocks <n>` | | Scan only the last N blocks (derived from `--to-block`/head; not with `--from-block`) |
+| `--skip-balance` | `false` | Skip the step-holder balance batch (faster incremental scans; omits outstanding balance) |
+| `--lifecycle-cache` | `true` | Summary only: reuse/extend local cumulative cache under `~/.aries/xyo-rewards/<network>/lifecycle/v1/` |
+| `--refresh-lifecycle-cache` | `false` | Summary only: force a full cumulative rescan and rewrite the local cache |
+| `--concurrency <n>` | `8` | Indexed ranges read concurrently, from 1 to 16 |
 | `--json` | `false` | Stable machine-readable output; XL1 amounts include atto and decimal forms |
 | `--explain` | `false` | Show indexed frame use, direct reads, gateway setup/scan/balance requests, bytes, timing, and SDK budget warnings |
 | `--no-progress` | | Suppress the default gateway and scan progress written to stderr |
 
-The initial rewards-index backfill is an internal S3 mutation and is intentionally
-excluded from the public `aries` binary. Operators run it through `ariesi` only
-while the automatic indexer writer is stopped:
+**Incremental / recent windows.** Full-history mainnet scans are expensive because every
+finalized block’s transfers are decoded. Prefer a bounded window when you only need recent
+activity:
+
+```sh
+aries xyo rewards mainnet summary --recent-blocks 50000 --skip-balance
+aries xyo rewards mainnet summary --from-block 900000 --to-block 950000 --skip-balance
+```
+
+With a non-zero start, funding/allocation/escrow nets are **range deltas**. Step-holder
+balance (unless `--skip-balance`) remains the actual balance at `--to-block`.
+
+**Local lifecycle cache (summary).** Cumulative `summary` runs (`--from-block 0`, no
+`--recent-blocks`) persist accumulator state under
+`~/.aries/xyo-rewards/<network>/lifecycle/v1/head.json`. The next run verifies the
+cached block hash, hydrates unique sets and totals, and **only live-scans the tip**
+above the cache watermark. Use `--no-lifecycle-cache` to disable, or
+`--refresh-lifecycle-cache` to rebuild. Cache status appears in `--explain` and
+stderr progress. This is a client-side acceleration cache — not the durable
+network-stake rewards index under `rewards/network-stake/...`.
+
+The initial **network-stake** rewards-index backfill is an internal S3 mutation and
+is intentionally excluded from the public `aries` binary. It builds stake-allocation
+snapshots under `rewards/network-stake/...` and does **not** feed or accelerate
+`summary` / `steps` / `recipients` / `address`. Operators run it through `ariesi`
+only while the automatic indexer writer is stopped:
 
 ```sh
 ariesi xyo rewards sequence index backfill --dry-run
@@ -1186,8 +1222,12 @@ while the step-holder balance remains the actual balance at `--to-block`.
 
 `--explain` is intentionally part of the product rather than only a debugging
 flag. It separates gateway startup work from the reward scan and makes direct
-block fallbacks, payload volume, and repeated request patterns visible. Those
-measurements identify reward-specific indexes worth publishing through the XL1
+block fallbacks, payload volume, and repeated request patterns visible. It also
+reports **blocks-index lag** (multi-family `blocks/*` watermark vs chain head):
+when the blocks index trails the tip, the unfinished range falls back to
+per-block GETs and full-history scans slow down sharply. Check overall index
+health with `ariesi xyo s3 index monitor mainnet`. Those measurements also
+identify reward-specific lifecycle indexes worth publishing through the XL1
 indexing pipeline as full-history use grows.
 
 Human-readable commands print gateway initialization and bounded scan progress