[codex] Upgrade cluster mempool support to Bitcoin Core 31

CHANGELOG.md

@@ -59,7 +59,7 @@ instrumentation, and a complete bilingual interface.
   - `/fees/compare` shows estimates alongside fee rates from most recent demo/policy runs
 
 - **Cluster Mempool Detector** — `GET /mempool/cluster/compatibility`, `ClusterMempoolPanel.tsx`
-  - Probes `getmempoolcluster` and `getmempoolfeeratediagram`; reports `unavailable` on BC26 without false positives
+  - Probes `getmempoolcluster` and `getmempoolfeeratediagram`; reports `unavailable` on pre-31 nodes without false positives
 
 ### Added — Live Simulation
 

PROJECT_STATUS.md

@@ -32,7 +32,7 @@ http://localhost:5173
 
 | Area | Status | Notes |
 |---|---|---|
-| Bitcoin Core regtest | Ready | Compose starts Bitcoin Core 26 without mainnet, wallet keys, or external services. |
+| Bitcoin Core regtest | Ready | Compose starts Bitcoin Core 31 without mainnet, wallet keys, or external services. |
 | RPC snapshot | Ready | FastAPI reads chain and mempool state through Bitcoin Core RPC. |
 | ZMQ rawtx/rawblock | Ready | Monitor subscribes to real regtest ZMQ events. |
 | NDJSON event logs | Ready | Monitor writes append-only logs under `logs/`. |
@@ -45,7 +45,7 @@ http://localhost:5173
 | ZMQ Event Tape | Ready | Live rawtx/rawblock event stream with topic filters and tx linking. |
 | Mempool Policy Arena | Ready | 4 runnable scenarios: normal, low-fee, RBF (bumpfee), CPFP (raw tx pipeline). |
 | Reorg Lab | Ready (experimental) | 10-step controlled reorg via invalidateblock/reconsiderblock in regtest. |
-| Cluster Mempool Detector | Ready | Detects getmempoolcluster/getmempoolfeeratediagram availability; unavailable on BC26 (documented). |
+| Cluster Mempool Detector | Ready | Detects getmempoolcluster/getmempoolfeeratediagram availability; available on BC31, with fallback for older nodes. |
 | Proof Reports | Ready | JSON proof exported per demo/scenario/reorg run; copiável e downloadable. |
 | Persistence (SQLite) | Ready | Local SQLite storage of proof reports, demo/policy/reorg run history. Memory fallback if SQLite unavailable. |
 | Historical Dashboard | Ready | Browser dashboard listing all past runs across Proof Reports, Demo Runs, Policy Runs, and Reorg Runs with copy-proof support. |
@@ -161,7 +161,7 @@ If SQLite initialisation fails, the API transparently falls back to an in-memory
 - The official demo uses Bitcoin Core regtest only; signet/mainnet operation is intentionally out of scope.
 - `logs/` is local runtime storage, not a production database.
 - Local non-Docker mode is available for development, but Docker is the validated judging path.
-- Cluster mempool RPCs (`getmempoolcluster`, `getmempoolfeeratediagram`) require Bitcoin Core v28+. BC26 returns `unavailable` (documented).
+- Cluster mempool RPCs (`getmempoolcluster`, `getmempoolfeeratediagram`) require Bitcoin Core v31+. pre-31 nodes return `unavailable` (documented).
 - Reorg Lab is experimental and runs only in regtest. Not suitable for production.
 - `prometheus-client` must be installed for `/metrics` to return Prometheus data (included in `requirements.txt`).
 - SQLite history database is local to the container volume. History does not survive `docker compose down -v` unless the volume is preserved.
@@ -196,4 +196,4 @@ If SQLite initialisation fails, the API transparently falls back to an in-memory
 | Multi-node support | Planned |
 | Kubernetes manifests / Helm chart | Planned |
 | signet / mainnet read-only guard | Ready (mutating lab endpoints blocked outside regtest) |
