docs: mining epoch design (per-epoch units, reward-triggered rotation) #12

Merged

vnprc merged 6 commits from agent/epoch-design-docs into master

2026-08-13 06:22:57 +01:00

vnprc-agent commented

2026-08-12 18:05:17 +01:00

Collaborator

Design docs only — no code or config changes for any running machine.

Adds docs/EPOCH_DESIGN.md, the canonical design for mining epochs: per-epoch currency units named by block height, mint-owned epoch creation, mint-side block-reward detection, quotes held unpaid until the epoch boundary confirms, and reorg resolution via provisional boundaries (dissolve = re-stamp and pay; same-height re-mine reuses the epoch).

Adds docs/pr/cdk-dynamic-payment-processors.md, the upstream-facing design for registering and retiring payment processors on a running CDK mint — written to be filed on cashubtc/cdk for discussion before the PR.

Updates docs/SETTLEMENT_DESIGN.md in place with marked supersession notes at exactly the passages the new design replaces (pool-sent BlockFound as the trigger; pool-requested asset creation; HASH_epoch_42 naming). Settlement mechanics themselves are untouched and remain future work.

Nothing here executes; if any of it is wrong, the fix is editing the docs. A tracking issue plus six implementation issues follow on the forge and will reference these documents.

Validation

Design claims were verified against the pinned CDK revision and the current tree during the design session: quote-state gating (unpaid quotes excluded from the mintable lookup filter and rejected twice at mint time; pay idempotent by payment id), keyset creation for brand-new units, unit-blind quote lookup and per-unit wallet-store safety, the frozen payment-processor map and its consumers, and the dev harness block-production behavior. Decisions record owner rulings from the session.

Design docs only — no code or config changes for any running machine. Adds `docs/EPOCH_DESIGN.md`, the canonical design for mining epochs: per-epoch currency units named by block height, mint-owned epoch creation, mint-side block-reward detection, quotes held unpaid until the epoch boundary confirms, and reorg resolution via provisional boundaries (dissolve = re-stamp and pay; same-height re-mine reuses the epoch). Adds `docs/pr/cdk-dynamic-payment-processors.md`, the upstream-facing design for registering and retiring payment processors on a running CDK mint — written to be filed on cashubtc/cdk for discussion before the PR. Updates `docs/SETTLEMENT_DESIGN.md` in place with marked supersession notes at exactly the passages the new design replaces (pool-sent `BlockFound` as the trigger; pool-requested asset creation; `HASH_epoch_42` naming). Settlement mechanics themselves are untouched and remain future work. Nothing here executes; if any of it is wrong, the fix is editing the docs. A tracking issue plus six implementation issues follow on the forge and will reference these documents. ## Validation Design claims were verified against the pinned CDK revision and the current tree during the design session: quote-state gating (unpaid quotes excluded from the mintable lookup filter and rejected twice at mint time; pay idempotent by payment id), keyset creation for brand-new units, unit-blind quote lookup and per-unit wallet-store safety, the frozen payment-processor map and its consumers, and the dev harness block-production behavior. Decisions record owner rulings from the session.

vnprc-agent added 1 commit

2026-08-12 18:05:17 +01:00