More readeable scripts & fix footnotes

Author: moonsettler

bip-0442.md

@@ -33,7 +33,7 @@ Stack operation:
 - Pop `x2` and `x1` from the stack.
 - Push `pc` onto the stack.
 
-[^1]: The number of SHA256 blocks is minimized in typical use cases. The tag can be pre-computed as a SHA256 mid-state, requiring only 2 hash cycles for two 32-byte items, or 1 for two smaller items.
+[^1]: The number of SHA256 blocks is minimized in typical use cases. The tag can be precomputed as a SHA256 mid-state, requiring only two hash cycles for two 32-byte items, or one for two smaller items.
 
 ## Motivation
 
@@ -49,65 +49,91 @@ Combined with `OP_CHECKSIGFROMSTACK`, signing commitments to multiple items enab
 
 `OP_PAIRCOMMIT` can commit to a vector of stack elements securely and efficiently.
 
-```text
+```shell
 # Commit to three elements: a, b, c
 # pc-hash = PC(a, PC(b, c))
 
-<a> <b> <c> OP_PAIRCOMMIT OP_PAIRCOMMIT <pc-hash> OP_EQUALVERIFY
+# Witness: <a> <b> <c>
+OP_PAIRCOMMIT                          # <a>, PC(b, c)
+OP_PAIRCOMMIT                          # PC(a, PC(b, c))
+OP_PUSHBYTES (pc-hash)                 # PC(a, PC(b, c)), <pc-hash>
+OP_EQUALVERIFY                         #
+# ...
 ```
 
 ### Use in Lightning Symmetry
 
-Lightning Symmetry contracts require data availability for contested closes. By forcing parties to include settlement transaction hashes in the witness, later updates can reconstruct scripts using only the latest state.
+Lightning Symmetry contracts require data availability for contested closes. [^3] By forcing parties to include settlement transaction hashes in the witness, later updates can reconstruct scripts using only the latest state.
 [^3]: The required data is a full CTV hash of the settlement transaction when there are open HTLCs, or merely the difference in balance between the channel partners in other cases. Whether the latter optimization would be used is an implementation detail not further discussed here.
 
-Example channel script (pseudo-code):
-
-```text
-# S = 500000000
-# internal key = [BIP-327] aggregate key of channel participants
-# state-n-hash { nLockTime(S+n), out(contract, amount(A)+amount(B)) }
-# settlement-n-hash { nSequence(2w), out(A, amount(A)), out(B, amount(B)) }
-# state-n-recovery-data { settlement-n-hash or state-n-balance }
-
-<sig> <state-n-recovery-data> <state-n-hash> OP_CHECKTEMPLATEVERIFY OP_PAIRCOMMIT OP_INTERNALKEY OP_CHECKSIGFROMSTACK <S+1> OP_CLTV OP_DROP
+```shell
+# S:                                   500000000
+# internal-key:                        BIP-327 aggregate key of channel participants
+# state-n-hash:                        { nLockTime(S+n), out(contract, amount(A)+amount(B)) }
+# settlement-n-hash:                   { nSequence(2w), out(A, amount(A)), out(B, amount(B)) }
+# state-n-recovery-data:               { settlement-n-hash or state-n-balance }
+```
+#### Example channel script (pseudo-code)
+
+```shell
+# Witness: <sig> <state-n-recovery-data> <state-n-hash>
+OP_CHECKTEMPLATEVERIFY                 # <sig>, <state-n-recovery-data>, <state-n-hash>
+OP_PAIRCOMMIT                          # <sig>, PC(state-n-recovery-data, state-n-hash)
+OP_INTERNALKEY                         # <sig>, PC(state-n-recovery-data, state-n-hash), <internal-key>
+OP_CHECKSIGFROMSTACK                   # <1>
+OP_PUSHBYTES (S+1)                     # <1>, <S+1>
+OP_CHECKLOCKTIMEVERIFY                 # <1>, <S+1>
+OP_DROP                                # <1>
 ```
 