-| Cluster mempool visualization | Ready (fallback visual groups; BC28+ RPCs detected when available) |
+| Cluster mempool visualization | Ready (fallback visual groups; BC31+ RPCs detected when available) |

README.md

@@ -296,12 +296,12 @@ cluster mempool RPCs:
 - `getmempoolcluster`
 - `getmempoolfeeratediagram`
 
-If supported, they are used and results are displayed. If unavailable (Bitcoin Core 26 and earlier),
+If supported, they are used and results are displayed. If unavailable (Bitcoin Core versions before 31),
 NodeScope returns an honest `unavailable` status with a clear explanation — never a false positive.
 
 Available via `GET /mempool/cluster/compatibility`, `GET /mempool/clusters`, and the **Cluster Mempool** tab.
 
-> Cluster mempool RPCs are expected in Bitcoin Core 28+. This build uses Bitcoin Core 26.
+> Cluster mempool RPCs are expected in Bitcoin Core 31+. This build uses Bitcoin Core 31.
 
 ---
 
@@ -501,7 +501,7 @@ The dashboard includes an **Operational Alerts** panel that polls the API every
 
 - Bitcoin Core RPC offline (critical)
 - Live simulation errors (warning)
-- Cluster mempool RPCs unavailable (info — expected on BC26)
+- Cluster mempool RPCs unavailable (info — expected on pre-31 nodes)
 - Reorg Lab experimental note (info)
 
 Alerts are displayed in EN-US or PT-BR according to the active language toggle.
@@ -523,7 +523,7 @@ Output: latency table (min/mean/median/p95/max) per endpoint. Results vary by ho
 ## Limitations
 
 - **Regtest-only** for demo scenarios. Mainnet/signet/testnet observability is possible with configuration changes but not validated in this release.
-- **Cluster mempool RPCs** (`getmempoolcluster`, `getmempoolfeeratediagram`) require Bitcoin Core 28+. This build uses Bitcoin Core 26 — these RPCs return `unavailable` with an honest explanation.
+- **Cluster mempool RPCs** (`getmempoolcluster`, `getmempoolfeeratediagram`) require Bitcoin Core 31+. This build uses Bitcoin Core 31 — these RPCs are available when the node is running.
 - **Reorg Lab** is marked **experimental**: the scenario is reproducible in regtest but may behave differently depending on wallet state.
 - **CPFP child construction** requires the parent output to be tracked in the wallet (`listunspent minconf=0`). If not found, a fallback path is used and the proof records it.
 - **ZMQ events** are stored as NDJSON in `logs/`. There is no persistence across container restarts.
@@ -538,7 +538,7 @@ Output: latency table (min/mean/median/p95/max) per endpoint. Results vary by ho
 |---|---|
 | Signet/testnet support | Planned |
 | Public-network read-only mode | Ready (network guard blocks lab mutations outside regtest) |
-| Cluster mempool visualization | Ready (fallback visual groups; BC28+ RPCs detected when available) |
+| Cluster mempool visualization | Ready (fallback visual groups; BC31+ RPCs detected when available) |
 | Mempool eviction scenario | Planned |
 | Multi-node topology | Planned |
 | Postgres / TimescaleDB for event persistence | Planned |

README.pt-BR.md

@@ -295,12 +295,12 @@ O NodeScope verifica automaticamente se o nó Bitcoin Core conectado suporta RPC
 - `getmempoolcluster`
 - `getmempoolfeeratediagram`
 
-Se suportados, são usados e os resultados são exibidos. Se indisponíveis (Bitcoin Core 26 e anteriores),
+Se suportados, são usados e os resultados são exibidos. Se indisponíveis (versões do Bitcoin Core anteriores à 31),
 o NodeScope retorna um status `unavailable` honesto com explicação clara — nunca um falso positivo.
 
 Disponível via `GET /mempool/cluster/compatibility`, `GET /mempool/clusters` e na aba **Cluster Mempool**.
 
-> RPCs de cluster mempool são esperados no Bitcoin Core 28+. Esta build usa Bitcoin Core 26.
+> RPCs de cluster mempool são esperados no Bitcoin Core 31+. Esta build usa Bitcoin Core 31.
 
 ---
 
