fix(compose): forward the observer's cranker and cleanup settings

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+
+### Fixed
+
+- **Observer cranker settings reachable from `.env`** — `CRANK_BATCH_SIZE`,
+  `CRANK_CLOSE_EPOCHS`, `CRANK_EPOCH_RETENTION`, `CRANK_WARN_BALANCE_SOL`,
+  `CRANK_CRITICAL_BALANCE_SOL`, `CLEANUP_BATCH_SIZE`,
+  `CLEANUP_FAILURE_THRESHOLD`, `MAX_CLEANUP_TXS_PER_CYCLE`,
+  `ALT_RECLAIM_SCAN_LIMIT` and `OBSERVED_GATEWAY_HOSTS` are read by the observer
+  but were never passed into its container, so setting them in `.env` had no
+  effect. Forwarded with the established empty-default pattern and documented,
+  completing what #842 (poll/cleanup intervals) and #846 (prune budget) started.
+  An empty value resolves to each setting's existing default, so nothing changes
+  unless an operator sets one.
+
 ## [Release 82] - 2026-08-11
 
 This is a **recommended release** focused on **data-retrieval correctness and

docker-compose.yaml

@@ -648,6 +648,16 @@ services:
       - CRANK_POLL_INTERVAL_MS=${CRANK_POLL_INTERVAL_MS:-}
       - CLEANUP_MIN_INTERVAL_MS=${CLEANUP_MIN_INTERVAL_MS:-}
       - CLEANUP_TO_RETURNED_TXS_PER_CYCLE=${CLEANUP_TO_RETURNED_TXS_PER_CYCLE:-}
+      - CRANK_BATCH_SIZE=${CRANK_BATCH_SIZE:-}
+      - CRANK_CLOSE_EPOCHS=${CRANK_CLOSE_EPOCHS:-}
+      - CRANK_EPOCH_RETENTION=${CRANK_EPOCH_RETENTION:-}
+      - CRANK_WARN_BALANCE_SOL=${CRANK_WARN_BALANCE_SOL:-}
+      - CRANK_CRITICAL_BALANCE_SOL=${CRANK_CRITICAL_BALANCE_SOL:-}
+      - CLEANUP_BATCH_SIZE=${CLEANUP_BATCH_SIZE:-}
+      - CLEANUP_FAILURE_THRESHOLD=${CLEANUP_FAILURE_THRESHOLD:-}
+      - MAX_CLEANUP_TXS_PER_CYCLE=${MAX_CLEANUP_TXS_PER_CYCLE:-}
+      - ALT_RECLAIM_SCAN_LIMIT=${ALT_RECLAIM_SCAN_LIMIT:-}
+      - OBSERVED_GATEWAY_HOSTS=${OBSERVED_GATEWAY_HOSTS:-}
       # Solana wallet identities (operator/observer/upload). All four
       # supported configurations are documented in the observer's
       # `src/wallet-config.ts`. Each role accepts EITHER a JSON-file path

docs/envs.md

@@ -177,6 +177,16 @@ This document describes the environment variables that can be used to configure
 | CRANK_POLL_INTERVAL_MS                           | Number               | derived from epoch duration                   | Observer epoch-cranker poll cadence, in milliseconds. Only applies when `ENABLE_EPOCH_CRANKING=true`. Leave unset to let the observer derive the cadence from the epoch duration; an explicit value always wins. Must be a positive integer when set.                    |
 | CLEANUP_MIN_INTERVAL_MS                          | Number               | derived from epoch duration                   | Minimum interval, in milliseconds, between observer cleanup passes. Only applies when `ENABLE_CLEANUP=true`. Leave unset to let the observer derive the cadence from the epoch duration; an explicit value always wins. Must be a positive integer when set.             |
 | CLEANUP_TO_RETURNED_TXS_PER_CYCLE                | Number               | 10                                            | Maximum `prune_name_to_returned` transactions the cranker submits per cleanup scan. Only applies when `ENABLE_CLEANUP=true`. The instruction takes a single ArNS record, so unlike the other prune steps it cannot batch into one transaction and this sets its throughput. One per scan caps conversion at roughly the rate leases expire, so an expired-lease backlog never drains and each name that ages out of its return-auction window loses that auction permanently. Requires observer image 15e285b0 or newer. |
