BOLT2.hs (5078B)
1 {-# OPTIONS_HADDOCK prune #-} 2 3 -- | 4 -- Module: Lightning.Protocol.BOLT2 5 -- Copyright: (c) 2025 Jared Tobin 6 -- License: MIT 7 -- Maintainer: Jared Tobin <jared@ppad.tech> 8 -- 9 -- The peer protocol of the Lightning Network, per 10 -- [BOLT #2](https://github.com/lightning/bolts/blob/master/02-peer-protocol.md): 11 -- the messages for channel establishment (v1 and v2), interactive 12 -- transaction construction, quiescence, channel close, normal operation 13 -- and message retransmission. 14 -- 15 -- Fundamental types (channel ids, points, signatures, amounts, TLV 16 -- streams) come from ppad-bolt1, transaction ids from ppad-tx, and 17 -- feature vectors from ppad-bolt9. 18 -- 19 -- Each message has a payload codec, @encode_\<msg\>@ and 20 -- @decode_\<msg\>@; 'encode_message' and 'decode_message' handle 21 -- complete messages, including the type. Decoders consume the whole 22 -- payload: bytes after the fixed fields are the message's TLV stream. 23 -- Known TLV records are decoded into typed fields, an unknown even 24 -- record fails the decode, and unknown odd records are kept in the 25 -- message's @_tlvs@ field, so re-encoding a decoded message reproduces 26 -- its bytes. 27 -- 28 -- The examples below assume: 29 -- 30 -- >>> :set -XOverloadedStrings 31 -- >>> import qualified Data.ByteString as BS 32 -- >>> import qualified Lightning.Protocol.BOLT1 as BOLT1 33 -- >>> import Lightning.Protocol.BOLT2 34 -- >>> let Just cid = BOLT1.channel_id (BS.replicate 32 0xab) 35 -- 36 -- Encode a message, and decode it again: 37 -- 38 -- >>> let fee = UpdateFee cid 2500 BOLT1.empty_tlv_stream 39 -- >>> let Right wire = encode_message (MsgUpdateFee fee) 40 -- >>> BS.length wire 41 -- 38 42 -- >>> decode_message wire == Right (MsgUpdateFee fee) 43 -- True 44 -- 45 -- Unknown odd TLV records are preserved, and unknown even ones 46 -- rejected: 47 -- 48 -- >>> let payload = encode_update_fee fee 49 -- >>> fmap update_fee_tlvs (decode_update_fee (payload <> "\x05\x01\x2a")) 50 -- Right (TlvStream [TlvRecord {tlv_type = 5, tlv_value = "*"}]) 51 -- >>> decode_update_fee (payload <> "\x04\x01\x2a") 52 -- Left (DecodeTlvError (TlvUnknownEvenType 4)) 53 54 module Lightning.Protocol.BOLT2 ( 55 -- * Messages 56 Message(..) 57 , message_type 58 59 -- ** Channel establishment v1 60 , OpenChannel(..) 61 , AcceptChannel(..) 62 , FundingCreated(..) 63 , FundingSigned(..) 64 , ChannelReady(..) 65 66 -- ** Channel establishment v2 67 , OpenChannel2(..) 68 , AcceptChannel2(..) 69 70 -- ** Interactive transaction construction 71 , TxAddInput(..) 72 , TxAddOutput(..) 73 , TxRemoveInput(..) 74 , TxRemoveOutput(..) 75 , TxComplete(..) 76 , TxSignatures(..) 77 , TxInitRbf(..) 78 , TxAckRbf(..) 79 , TxAbort(..) 80 81 -- ** Channel quiescence 82 , Stfu(..) 83 84 -- ** Channel close 85 , Shutdown(..) 86 , ClosingComplete(..) 87 , ClosingSig(..) 88 , ClosingSigned(..) 89 90 -- ** Normal operation 91 , UpdateAddHtlc(..) 92 , UpdateFulfillHtlc(..) 93 , UpdateFailHtlc(..) 94 , UpdateFailMalformedHtlc(..) 95 , CommitmentSigned(..) 96 , RevokeAndAck(..) 97 , UpdateFee(..) 98 99 -- ** Message retransmission 100 , ChannelReestablish(..) 101 102 -- * Field types 103 , HtlcId(..) 104 , SerialId(..) 105 , ScriptPubKey 106 , script_pubkey 107 , un_script_pubkey 108 , Witness 109 , witness 110 , un_witness 111 , OnionRoutingPacket 112 , onion_routing_packet 113 , un_onion_routing_packet 114 , OnionHash 115 , onion_hash 116 , un_onion_hash 117 , AttributionData 118 , attribution_data 119 , un_attribution_data 120 , FeeRange(..) 121 , NextFunding(..) 122 123 -- * Encoding and decoding messages 124 , encode_message 125 , decode_message 126 , EncodeError(..) 127 , DecodeError(..) 128 129 -- ** Payloads 130 , encode_open_channel 131 , decode_open_channel 132 , encode_accept_channel 133 , decode_accept_channel 134 , encode_funding_created 135 , decode_funding_created 136 , encode_funding_signed 137 , decode_funding_signed 138 , encode_channel_ready 139 , decode_channel_ready 140 , encode_open_channel2 141 , decode_open_channel2 142 , encode_accept_channel2 143 , decode_accept_channel2 144 , encode_tx_add_input 145 , decode_tx_add_input 146 , encode_tx_add_output 147 , decode_tx_add_output 148 , encode_tx_remove_input 149 , decode_tx_remove_input 150 , encode_tx_remove_output 151 , decode_tx_remove_output 152 , encode_tx_complete 153 , decode_tx_complete 154 , encode_tx_signatures 155 , decode_tx_signatures 156 , encode_tx_init_rbf 157 , decode_tx_init_rbf 158 , encode_tx_ack_rbf 159 , decode_tx_ack_rbf 160 , encode_tx_abort 161 , decode_tx_abort 162 , encode_stfu 163 , decode_stfu 164 , encode_shutdown 165 , decode_shutdown 166 , encode_closing_complete 167 , decode_closing_complete 168 , encode_closing_sig 169 , decode_closing_sig 170 , encode_closing_signed 171 , decode_closing_signed 172 , encode_update_add_htlc 173 , decode_update_add_htlc 174 , encode_update_fulfill_htlc 175 , decode_update_fulfill_htlc 176 , encode_update_fail_htlc 177 , decode_update_fail_htlc 178 , encode_update_fail_malformed_htlc 179 , decode_update_fail_malformed_htlc 180 , encode_commitment_signed 181 , decode_commitment_signed 182 , encode_revoke_and_ack 183 , decode_revoke_and_ack 184 , encode_update_fee 185 , decode_update_fee 186 , encode_channel_reestablish 187 , decode_channel_reestablish 188 ) where 189 190 import Lightning.Protocol.BOLT2.Codec 191 import Lightning.Protocol.BOLT2.Messages 192 import Lightning.Protocol.BOLT2.Types