BOLT3.hs (6640B)
1 {-# OPTIONS_HADDOCK prune #-} 2 3 -- | 4 -- Module: Lightning.Protocol.BOLT3 5 -- Copyright: (c) 2025 Jared Tobin 6 -- License: MIT 7 -- Maintainer: Jared Tobin <jared@ppad.tech> 8 -- 9 -- Bitcoin transaction formats for the Lightning Network, per 10 -- [BOLT #3](https://github.com/lightning/bolts/blob/master/03-transactions.md). 11 -- 12 -- = Overview 13 -- 14 -- This library implements the transaction and script formats defined in 15 -- BOLT #3, including: 16 -- 17 -- * Commitment transactions with to_local, to_remote, anchor, and HTLC 18 -- outputs 19 -- * HTLC-timeout and HTLC-success second-stage transactions 20 -- * Closing transactions (legacy and option_simple_close) 21 -- * Per-commitment key derivation and secret storage 22 -- * Transaction serialization and parsing 23 -- * Stateless validation 24 -- 25 -- = Quick Start 26 -- 27 -- @ 28 -- import Lightning.Protocol.BOLT3 29 -- 30 -- -- Build a commitment transaction 31 -- let ctx = CommitmentContext { ... } 32 -- tx = build_commitment_tx ctx 33 -- 34 -- -- Serialize for signing 35 -- let bytes = encode_tx tx 36 -- 37 -- -- Validate the transaction 38 -- case validate_commitment_tx dustLimit features tx of 39 -- Right () -> putStrLn "Valid" 40 -- Left err -> print err 41 -- @ 42 -- 43 -- = Modules 44 -- 45 -- * "Lightning.Protocol.BOLT3.Types" - Core types (Satoshi, Pubkey, HTLC, 46 -- etc.) 47 -- * "Lightning.Protocol.BOLT3.Keys" - Per-commitment key derivation and 48 -- secret storage 49 -- * "Lightning.Protocol.BOLT3.Scripts" - Witness script templates (funding, 50 -- to_local, HTLC, anchor) 51 -- * "Lightning.Protocol.BOLT3.Tx" - Transaction assembly 52 -- * "Lightning.Protocol.BOLT3.Encode" - Transaction serialization 53 -- * "Lightning.Protocol.BOLT3.Decode" - Transaction parsing 54 -- * "Lightning.Protocol.BOLT3.Validate" - Stateless validation 55 56 module Lightning.Protocol.BOLT3 ( 57 -- * Types 58 -- ** Monetary amounts 59 Satoshi(..) 60 , MilliSatoshi(..) 61 , msatToSat 62 , satToMsat 63 64 -- ** Keys and points 65 , Pubkey 66 , unPubkey 67 , pubkey 68 , Seckey 69 , unSeckey 70 , seckey 71 , Point 72 , unPoint 73 , point 74 75 -- ** Hashes 76 , PaymentHash 77 , unPaymentHash 78 , paymentHash 79 , PaymentPreimage 80 , unPaymentPreimage 81 , paymentPreimage 82 83 -- ** Transaction primitives 84 , TxId(..) 85 , mkTxId 86 , OutPoint(..) 87 , Sequence(..) 88 , Locktime(..) 89 90 -- ** Channel parameters 91 , CommitmentNumber 92 , unCommitmentNumber 93 , commitment_number 94 , next_commitment_number 95 , ToSelfDelay(..) 96 , CltvExpiry(..) 97 , DustLimit(..) 98 , FeeratePerKw(..) 99 100 -- ** HTLC types 101 , HTLC(..) 102 , HTLCDirection(..) 103 104 -- ** Basepoints 105 , Basepoints(..) 106 , PerCommitmentPoint(..) 107 , PerCommitmentSecret 108 , unPerCommitmentSecret 109 , perCommitmentSecret 110 , RevocationBasepoint(..) 111 , PaymentBasepoint(..) 112 , DelayedPaymentBasepoint(..) 113 , HtlcBasepoint(..) 114 115 -- ** Derived keys 116 , LocalPubkey(..) 117 , RemotePubkey(..) 118 , LocalDelayedPubkey(..) 119 , RemoteDelayedPubkey(..) 120 , LocalHtlcPubkey(..) 121 , RemoteHtlcPubkey(..) 122 , RevocationPubkey(..) 123 , FundingPubkey(..) 124 125 -- ** Script and witness 126 , Script(..) 127 , Witness(..) 128 129 -- ** Channel features 130 , ChannelFeatures(..) 131 , has_anchors 132 133 -- ** Constants 134 , commitment_weight_no_anchors 135 , commitment_weight_anchors 136 , htlc_timeout_weight_no_anchors 137 , htlc_timeout_weight_anchors 138 , htlc_success_weight_no_anchors 139 , htlc_success_weight_anchors 140 , htlc_output_weight 141 , dust_p2pkh 142 , dust_p2sh 143 , dust_p2wpkh 144 , dust_p2wsh 145 , anchor_output_value 146 147 -- * Key derivation 148 , derive_per_commitment_point 149 , derive_per_commitment_point' 150 , derive_pubkey 151 , derive_pubkey' 152 , derive_localpubkey 153 , derive_localpubkey' 154 , derive_local_htlcpubkey 155 , derive_local_htlcpubkey' 156 , derive_remote_htlcpubkey 157 , derive_remote_htlcpubkey' 158 , derive_local_delayedpubkey 159 , derive_local_delayedpubkey' 160 , derive_remote_delayedpubkey 161 , derive_remote_delayedpubkey' 162 , derive_revocationpubkey 163 164 -- ** Secret generation 165 , generate_from_seed 166 , derive_secret 167 168 -- ** Secret storage 169 , SecretStore(..) 170 , SecretEntry(..) 171 , empty_store 172 , insert_secret 173 , derive_old_secret 174 175 -- ** Commitment number 176 , obscured_commitment_number 177 178 -- * Scripts 179 -- ** Funding output 180 , funding_script 181 , funding_witness 182 183 -- ** to_local output 184 , to_local_script 185 , to_local_witness_spend 186 , to_local_witness_revoke 187 188 -- ** to_remote output 189 , to_remote_script 190 , to_remote_witness 191 192 -- ** Anchor outputs 193 , anchor_script 194 , anchor_witness_owner 195 , anchor_witness_anyone 196 197 -- ** Offered HTLC 198 , offered_htlc_script 199 , offered_htlc_witness_preimage 200 , offered_htlc_witness_revoke 201 202 -- ** Received HTLC 203 , received_htlc_script 204 , received_htlc_witness_timeout 205 , received_htlc_witness_revoke 206 207 -- ** HTLC output (same as to_local) 208 , htlc_output_script 209 , htlc_output_witness_spend 210 , htlc_output_witness_revoke 211 212 -- ** P2WSH helpers 213 , to_p2wsh 214 , witness_script_hash 215 216 -- * Transaction assembly 217 -- ** Commitment transactions 218 , CommitmentTx(..) 219 , CommitmentContext(..) 220 , CommitmentKeys(..) 221 , build_commitment_tx 222 223 -- ** HTLC transactions 224 , HTLCTx(..) 225 , HTLCContext(..) 226 , build_htlc_timeout_tx 227 , build_htlc_success_tx 228 229 -- ** Closing transactions 230 , ClosingTx(..) 231 , ClosingContext(..) 232 , build_closing_tx 233 , build_legacy_closing_tx 234 235 -- ** Transaction outputs 236 , TxOutput(..) 237 , OutputType(..) 238 239 -- ** Fee calculation 240 , commitment_fee 241 , commitment_weight 242 , htlc_timeout_fee 243 , htlc_success_fee 244 245 -- ** Trimming 246 , htlc_trim_threshold 247 , is_trimmed 248 , trimmed_htlcs 249 , untrimmed_htlcs 250 251 -- ** Output ordering 252 , sort_outputs 253 254 -- * Conversion to ppad-tx 255 , commitment_to_tx 256 , htlc_to_tx 257 , closing_to_tx 258 259 -- * Serialization 260 , encode_tx 261 , encode_htlc_tx 262 , encode_closing_tx 263 , encode_tx_for_signing 264 , encode_witness 265 , encode_funding_witness 266 267 -- * Parsing 268 , BT.Tx(..) 269 , BT.TxIn(..) 270 , BT.TxOut(BT.TxOut) 271 , BT.from_bytes 272 , decode_tx 273 274 -- * Validation 275 , ValidationError(..) 276 , validate_commitment_tx 277 , validate_commitment_locktime 278 , validate_commitment_sequence 279 , validate_htlc_tx 280 , validate_htlc_timeout_tx 281 , validate_htlc_success_tx 282 , validate_closing_tx 283 , validate_legacy_closing_tx 284 , validate_output_ordering 285 , validate_dust_limits 286 , validate_anchor_outputs 287 , validate_commitment_fee 288 , validate_htlc_fee 289 ) where 290 291 import qualified Bitcoin.Prim.Tx as BT 292 import Lightning.Protocol.BOLT3.Types 293 import Lightning.Protocol.BOLT3.Keys 294 import Lightning.Protocol.BOLT3.Scripts 295 import Lightning.Protocol.BOLT3.Tx 296 import Lightning.Protocol.BOLT3.Encode 297 import Lightning.Protocol.BOLT3.Decode 298 import Lightning.Protocol.BOLT3.Validate