Verification feature map: behavior-level map the verify-merge skill drives #48

New issue

Open

opened 2026-10-18 23:18:23 +01:00 by vnprc-agent · 0 comments

vnprc-agent commented

2026-10-18 23:18:23 +01:00

Collaborator

Create the behavior-level verification feature map (verification/) that the verify-merge skill drives (allod/memory#83): per-area files answering what exists, how to reach it, how to drive it, and what usually lies — making the full miner→quote→epoch→ecash flow provable on demand, the UI contract explicit field by field, and the keyset rotation behavior covered.

Primary goals:

Skeleton plus three load-bearing areas — verification/features/README.md (baseline preconditions, proof standard, sweep order, the four-questions template) plus share-to-quote.md, epoch-lifecycle.md, and keyset-rotation.md; the remaining areas follow as small PRs, one file each.
Keyset rotation as a first-class behavior — rotation triggers (reward opens the epoch keyset, admin lever, unit-name collision suffix), previous-keyset retirement, mint-info/keys API reflection, wallet keyset-cache behavior, and what the UI shows about the active and retired keysets. Behavioral tests assert the full trigger→keyset→visible transition, not just that a rotation log line appeared.
The UI as a field-level contract — web-ui.md inventories every page of web-pool/web-proxy and every populated field with its data source (prometheus query, API endpoint, db read), and assertions check field population and value shape, never mere HTTP 200. The map, not the templates, is the source of truth for what the UI must show; the planned redesign is judged by the same assertions.
Driver = the stack we already have — devenv stack via justfile (bitcoind regtest, mint, pool, translator, web dashboards), the regtest scenario runner from 92dddda, bitcoin-cli for blocks/reorgs, curl against mint HTTP, sqlite reads for state assertions. Doctor = stack-health preflight (processes, fresh regtest, wallets funded, tip known).
Maintenance rule from allod/memory#83 — map drift is fixed in the same PR as the behavior change; AGENTS.md links the map.

Current state and specifics

The full flow has never been proven end to end; verification to date is unit-level plus the reward-trigger scenario script. Behavior areas:

share-to-quote.md — share accepted (pool message_handler.rs) → quote dispatched → mint pays at finality; vardiff, duplicate suppression; the three difficulty knobs (pool [validation] minimum_share_difficulty_bits, [ehash] minimum_difficulty, dispatcher unwrap_or(32)`) and their mismatch history (security review C-1); #44 mint-side recompute once landed.
epoch-lifecycle.md — rotation on reward (roles/mint/src/lib/epoch/), provisional→final at confirmation_depth, dissolve on reorg, same-height re-mine, watcher watermark recovery; never-reopen and one-epoch-per-height invariants per docs/EPOCH_DESIGN.md.
keyset-rotation.md — per the goal above; includes the collision-suffix path (_1, _2) and retirement of the prior epoch's payment-processor registration.
mint-http-api.md — NUT endpoints, ehash quote status, unit stamping, forged-quote blocker (ea469ca), keyset visibility in mint info.
translator-wallet.md — sweeper discovery via pubkey lookup, unit derivation from quotes not mint-info, restamp handling, reservation recovery (roles/translator/src/lib/payment/quote_sweeper.rs).
pool-listeners.md — connect/handshake/reconnect on both listeners, the wedging regression (#45), connection caps, quote-link loss/recovery (mint_connection.rs, hub pending dedup).
admin-and-faucet.md — rotation lever, loopback binds, faucet issuance limits.
web-ui.md — per page: purpose, every rendered field, its data source, populated/empty/loading states; miner table, hashrate charts and metrics windows, epoch/unit display, keyset and mint-info panels, redaction (redact_ip) behavior. Written as the redesign contract: see below.
multi-surface-journeys.md — full happy path (mine → quote → epoch final → keyset live → sweep → balance visible in UI) and a reorg mid-flight; the regression sweep order.

UI redesign, sequenced through the map: the planned redesign to expose the new features (epoch state, keysets, unit attribution) starts by writing web-ui.md against the current UI — every field that exists today, plus a gap list of behaviors that exist in the backend but surface nowhere (candidates: per-epoch keyset identity, epoch provisional/final state, per-miner ehash attribution, unit provenance on balances). The redesign PR then implements the gap list and updates the map in the same commit, so acceptance of the redesign is literally running the sweep. No redesign work happens before the map exists; the map is the spec.

Seed sources: the security review (notes/hashpool/security-review-2026-10-15.md) for the lying traps; roles/roles-utils/web-assets/ and the web-pool/web-proxy crates for the field inventory.

Scope

In scope: this issue lands the skeleton, README, and files 1–3, with a first end-to-end sweep recorded (commands + observed outputs committed as the example proof) and the web-ui.md field inventory begun as the redesign contract. Follow-up PRs add 4–9. Out of scope: the redesign implementation itself, CI wiring, the verify-merge skill (allod/memory#83), prod-deployment verification. Validation: from clean just clean regtest, the README sweep runs green; share-to-quote.md detects a deliberately broken quote path; keyset-rotation.md fails if rotation is stubbed.

Create the behavior-level verification feature map (`verification/`) that the verify-merge skill drives (allod/memory#83): per-area files answering what exists, how to reach it, how to drive it, and what usually lies — making the full miner→quote→epoch→ecash flow provable on demand, the UI contract explicit field by field, and the keyset rotation behavior covered. Primary goals: - **Skeleton plus three load-bearing areas** — `verification/features/README.md` (baseline preconditions, proof standard, sweep order, the four-questions template) plus `share-to-quote.md`, `epoch-lifecycle.md`, and `keyset-rotation.md`; the remaining areas follow as small PRs, one file each. - **Keyset rotation as a first-class behavior** — rotation triggers (reward opens the epoch keyset, admin lever, unit-name collision suffix), previous-keyset retirement, mint-info/keys API reflection, wallet keyset-cache behavior, and what the UI shows about the active and retired keysets. Behavioral tests assert the full trigger→keyset→visible transition, not just that a rotation log line appeared. - **The UI as a field-level contract** — `web-ui.md` inventories every page of web-pool/web-proxy and every populated field with its data source (prometheus query, API endpoint, db read), and assertions check field population and value shape, never mere HTTP 200. The map, not the templates, is the source of truth for what the UI must show; the planned redesign is judged by the same assertions. - **Driver = the stack we already have** — devenv stack via justfile (bitcoind regtest, mint, pool, translator, web dashboards), the regtest scenario runner from 92dddda, `bitcoin-cli` for blocks/reorgs, curl against mint HTTP, sqlite reads for state assertions. Doctor = stack-health preflight (processes, fresh regtest, wallets funded, tip known). - **Maintenance rule from allod/memory#83** — map drift is fixed in the same PR as the behavior change; `AGENTS.md` links the map. ### Current state and specifics The full flow has never been proven end to end; verification to date is unit-level plus the reward-trigger scenario script. Behavior areas: 1. `share-to-quote.md` — share accepted (pool `message_handler.rs`) → quote dispatched → mint pays at finality; vardiff, duplicate suppression; the three difficulty knobs (pool `[validation] minimum_share_difficulty_bits`, `[ehash] minimum_difficulty, dispatcher `unwrap_or(32)`) and their mismatch history (security review C-1); #44 mint-side recompute once landed. 2. `epoch-lifecycle.md` — rotation on reward (`roles/mint/src/lib/epoch/`), provisional→final at `confirmation_depth`, dissolve on reorg, same-height re-mine, watcher watermark recovery; never-reopen and one-epoch-per-height invariants per `docs/EPOCH_DESIGN.md`. 3. `keyset-rotation.md` — per the goal above; includes the collision-suffix path (`_1`, `_2`) and retirement of the prior epoch's payment-processor registration. 4. `mint-http-api.md` — NUT endpoints, ehash quote status, unit stamping, forged-quote blocker (ea469ca), keyset visibility in mint info. 5. `translator-wallet.md` — sweeper discovery via pubkey lookup, unit derivation from quotes not mint-info, restamp handling, reservation recovery (`roles/translator/src/lib/payment/quote_sweeper.rs`). 6. `pool-listeners.md` — connect/handshake/reconnect on both listeners, the wedging regression (#45), connection caps, quote-link loss/recovery (`mint_connection.rs`, hub pending dedup). 7. `admin-and-faucet.md` — rotation lever, loopback binds, faucet issuance limits. 8. `web-ui.md` — per page: purpose, every rendered field, its data source, populated/empty/loading states; miner table, hashrate charts and metrics windows, epoch/unit display, keyset and mint-info panels, redaction (`redact_ip`) behavior. Written as the redesign contract: see below. 9. `multi-surface-journeys.md` — full happy path (mine → quote → epoch final → keyset live → sweep → balance visible in UI) and a reorg mid-flight; the regression sweep order. **UI redesign, sequenced through the map:** the planned redesign to expose the new features (epoch state, keysets, unit attribution) starts by writing `web-ui.md` against the current UI — every field that exists today, plus a gap list of behaviors that exist in the backend but surface nowhere (candidates: per-epoch keyset identity, epoch provisional/final state, per-miner ehash attribution, unit provenance on balances). The redesign PR then implements the gap list and updates the map in the same commit, so acceptance of the redesign is literally running the sweep. No redesign work happens before the map exists; the map is the spec. Seed sources: the security review (`notes/hashpool/security-review-2026-10-15.md`) for the lying traps; `roles/roles-utils/web-assets/` and the web-pool/web-proxy crates for the field inventory. ### Scope In scope: this issue lands the skeleton, README, and files 1–3, with a first end-to-end sweep recorded (commands + observed outputs committed as the example proof) and the `web-ui.md` field inventory begun as the redesign contract. Follow-up PRs add 4–9. Out of scope: the redesign implementation itself, CI wiring, the verify-merge skill (allod/memory#83), prod-deployment verification. Validation: from clean `just clean regtest`, the README sweep runs green; `share-to-quote.md` detects a deliberately broken quote path; `keyset-rotation.md` fails if rotation is stubbed.

vnprc-agent referenced this issue from a commit

2026-10-19 00:02:00 +01:00

memory: drop departed skills from the private index, add hashpool in-flight pointer

vnprc-agent referenced this issue

2026-10-21 22:12:52 +01:00

Merge rights ledger #49