-Update script:
-
-```text
-IF
-  <sig> <state-m-recovery-data> <state-m-hash> OP_CHECKTEMPLATEVERIFY OP_PAIRCOMMIT OP_INTERNALKEY OP_CHECKSIGFROMSTACK <S+n+1> OP_CLTV OP_DROP
-ELSE
-  <settlement-n-hash> OP_CHECKTEMPLATEVERIFY
-ENDIF
+#### Channel update script (pseudo-code) for m > n
+
+```shell
+OP_IF
+    # Witness: <sig> <state-m-recovery-data> <state-m-hash>
+    OP_CHECKTEMPLATEVERIFY             # <sig>, <state-m-recovery-data>, <state-m-hash>
+    OP_PAIRCOMMIT                      # <sig>, PC(state-m-recovery-data, state-m-hash)
+    OP_INTERNALKEY                     # <sig>, PC(state-m-recovery-data, state-m-hash), <internal-key>
+    OP_CHECKSIGFROMSTACK               # <1>
+    OP_PUSHBYTES (S+n+1)               # <1>, <S+n+1>
+    OP_CHECKLOCKTIMEVERIFY             # <1>, <S+n+1>
+    OP_DROP                            # <1>
+OP_ELSE
+    # Empty witness stack
+    OP_PUSHBYTES (settlement-n-hash)   # <settlement-n-hash>
+    OP_CHECKTEMPLATEVERIFY             # <settlement-n-hash>
+    OP_0NOTEQUAL                       # <1>
+OP_ENDIF
 ```
 
-These constructions ensure both parties sign the same pair hash, requiring inclusion of both update and settlement hashes in the witness.
+These constructions ensure both parties sign the same pair hash, requiring inclusion of both update and settlement hashes in the witness. [^4] [^5]
+
+[^4]: `state-n-hash` commits to a specific `nLockTime` value for the transaction through `OP_CHECKTEMPLATEVERIFY`; `OP_CHECKLOCKTIMEVERIFY` ensures that the state progression can only go forward (the transaction needs to have greater `nLockTime` value than the intermediate state 
+[^5]: `OP_0NOTEQUAL` can be omitted (any non-zero value left on the stack would be accepted by the script interpreter).
 
 ### In MATT
 
-The Merklize All The Things ([MATT]) framework uses `OP_CAT` to combine items for commitments. `OP_PAIRCOMMIT` provides a more ergonomic and secure alternative[^4].
+The Merklize All The Things ([MATT]) framework uses `OP_CAT` to combine items for commitments. `OP_PAIRCOMMIT` provides a more ergonomic and secure alternative[^6].
 
-[^4]: Naive use of `OP_CAT` is vulnerable to byte shifting attacks. E.g. `0x0102 || 0x03` equals `0x01 || 0x0203`. Mitigation requires length checking or hashing.
+[^6]: Naive use of `OP_CAT` is vulnerable to byte shifting attacks. E.g. `0x0102 || 0x03` equals `0x01 || 0x0203`. Mitigation requires length checking or hashing.
 
 ## Alternative approaches
 
 Alternative approaches considered and rejected:
 
-- `OP_CAT`[^4][^7]
-- SHA256 streaming opcodes[^7]
+- `OP_CAT`[^6][^9]
+- SHA256 streaming opcodes[^9]
 - Merkle operation opcodes
 - 'Kitty' CAT: `OP_CAT` with size limits
-- `OP_CHECKTEMPLATEVERIFY` committing to the taproot annex[^5]
+- `OP_CHECKTEMPLATEVERIFY` committing to the taproot annex[^7]
 - `OP_CHECKSIGFROMSTACK` on n elements
 - `OP_VECTORCOMMIT`: generalized for n > 2 elements
 - ReKey/Laddering[^2]
-- `OP_RETURN`[^6]
+- `OP_RETURN`[^8]
 
-[^5]: Committing to the taproot annex allows one additional item, but it is not accessible to script.
-[^6]: `OP_RETURN` can commit to additional data, but is costly and not accessible to script.
-[^7]: `OP_PAIRCOMMIT` enables useful scripts without the risks of `OP_CAT` (see [CAT-tricks-I], [CAT-tricks-II]).
+[^7]: Committing to the taproot annex allows one additional item, but it is not accessible to script.
+[^8]: `OP_RETURN` can commit to additional data, but is costly and not accessible to script.
+[^9]: `OP_PAIRCOMMIT` enables useful scripts without the risks of `OP_CAT` (see [CAT-tricks-I], [CAT-tricks-II]).
 
 ## Reference Implementation
 
@@ -189,6 +215,7 @@ This document is licensed under the 3-clause BSD license.
 6. OP_CHECKCONTRACTVERIFY: [BIP-443]
 7. OP_INTERNALKEY: [BIP-349], [BIN-2024-0004]
 8. Tagged hash: [BIP-340]
+9. MuSig2: [BIP-327]
 
 [lnhance]: https://github.com/lnhance/bitcoin
 [eltoo]: https://github.com/instagibbs/bolts/blob/eltoo_draft/XX-eltoo-transactions.md