BOLT3.hs (6298B)
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 , msat_to_sat 62 , sat_to_msat 63 64 -- ** Keys and points 65 , Pubkey(..) 66 , pubkey 67 , Seckey(..) 68 , seckey 69 , Point(..) 70 , point 71 72 -- ** Hashes 73 , PaymentHash(..) 74 , payment_hash 75 , PaymentPreimage(..) 76 , payment_preimage 77 78 -- ** Transaction primitives 79 , TxId(..) 80 , mkTxId 81 , OutPoint(..) 82 , Sequence(..) 83 , Locktime(..) 84 85 -- ** Channel parameters 86 , CommitmentNumber(..) 87 , commitment_number 88 , ToSelfDelay(..) 89 , CltvExpiry(..) 90 , DustLimit(..) 91 , FeeratePerKw(..) 92 93 -- ** HTLC types 94 , HTLC(..) 95 , HTLCDirection(..) 96 97 -- ** Basepoints 98 , Basepoints(..) 99 , PerCommitmentPoint(..) 100 , PerCommitmentSecret(..) 101 , per_commitment_secret 102 , RevocationBasepoint(..) 103 , PaymentBasepoint(..) 104 , DelayedPaymentBasepoint(..) 105 , HtlcBasepoint(..) 106 107 -- ** Derived keys 108 , LocalPubkey(..) 109 , RemotePubkey(..) 110 , LocalDelayedPubkey(..) 111 , RemoteDelayedPubkey(..) 112 , LocalHtlcPubkey(..) 113 , RemoteHtlcPubkey(..) 114 , RevocationPubkey(..) 115 , FundingPubkey(..) 116 117 -- ** Script and witness 118 , Script(..) 119 , Witness(..) 120 121 -- ** Channel features 122 , ChannelFeatures(..) 123 , has_anchors 124 125 -- ** Constants 126 , commitment_weight_no_anchors 127 , commitment_weight_anchors 128 , htlc_timeout_weight_no_anchors 129 , htlc_timeout_weight_anchors 130 , htlc_success_weight_no_anchors 131 , htlc_success_weight_anchors 132 , htlc_output_weight 133 , dust_p2pkh 134 , dust_p2sh 135 , dust_p2wpkh 136 , dust_p2wsh 137 , anchor_output_value 138 139 -- * Key derivation 140 , derive_per_commitment_point 141 , derive_pubkey 142 , derive_localpubkey 143 , derive_local_htlcpubkey 144 , derive_remote_htlcpubkey 145 , derive_local_delayedpubkey 146 , derive_remote_delayedpubkey 147 , derive_revocationpubkey 148 149 -- ** Secret generation 150 , generate_from_seed 151 , derive_secret 152 153 -- ** Secret storage 154 , SecretStore 155 , empty_store 156 , insert_secret 157 , derive_old_secret 158 159 -- ** Commitment number 160 , obscured_commitment_number 161 162 -- * Scripts 163 -- ** Funding output 164 , funding_script 165 , funding_witness 166 167 -- ** to_local output 168 , to_local_script 169 , to_local_witness_spend 170 , to_local_witness_revoke 171 172 -- ** to_remote output 173 , to_remote_script 174 , to_remote_witness 175 176 -- ** Anchor outputs 177 , anchor_script 178 , anchor_witness_owner 179 , anchor_witness_anyone 180 181 -- ** Offered HTLC 182 , offered_htlc_script 183 , offered_htlc_witness_preimage 184 , offered_htlc_witness_revoke 185 186 -- ** Received HTLC 187 , received_htlc_script 188 , received_htlc_witness_timeout 189 , received_htlc_witness_revoke 190 191 -- ** HTLC output (same as to_local) 192 , htlc_output_script 193 , htlc_output_witness_spend 194 , htlc_output_witness_revoke 195 196 -- ** P2WSH helpers 197 , to_p2wsh 198 , witness_script_hash 199 200 -- * Transaction assembly 201 -- ** Commitment transactions 202 , CommitmentTx(..) 203 , CommitmentContext(..) 204 , CommitmentKeys(..) 205 , build_commitment_tx 206 207 -- ** HTLC transactions 208 , HTLCTx(..) 209 , HTLCContext(..) 210 , build_htlc_timeout_tx 211 , build_htlc_success_tx 212 213 -- ** Closing transactions 214 , ClosingTx(..) 215 , ClosingContext(..) 216 , build_closing_tx 217 , build_legacy_closing_tx 218 219 -- ** Transaction outputs 220 , TxOutput(..) 221 , OutputType(..) 222 223 -- ** Fee calculation 224 , commitment_fee 225 , commitment_weight 226 , htlc_timeout_fee 227 , htlc_success_fee 228 229 -- ** Trimming 230 , htlc_trim_threshold 231 , is_trimmed 232 , trimmed_htlcs 233 , untrimmed_htlcs 234 235 -- ** Output ordering 236 , sort_outputs 237 238 -- * Conversion to ppad-tx 239 , commitment_to_tx 240 , htlc_to_tx 241 , closing_to_tx 242 243 -- * Serialization 244 , encode_tx 245 , encode_htlc_tx 246 , encode_closing_tx 247 , encode_tx_for_signing 248 , encode_witness 249 , encode_funding_witness 250 251 -- * Parsing 252 , BT.Tx(..) 253 , BT.TxIn(..) 254 , BT.TxOut(BT.TxOut) 255 , BT.from_bytes 256 , decode_tx 257 258 -- * Validation 259 , ValidationError(..) 260 , validate_commitment_tx 261 , validate_commitment_locktime 262 , validate_commitment_sequence 263 , validate_htlc_tx 264 , validate_htlc_timeout_tx 265 , validate_htlc_success_tx 266 , validate_closing_tx 267 , validate_legacy_closing_tx 268 , validate_output_ordering 269 , validate_dust_limits 270 , validate_anchor_outputs 271 , validate_commitment_fee 272 , validate_htlc_fee 273 ) where 274 275 import qualified Bitcoin.Prim.Tx as BT 276 import Lightning.Protocol.BOLT3.Types 277 import Lightning.Protocol.BOLT3.Keys 278 import Lightning.Protocol.BOLT3.Scripts 279 import Lightning.Protocol.BOLT3.Tx 280 import Lightning.Protocol.BOLT3.Encode 281 import Lightning.Protocol.BOLT3.Decode 282 import Lightning.Protocol.BOLT3.Validate