Unit 8: the commitment scheme, spec and record

CLAUDE.md

@@ -62,7 +62,8 @@ In practice this means:
    touching semantics references its spec section. The spec states
    behavior only, and stays complete enough on its own to predict
    every vector's outcome. Rationale, oracle provenance, and decision
-   records live in `docs/` (for the VM, `docs/vm-record.md`), with
+   records live in `docs/` (for the VM, `docs/vm-record.md`, for the
+   commitment scheme, `docs/commitment-record.md`), with
    no exception: a curation-note carve-out was ratified 2026-07-29
    and reversed 2026-08-08 (decisions 5 and 17 in
    `docs/condition-record.md`).

docs/README.md

@@ -14,6 +14,10 @@
   behind spec/CONDITIONS.md and spec/VALIDATION.md, the
   divergence-from-Chia table, reference provenance, decision record,
   and the novel-layer register. Cited by CLAUDE.md ground rule 3.
+- [commitment-record.md](commitment-record.md): the record behind
+  spec/SPEC.md, the leaf version and commitment scheme, its
+  reference provenance, the measurements it rests on, and the
+  decision record.
 - [opcode-comparison.md](opcode-comparison.md): informative side-by-side
   of the CLVM, bllsh, and BitLisp operator sets.
 - [objection-register.md](objection-register.md): every objection on

docs/condition-comparison.md

@@ -102,6 +102,7 @@ delegate to.
 | own amount | `ASSERT_MY_AMOUNT` 73 | `ASSERT_MY_AMOUNT` `0x33`, normative |
 | own taproot components | absent | removed (decision 29): `ASSERT_MY_TAPTREE` `0x38` subsumes the derivation assert, `0x37` now a visible gap |
 | own taptree | absent | `ASSERT_MY_TAPTREE` `0x38`, normative, reads the control block's internal key and merkle root at the generic cost (decision 28) |
+| own annex | absent | `ASSERT_MY_ANNEX` `0x39`, normative, reads the annex's BIP341 sha_annex digest at the generic cost, the annex admitted only under it (decision 30) |
 | own birth time or height | `ASSERT_MY_BIRTH_SECONDS` 74, `ASSERT_MY_BIRTH_HEIGHT` 75 | declined, a chain read outside the transaction view (C13) |
 | ephemerality | `ASSERT_EPHEMERAL` 76, the coin was created in the same block it is spent | declined, structurally inexpressible within one transaction (C14) |
 

docs/condition-record.md

@@ -39,6 +39,7 @@ Section 4 registers the rules that have no external reference at all.
 | C22 | signature-condition cost | 1,200,000 (AGG_SIG_COST) per occurrence in every regime, pricing one BLS pairing toward the bundle aggregate | 1,300,000 (CONDITION_SIG_ASSERT_COST), equal to the VM's SECP_VERIFY_COST, PROVISIONAL | Both layers of BitLisp price the same BIP340 verification, so the condition constant ties to the operator constant rather than to Chia's BLS figure: one Phase 4 measurement settles both, and a program can never buy the same verification cheaper in one layer than the other. Chia's magnitude corroborates the range, their pairing being work of the same order. Ratified 2026-08-09, decision 25. | `conditions/costs.json` signature cases |
 | C23 | execution-identity addressing | none: puzzle hash is both the coin's script commitment and the executing program, one field carries both meanings | the specifier table composes the executing leaf's tapleaf hash (bit 3) and the spending path's merkle root (bit 4) onto the prevout rows, commitment values 0 to 31, the mode packed as assurer times 32 plus requirer, both fields validator-filled from the control block. The pair itself is renamed ASSURE and REQUIRE (decision 27) | Taproot splits Chia's one identity into two, and the C9 mapping carried only the script commitment, so program-to-program trust had no faithful addressing field. Internal-key addressing declined as attacker-satisfiable (no possession proof in BIP341). Grafted-leaf and moved-root caveats recorded in decision 26 and in rule 3's author guidance. Ratified 2026-08-18, decision 26, landed 2026-08-20. | `validation/messages.json` identity cases, `conditions/messages.json` composed-mode cases |
 | C24 | the cheap identity assert | none: ASSERT_MY_PUZZLEHASH reads the one identity field, and no derive-versus-read split exists because a puzzle hash is a plain tree hash | ASSERT_MY_TAPTREE, a self assert over the control block's internal key and merkle root at the generic cost, the transaction view's identity widened to a triple. ASSERT_MY_TAPROOT, the derivation assert it subsumes, removed once the puzzle rework landed (decision 29) | Taproot's identity is a tweak preimage the control block reveals and base consensus authenticates, so the assert reads it at 200 where the derivation assert re-derives it at a point multiplication, the largest single cost in both landed puzzles. Internal key read by self asserts only: decision 26's attacker-satisfiable objection concerns a counterpart's key, not the spending input's own. Ratified 2026-08-22, decision 28. | `validation/self-asserts.json` taptree cases, `conditions/self-asserts.json` and `conditions/costs.json` taptree cases |