@@ -500,7 +500,7 @@ O dashboard inclui um painel de **Alertas Operacionais** que verifica o estado d
 
 - Bitcoin Core RPC offline (crítico)
 - Erros na simulação ao vivo (aviso)
-- RPCs de cluster mempool indisponíveis (info — esperado no BC26)
+- RPCs de cluster mempool indisponíveis (info — esperado em nós pré-31)
 - Nota experimental do Reorg Lab (info)
 
 Os alertas são exibidos em PT-BR ou EN-US conforme o idioma ativo.
@@ -522,7 +522,7 @@ Saída: tabela de latência (min/média/mediana/p95/max) por endpoint. Os result
 ## Limitações
 
 - **Apenas regtest** para cenários de demo. Observabilidade em mainnet/signet/testnet é possível com mudanças de configuração, mas não validada nesta versão.
-- **RPCs de cluster mempool** (`getmempoolcluster`, `getmempoolfeeratediagram`) exigem Bitcoin Core 28+. Esta build usa Bitcoin Core 26 — esses RPCs retornam `unavailable` com explicação honesta.
+- **RPCs de cluster mempool** (`getmempoolcluster`, `getmempoolfeeratediagram`) exigem Bitcoin Core 31+. Esta build usa Bitcoin Core 31 — esses RPCs ficam disponíveis quando o nó está em execução.
 - **Reorg Lab** é marcado como **experimental**: o cenário é reproduzível em regtest, mas pode ter comportamento diferente dependendo do estado da carteira.
 - **Construção do child CPFP** requer que o output do parent esteja rastreado na carteira (`listunspent minconf=0`). Se não encontrado, um caminho alternativo é usado e a prova o registra.
 - **Eventos ZMQ** são armazenados como NDJSON em `logs/`. Não há persistência entre reinicializações de container.
@@ -537,7 +537,7 @@ Saída: tabela de latência (min/média/mediana/p95/max) por endpoint. Os result
 |---|---|
 | Suporte a signet/testnet | Planejado |
 | Modo read-only para redes públicas | Pronto (proteção bloqueia mutações de laboratório fora de regtest) |
-| Visualização de cluster mempool | Pronto (grupos visuais via fallback; RPCs BC28+ detectados quando disponíveis) |
+| Visualização de cluster mempool | Pronto (grupos visuais via fallback; RPCs BC31+ detectados quando disponíveis) |
 | Cenário de expulsão da mempool | Planejado |
 | Topologia multi-nó | Planejado |
 | Postgres / TimescaleDB para persistência de eventos | Planejado |

RELEASE_NOTES_v1.1.0.md

@@ -61,7 +61,7 @@ RPC offline (critical), simulation errors (warning), cluster mempool unavailable
 
 **Cluster Mempool Detector**
 Probes `getmempoolcluster` and `getmempoolfeeratediagram`. Returns an honest `unavailable`
-on Bitcoin Core 26 — never a false positive. Ready for Bitcoin Core 28+.
+on pre-31 Bitcoin Core nodes — never a false positive. Ready for Bitcoin Core 31+.
 
 ---
 
@@ -155,7 +155,7 @@ No database migrations required. SQLite history is created automatically on firs
 ## Known Limitations
 
 - Regtest-only for demo scenarios. Signet/mainnet support is planned.
-- Cluster mempool RPCs require Bitcoin Core 28+. This release uses Bitcoin Core 26 — `getmempoolcluster` returns `unavailable`.
+- Cluster mempool RPCs require Bitcoin Core 31+. This release uses Bitcoin Core 31 — `getmempoolcluster` is available.
 - Reorg Lab is marked experimental. Behavior may vary depending on wallet state.
 - SQLite history is local to the container volume and does not survive `docker compose down -v`.
 - `estimatesmartfee` returns `unavailable` or `limited` in regtest — no real fee market exists.

ROADMAP.md

