| Copyright | (c) 2025 Jared Tobin |
|---|---|
| License | MIT |
| Maintainer | Jared Tobin <jared@ppad.tech> |
| Safe Haskell | None |
| Language | Haskell2010 |
Lightning.Protocol.BOLT5.Detect
Description
Close identification, output classification, and preimage extraction for BOLT #5 on-chain transaction handling.
Synopsis
- identify_close :: CommitmentTx -> CommitmentTx -> ByteString -> Maybe CloseType
- classify_local_commit_outputs :: CommitmentTx -> CommitmentKeys -> ToSelfDelay -> ChannelFeatures -> [HTLC] -> [UnresolvedOutput]
- classify_remote_commit_outputs :: CommitmentTx -> CommitmentKeys -> ChannelFeatures -> [HTLC] -> [UnresolvedOutput]
- classify_revoked_commit_outputs :: CommitmentTx -> CommitmentKeys -> RevocationPubkey -> ChannelFeatures -> [HTLC] -> [UnresolvedOutput]
- extract_preimage_offered :: Witness -> Maybe PaymentPreimage
- extract_preimage_htlc_success :: Witness -> Maybe PaymentPreimage
- htlc_timed_out :: Word32 -> HTLC -> Bool
Close identification
Arguments
| :: CommitmentTx | Our local commitment tx. |
| -> CommitmentTx | The remote commitment tx (current). |
| -> ByteString | Raw serialized transaction found on chain. |
| -> Maybe CloseType |
Identify the type of channel close from a transaction that spends the funding output.
Compares the on-chain transaction bytes against the known local and remote commitment transaction serializations (stripped/unsigned) to determine whether it's a local or remote commitment close.
Returns Nothing if the transaction doesn't match either
commitment. Mutual close and revoked commitment detection
require additional checks by the caller (e.g. comparing
closing tx format, checking a secret store for older
commitment numbers).
Output classification
classify_local_commit_outputs Source #
Arguments
| :: CommitmentTx | Our local commitment transaction. |
| -> CommitmentKeys | Derived keys for this commitment. |
| -> ToSelfDelay | Remote's to_self_delay (CSV delay for our outputs). |
| -> ChannelFeatures | Channel feature flags. |
| -> [HTLC] | HTLCs in this commitment. |
| -> [UnresolvedOutput] |
Classify outputs of our local commitment transaction.
Per BOLT #5: when we discover our local commitment on chain, we must resolve each output. to_local requires a CSV-delayed spend, to_remote is resolved by the commitment itself, HTLC outputs need second-stage transactions, and anchors can be spent immediately.
classify_remote_commit_outputs Source #
Arguments
| :: CommitmentTx | The remote commitment transaction. |
| -> CommitmentKeys | Derived keys for this commitment (from remote's perspective, so local/remote are swapped). |
| -> ChannelFeatures | Channel feature flags. |
| -> [HTLC] | HTLCs in this commitment. |
| -> [UnresolvedOutput] |
Classify outputs of the remote commitment transaction.
Per BOLT #5: when we discover the remote commitment on chain, there are no CSV delays on our outputs. We can spend offered HTLCs directly after timeout, and received HTLCs directly with the preimage.
classify_revoked_commit_outputs Source #
Arguments
| :: CommitmentTx | The revoked commitment transaction. |
| -> CommitmentKeys | Derived keys for the revoked commitment. |
| -> RevocationPubkey | Revocation pubkey (derived from the revealed secret). |
| -> ChannelFeatures | Channel feature flags. |
| -> [HTLC] | HTLCs in the revoked commitment. |
| -> [UnresolvedOutput] |
Classify outputs of a revoked commitment transaction.
Per BOLT #5: when we discover a revoked commitment, we can claim everything using the revocation key. to_local is spent via revocation, HTLCs are spent via revocation, and we can also optionally sweep to_remote.
Preimage extraction
extract_preimage_offered :: Witness -> Maybe PaymentPreimage Source #
Extract a payment preimage from an offered HTLC witness.
When the remote party claims an offered HTLC on our local commitment, the witness contains the preimage. The witness stack for a preimage claim is:
<remotehtlcsig> <paymentPreimage>
The preimage is the second item (32 bytes) and must hash to the expected payment hash.
extract_preimage_htlc_success :: Witness -> Maybe PaymentPreimage Source #
Extract a payment preimage from an HTLC-success transaction witness.
When the remote party uses an HTLC-success tx on their commitment to claim a received HTLC, the witness contains the preimage. The witness stack is:
0 <remotehtlcsig> <localhtlcsig> <paymentPreimage>
The preimage is the fourth item (32 bytes).