+| CRANK_BATCH_SIZE                                 | Number               | 15                                            | Gateway/observer accounts processed per `tally` and `distribute` transaction. Only applies when `ENABLE_EPOCH_CRANKING=true`. |
+| CRANK_CLOSE_EPOCHS                               | Boolean              | true                                          | Close fully-distributed epochs past `CRANK_EPOCH_RETENTION`, refunding their PDA rent to the cranker wallet. Closing an epoch also closes its Observation PDAs, which removes that epoch's per-observer report detail from chain — set `false` to keep the detail readable at the cost of the rent. |
+| CRANK_EPOCH_RETENTION                            | Number               | 7                                             | Number of recent epochs to keep before closing. The cranker closes epoch `current - CRANK_EPOCH_RETENTION`, so this is how many epochs of on-chain history remain queryable. Note `close_observation` and `close_epoch` are permissionless: another operator's cranker running a lower retention will close epochs regardless of this setting. |
+| CRANK_WARN_BALANCE_SOL                           | Number               | 0.3                                           | Log a warning when the cranker wallet's SOL balance falls below this. |
+| CRANK_CRITICAL_BALANCE_SOL                       | Number               | 0.1                                           | Log a critical alert when the cranker wallet's SOL balance falls below this. Cranking stops once the wallet cannot pay transaction fees. |
+| CLEANUP_BATCH_SIZE                               | Number               | 15                                            | Accounts pruned per cleanup transaction (`prune_expired_names`, `prune_returned_names`). Only applies when `ENABLE_CLEANUP=true`. |
+| CLEANUP_FAILURE_THRESHOLD                        | Number               | 30                                            | Consecutive-failure count at which a gateway becomes eligible for `prune_gateway`. Mirrors the on-chain `EpochSettings.max_consecutive_failures`. |
+| MAX_CLEANUP_TXS_PER_CYCLE                        | Number               | 50                                            | Hard cap on cleanup transactions submitted per cleanup cycle, shared across all cleanup phases. Bounds gas spend if discovery returns thousands of stale accounts. |
+| ALT_RECLAIM_SCAN_LIMIT                           | Number               | 200                                           | Recent signatures scanned per pass when reclaiming rent from single-use prescribe Address Lookup Tables (~0.0126 SOL each). Set `0` to disable reclamation. Reclaiming a prescribe ALT removes the observer index for its epoch, so `getEpoch` can no longer enumerate that epoch's reports even while the underlying accounts live. |
+| OBSERVED_GATEWAY_HOSTS                           | String               | (all registered gateways)                     | Comma-separated list restricting which gateway hosts this observer assesses. Empty observes every gateway in the registry. **Do not put spaces after the commas** — entries are split on `,` and are not trimmed, so `a.com, b.com` yields a second entry of `" b.com"` that matches no gateway. Use `a.com,b.com`. |
 | REDIS_MAX_MEMORY                                 | String               | 256mb                                         | Sets the max memory allocated to Redis                                                                                                                               |
 | REDIS_DATA_PATH                                  | String               | "./data/redis"                                | Sets the location for Redis data persistence files (dump.rdb, appendonly.aof). Only used if persistence is enabled via EXTRA_REDIS_FLAGS                            |
 | EXTRA_REDIS_FLAGS                                | String               | --save "" --appendonly no                     | Additional CLI flags passed to Redis server. Default disables persistence for performance. Set to "--save 300 10 --appendonly yes --appendfsync everysec" to enable hybrid persistence (recommended for x402 paid tokens) |