@xyo-network/xl1-cli 4.3.0 → 4.3.1

package/README.md

@@ -765,7 +765,7 @@ Indexer: `s3-index` publish + REST CDN viewers.
 
 ## Per-actor production deployment
 
-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.
+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-compatible object storage (e.g. Cloudflare R2) 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 |
 |-------|---------------------|--------------|-------|
@@ -781,7 +781,7 @@ One config per actor **process** — the shape a real multi-host deployment runs
 - **`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` 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.
+- **Secrets.** `YOUR_*` placeholders (S3 credentials, 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)
 
@@ -1290,6 +1290,22 @@ export XL1_ACTORS__1__PUBLISH_ON_FINALIZE=true
 export XL1_ACTORS__2__PUBLISH_SYNC_INTERVAL=5000
 ```
 
+### Naming reference (bucket roles vs frozen legacy names)
+
+The naming convention across XL1 code and config: **"S3"** means the S3-compatible object-storage protocol (Cloudflare R2 is one implementation — "R2" only appears in Cloudflare-specific helpers and docs), and each bucket is identified by its **role**: `finalized`, `chain-state`, `index` (plus `datalake` where used). Casing follows context — camelCase in TypeScript identifiers and config record keys (`chainState`), kebab-case in connection names, env-var segments, and physical names (`s3-chain-state`).
+
+| Bucket role | Connection name | Env prefix | Typical bucket (frozen) | Endpoint subdomain (frozen) | Wire schemas served (frozen) |
+|---|---|---|---|---|---|
+| `finalized` | `s3-finalized` | `XL1_CONNECTIONS__S3_FINALIZED__*` | `xl1-chain` | `blocks.<domain>` | `network.xyo.s3.chain.manifest` |
+| `chain-state` | `s3-chain-state` | `XL1_CONNECTIONS__S3_CHAIN_STATE__*` | `xl1-chain-state` | `state.<domain>` | `network.xyo.s3.chain.contract` |
+| `index` | `s3-index` | `XL1_CONNECTIONS__S3_INDEX__*` | `xl1-index` | `indexes.<domain>` | `network.xyo.s3.index.manifest`, `network.xyo.s3.index.head` |
+
+The columns marked **frozen** are deployed infrastructure or wire format that predates the role naming — they intentionally do not match the role names and must not be "fixed":
+
+- The physical bucket `xl1-chain` serves the `finalized` role (it predates the role name; live buckets are a migration, not a rename).
+- The `blocks.` / `state.` / `indexes.` endpoint subdomains (derived by the SDK's `restGatewayConfigFromEndpoint`) are deployed DNS; the `finalized` role maps to the `blocks.` subdomain.
+- The static-layout document schemas are namespaced `network.xyo.s3.*` even though the documents are transport-neutral; renaming them would be a breaking wire change. New static-layout schemas should use a transport-neutral namespace instead.
+
 ## 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.