Skip to content

Commit ec89ded

Browse files
jeffrey-l-turnerjltatbeach
authored andcommitted
docs(casper): open the cost-accounting decision ledger
- Add docs/casper/design/decision-ledger with an index and eleven entries that compare dev with PR #216 on each Casper consensus decision - Each entry records both positions, the divergence, the options, one unification proposal, and a ratification checklist - Add eleven Proposed rows dated 2026-09-05 to the CONSENSUS_PHILOSOPHY decision table, one per entry, with the flip rule stated - Link the ledger from the casper README design-analyses row
1 parent 093c573 commit ec89ded

14 files changed

Lines changed: 858 additions & 1 deletion

docs/casper/CONSENSUS_PHILOSOPHY.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,19 @@ The method of this document also follows the CBC spirit. CBC derives protocols s
234234
| 2026-08-22 | The scan benchmark uses the 256-block floor limit, 512 visible blocks, and a 10-percent regression limit | Ratified. Measurement remains a merge gate. |
235235
| 2026-09-01 | The repeat-deploy signature index is a consensus-complete carrier cache over valid, invalid, and approved blocks. An in-window absence skips the ancestor scan, a hit requires scope verification, and a read failure falls back to the scan. | Implemented as an issue #24 fast path. Semantic ratification and final issue resolution remain pending. |
236236
| 2026-09-03 | `validate.rs`, `carrier_index.rs`, and `block_dag_key_value_storage.rs` join the mandatory issue #24 CbC scope. | Ratified for `CLAIM-FINALITY-002`. Claim discharge remains pending. |
237+
| 2026-09-05 | D-01: Protocol-version authority and activation. | Proposed in the [decision ledger](./design/decision-ledger/01-protocol-version-authority.md). Pending maintainer ratification. |
238+
| 2026-09-05 | D-02: Certified finalized floor and authority committee. | Proposed in the [decision ledger](./design/decision-ledger/02-certified-floor-authority.md). Pending maintainer ratification. |
239+
| 2026-09-05 | D-03: Fork choice over a certified context. | Proposed in the [decision ledger](./design/decision-ledger/03-fork-choice-certified-context.md). Pending maintainer ratification. |
240+
| 2026-09-05 | D-04: State-preserving finality and effect provenance, including threshold strictness. | Proposed in the [decision ledger](./design/decision-ledger/04-state-preserving-finality.md). Pending maintainer ratification. |
241+
| 2026-09-05 | D-05: Durable finalization publication and its three consensus-visible invariants. | Proposed in the [decision ledger](./design/decision-ledger/05-finalization-publication.md). Pending maintainer ratification. |
242+
| 2026-09-05 | D-06: Heartbeat intents and stale-LFB recovery leadership. | Proposed in the [decision ledger](./design/decision-ledger/06-heartbeat-recovery-leadership.md). Pending maintainer ratification. |
243+
| 2026-09-05 | D-07: Exact-occurrence recovery, carrier-owner custody, and collective-coverage retry packaging. | Proposed in the [decision ledger](./design/decision-ledger/07-deploy-recovery-custody.md). Pending maintainer ratification. |
244+
| 2026-09-05 | D-08: Additive merge semantics, causal rejection closure, and locally replayed mergeable evidence. | Proposed in the [decision ledger](./design/decision-ledger/08-merge-algebra-and-rejection-records.md). Pending maintainer ratification. |
245+
| 2026-09-05 | D-09: Slash authorization from canonical evidence, validator lifetime identity, and the neglect penalty. | Proposed in the [decision ledger](./design/decision-ledger/09-slashing-authorization.md). Pending maintainer ratification. |
246+
| 2026-09-05 | D-10: Carrier-index key, models, and claim text. | Proposed in the [decision ledger](./design/decision-ledger/10-repeat-deploy-carrier-index.md). Pending maintainer ratification. |
247+
| 2026-09-05 | D-11: CbC and FV governance after the cost-accounting work. | Proposed in the [decision ledger](./design/decision-ledger/11-cbc-fv-governance.md). Pending maintainer ratification. |
248+
249+
The 2026-09-05 rows compare `dev` with PR #216. The [decision ledger](./design/decision-ledger/README.md) holds each position, the options, and the unification proposal. A row changes to ratified only after a maintainer approves the ledger entry.
237250

238251
The phase-2 working record lives in the TDD plan
239252
[`docs/tdd-plans/key-contention-starvation-2026-08-20T04-52-46Z.md`](../tdd-plans/key-contention-starvation-2026-08-20T04-52-46Z.md).