+| C25 | the annex assert | none: Chia has no annex | ASSERT_MY_ANNEX, a self assert over the BIP341 `sha_annex` digest of the spending input's annex at the generic cost, the annex admitted on a BitLisp spend only under it | Bitcoin's annex is a witness element no operator reads and no BitLisp signature digest commits to, so an ignored annex is third-party malleability on every spend, and a rejected one closes the upgrade path under this leaf version, since a soft fork cannot loosen. Admitting it only under a self assert commits the spender to it, keeps keyless paths safe by default, and leaves the door open. Ratified 2026-09-06, decision 30. | owed to the reference witness layer: `validation/self-asserts.json` and `conditions/self-asserts.json` annex cases |
 
 ## 2. Reference provenance
 
@@ -1609,6 +1610,41 @@ Section 4 registers the rules that have no external reference at all.
     with no intermediate assert. CREATE_OUTPUT_TAPROOT and the
     derivation machinery are untouched.
 
+30. **ASSERT_MY_ANNEX, the annex under a self assert.** RATIFIED
+    (decision by Evan, 2026-09-06, at the review of the
+    commitment-scheme PR, revising the approved unit plan). A
+    seventh self assert at 0x39, `(0x39 annex_hash)`, over the
+    BIP341 `sha_annex` digest of the spending input's annex, the
+    transaction view's BitLisp input gaining an optional
+    `annexHash`. An annex is admitted exactly when the list
+    carries the assert (`unasserted_annex` otherwise), and the
+    assert is unsatisfied without an annex or with another's hash.
+    Three shapes were weighed:
+    - Reject every annex, the unit plan's choice. Closes
+      malleability on every spend including keyless ones, but a
+      soft fork can only tighten, so any later annex use for
+      BitLisp inputs would need a new leaf version.
+    - Bind an annex hash into every signature-assert digest,
+      tapscript's own commit-and-reserve idiom. Keeps the door
+      open but protects signed spends only: a stranger can still
+      attach an annex to a keyless recovery, a consolidation, or
+      a singleton spend sealed through its inner program, and it
+      re-pins every signature vector.
+    - Admit the annex only under a self assert. Keyless paths are
+      protected by default because they carry no assert, a
+      program that wants an annex commits to it in one condition,
+      and a future soft fork can give annex contents meaning to
+      programs that opt in, under this leaf version.
+    The third was taken. Cost: one vocabulary entry for a feature
+    no puzzle uses yet, accepted because the alternative is a
+    leaf version. The hash mirrors BIP341's `sha_annex`, length
+    prefix and `0x50` included, so any taproot tooling computes
+    the same value. 0x39 follows the taptree assert, 0x34 to 0x37
+    staying the visible gap. Error `unsatisfied_annex_assert` for
+    the condition and `unasserted_annex` for the witness rule,
+    each its own vector, both owed to the reference witness layer
+    with the implementation.
+
 ## 4. Novel-layer register
 
 The validation rules have no external reference: no deployed system

docs/glossary.md

@@ -29,6 +29,8 @@ A term enters this table in the same PR that introduces it.
 | ASSERT_MY_SCRIPTPUBKEY | asserts the spent output's scriptPubKey | ASSERT_MY_PUZZLEHASH | raw script bytes per divergence C1, empty script allowed as prevout content |
 | ASSERT_MY_AMOUNT | asserts the spent output's amount | ASSERT_MY_AMOUNT | numeric equality in satoshis |
 | ASSERT_MY_TAPTREE | asserts the internal key and merkle root the control block carries | ASSERT_MY_PUZZLEHASH is the nearest, reading the one identity field | proves the spent output is the taproot output of its operands by reading the identity base consensus authenticated, no derivation, the self-propagation covenant primitive beside CREATE_OUTPUT_TAPROOT (condition-record decisions 28 and 29, divergence C24) |
