BOLT 3: Commitment Transaction Format

The per_commitment_secret generation and shachain-based revocation are the core security mechanism preventing counterparty theft. Implementers must ensure the shachain is stored durably and that revocation secrets are delivered and verified before signing a new commitment. A failure to revoke an old state—or a bug in the derivation path—allows a counterparty to broadcast a revoked commitment and claim all channel funds. Hardware wallets and custody providers must handle the 49-day CSV delay and to_self_delay enforcement correctly.

Offered and received HTLCs use distinct script templates with specific CLTV/CSV timelock ordering. A single off-by-one error in the OP_CHECKLOCKTIMEVERIFY or OP_CHECKSEQUENCEVERIFY stack can make an output unclaimable or stealable. The second-stage HTLC transactions introduce additional fee and dust-limit edge cases. Security engineers must validate that the local/remote pubkey placement, revocation key inclusion, and timelock values match the canonical BOLT 3 templates exactly for each commitment transaction format.

The anchor outputs format adds zero-value OP_RETURN outputs to commitment and HTLC transactions, enabling Child-Pays-For-Parent fee bumping. This changes the transaction weight calculation and requires wallets to create and sign a separate spend of the anchor output with a high fee. Implementers must ensure the anchor output is not accidentally spent by a non-cooperative party and that the CSV delay on the to_self output is respected when spending the anchor in a CPFP package. Incorrect anchor handling can lead to stuck channels during fee spikes.

The transition to Taproot-based channels replaces the complex HTLC script trees with a single MuSig2 aggregate key and a taptree of spending conditions. This radically simplifies the on-chain footprint but introduces new signing-round requirements and changes the revocation mechanism to use a NUMS point instead of a shachain. Custody providers and hardware security modules must support two-round MuSig2 signing sessions and adapt their key-management policies. The PTLC migration further changes the cryptographic primitives for conditional payments.

The canonical BOLT 3 specification defines commitment transaction construction, obscured commitment numbers, funding input handling, output ordering, key derivation, HTLC scripts, fee calculation, trimming, and signature requirements. Implementers should treat its script templates and transaction-weight calculations as security-critical interoperability rules. Build deterministic test vectors for both commitment owners, every HTLC direction, dust-boundary cases, anchor-output channel types where supported, and revoked-state spends. Confirm that generated transactions are standard and valid under the Bitcoin node and policy configuration used in production.

The Lightning BOLTs repository is the authoritative review history for specification text, proposed amendments, and cross-BOLT dependencies. Teams should inspect merged commits and open pull requests affecting transaction weights, script construction, feature negotiation, channel types, or HTLC handling rather than relying on a static summary. During an implementation review, pin the tested behavior to a repository revision, record any deliberate deviations, and verify that experimental proposals have not been mistaken for broadly interoperable requirements.

BOLT 2 defines the peer message flow that creates, signs, revokes, and advances the commitment transactions formatted under BOLT 3. Review it alongside BOLT 3 to validate commitment-number progression, signature exchange, HTLC add/fulfill/fail sequencing, revocation-secret release, shutdown, and reestablishment behavior. Security tests should cover disconnects at every state transition and ensure a node never publishes or accepts a commitment whose signatures, HTLC set, or revocation status disagrees with its persisted channel state.

BOLT 5 specifies how nodes recognize and respond to funding spends, unilateral closes, revoked commitments, and HTLC outputs after transactions reach the Bitcoin network. Operators should use it to review sweep generation, preimage extraction, timeout handling, fee-bumping strategy, reorganization recovery, and breach-remediation monitoring. Wallets, custodians, and watchtowers must retain enough state and key material to construct the correct justice or claim path within the applicable CSV or CLTV window, including during fee spikes and backend outages.

BIP 112 documents the Bitcoin consensus primitive used to enforce relative delays in Lightning commitment-output spending paths. Review it with BIP 68 sequence-lock semantics and BIP 113 median-time-past rules when validating transaction construction and chain-monitoring deadlines. Implementers should test sequence values, transaction versions, script-number encoding, and delayed-output sweeps against the supported Bitcoin Core versions. Do not model to_self_delay as a wall-clock timer; enforcement depends on Bitcoin consensus and confirmation state.

BIP 68 defines how transaction input sequence numbers encode relative lock-time constraints, which underpin delayed recovery paths in Lightning commitments. Transaction builders, hardware signers, and custody policy engines should preserve the required transaction version and sequence semantics instead of normalizing fields as if they were ordinary wallet transactions. Include confirmation-depth changes and chain reorganizations in tests because the spendability point is derived from the confirmed ancestor state, not merely from local transaction-creation time.