BOLT3.hs (6440B)
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_pubkey 150 , derive_localpubkey 151 , derive_local_htlcpubkey 152 , derive_remote_htlcpubkey 153 , derive_local_delayedpubkey 154 , derive_remote_delayedpubkey 155 , derive_revocationpubkey 156 157 -- ** Secret generation 158 , generate_from_seed 159 , derive_secret 160 161 -- ** Secret storage 162 , SecretStore(..) 163 , SecretEntry(..) 164 , empty_store 165 , insert_secret 166 , derive_old_secret 167 168 -- ** Commitment number 169 , obscured_commitment_number 170 171 -- * Scripts 172 -- ** Funding output 173 , funding_script 174 , funding_witness 175 176 -- ** to_local output 177 , to_local_script 178 , to_local_witness_spend 179 , to_local_witness_revoke 180 181 -- ** to_remote output 182 , to_remote_script 183 , to_remote_witness 184 185 -- ** Anchor outputs 186 , anchor_script 187 , anchor_witness_owner 188 , anchor_witness_anyone 189 190 -- ** Offered HTLC 191 , offered_htlc_script 192 , offered_htlc_witness_preimage 193 , offered_htlc_witness_revoke 194 195 -- ** Received HTLC 196 , received_htlc_script 197 , received_htlc_witness_timeout 198 , received_htlc_witness_revoke 199 200 -- ** HTLC output (same as to_local) 201 , htlc_output_script 202 , htlc_output_witness_spend 203 , htlc_output_witness_revoke 204 205 -- ** P2WSH helpers 206 , to_p2wsh 207 , witness_script_hash 208 209 -- * Transaction assembly 210 -- ** Commitment transactions 211 , CommitmentTx(..) 212 , CommitmentContext(..) 213 , CommitmentKeys(..) 214 , build_commitment_tx 215 216 -- ** HTLC transactions 217 , HTLCTx(..) 218 , HTLCContext(..) 219 , build_htlc_timeout_tx 220 , build_htlc_success_tx 221 222 -- ** Closing transactions 223 , ClosingTx(..) 224 , ClosingContext(..) 225 , build_closing_tx 226 , build_legacy_closing_tx 227 228 -- ** Transaction outputs 229 , TxOutput(..) 230 , OutputType(..) 231 232 -- ** Fee calculation 233 , commitment_fee 234 , commitment_weight 235 , htlc_timeout_fee 236 , htlc_success_fee 237 238 -- ** Trimming 239 , htlc_trim_threshold 240 , is_trimmed 241 , trimmed_htlcs 242 , untrimmed_htlcs 243 244 -- ** Output ordering 245 , sort_outputs 246 247 -- * Conversion to ppad-tx 248 , commitment_to_tx 249 , htlc_to_tx 250 , closing_to_tx 251 252 -- * Serialization 253 , encode_tx 254 , encode_htlc_tx 255 , encode_closing_tx 256 , encode_tx_for_signing 257 , encode_witness 258 , encode_funding_witness 259 260 -- * Parsing 261 , BT.Tx(..) 262 , BT.TxIn(..) 263 , BT.TxOut(BT.TxOut) 264 , BT.from_bytes 265 , decode_tx 266 267 -- * Validation 268 , ValidationError(..) 269 , validate_commitment_tx 270 , validate_commitment_locktime 271 , validate_commitment_sequence 272 , validate_htlc_tx 273 , validate_htlc_timeout_tx 274 , validate_htlc_success_tx 275 , validate_closing_tx 276 , validate_legacy_closing_tx 277 , validate_output_ordering 278 , validate_dust_limits 279 , validate_anchor_outputs 280 , validate_commitment_fee 281 , validate_htlc_fee 282 ) where 283 284 import qualified Bitcoin.Prim.Tx as BT 285 import Lightning.Protocol.BOLT3.Types 286 import Lightning.Protocol.BOLT3.Keys 287 import Lightning.Protocol.BOLT3.Scripts 288 import Lightning.Protocol.BOLT3.Tx 289 import Lightning.Protocol.BOLT3.Encode 290 import Lightning.Protocol.BOLT3.Decode 291 import Lightning.Protocol.BOLT3.Validate