docs/casper/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ replication.
1818
| Vocabulary | [Casper Glossary](./GLOSSARY.md) (canonical casper-domain terms; repo-wide terms stay in [docs/Glossary.md](../Glossary.md)) |
1919
| Theory dossiers | [theory/](./theory/README.md) — fork choice, finalized floor, merge algebra, slashing |
2020
| Validation | [validation/](./validation/) — FV campaign gap analysis, merge-recovery validation plan, PR-280 FV review |
21-
| Design analyses | [Casper CbC repair plan](./design/cbc-repair-plan.md) · [LFS Block Requester analysis](./design/lfs-block-requester-analysis.md) · [Cost-accounting CbC and FV reconciliation](./design/cost-accounting-cbc-fv-reconciliation.md) |
21+
| Design analyses | [Casper CbC repair plan](./design/cbc-repair-plan.md) · [LFS Block Requester analysis](./design/lfs-block-requester-analysis.md) · [Cost-accounting CbC and FV reconciliation](./design/cost-accounting-cbc-fv-reconciliation.md) · [Decision ledger](./design/decision-ledger/README.md) |
2222
| CbC claims | [Repeat-deploy carrier-index equivalence](../claims/repeat-deploy-carrier-index-equivalence.md) · [Replay liveness bound](../claims/replay-liveness-bound.md) |
2323
| Economic layer | `casper/src/main/resources/PoS.rhox` — the Rholang bond/slash/reward contract (see [Rholang macro docs](../rholang/16-rhox-macros.md)) |
2424

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# D-01 Protocol-Version Authority and Activation
2+
3+
**Status:** Proposed. Pending maintainer ratification.
4+
**Kind:** Protocol.
5+
**Sources:** dev [Consensus Protocol](../../CONSENSUS_PROTOCOL.md) section 10 and [`formal/tlaplus/deploy_recovery/`](../../../../formal/tlaplus/deploy_recovery). PR #216 DR-34, DR-47, `finalized-floor-specification.md` section 5.2, `CONSENSUS_PROTOCOL.md` "Protocol-Version Authority", `ProtocolVersionLifecycle.tla`, `ProtocolVersionLifecycle.v`.
6+
7+
## 1. Question
8+
9+
Does the Casper protocol have one version authority, and does a new protocol version activate only through a fresh genesis?
10+
11+
## 2. Position on dev
12+
13+
The protocol document lists genesis-locked parameters: the fault-tolerance threshold, the synchrony-constraint threshold, and the native token metadata. Any change needs a new genesis. No normative rule names a protocol version, a supported version set, or a version authority chain.
14+
15+
Two models exist on dev without a normative rule. `ProtocolActivationCoherence.tla` models the migration boundary between legacy and exact-occurrence records. `ProtocolVersionLifecycle.tla` models ceremony, approval, adoption, proposal, and reception with protocol 3 as the current version. Neither model is in the CI gate list.
16+
17+
## 3. Position on PR #216
18+
19+
Section 5.2 of the finalized-floor specification states six rules.
20+
21+
- **R-GENESIS-VERSION.** The ceremony master writes the configured version into the genesis candidate. Each approver compares it with its own configured version before signing.
22+
- **R-APPROVED-SUPPORT.** Approved-block validation rejects every version outside the binary's supported set. The supported set is exactly protocol 6.
23+
- **R-VERSION-ADOPTION.** Every node adopts the approved version into the running shard configuration.
24+
- **R-VERSION-PROPOSAL.** Every proposal carries the running version. No compile-time default bypasses it.
25+
- **R-VERSION-RECEPTION.** Peer-interest filtering and validation compare against the running version and no second source.
26+
- **R-FRESH-GENESIS.** Protocol 6 activates through a fresh genesis. No node-local switch, A/B mode, or block-height window exists.
27+
28+
The protocol document assigns meaning to each version. Version 2 introduces the exact rejected-deploy format. Version 3 adds per-execution state-effect provenance. Version 4 adds vault-backed byte evidence. Version 5 adds certified validator incarnation identity. Version 6 adds signed finalized-floor commitments with certificate sidecars. Versions 1 to 5 remain recognizable but a historical approved genesis is rejected before Casper starts.
29+
30+
DR-34 records the motivating defect: the ceremony hard-coded version 1 while proposal used version 2, so honest validators discarded each other's blocks. DR-34 rejects a block-height switch because it contradicts fresh-genesis deployment and makes replay depend on a removed engine. Genesis-locked parameters gain `max-cosigners-per-deploy`, `initial-phlogiston`, `epoch-phlogiston`, and `client-fuel-allocations`.
31+
32+
## 4. Divergence
33+
34+
| Aspect | dev | PR #216 |
35+
|---|---|---|
36+
| Version authority rule | None | One chain from ceremony to reception |
37+
| Supported set | Not stated | Exactly protocol 6 |
38+
| Activation | New genesis for locked parameters only | New genesis for every protocol version |
39+
| Model gating | Models exist, not gated | `MC_ProtocolVersionLifecycle` and two rejected-version configurations gated |
40+
| Decision record | None | DR-34 says protocol 3. Its historical note says DR-47 moved the value to 4. The specification says 6. |
41+
42+
## 5. Options
43+
44+
- **A. Adopt section 5.2 as written.** The supported set is a specification constant. Every future version change edits the specification and requires a fresh genesis.
45+
- **B. Adopt the authority chain and keep the supported set as a release decision.** Rules R-GENESIS-VERSION to R-VERSION-RECEPTION become normative. R-FRESH-GENESIS and the supported set become a deployment decision with its own ratification row per version.
46+
- **C. Reject fresh-genesis-only activation.** Require a height-activated upgrade path. DR-34 rejects this option because historical replay would need the removed engine.
47+
48+
## 6. Unification proposal
49+
50+
Adopt option B.
51+
52+
The authority chain follows principle P2. The running version derives from the approved block, which is on-chain data every validator sees. A second local source recreates the fork that DR-34 describes.
53+
54+
The supported set and the activation mode are deployment facts. They belong in a dated row per version, not in a rule that changes with each release. The first such row would state that protocol 6 is the sole supported version and activates through a fresh genesis.
55+
56+
## 7. Ratification checklist
57+
58+
- Confirm the protocol number. The DR file, the protocol document, and the specification must agree before the row flips.
59+
- Confirm the operator consequence. Every running shard needs a new genesis to move to protocol 6. The row must say so.
60+
- Add `MC_ProtocolVersionLifecycle` and its two rejected-version configurations to the TLA+ gate list on `dev` when the rules land.
61+
- After ratification, edit the Consensus Protocol section 1 and the finalized-floor specification. Add the version meanings to the Casper glossary.
62+
63+
## 8. Open questions
64+
65+
1. Which version number is current on PR #216 at ratification time? The three sources disagree.
66+
2. Does the read-only observer role need version adoption rules, or does it inherit them from approved-block validation?
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# D-02 Certified Finalized Floor and Authority Committee
2+
3+
**Status:** Proposed. Pending maintainer ratification.
4+
**Kind:** Protocol.
5+
**Sources:** dev [finalized-floor specification](../../theory/finalized-floor/finalized-floor-specification.md) rules R-FLOOR, R-COMM, and S8, [Consensus Philosophy](../../CONSENSUS_PHILOSOPHY.md) ground truth 1, [Consensus Protocol](../../CONSENSUS_PROTOCOL.md) section 2 step 2. PR #216 rules R-AUTHORITY, R-POST-STATE-BONDS, R-PROPOSAL-AUTHORITY, R-PARENT-FLOOR, R-CERTIFICATE-DEPENDENCY to R-CERTIFICATE-RESTART, R-CARRIER-EQUIVALENCE, R-CARRIER-PAIR, R-CARRIER-WAKE, invariants S8, S42, S44, models `CertifiedFloorCommitment.tla`, `FinalizationCertificateRetrieval.tla`, `WitnessEquivalentCarrier.tla`, `WitnessEquivalentCarrier.v`.
6+
7+
## 1. Question
8+
9+
Which committee authorizes a block, and does a block carry a signed commitment to its finalized floor with a detachable certificate?
10+
11+
## 2. Position on dev
12+
13+
R-COMM says the committee that validates a block's bonds is `bonds_of(floor(B))`, a pure function of the floor. S8 forbids validation against a non-floor committee. The protocol document's proposal constraint says the sender must be in the bonded validator set with non-zero stake, and the synchrony constraint counts other validators' recent blocks.
14+
15+
Ground truth 1 says validators replay declared parents and never recompute fork choice. Only the recomputed merge base and the bond check bind the main-parent order. A block carries no floor commitment. The floor is derived from the block's frozen justifications on every node.
16+
17+
## 3. Position on PR #216
18+
19+
- **R-AUTHORITY.** The authority committee is the positive active bonds of `post_state(floor(B))`. The justification validators equal that committee exactly. The sender is a member with positive stake. Synchrony weights use the same committee. A bond transition in the block's own post-state never authorizes that block.
20+
- **R-POST-STATE-BONDS.** The serialized bonds field is a post-state cache, not an authority declaration. Only an accepted block may use it to register a new validator's latest-message slot.
21+
- **R-PROPOSAL-AUTHORITY.** Before replay, a proposer derives the prospective floor from its selected parents and defers when the committee differs from the captured LFB committee.
22+
- **R-PARENT-FLOOR.** A protocol-6 block declares at least one parent that descends from its signed finalized floor. Parent floors form one comparable chain. A verified certificate cache never bypasses the check. The receiver never requires equality with its own preferred frontier.
23+
- **Certificate rules.** A block that names an unavailable certificate is stored detached and waits on a typed dependency. Requests are content-addressed, bounded, and retried with backoff. Responses mutate storage only when they hash to the requested digest. Detached blocks and sidecars survive restart.
24+
- **Carrier rules.** A predecessor certificate carrier is eligible by accepted causal membership, protocol version, exact floor hash, and exact post-state. Two honest nodes can certify the same state from different latest-message snapshots, so the digest may differ. Selection returns the carrier and its own digest as one pair. A parked finalizer wakes on any eligible carrier.
25+
26+
The Consensus Philosophy on PR #216 adds one boundary to ground truth 1: a declared parent must carry the block's signed floor, and the receiver still does not require frontier equality. The floor rule R-FLOOR gains a third source, universal certified advancement, which entry D-04 covers.
27+
28+
## 4. Divergence
29+
30+
| Aspect | dev | PR #216 |
31+
|---|---|---|
32+
| Authority derivation | Bonds of the floor validate bonds. Sender must be bonded. | Positive active bonds of the floor post-state authorize sender, justifications, and synchrony. |
33+
| Justification set | One per bonded validator | Exactly the authority committee |
34+
| Bonds field | Current validator set | Post-state cache with no authority |
35+
| Floor commitment | None. Derived on every node. | Signed in the block. Certificate in a sidecar. |
36+
| Missing floor evidence | Floor walk holds when a block is absent (AbsenceHold) | Typed certificate dependency with bounded retrieval |
37+
| Proposer deferral | None | Defer when the prospective committee differs from the captured LFB committee |
38+
| Wire change | None | Yes. Protocol 6 only. |
39+
40+
## 5. Options
41+
42+
- **A. Adopt the full certificate model.** Signed commitments, sidecars, retrieval, and carrier equivalence become normative at protocol 6.
43+
- **B. Adopt the committee rules now and the certificate rules at the protocol boundary.** R-AUTHORITY, R-POST-STATE-BONDS, and R-PROPOSAL-AUTHORITY need no wire change. They are computable from existing blocks. The certificate rules ratify with D-01 and apply only at protocol 6.
44+
- **C. Keep dev.** The floor stays a derived fact with no commitment.
45+
46+
## 6. Unification proposal
47+
48+
Adopt option B.
49+
50+
The committee rules sharpen R-COMM without changing the wire. They make the sender, justification, and synchrony checks read one committee, which closes the head-local authority split that S8 on PR #216 names. This follows principle P2. The bonds-as-cache rule closes an injection path where an invalid block could register a validator slot from unverified bytes.
51+
52+
The certificate rules change block bytes and add a dependency type. They belong to the protocol-6 boundary that D-01 governs. Ratify them as the protocol-6 form of the floor rule, conditional on D-01.
53+
54+
## 7. Ratification checklist
55+
56+
- Confirm that R-AUTHORITY changes no verdict for any block valid on `dev` today. The sources give no differential evidence for this claim.
57+
- Decide the liveness rule for a block whose certificate is unavailable for longer than the retrieval budget. R-CERTIFICATE-REQUEST retains the obligation. The sources state no upper bound.
58+
- After ratification, amend ground truth 1, replace R-COMM with R-AUTHORITY, and update the proposal constraint table.
59+
60+
## 8. Open questions
61+
62+
1. Does the exact-justification rule reject a block from a validator that learned of a bond change late? R-PROPOSAL-AUTHORITY defers on the proposer side. The receiver-side consequence is not stated.
63+
2. Does the read-only observer need certificate retrieval, or does it inherit certificates from the blocks it validates?

0 commit comments

Comments
 (0)