+| ASSERT_MY_ANNEX | asserts the BIP341 sha_annex digest of the input's own annex | none: Chia has no annex | the annex is admitted on a BitLisp spend only under this assert, so it is committed data the spender chose (spec/SPEC.md section 3.4, condition-record decision 30, divergence C25), glossed 2026-09-06 |
+| annex | BIP341 term, the optional last witness element beginning `0x50`, reserved for future use | none | admitted on a BitLisp spend only under ASSERT_MY_ANNEX and bounded at 10,000 bytes like the solution and program elements (spec/SPEC.md sections 3.1 and 3.4), glossed 2026-09-06 |
 | satisfier | compare miniscript satisfactions, which are spender-side | none | the transaction resource assigned to a claim, one per claim. A miniscript satisfaction is what the spender gives a script, a satisfier is what the transaction gives a claim |
 | composition guarantee | batching and coinjoin practice, no consensus equivalent | spend bundle aggregation, offers | two valid transactions with disjoint outpoints, same-typed locktimes, and no seal condition concatenate into a valid transaction (VALIDATION.md preamble, condition-record decisions 14, 15, and 24) |
 | spend | input plus its witness | coin spend | one input's evaluation and conditions |
@@ -37,6 +39,9 @@ A term enters this table in the same PR that introduces it.
 | ASSURE, REQUIRE | no direct equivalent | SEND_MESSAGE, RECEIVE_MESSAGE (CHIP-0025) | landed 2026-08-07 as SEND_MESSAGE and RECEIVE_MESSAGE, opcodes numerically Chia's, transaction-scoped counted balance (condition-record decision 16), renamed 2026-08-20 (decision 27): the pair reads as what each condition demands rather than as a transport metaphor |
 | assurer half, requirer half | no direct equivalent | the mode's sender and receiver bit fields | the two commitment values a mode packs, assurer times 32 plus requirer since the execution-identity widening (condition-record decision 26) |
 | execution identity | tapleaf hash, merkle root, and internal key of the script-path spend | puzzle hash (one field carries both meanings) | the triple validator-filled from the control block: the tapleaf hash and merkle root are specifier fields addressing the executing program and its tree, the internal key is read by self asserts only (condition-record decisions 26 to 28, divergences C23 and C24) |
+| leaf version | BIP341 term, the control block's first byte with its low bit cleared | none: a coin's puzzle is not versioned | `BITLISP_LEAF_VERSION = 0xd0`, provisional until deployment, the byte that makes a script-path spend a BitLisp spend (spec/SPEC.md section 2.1), glossed 2026-09-06 with the commitment scheme |
+| leaf script | BIP341 term, the script a leaf commits to and a spend reveals | puzzle hash, as the value a coin commits to | the 32-byte tree hash of the committed program, never executed, the program itself a separate witness element the validator checks against it (spec/SPEC.md section 2.2), glossed 2026-09-06 |
+| per-path leaf | one tapleaf per spending condition, the taproot idiom | none: a puzzle's paths share one puzzle hash | a spend path written as its own curried program in its own leaf, so a spend reveals the executed path and 32 bytes of control block per tree level (spec/SPEC.md section 2.3, commitment-record decisions 7 and 8), glossed 2026-09-06 |
 | ANNOUNCE, ASSERT_ANNOUNCEMENT | no direct equivalent | the four announcement conditions (coin and puzzle, create and assert) | landed 2026-08-07, the unaddressed pair, namespace first-class, announcer precision chosen by the assert (condition-record decisions 10 and 16) |
 | message record | no direct equivalent | send and receive balancing in chia_rs | the third condition sort beside claims and asserts, a weighted ledger entry (+1 or -1) whose record must net to zero (VALIDATION.md rule 3, condition-record decision 16) |
 | RESERVE_FEE | no direct opcode, the fee itself is implicit (inputs minus outputs) | RESERVE_FEE 52 | landed 2026-08-09 at 0x50, demands the transaction's fee reach the summed reservations (VALIDATION.md rule 7, condition-record decision 21) |

docs/lang/curry.md

@@ -98,9 +98,10 @@ to the inner program and every fixed value at once, which is what
 makes currying the specialization step: template plus parameters
 becomes one committed identity.
 
-What a scriptPubKey commits to on chain is decided by the
-commitment scheme and measured in Phase 4. The tree hash is the
-program-level identity those commitments build on.
+What a scriptPubKey commits to on chain is the commitment scheme
+of `spec/SPEC.md`: a leaf whose script is the program's tree hash,
+the curried tree hash for a curried program. The tree hash is the
+program-level identity that commitment builds on.
 
 ## The command surfaces