@@ -23,7 +23,7 @@ Everything below is shipped and functional in the current release.
 | ZMQ Event Tape | Live rawtx/rawblock stream with topic filters and tx linking |
 | Mempool Policy Arena | 4 scenarios: Normal, Low-fee, RBF (BIP125), CPFP |
 | Reorg Lab | 10-step controlled chain reorganization (experimental) |
-| Cluster Mempool Detector | Probes getmempoolcluster/getmempoolfeeratediagram; honest unavailable on BC26 |
+| Cluster Mempool Detector | Probes getmempoolcluster/getmempoolfeeratediagram; honest available on BC31 |
 | Proof Reports | JSON audit trail per demo/scenario/reorg run; copyable and downloadable |
 | Live Simulation Engine | Auto-mines blocks and sends transactions at configurable intervals |
 | Prometheus metrics (`/metrics`) | 24+ metrics covering HTTP, RPC, ZMQ, mempool, chain, simulation, storage |
@@ -32,7 +32,7 @@ Everything below is shipped and functional in the current release.
 | Historical trend charts | Mempool size and minimum fee time-series charts |
 | Read-only network guard | Blocks mutating lab operations outside regtest unless explicitly allowed |
 | API rate limiting | Sliding-window protection with demo-friendly defaults |
-| Visual cluster mempool view | Uses BC28+ cluster RPCs when available; otherwise displays honest fallback groups |
+| Visual cluster mempool view | Uses BC31+ cluster RPCs when available; otherwise displays honest fallback groups |
 | Optional API key auth | Mutating endpoints protected via `X-NodeScope-API-Key` when `NODESCOPE_REQUIRE_API_KEY=true` |
 | SQLite persistence | Proof reports, demo/policy/reorg run history; in-memory fallback if SQLite unavailable |
 | Historical Dashboard | Paginated view of all past runs across all scenario types |
@@ -65,7 +65,7 @@ Nothing is currently in active development.
 | Dashboard adapted for signet | Remove "mine block" controls; read-only mode indicators |
 | Mainnet read-only mode | `BITCOIN_NETWORK=mainnet` with explicit network safeguards |
 | Hosted deployment tuning | Public rate-limit profiles, reverse proxy examples, and SSE sizing |
-| Enhanced Bitcoin Core 28+ cluster views | More detailed diagrams when getmempoolcluster/getmempoolfeeratediagram are available |
+| Enhanced Bitcoin Core 31+ cluster views | More detailed diagrams when getmempoolcluster/getmempoolfeeratediagram are available |
 | Mempool eviction scenario | Demonstrate fee-based eviction from the mempool |
 | Advanced classification heuristics | UTXO consolidation, batch payments, Taproot script patterns |
 | OpenTelemetry traces | RPC, ZMQ, and API request traces |
@@ -87,7 +87,7 @@ Nothing is currently in active development.
 ## Design Principles
 
 - **Observable internals.** Every classification includes confidence signals. Every scenario generates a Proof Report.
-- **Honest accounting.** Unavailable features (cluster mempool on BC26, fee estimation in regtest) are reported as `unavailable` — never hidden or faked.
+- **Honest accounting.** Unavailable features (cluster mempool on pre-31 nodes, fee estimation in regtest) are reported as `unavailable` — never hidden or faked.
 - **Replayable data.** NDJSON logs are the durable source of truth; the engine can reprocess from scratch.
 - **No custodial operations.** NodeScope never signs transactions or manages private keys in production mode.
 - **Explicit network scoping.** regtest, signet, and mainnet will be explicitly configured and guarded.

api/rpc.py

@@ -78,6 +78,9 @@ def loadwallet(self, wallet_name: str) -> dict[str, Any]:
     def getwalletinfo(self) -> dict[str, Any]:
         return self.call("getwalletinfo")  # type: ignore[return-value]
 
+    def getbalances(self) -> dict[str, Any]:
+        return self.call("getbalances")  # type: ignore[return-value]
+
     def listwallets(self) -> list[str]:
         return self.call("listwallets")  # type: ignore[return-value]