The Lightning to_local witness script and its two spending conditions
DefinitionBitcoinToLocalNames over the script, signature and verification missions; nothing of Core is re-transcribed.
numInstr n / numBytes n — what CScript::operator<<(int64_t) emits for a small integer: OP_1NEGATE for , OP_1 … OP_16 for … , and the CScriptNum push otherwise (the empty push for ), as an instruction and as bytes.
toLocalScript rev delay dpk — the BOLT #3 to_local witness script OP_IF <rev> OP_ELSE <delay> OP_CHECKSEQUENCEVERIFY OP_DROP <dpk> OP_ENDIF OP_CHECKSIG, parsed; toLocalBytes rev delay dpk — the same as CScript serializes it.
CsvPasses f o delay — what OP_CHECKSEQUENCEVERIFY lets through for the operand delay under flags and oracle : the CHECKSEQUENCEVERIFY flag is off, or delay is non-negative and either carries the disable bit (bit 31) or satisfies the oracle's checkSequence.
SpendCondition f o rev delay dpk b sig — the revocation path ( true and o.checkSig sig rev = some true) or the delayed path ( false, CsvPasses f o delay, and o.checkSig sig dpk = some true), for the witness stack [b, sig] (top first).
inputSequence tx nIn — the nSequence of input nIn of a transaction (an empty input when out of range).
Formalization Note. Flags, Oracle, evalScript, serialize, castToBool are the script mission's; legacyOracle, checkSequence, parseScript, pushBytes the signature mission's; verifyScript, executeWitnessScriptV0, topTrue, witnessBytes the verification mission's. Only Std is imported. MINIMALIF is a policy flag and is off, so any true value selects the revocation branch under consensus.
import Definitions.Def_BitcoinVerify
/-!
# The Lightning `to_local` output under Bitcoin's script interpreter
BOLT #3 (Lightning Network specification, *Bitcoin Transaction and Script Formats*) gives the
`to_local` output of a commitment transaction the witness script
```
OP_IF
<revocationpubkey>
OP_ELSE
`to_self_delay`
OP_CHECKSEQUENCEVERIFY
OP_DROP
<local_delayedpubkey>
OP_ENDIF
OP_CHECKSIG
```
paid to as pay-to-witness-script-hash. The intent is that the output can be spent either by the
counterparty with the revocation key at any time, or by the local node with its delayed key once
`to_self_delay` blocks have passed. This file states that script as the script and verification
missions model it, so that the two spending conditions can be proved to be exactly what the
interpreter enforces.
-/
namespace BitcoinToLocal
open BitcoinScript BitcoinSig BitcoinVerify
/-- `CScript::operator<<(int64_t n)`: `OP_1NEGATE` for `-1`, `OP_1` … `OP_16` for `1` … `16`, and the
`CScriptNum` push otherwise (`OP_0`, the empty push, for `0`). -/
def numInstr (n : Int) : Instr :=
if n = -1 ∨ (1 ≤ n ∧ n ≤ 16) then .op (BitVec.ofNat 8 (n + (OP_1.toNat - 1)).toNat)
else .push (serialize n)
/-- The bytes `CScript::operator<<(int64_t n)` appends. -/
def numBytes (n : Int) : Bytes :=
if n = -1 ∨ (1 ≤ n ∧ n ≤ 16) then [BitVec.ofNat 8 (n + (OP_1.toNat - 1)).toNat]
else pushBytes (serialize n)
/-- The BOLT #3 `to_local` witness script, parsed. -/
def toLocalScript (revocationPubkey : Bytes) (toSelfDelay : Int) (localDelayedPubkey : Bytes) : Script :=
[.op OP_IF, .push revocationPubkey, .op OP_ELSE, numInstr toSelfDelay, .op OP_CHECKSEQUENCEVERIFY,
.op OP_DROP, .push localDelayedPubkey, .op OP_ENDIF, .op OP_CHECKSIG]
/-- The BOLT #3 `to_local` witness script, as `CScript` serializes it. -/
def toLocalBytes (revocationPubkey : Bytes) (toSelfDelay : Int) (localDelayedPubkey : Bytes) : Bytes :=
[OP_IF] ++ pushBytes revocationPubkey ++ [OP_ELSE] ++ numBytes toSelfDelay ++
[OP_CHECKSEQUENCEVERIFY, OP_DROP] ++ pushBytes localDelayedPubkey ++ [OP_ENDIF, OP_CHECKSIG]
/-- What `OP_CHECKSEQUENCEVERIFY` lets through for the operand `delay`: nothing is checked when the
`CHECKSEQUENCEVERIFY` flag is off; otherwise the operand must be non-negative and either carry the
disable flag (bit 31) or satisfy the checker's `CheckSequence`. -/
def CsvPasses (f : Flags) (o : Oracle) (delay : Int) : Prop :=
f.csv = false ∨ (0 ≤ delay ∧ ((delay.toNat &&& BitcoinScript.SEQUENCE_LOCKTIME_DISABLE_FLAG) ≠ 0 ∨ o.checkSequence delay = true))
instance (f : Flags) (o : Oracle) (delay : Int) : Decidable (CsvPasses f o delay) := by
unfold CsvPasses; infer_instance
/-- The two ways of satisfying the `to_local` script with the witness stack `[b, sig]` (top first):
the revocation path, `b` true and `sig` valid for the revocation key; or the delayed path, `b` false,
the delay check passing, and `sig` valid for the delayed key. -/
def SpendCondition (f : Flags) (o : Oracle) (revocationPubkey : Bytes) (toSelfDelay : Int)
(localDelayedPubkey : Bytes) (b sig : Bytes) : Prop :=
(castToBool b = true ∧ o.checkSig sig revocationPubkey = some true) ∨
(castToBool b = false ∧ CsvPasses f o toSelfDelay ∧ o.checkSig sig localDelayedPubkey = some true)
/-- The `nSequence` of input `nIn` of a transaction (an empty input when out of range). -/
def inputSequence (tx : BitcoinSer.Tx) (nIn : Nat) : Nat := (tx.vin.getD nIn ⟨⟨[], 0⟩, [], 0, []⟩).nSequence
end BitcoinToLocal
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_BitcoinToLocal.lean
Throughout, a byte is an 8-bit word, a byte string is a finite list of bytes, and denotes the length of a list . Stacks are lists written top-first. Bitwise operations , act on natural numbers. Integer-to-natural truncation sends every negative integer to and fixes non-negative ones. Several notions from the preamble are unfolded where first used.
1. numInstr
For an integer , is a single parsed script instruction (an instruction is either a data push carrying a byte string, or a non-push opcode carrying one byte), defined by cases:
- if , or , it is the opcode whose byte is reduced modulo (the constant is , where is the byte called
OP_1). Concretely this is byte () for and bytes () for ; no truncation or modular reduction actually occurs in this branch; - otherwise (so for , , or ), it is the data push of .
Here byte strings is the following encoding: (the empty string). For let be the little-endian base- digit list of with no trailing zero bytes (so is non-empty and its last byte is non-zero). If the last byte of has its bit set, the result is followed by one extra byte, if and if ; otherwise, if the result is with the bit set on its last byte, and if the result is itself. In particular is a push of the empty byte string.
2. numBytes
For an integer , is a byte string:
- if or , the one-byte string , i.e. for and for ;
- otherwise .
Here , for a byte string , is: if (), the byte followed by ; else if , the bytes followed by ; else if , the byte , then the two-byte little-endian encoding of , then ; otherwise the byte , the four-byte little-endian encoding of , then . In particular .
3. toLocalScript
For byte strings (named revocationPubkey) and (named localDelayedPubkey) and an integer (named toSelfDelay), is the following list of exactly nine instructions, in this order:
where the opcode bytes are named in the preamble OP_IF (), OP_ELSE (), OP_CHECKSEQUENCEVERIFY (), OP_DROP (), OP_ENDIF (), OP_CHECKSIG (). No restriction is placed on , , or by this definition; the fourth instruction is an opcode when and a data push of otherwise (the empty push when ).
4. toLocalBytes
For , , as above, is the byte string obtained by concatenation:
with and as unfolded above. Again there is no restriction on , , ; for or above the push prefix becomes the two-byte () or longer forms.
5. CsvPasses
Let be a flag record — a triple of booleans — and let be an oracle: a record of eight arbitrary functions, five hash functions from byte strings to byte strings, a function from two byte strings (signature first, public key second) to an optional boolean (either "none" or "some " with a boolean), and . Nothing is assumed about these functions. For an integer (named delay), the proposition is
where is the constant the preamble calls SEQUENCE_LOCKTIME_DISABLE_FLAG (the script-layer copy of it). Edge cases: when the proposition holds for every , negative or not, whatever is; when every negative fails it (the truncation is never evaluated on a negative in a way that matters, because of the guard ); when and has bit set, it holds regardless of ; otherwise it holds exactly when .
6. Decidability instance for CsvPasses
For every , , the proposition is given a decision procedure (obtained by unfolding the definition and combining the decidability of boolean equality, integer order, natural-number disequality, and the connectives). This declaration asserts nothing mathematical beyond that; it is what allows later statements to write "if then else " as a computable branch.
7. SpendCondition
For a flag record , an oracle , byte strings (revocationPubkey), (localDelayedPubkey), an integer (toSelfDelay), and two further byte strings and , the proposition is the disjunction
Here of a byte string is: for the empty string; for a one-byte string , true iff and ; for a string with non-empty, true iff or . Equivalently, some byte is non-zero, except that a string whose only non-zero byte is its last byte and that byte equals is false. The two disjuncts are mutually exclusive since is a single boolean. In both disjuncts the oracle's signature check must return exactly : the outcomes "none" and "" both fail the condition. is as in item 5; note it is trivially satisfied when .
8. inputSequence
A transaction is a record with fields , (a list of inputs), (a list of outputs) and ; an input is a record with fields (a pair of a byte string and a natural), (a byte string), , and (a list of byte strings). No upper bound on or is imposed by these types. For a transaction and a natural ,
the sequence number of the -th input (zero-indexed), where if the "default input" is used instead, so the value is in that out-of-range case.
Confirmed by the mission captain (proposal self-audit).
Confirmed by the moderator at approval.