The Lightning offered and received HTLC witness scripts and their spending conditions
DefinitionBitcoinHtlcNames over the script, signature, verification and to_local missions; nothing of Core is re-transcribed.
offeredScript revHash remoteKey localKey payHash / offeredBytes … — the BOLT #3 offered-HTLC witness script OP_DUP OP_HASH160 <revHash> OP_EQUAL OP_IF OP_CHECKSIG OP_ELSE <remoteKey> OP_SWAP OP_SIZE 32 OP_EQUAL OP_NOTIF OP_DROP 2 OP_SWAP <localKey> 2 OP_CHECKMULTISIG OP_ELSE OP_HASH160 <payHash> OP_EQUALVERIFY OP_CHECKSIG OP_ENDIF OP_ENDIF, parsed and as CScript serializes it (2 as OP_2, 32 as the one-byte push 0x20).
receivedScript … expiry / receivedBytes … — the received-HTLC script, whose inner branches are OP_IF OP_HASH160 <payHash> OP_EQUALVERIFY 2 OP_SWAP <localKey> 2 OP_CHECKMULTISIG OP_ELSE OP_DROP <expiry> OP_CHECKLOCKTIMEVERIFY OP_DROP OP_CHECKSIG OP_ENDIF, the expiry encoded by the to_local mission's numInstr/numBytes.
CltvPasses f o expiry — what OP_CHECKLOCKTIMEVERIFY lets through: the flag is off, or expiry is non-negative and the oracle's checkLockTime expiry holds.
OfferedSpend f o revHash remoteKey localKey payHash st — for a witness stack st (top first): the revocation path [pk, sig] with hash160 pk = revHash and sig valid for pk; the preimage path [preimage, sig] with hash160 preimage ≠ revHash, a 32-byte preimage hashing to payHash, and sig valid for remoteKey; or the timeout path [x, localSig, remoteSig, dummy] with hash160 x ≠ revHash, x not 32 bytes, the 2-of-2 multisigLoop o [localSig, remoteSig] [localKey, remoteKey] passing, and an empty dummy when NULLDUMMY is enforced.
ReceivedSpend … expiry st — the revocation path as above; the success path [preimage, localSig, remoteSig, dummy] (32-byte preimage hashing to payHash, not to revHash, the 2-of-2 passing, dummy as above); or the timeout path [x, sig] with hash160 x ≠ revHash, x not 32 bytes, CltvPasses, and sig valid for remoteKey.
Formalization Note. multisigLoop, Flags, Oracle, evalScript are the script mission's; legacyOracle, checkLockTime, parseScript the signature mission's; verifyScript, topTrue the verification mission's; numInstr, inputSequence the to_local mission's. The two 20-byte hashes are free parameters. Only Std is imported.
import Definitions.Def_BitcoinToLocal
/-!
# The Lightning HTLC outputs under Bitcoin's script interpreter
BOLT #3 (Lightning Network specification, *Bitcoin Transaction and Script Formats*, non-anchor
form) gives the two HTLC outputs of a commitment transaction the witness scripts
Offered HTLC (the local node offered the HTLC):
```
OP_DUP OP_HASH160 <RIPEMD160(SHA256(revocationpubkey))> OP_EQUAL
OP_IF OP_CHECKSIG
OP_ELSE <remote_htlcpubkey> OP_SWAP OP_SIZE 32 OP_EQUAL
OP_NOTIF OP_DROP 2 OP_SWAP <local_htlcpubkey> 2 OP_CHECKMULTISIG
OP_ELSE OP_HASH160 <RIPEMD160(payment_hash)> OP_EQUALVERIFY OP_CHECKSIG
OP_ENDIF
OP_ENDIF
```
Received HTLC:
```
OP_DUP OP_HASH160 <RIPEMD160(SHA256(revocationpubkey))> OP_EQUAL
OP_IF OP_CHECKSIG
OP_ELSE <remote_htlcpubkey> OP_SWAP OP_SIZE 32 OP_EQUAL
OP_IF OP_HASH160 <RIPEMD160(payment_hash)> OP_EQUALVERIFY 2 OP_SWAP <local_htlcpubkey> 2 OP_CHECKMULTISIG
OP_ELSE OP_DROP <cltv_expiry> OP_CHECKLOCKTIMEVERIFY OP_DROP OP_CHECKSIG
OP_ENDIF
OP_ENDIF
```
paid to as pay-to-witness-script-hash. The 20-byte hashes are parameters `revHash` and `payHash`
(any bytes), the keys `remoteKey` and `localKey`. `2` is `CScript << 2` (`OP_2`), `32` is
`CScript << 32` (the one-byte script-number push `01 20`), and `<cltv_expiry>` is
`CScript << int64` (`BitcoinToLocal.numInstr` / `numBytes`).
Witness stacks are listed top first, as `evalScript` takes them. In BOLT #3's `CScriptWitness`
order (last element on top) the witnesses are: revocation `<revocation_sig> <revocationpubkey>`;
offered-timeout `0 <remotehtlcsig> <localhtlcsig> <>`; offered-preimage
`<remotehtlcsig> <payment_preimage>`; received-success `0 <remotehtlcsig> <localhtlcsig>
<payment_preimage>`; received-timeout `<remotehtlcsig> <>`.
-/
namespace BitcoinHtlc
open BitcoinScript BitcoinSig BitcoinVerify BitcoinToLocal
/-- The BOLT #3 offered-HTLC witness script, parsed. -/
def offeredScript (revHash remoteKey localKey payHash : Bytes) : Script :=
[.op OP_DUP, .op OP_HASH160, .push revHash, .op OP_EQUAL,
.op OP_IF, .op OP_CHECKSIG,
.op OP_ELSE, .push remoteKey, .op OP_SWAP, .op OP_SIZE, numInstr 32, .op OP_EQUAL,
.op OP_NOTIF, .op OP_DROP, numInstr 2, .op OP_SWAP, .push localKey, numInstr 2, .op OP_CHECKMULTISIG,
.op OP_ELSE, .op OP_HASH160, .push payHash, .op OP_EQUALVERIFY, .op OP_CHECKSIG,
.op OP_ENDIF,
.op OP_ENDIF]
/-- The BOLT #3 received-HTLC witness script, parsed. -/
def receivedScript (revHash remoteKey localKey payHash : Bytes) (expiry : Int) : Script :=
[.op OP_DUP, .op OP_HASH160, .push revHash, .op OP_EQUAL,
.op OP_IF, .op OP_CHECKSIG,
.op OP_ELSE, .push remoteKey, .op OP_SWAP, .op OP_SIZE, numInstr 32, .op OP_EQUAL,
.op OP_IF, .op OP_HASH160, .push payHash, .op OP_EQUALVERIFY, numInstr 2, .op OP_SWAP, .push localKey,
numInstr 2, .op OP_CHECKMULTISIG,
.op OP_ELSE, .op OP_DROP, numInstr expiry, .op OP_CHECKLOCKTIMEVERIFY, .op OP_DROP, .op OP_CHECKSIG,
.op OP_ENDIF,
.op OP_ENDIF]
/-- The offered-HTLC witness script, as `CScript` serializes it. -/
def offeredBytes (revHash remoteKey localKey payHash : Bytes) : Bytes :=
[OP_DUP, OP_HASH160] ++ pushBytes revHash ++ [OP_EQUAL, OP_IF, OP_CHECKSIG, OP_ELSE] ++
pushBytes remoteKey ++ [OP_SWAP, OP_SIZE] ++ numBytes 32 ++ [OP_EQUAL, OP_NOTIF, OP_DROP] ++
numBytes 2 ++ [OP_SWAP] ++ pushBytes localKey ++ numBytes 2 ++ [OP_CHECKMULTISIG, OP_ELSE, OP_HASH160] ++
pushBytes payHash ++ [OP_EQUALVERIFY, OP_CHECKSIG, OP_ENDIF, OP_ENDIF]
/-- The received-HTLC witness script, as `CScript` serializes it. -/
def receivedBytes (revHash remoteKey localKey payHash : Bytes) (expiry : Int) : Bytes :=
[OP_DUP, OP_HASH160] ++ pushBytes revHash ++ [OP_EQUAL, OP_IF, OP_CHECKSIG, OP_ELSE] ++
pushBytes remoteKey ++ [OP_SWAP, OP_SIZE] ++ numBytes 32 ++ [OP_EQUAL, OP_IF, OP_HASH160] ++
pushBytes payHash ++ [OP_EQUALVERIFY] ++ numBytes 2 ++ [OP_SWAP] ++ pushBytes localKey ++ numBytes 2 ++
[OP_CHECKMULTISIG, OP_ELSE, OP_DROP] ++ numBytes expiry ++
[OP_CHECKLOCKTIMEVERIFY, OP_DROP, OP_CHECKSIG, OP_ENDIF, OP_ENDIF]
/-- What `OP_CHECKLOCKTIMEVERIFY` lets through for the operand `expiry`: nothing is checked when the
`CHECKLOCKTIMEVERIFY` flag is off; otherwise the operand must be non-negative and satisfy the
checker's `CheckLockTime` (there is no disable bit for lock times). -/
def CltvPasses (f : Flags) (o : Oracle) (expiry : Int) : Prop :=
f.cltv = false ∨ (0 ≤ expiry ∧ o.checkLockTime expiry = true)
instance (f : Flags) (o : Oracle) (expiry : Int) : Decidable (CltvPasses f o expiry) := by
unfold CltvPasses; infer_instance
/-- The three ways of satisfying the offered-HTLC script, on a witness stack `st` (top first):
the revocation path `[pubkey, sig]` with the pubkey hashing to `revHash` and `sig` valid for it;
the preimage path `[preimage, sig]` with a 32-byte preimage hashing to `payHash` (and not to
`revHash`) and `sig` valid for the remote key; or the timeout path `[x, localSig, remoteSig, dummy]`
with `x` neither hashing to `revHash` nor 32 bytes long, the 2-of-2 check of the local then the
remote signature passing, and an empty dummy when `NULLDUMMY` is enforced. -/
def OfferedSpend (f : Flags) (o : Oracle) (revHash remoteKey localKey payHash : Bytes) (st : List Bytes) : Prop :=
(∃ pk sig, st = [pk, sig] ∧ o.hash160 pk = revHash ∧ o.checkSig sig pk = some true) ∨
(∃ preimage sig, st = [preimage, sig] ∧ o.hash160 preimage ≠ revHash ∧ preimage.length = 32 ∧
o.hash160 preimage = payHash ∧ o.checkSig sig remoteKey = some true) ∨
(∃ x localSig remoteSig dummy, st = [x, localSig, remoteSig, dummy] ∧ o.hash160 x ≠ revHash ∧ x.length ≠ 32 ∧
multisigLoop o [localSig, remoteSig] [localKey, remoteKey] = some true ∧ (f.nulldummy = true → dummy = []))
/-- The three ways of satisfying the received-HTLC script, on a witness stack `st` (top first):
the revocation path `[pubkey, sig]`; the success path `[preimage, localSig, remoteSig, dummy]` with a
32-byte preimage hashing to `payHash` (and not to `revHash`), the 2-of-2 check passing and an empty
dummy when `NULLDUMMY` is enforced; or the timeout path `[x, sig]` with `x` neither hashing to
`revHash` nor 32 bytes long, the lock-time check passing and `sig` valid for the remote key. -/
def ReceivedSpend (f : Flags) (o : Oracle) (revHash remoteKey localKey payHash : Bytes) (expiry : Int)
(st : List Bytes) : Prop :=
(∃ pk sig, st = [pk, sig] ∧ o.hash160 pk = revHash ∧ o.checkSig sig pk = some true) ∨
(∃ preimage localSig remoteSig dummy, st = [preimage, localSig, remoteSig, dummy] ∧
o.hash160 preimage ≠ revHash ∧ preimage.length = 32 ∧ o.hash160 preimage = payHash ∧
multisigLoop o [localSig, remoteSig] [localKey, remoteKey] = some true ∧ (f.nulldummy = true → dummy = [])) ∨
(∃ x sig, st = [x, sig] ∧ o.hash160 x ≠ revHash ∧ x.length ≠ 32 ∧ CltvPasses f o expiry ∧
o.checkSig sig remoteKey = some true)
end BitcoinHtlc
Read-back
What the Lean code literally says, in plain math · claude-fable-5-1 (independent sub-agent, blind: Lean code + auditor instructions only)
Read-back: Def_BitcoinHtlc.lean (definitions, in file order)
The file introduces eight declarations in the namespace BitcoinHtlc: offeredScript, receivedScript, offeredBytes, receivedBytes, CltvPasses, a decidability instance for CltvPasses, OfferedSpend and ReceivedSpend. The preamble notions they depend on are rendered first, then one paragraph per definition.
Basic notions used throughout. A byte is an 8-bit word and a byte string (written ) is a finite list of bytes; denotes the length of a byte string . The constant is the interpreter's maximum size of one stack element. A flag set consists of three Booleans , , . An oracle is an arbitrary structure supplying eight functions with no constraints whatsoever on their behaviour: (so in particular is any function from byte strings to byte strings, not necessarily RIPEMD160SHA256, not necessarily 20-byte-valued), (first argument the signature, second the public key; the value represents a script-aborting failure, a verdict ), and . Stacks are lists written top element first. is: false for the empty string; for a one-byte string , true iff and ; for with non-empty, true iff or (so a string of zero bytes whose last byte is is false). and (the empty string). The script-number encoding of an integer is: if ; otherwise the little-endian bytes of with no trailing zero byte, then, if the last of those bytes has its top bit () set, an extra byte (for ) or (for ) is appended, and otherwise, for , the top bit of the last byte is set. For example and . The decoding ("script number of at most bytes, non-minimal encodings allowed") is if , and otherwise of the little-endian value of with the top bit of the last byte read as a sign (the empty string decodes to ).
The number push / . For an integer , is the single opcode with byte value when or (so is the opcode , is the opcode , i.e. OP_2), and otherwise it is the data push of (so is the push of the one-byte string , and is the push of the empty string). is the byte-level form: the one opcode byte in the first case, and otherwise, where is the canonical push encoding of a byte string : if ; if ; if ; and otherwise.
The multisignature matching loop. , for lists of signatures and keys (top first), is defined by recursion: it is when is empty; when is non-empty and is empty; and for , it evaluates : if that is the loop is ; if it is the loop is when and otherwise ; if it is the loop is when and otherwise . Unfolded on exactly two signatures and two keys, is: if ; if (since ; the second signature is then never checked); and if it is , or according as is , or .
1. offeredScript
For four arbitrary byte strings (revHash), (remoteKey), (localKey), (payHash), with no constraint on their lengths or contents (in particular and need not be 20 bytes long nor be hash values of anything), is the following list of 26 parsed instructions, where is the data push of : OP_DUP, OP_HASH160, , OP_EQUAL, OP_IF, OP_CHECKSIG, OP_ELSE, , OP_SWAP, OP_SIZE, , OP_EQUAL, OP_NOTIF, OP_DROP, the opcode (OP_2), OP_SWAP, , , OP_CHECKMULTISIG, OP_ELSE, OP_HASH160, , OP_EQUALVERIFY, OP_CHECKSIG, OP_ENDIF, OP_ENDIF. The opcode bytes are OP_DUP , OP_HASH160 , OP_EQUAL , OP_IF , OP_CHECKSIG , OP_ELSE , OP_SWAP , OP_SIZE , OP_NOTIF , OP_DROP , OP_CHECKMULTISIG , OP_EQUALVERIFY , OP_ENDIF .
2. receivedScript
For the same four arbitrary byte strings and an arbitrary integer (expiry; any integer, possibly zero or negative), is the following list of 28 parsed instructions: OP_DUP, OP_HASH160, , OP_EQUAL, OP_IF, OP_CHECKSIG, OP_ELSE, , OP_SWAP, OP_SIZE, , OP_EQUAL, OP_IF, OP_HASH160, , OP_EQUALVERIFY, (OP_2), OP_SWAP, , (OP_2), OP_CHECKMULTISIG, OP_ELSE, OP_DROP, , OP_CHECKLOCKTIMEVERIFY (), OP_DROP, OP_CHECKSIG, OP_ENDIF, OP_ENDIF. Here is the opcode when or , and otherwise the data push of (the empty push for ; for a push whose last byte carries the sign bit; for large a push of as many bytes as the little-endian magnitude needs, possibly more than 5).
3. offeredBytes
For the same four arbitrary byte strings, is the byte string obtained by concatenating, in order: ; ; ; ; ; ; ; ; ; ; ; ; ; . Each is the canonical push encoding defined above (a one-byte length prefix when , otherwise a PUSHDATA1/2/4 prefix according to ).
4. receivedBytes
For the same parameters and an arbitrary integer , is the concatenation, in order, of: ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; , where is the single byte when or and otherwise (, the empty push, for ).
5. CltvPasses
For a flag set , an oracle and an integer , is the proposition
It holds for every when the cltv flag is off; when the flag is on it requires and acceptance by the oracle's (arbitrary) lock-time function. No disable bit, size bound, or relation between and or is part of this definition.
6. Decidability instance for CltvPasses
The file declares that, for every flag set , oracle and integer , the proposition is decidable, by unfolding it to the disjunction/conjunction of decidable Boolean equalities and the integer comparison above. This is what allows the theorem statements to write "if then … else …". It asserts nothing beyond decidability.
7. OfferedSpend
For a flag set , an oracle , byte strings and a list of byte strings (a stack, top first), is the disjunction of exactly these three propositions. (i) Revocation disjunct: there exist byte strings and such that (a two-element stack, on top), , and (the signature is checked against the stack element ). (ii) Preimage disjunct: there exist byte strings and such that , , , , and . (iii) Timeout disjunct: there exist byte strings such that (a four-element stack, on top, at the bottom), , , (unfolded above: both and must be ), and (when the nulldummy flag is off, may be anything). Consequently the predicate is false for every stack whose length is not or , including the empty stack; disjuncts (i) and (ii) can both hold for the same two-element stack only if of its top equals and differs from , which is impossible, so they are mutually exclusive, while (iii) concerns four-element stacks only; no disjunct bounds the sizes of the stack elements; and , are the arbitrary oracle functions.
8. ReceivedSpend
For a flag set , an oracle , byte strings , an integer and a stack , is the disjunction of exactly these three propositions. (i) Revocation disjunct: there exist byte strings and such that , , and . (ii) Success disjunct: there exist byte strings such that ( on top, at the bottom), , , , , and . (iii) Timeout disjunct: there exist byte strings and such that , , , holds (i.e. , or and ), and . The predicate is false for every stack whose length is not or (including the empty stack); disjuncts (i) and (iii) both concern two-element stacks and are mutually exclusive via the condition on the top element; no size bound is placed on any stack element; the expiry enters only through in disjunct (iii), and only through the oracle's arbitrary function.
Confirmed by the mission captain (proposal self-audit).
Confirmed by the moderator at approval.