/
msgs.rs
2774 lines (2560 loc) · 108 KB
/
msgs.rs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// This file is Copyright its original authors, visible in version control
// history.
//
// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
// You may not use this file except in accordance with one or both of these
// licenses.
//! Wire messages, traits representing wire message handlers, and a few error types live here.
//!
//! For a normal node you probably don't need to use anything here, however, if you wish to split a
//! node into an internet-facing route/message socket handling daemon and a separate daemon (or
//! server entirely) which handles only channel-related messages you may wish to implement
//! ChannelMessageHandler yourself and use it to re-serialize messages and pass them across
//! daemons/servers.
//!
//! Note that if you go with such an architecture (instead of passing raw socket events to a
//! non-internet-facing system) you trust the frontend internet-facing system to not lie about the
//! source node_id of the message, however this does allow you to significantly reduce bandwidth
//! between the systems as routing messages can represent a significant chunk of bandwidth usage
//! (especially for non-channel-publicly-announcing nodes). As an alternate design which avoids
//! this issue, if you have sufficient bidirectional bandwidth between your systems, you may send
//! raw socket events into your non-internet-facing system and then send routing events back to
//! track the network on the less-secure system.
use bitcoin::secp256k1::PublicKey;
use bitcoin::secp256k1::ecdsa::Signature;
use bitcoin::secp256k1;
use bitcoin::blockdata::script::Script;
use bitcoin::hash_types::{Txid, BlockHash};
use ln::features::{ChannelFeatures, ChannelTypeFeatures, InitFeatures, NodeFeatures};
use prelude::*;
use core::fmt;
use core::fmt::Debug;
use io::{self, Read};
use io_extras::read_to_end;
use util::events::MessageSendEventsProvider;
use util::logger;
use util::ser::{Readable, Writeable, Writer, FixedLengthReader, HighZeroBytesDroppedVarInt, Hostname};
use ln::{PaymentPreimage, PaymentHash, PaymentSecret};
/// 21 million * 10^8 * 1000
pub(crate) const MAX_VALUE_MSAT: u64 = 21_000_000_0000_0000_000;
/// An error in decoding a message or struct.
#[derive(Clone, Debug, PartialEq)]
pub enum DecodeError {
/// A version byte specified something we don't know how to handle.
/// Includes unknown realm byte in an OnionHopData packet
UnknownVersion,
/// Unknown feature mandating we fail to parse message (eg TLV with an even, unknown type)
UnknownRequiredFeature,
/// Value was invalid, eg a byte which was supposed to be a bool was something other than a 0
/// or 1, a public key/private key/signature was invalid, text wasn't UTF-8, TLV was
/// syntactically incorrect, etc
InvalidValue,
/// Buffer too short
ShortRead,
/// A length descriptor in the packet didn't describe the later data correctly
BadLengthDescriptor,
/// Error from std::io
Io(/// (C-not exported) as ErrorKind doesn't have a reasonable mapping
io::ErrorKind),
/// The message included zlib-compressed values, which we don't support.
UnsupportedCompression,
}
/// An init message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct Init {
/// The relevant features which the sender supports
pub features: InitFeatures,
/// The receipient's network address. This adds the option to report a remote IP address
/// back to a connecting peer using the init message. A node can decide to use that information
/// to discover a potential update to its public IPv4 address (NAT) and use
/// that for a node_announcement update message containing the new address.
pub remote_network_address: Option<NetAddress>,
}
/// An error message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ErrorMessage {
/// The channel ID involved in the error.
///
/// All-0s indicates a general error unrelated to a specific channel, after which all channels
/// with the sending peer should be closed.
pub channel_id: [u8; 32],
/// A possibly human-readable error description.
/// The string should be sanitized before it is used (e.g. emitted to logs or printed to
/// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in
/// the terminal emulator or the logging subsystem.
pub data: String,
}
/// A warning message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct WarningMessage {
/// The channel ID involved in the warning.
///
/// All-0s indicates a warning unrelated to a specific channel.
pub channel_id: [u8; 32],
/// A possibly human-readable warning description.
/// The string should be sanitized before it is used (e.g. emitted to logs or printed to
/// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in
/// the terminal emulator or the logging subsystem.
pub data: String,
}
/// A ping message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct Ping {
/// The desired response length
pub ponglen: u16,
/// The ping packet size.
/// This field is not sent on the wire. byteslen zeros are sent.
pub byteslen: u16,
}
/// A pong message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct Pong {
/// The pong packet size.
/// This field is not sent on the wire. byteslen zeros are sent.
pub byteslen: u16,
}
/// An open_channel message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct OpenChannel {
/// The genesis hash of the blockchain where the channel is to be opened
pub chain_hash: BlockHash,
/// A temporary channel ID, until the funding outpoint is announced
pub temporary_channel_id: [u8; 32],
/// The channel value
pub funding_satoshis: u64,
/// The amount to push to the counterparty as part of the open, in milli-satoshi
pub push_msat: u64,
/// The threshold below which outputs on transactions broadcast by sender will be omitted
pub dust_limit_satoshis: u64,
/// The maximum inbound HTLC value in flight towards sender, in milli-satoshi
pub max_htlc_value_in_flight_msat: u64,
/// The minimum value unencumbered by HTLCs for the counterparty to keep in the channel
pub channel_reserve_satoshis: u64,
/// The minimum HTLC size incoming to sender, in milli-satoshi
pub htlc_minimum_msat: u64,
/// The feerate per 1000-weight of sender generated transactions, until updated by update_fee
pub feerate_per_kw: u32,
/// The number of blocks which the counterparty will have to wait to claim on-chain funds if they broadcast a commitment transaction
pub to_self_delay: u16,
/// The maximum number of inbound HTLCs towards sender
pub max_accepted_htlcs: u16,
/// The sender's key controlling the funding transaction
pub funding_pubkey: PublicKey,
/// Used to derive a revocation key for transactions broadcast by counterparty
pub revocation_basepoint: PublicKey,
/// A payment key to sender for transactions broadcast by counterparty
pub payment_point: PublicKey,
/// Used to derive a payment key to sender for transactions broadcast by sender
pub delayed_payment_basepoint: PublicKey,
/// Used to derive an HTLC payment key to sender
pub htlc_basepoint: PublicKey,
/// The first to-be-broadcast-by-sender transaction's per commitment point
pub first_per_commitment_point: PublicKey,
/// Channel flags
pub channel_flags: u8,
/// Optionally, a request to pre-set the to-sender output's scriptPubkey for when we collaboratively close
pub shutdown_scriptpubkey: OptionalField<Script>,
/// The channel type that this channel will represent. If none is set, we derive the channel
/// type from the intersection of our feature bits with our counterparty's feature bits from
/// the Init message.
pub channel_type: Option<ChannelTypeFeatures>,
}
/// An accept_channel message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct AcceptChannel {
/// A temporary channel ID, until the funding outpoint is announced
pub temporary_channel_id: [u8; 32],
/// The threshold below which outputs on transactions broadcast by sender will be omitted
pub dust_limit_satoshis: u64,
/// The maximum inbound HTLC value in flight towards sender, in milli-satoshi
pub max_htlc_value_in_flight_msat: u64,
/// The minimum value unencumbered by HTLCs for the counterparty to keep in the channel
pub channel_reserve_satoshis: u64,
/// The minimum HTLC size incoming to sender, in milli-satoshi
pub htlc_minimum_msat: u64,
/// Minimum depth of the funding transaction before the channel is considered open
pub minimum_depth: u32,
/// The number of blocks which the counterparty will have to wait to claim on-chain funds if they broadcast a commitment transaction
pub to_self_delay: u16,
/// The maximum number of inbound HTLCs towards sender
pub max_accepted_htlcs: u16,
/// The sender's key controlling the funding transaction
pub funding_pubkey: PublicKey,
/// Used to derive a revocation key for transactions broadcast by counterparty
pub revocation_basepoint: PublicKey,
/// A payment key to sender for transactions broadcast by counterparty
pub payment_point: PublicKey,
/// Used to derive a payment key to sender for transactions broadcast by sender
pub delayed_payment_basepoint: PublicKey,
/// Used to derive an HTLC payment key to sender for transactions broadcast by counterparty
pub htlc_basepoint: PublicKey,
/// The first to-be-broadcast-by-sender transaction's per commitment point
pub first_per_commitment_point: PublicKey,
/// Optionally, a request to pre-set the to-sender output's scriptPubkey for when we collaboratively close
pub shutdown_scriptpubkey: OptionalField<Script>,
/// The channel type that this channel will represent. If none is set, we derive the channel
/// type from the intersection of our feature bits with our counterparty's feature bits from
/// the Init message.
///
/// This is required to match the equivalent field in [`OpenChannel::channel_type`].
pub channel_type: Option<ChannelTypeFeatures>,
}
/// A funding_created message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct FundingCreated {
/// A temporary channel ID, until the funding is established
pub temporary_channel_id: [u8; 32],
/// The funding transaction ID
pub funding_txid: Txid,
/// The specific output index funding this channel
pub funding_output_index: u16,
/// The signature of the channel initiator (funder) on the initial commitment transaction
pub signature: Signature,
}
/// A funding_signed message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct FundingSigned {
/// The channel ID
pub channel_id: [u8; 32],
/// The signature of the channel acceptor (fundee) on the initial commitment transaction
pub signature: Signature,
}
/// A channel_ready message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelReady {
/// The channel ID
pub channel_id: [u8; 32],
/// The per-commitment point of the second commitment transaction
pub next_per_commitment_point: PublicKey,
/// If set, provides a short_channel_id alias for this channel. The sender will accept payments
/// to be forwarded over this SCID and forward them to this messages' recipient.
pub short_channel_id_alias: Option<u64>,
}
/// A shutdown message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct Shutdown {
/// The channel ID
pub channel_id: [u8; 32],
/// The destination of this peer's funds on closing.
/// Must be in one of these forms: p2pkh, p2sh, p2wpkh, p2wsh.
pub scriptpubkey: Script,
}
/// The minimum and maximum fees which the sender is willing to place on the closing transaction.
/// This is provided in [`ClosingSigned`] by both sides to indicate the fee range they are willing
/// to use.
#[derive(Clone, Debug, PartialEq)]
pub struct ClosingSignedFeeRange {
/// The minimum absolute fee, in satoshis, which the sender is willing to place on the closing
/// transaction.
pub min_fee_satoshis: u64,
/// The maximum absolute fee, in satoshis, which the sender is willing to place on the closing
/// transaction.
pub max_fee_satoshis: u64,
}
/// A closing_signed message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ClosingSigned {
/// The channel ID
pub channel_id: [u8; 32],
/// The proposed total fee for the closing transaction
pub fee_satoshis: u64,
/// A signature on the closing transaction
pub signature: Signature,
/// The minimum and maximum fees which the sender is willing to accept, provided only by new
/// nodes.
pub fee_range: Option<ClosingSignedFeeRange>,
}
/// An update_add_htlc message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateAddHTLC {
/// The channel ID
pub channel_id: [u8; 32],
/// The HTLC ID
pub htlc_id: u64,
/// The HTLC value in milli-satoshi
pub amount_msat: u64,
/// The payment hash, the pre-image of which controls HTLC redemption
pub payment_hash: PaymentHash,
/// The expiry height of the HTLC
pub cltv_expiry: u32,
pub(crate) onion_routing_packet: OnionPacket,
}
/// An update_fulfill_htlc message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateFulfillHTLC {
/// The channel ID
pub channel_id: [u8; 32],
/// The HTLC ID
pub htlc_id: u64,
/// The pre-image of the payment hash, allowing HTLC redemption
pub payment_preimage: PaymentPreimage,
}
/// An update_fail_htlc message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateFailHTLC {
/// The channel ID
pub channel_id: [u8; 32],
/// The HTLC ID
pub htlc_id: u64,
pub(crate) reason: OnionErrorPacket,
}
/// An update_fail_malformed_htlc message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateFailMalformedHTLC {
/// The channel ID
pub channel_id: [u8; 32],
/// The HTLC ID
pub htlc_id: u64,
pub(crate) sha256_of_onion: [u8; 32],
/// The failure code
pub failure_code: u16,
}
/// A commitment_signed message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct CommitmentSigned {
/// The channel ID
pub channel_id: [u8; 32],
/// A signature on the commitment transaction
pub signature: Signature,
/// Signatures on the HTLC transactions
pub htlc_signatures: Vec<Signature>,
}
/// A revoke_and_ack message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct RevokeAndACK {
/// The channel ID
pub channel_id: [u8; 32],
/// The secret corresponding to the per-commitment point
pub per_commitment_secret: [u8; 32],
/// The next sender-broadcast commitment transaction's per-commitment point
pub next_per_commitment_point: PublicKey,
}
/// An update_fee message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateFee {
/// The channel ID
pub channel_id: [u8; 32],
/// Fee rate per 1000-weight of the transaction
pub feerate_per_kw: u32,
}
#[derive(Clone, Debug, PartialEq)]
/// Proof that the sender knows the per-commitment secret of the previous commitment transaction.
/// This is used to convince the recipient that the channel is at a certain commitment
/// number even if they lost that data due to a local failure. Of course, the peer may lie
/// and even later commitments may have been revoked.
pub struct DataLossProtect {
/// Proof that the sender knows the per-commitment secret of a specific commitment transaction
/// belonging to the recipient
pub your_last_per_commitment_secret: [u8; 32],
/// The sender's per-commitment point for their current commitment transaction
pub my_current_per_commitment_point: PublicKey,
}
/// A channel_reestablish message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelReestablish {
/// The channel ID
pub channel_id: [u8; 32],
/// The next commitment number for the sender
pub next_local_commitment_number: u64,
/// The next commitment number for the recipient
pub next_remote_commitment_number: u64,
/// Optionally, a field proving that next_remote_commitment_number-1 has been revoked
pub data_loss_protect: OptionalField<DataLossProtect>,
}
/// An announcement_signatures message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct AnnouncementSignatures {
/// The channel ID
pub channel_id: [u8; 32],
/// The short channel ID
pub short_channel_id: u64,
/// A signature by the node key
pub node_signature: Signature,
/// A signature by the funding key
pub bitcoin_signature: Signature,
}
/// An address which can be used to connect to a remote peer
#[derive(Clone, Debug, PartialEq)]
pub enum NetAddress {
/// An IPv4 address/port on which the peer is listening.
IPv4 {
/// The 4-byte IPv4 address
addr: [u8; 4],
/// The port on which the node is listening
port: u16,
},
/// An IPv6 address/port on which the peer is listening.
IPv6 {
/// The 16-byte IPv6 address
addr: [u8; 16],
/// The port on which the node is listening
port: u16,
},
/// An old-style Tor onion address/port on which the peer is listening.
///
/// This field is deprecated and the Tor network generally no longer supports V2 Onion
/// addresses. Thus, the details are not parsed here.
OnionV2([u8; 12]),
/// A new-style Tor onion address/port on which the peer is listening.
/// To create the human-readable "hostname", concatenate ed25519_pubkey, checksum, and version,
/// wrap as base32 and append ".onion".
OnionV3 {
/// The ed25519 long-term public key of the peer
ed25519_pubkey: [u8; 32],
/// The checksum of the pubkey and version, as included in the onion address
checksum: u16,
/// The version byte, as defined by the Tor Onion v3 spec.
version: u8,
/// The port on which the node is listening
port: u16,
},
/// A hostname/port on which the peer is listening.
Hostname {
/// The hostname on which the node is listening.
hostname: Hostname,
/// The port on which the node is listening.
port: u16,
},
}
impl NetAddress {
/// Gets the ID of this address type. Addresses in node_announcement messages should be sorted
/// by this.
pub(crate) fn get_id(&self) -> u8 {
match self {
&NetAddress::IPv4 {..} => { 1 },
&NetAddress::IPv6 {..} => { 2 },
&NetAddress::OnionV2(_) => { 3 },
&NetAddress::OnionV3 {..} => { 4 },
&NetAddress::Hostname {..} => { 5 },
}
}
/// Strict byte-length of address descriptor, 1-byte type not recorded
fn len(&self) -> u16 {
match self {
&NetAddress::IPv4 { .. } => { 6 },
&NetAddress::IPv6 { .. } => { 18 },
&NetAddress::OnionV2(_) => { 12 },
&NetAddress::OnionV3 { .. } => { 37 },
// Consists of 1-byte hostname length, hostname bytes, and 2-byte port.
&NetAddress::Hostname { ref hostname, .. } => { u16::from(hostname.len()) + 3 },
}
}
/// The maximum length of any address descriptor, not including the 1-byte type.
/// This maximum length is reached by a hostname address descriptor:
/// a hostname with a maximum length of 255, its 1-byte length and a 2-byte port.
pub(crate) const MAX_LEN: u16 = 258;
}
impl Writeable for NetAddress {
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
match self {
&NetAddress::IPv4 { ref addr, ref port } => {
1u8.write(writer)?;
addr.write(writer)?;
port.write(writer)?;
},
&NetAddress::IPv6 { ref addr, ref port } => {
2u8.write(writer)?;
addr.write(writer)?;
port.write(writer)?;
},
&NetAddress::OnionV2(bytes) => {
3u8.write(writer)?;
bytes.write(writer)?;
},
&NetAddress::OnionV3 { ref ed25519_pubkey, ref checksum, ref version, ref port } => {
4u8.write(writer)?;
ed25519_pubkey.write(writer)?;
checksum.write(writer)?;
version.write(writer)?;
port.write(writer)?;
},
&NetAddress::Hostname { ref hostname, ref port } => {
5u8.write(writer)?;
hostname.write(writer)?;
port.write(writer)?;
},
}
Ok(())
}
}
impl Readable for Result<NetAddress, u8> {
fn read<R: Read>(reader: &mut R) -> Result<Result<NetAddress, u8>, DecodeError> {
let byte = <u8 as Readable>::read(reader)?;
match byte {
1 => {
Ok(Ok(NetAddress::IPv4 {
addr: Readable::read(reader)?,
port: Readable::read(reader)?,
}))
},
2 => {
Ok(Ok(NetAddress::IPv6 {
addr: Readable::read(reader)?,
port: Readable::read(reader)?,
}))
},
3 => Ok(Ok(NetAddress::OnionV2(Readable::read(reader)?))),
4 => {
Ok(Ok(NetAddress::OnionV3 {
ed25519_pubkey: Readable::read(reader)?,
checksum: Readable::read(reader)?,
version: Readable::read(reader)?,
port: Readable::read(reader)?,
}))
},
5 => {
Ok(Ok(NetAddress::Hostname {
hostname: Readable::read(reader)?,
port: Readable::read(reader)?,
}))
},
_ => return Ok(Err(byte)),
}
}
}
impl Readable for NetAddress {
fn read<R: Read>(reader: &mut R) -> Result<NetAddress, DecodeError> {
match Readable::read(reader) {
Ok(Ok(res)) => Ok(res),
Ok(Err(_)) => Err(DecodeError::UnknownVersion),
Err(e) => Err(e),
}
}
}
/// The unsigned part of a node_announcement
#[derive(Clone, Debug, PartialEq)]
pub struct UnsignedNodeAnnouncement {
/// The advertised features
pub features: NodeFeatures,
/// A strictly monotonic announcement counter, with gaps allowed
pub timestamp: u32,
/// The node_id this announcement originated from (don't rebroadcast the node_announcement back
/// to this node).
pub node_id: PublicKey,
/// An RGB color for UI purposes
pub rgb: [u8; 3],
/// An alias, for UI purposes. This should be sanitized before use. There is no guarantee
/// of uniqueness.
pub alias: [u8; 32],
/// List of addresses on which this node is reachable
pub addresses: Vec<NetAddress>,
pub(crate) excess_address_data: Vec<u8>,
pub(crate) excess_data: Vec<u8>,
}
#[derive(Clone, Debug, PartialEq)]
/// A node_announcement message to be sent or received from a peer
pub struct NodeAnnouncement {
/// The signature by the node key
pub signature: Signature,
/// The actual content of the announcement
pub contents: UnsignedNodeAnnouncement,
}
/// The unsigned part of a channel_announcement
#[derive(Clone, Debug, PartialEq)]
pub struct UnsignedChannelAnnouncement {
/// The advertised channel features
pub features: ChannelFeatures,
/// The genesis hash of the blockchain where the channel is to be opened
pub chain_hash: BlockHash,
/// The short channel ID
pub short_channel_id: u64,
/// One of the two node_ids which are endpoints of this channel
pub node_id_1: PublicKey,
/// The other of the two node_ids which are endpoints of this channel
pub node_id_2: PublicKey,
/// The funding key for the first node
pub bitcoin_key_1: PublicKey,
/// The funding key for the second node
pub bitcoin_key_2: PublicKey,
pub(crate) excess_data: Vec<u8>,
}
/// A channel_announcement message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelAnnouncement {
/// Authentication of the announcement by the first public node
pub node_signature_1: Signature,
/// Authentication of the announcement by the second public node
pub node_signature_2: Signature,
/// Proof of funding UTXO ownership by the first public node
pub bitcoin_signature_1: Signature,
/// Proof of funding UTXO ownership by the second public node
pub bitcoin_signature_2: Signature,
/// The actual announcement
pub contents: UnsignedChannelAnnouncement,
}
/// The unsigned part of a channel_update
#[derive(Clone, Debug, PartialEq)]
pub struct UnsignedChannelUpdate {
/// The genesis hash of the blockchain where the channel is to be opened
pub chain_hash: BlockHash,
/// The short channel ID
pub short_channel_id: u64,
/// A strictly monotonic announcement counter, with gaps allowed, specific to this channel
pub timestamp: u32,
/// Channel flags
pub flags: u8,
/// The number of blocks such that if:
/// `incoming_htlc.cltv_expiry < outgoing_htlc.cltv_expiry + cltv_expiry_delta`
/// then we need to fail the HTLC backwards. When forwarding an HTLC, cltv_expiry_delta determines
/// the outgoing HTLC's minimum cltv_expiry value -- so, if an incoming HTLC comes in with a
/// cltv_expiry of 100000, and the node we're forwarding to has a cltv_expiry_delta value of 10,
/// then we'll check that the outgoing HTLC's cltv_expiry value is at least 100010 before
/// forwarding. Note that the HTLC sender is the one who originally sets this value when
/// constructing the route.
pub cltv_expiry_delta: u16,
/// The minimum HTLC size incoming to sender, in milli-satoshi
pub htlc_minimum_msat: u64,
/// The maximum HTLC value incoming to sender, in milli-satoshi. Used to be optional.
pub htlc_maximum_msat: u64,
/// The base HTLC fee charged by sender, in milli-satoshi
pub fee_base_msat: u32,
/// The amount to fee multiplier, in micro-satoshi
pub fee_proportional_millionths: u32,
/// Excess data which was signed as a part of the message which we do not (yet) understand how
/// to decode. This is stored to ensure forward-compatibility as new fields are added to the
/// lightning gossip
pub excess_data: Vec<u8>,
}
/// A channel_update message to be sent or received from a peer
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelUpdate {
/// A signature of the channel update
pub signature: Signature,
/// The actual channel update
pub contents: UnsignedChannelUpdate,
}
/// A query_channel_range message is used to query a peer for channel
/// UTXOs in a range of blocks. The recipient of a query makes a best
/// effort to reply to the query using one or more reply_channel_range
/// messages.
#[derive(Clone, Debug, PartialEq)]
pub struct QueryChannelRange {
/// The genesis hash of the blockchain being queried
pub chain_hash: BlockHash,
/// The height of the first block for the channel UTXOs being queried
pub first_blocknum: u32,
/// The number of blocks to include in the query results
pub number_of_blocks: u32,
}
/// A reply_channel_range message is a reply to a query_channel_range
/// message. Multiple reply_channel_range messages can be sent in reply
/// to a single query_channel_range message. The query recipient makes a
/// best effort to respond based on their local network view which may
/// not be a perfect view of the network. The short_channel_ids in the
/// reply are encoded. We only support encoding_type=0 uncompressed
/// serialization and do not support encoding_type=1 zlib serialization.
#[derive(Clone, Debug, PartialEq)]
pub struct ReplyChannelRange {
/// The genesis hash of the blockchain being queried
pub chain_hash: BlockHash,
/// The height of the first block in the range of the reply
pub first_blocknum: u32,
/// The number of blocks included in the range of the reply
pub number_of_blocks: u32,
/// True when this is the final reply for a query
pub sync_complete: bool,
/// The short_channel_ids in the channel range
pub short_channel_ids: Vec<u64>,
}
/// A query_short_channel_ids message is used to query a peer for
/// routing gossip messages related to one or more short_channel_ids.
/// The query recipient will reply with the latest, if available,
/// channel_announcement, channel_update and node_announcement messages
/// it maintains for the requested short_channel_ids followed by a
/// reply_short_channel_ids_end message. The short_channel_ids sent in
/// this query are encoded. We only support encoding_type=0 uncompressed
/// serialization and do not support encoding_type=1 zlib serialization.
#[derive(Clone, Debug, PartialEq)]
pub struct QueryShortChannelIds {
/// The genesis hash of the blockchain being queried
pub chain_hash: BlockHash,
/// The short_channel_ids that are being queried
pub short_channel_ids: Vec<u64>,
}
/// A reply_short_channel_ids_end message is sent as a reply to a
/// query_short_channel_ids message. The query recipient makes a best
/// effort to respond based on their local network view which may not be
/// a perfect view of the network.
#[derive(Clone, Debug, PartialEq)]
pub struct ReplyShortChannelIdsEnd {
/// The genesis hash of the blockchain that was queried
pub chain_hash: BlockHash,
/// Indicates if the query recipient maintains up-to-date channel
/// information for the chain_hash
pub full_information: bool,
}
/// A gossip_timestamp_filter message is used by a node to request
/// gossip relay for messages in the requested time range when the
/// gossip_queries feature has been negotiated.
#[derive(Clone, Debug, PartialEq)]
pub struct GossipTimestampFilter {
/// The genesis hash of the blockchain for channel and node information
pub chain_hash: BlockHash,
/// The starting unix timestamp
pub first_timestamp: u32,
/// The range of information in seconds
pub timestamp_range: u32,
}
/// Encoding type for data compression of collections in gossip queries.
/// We do not support encoding_type=1 zlib serialization defined in BOLT #7.
enum EncodingType {
Uncompressed = 0x00,
}
/// Used to put an error message in a LightningError
#[derive(Clone, Debug)]
pub enum ErrorAction {
/// The peer took some action which made us think they were useless. Disconnect them.
DisconnectPeer {
/// An error message which we should make an effort to send before we disconnect.
msg: Option<ErrorMessage>
},
/// The peer did something harmless that we weren't able to process, just log and ignore
// New code should *not* use this. New code must use IgnoreAndLog, below!
IgnoreError,
/// The peer did something harmless that we weren't able to meaningfully process.
/// If the error is logged, log it at the given level.
IgnoreAndLog(logger::Level),
/// The peer provided us with a gossip message which we'd already seen. In most cases this
/// should be ignored, but it may result in the message being forwarded if it is a duplicate of
/// our own channel announcements.
IgnoreDuplicateGossip,
/// The peer did something incorrect. Tell them.
SendErrorMessage {
/// The message to send.
msg: ErrorMessage,
},
/// The peer did something incorrect. Tell them without closing any channels.
SendWarningMessage {
/// The message to send.
msg: WarningMessage,
/// The peer may have done something harmless that we weren't able to meaningfully process,
/// though we should still tell them about it.
/// If this event is logged, log it at the given level.
log_level: logger::Level,
},
}
/// An Err type for failure to process messages.
#[derive(Clone, Debug)]
pub struct LightningError {
/// A human-readable message describing the error
pub err: String,
/// The action which should be taken against the offending peer.
pub action: ErrorAction,
}
/// Struct used to return values from revoke_and_ack messages, containing a bunch of commitment
/// transaction updates if they were pending.
#[derive(Clone, Debug, PartialEq)]
pub struct CommitmentUpdate {
/// update_add_htlc messages which should be sent
pub update_add_htlcs: Vec<UpdateAddHTLC>,
/// update_fulfill_htlc messages which should be sent
pub update_fulfill_htlcs: Vec<UpdateFulfillHTLC>,
/// update_fail_htlc messages which should be sent
pub update_fail_htlcs: Vec<UpdateFailHTLC>,
/// update_fail_malformed_htlc messages which should be sent
pub update_fail_malformed_htlcs: Vec<UpdateFailMalformedHTLC>,
/// An update_fee message which should be sent
pub update_fee: Option<UpdateFee>,
/// Finally, the commitment_signed message which should be sent
pub commitment_signed: CommitmentSigned,
}
/// Messages could have optional fields to use with extended features
/// As we wish to serialize these differently from Option<T>s (Options get a tag byte, but
/// OptionalFeild simply gets Present if there are enough bytes to read into it), we have a
/// separate enum type for them.
/// (C-not exported) due to a free generic in T
#[derive(Clone, Debug, PartialEq)]
pub enum OptionalField<T> {
/// Optional field is included in message
Present(T),
/// Optional field is absent in message
Absent
}
/// A trait to describe an object which can receive channel messages.
///
/// Messages MAY be called in parallel when they originate from different their_node_ids, however
/// they MUST NOT be called in parallel when the two calls have the same their_node_id.
pub trait ChannelMessageHandler : MessageSendEventsProvider {
//Channel init:
/// Handle an incoming open_channel message from the given peer.
fn handle_open_channel(&self, their_node_id: &PublicKey, their_features: InitFeatures, msg: &OpenChannel);
/// Handle an incoming accept_channel message from the given peer.
fn handle_accept_channel(&self, their_node_id: &PublicKey, their_features: InitFeatures, msg: &AcceptChannel);
/// Handle an incoming funding_created message from the given peer.
fn handle_funding_created(&self, their_node_id: &PublicKey, msg: &FundingCreated);
/// Handle an incoming funding_signed message from the given peer.
fn handle_funding_signed(&self, their_node_id: &PublicKey, msg: &FundingSigned);
/// Handle an incoming channel_ready message from the given peer.
fn handle_channel_ready(&self, their_node_id: &PublicKey, msg: &ChannelReady);
// Channl close:
/// Handle an incoming shutdown message from the given peer.
fn handle_shutdown(&self, their_node_id: &PublicKey, their_features: &InitFeatures, msg: &Shutdown);
/// Handle an incoming closing_signed message from the given peer.
fn handle_closing_signed(&self, their_node_id: &PublicKey, msg: &ClosingSigned);
// HTLC handling:
/// Handle an incoming update_add_htlc message from the given peer.
fn handle_update_add_htlc(&self, their_node_id: &PublicKey, msg: &UpdateAddHTLC);
/// Handle an incoming update_fulfill_htlc message from the given peer.
fn handle_update_fulfill_htlc(&self, their_node_id: &PublicKey, msg: &UpdateFulfillHTLC);
/// Handle an incoming update_fail_htlc message from the given peer.
fn handle_update_fail_htlc(&self, their_node_id: &PublicKey, msg: &UpdateFailHTLC);
/// Handle an incoming update_fail_malformed_htlc message from the given peer.
fn handle_update_fail_malformed_htlc(&self, their_node_id: &PublicKey, msg: &UpdateFailMalformedHTLC);
/// Handle an incoming commitment_signed message from the given peer.
fn handle_commitment_signed(&self, their_node_id: &PublicKey, msg: &CommitmentSigned);
/// Handle an incoming revoke_and_ack message from the given peer.
fn handle_revoke_and_ack(&self, their_node_id: &PublicKey, msg: &RevokeAndACK);
/// Handle an incoming update_fee message from the given peer.
fn handle_update_fee(&self, their_node_id: &PublicKey, msg: &UpdateFee);
// Channel-to-announce:
/// Handle an incoming announcement_signatures message from the given peer.
fn handle_announcement_signatures(&self, their_node_id: &PublicKey, msg: &AnnouncementSignatures);
// Connection loss/reestablish:
/// Indicates a connection to the peer failed/an existing connection was lost. If no connection
/// is believed to be possible in the future (eg they're sending us messages we don't
/// understand or indicate they require unknown feature bits), no_connection_possible is set
/// and any outstanding channels should be failed.
fn peer_disconnected(&self, their_node_id: &PublicKey, no_connection_possible: bool);
/// Handle a peer reconnecting, possibly generating channel_reestablish message(s).
fn peer_connected(&self, their_node_id: &PublicKey, msg: &Init);
/// Handle an incoming channel_reestablish message from the given peer.
fn handle_channel_reestablish(&self, their_node_id: &PublicKey, msg: &ChannelReestablish);
/// Handle an incoming channel update from the given peer.
fn handle_channel_update(&self, their_node_id: &PublicKey, msg: &ChannelUpdate);
// Error:
/// Handle an incoming error message from the given peer.
fn handle_error(&self, their_node_id: &PublicKey, msg: &ErrorMessage);
}
/// A trait to describe an object which can receive routing messages.
///
/// # Implementor DoS Warnings
///
/// For `gossip_queries` messages there are potential DoS vectors when handling
/// inbound queries. Implementors using an on-disk network graph should be aware of
/// repeated disk I/O for queries accessing different parts of the network graph.
pub trait RoutingMessageHandler : MessageSendEventsProvider {
/// Handle an incoming node_announcement message, returning true if it should be forwarded on,
/// false or returning an Err otherwise.
fn handle_node_announcement(&self, msg: &NodeAnnouncement) -> Result<bool, LightningError>;
/// Handle a channel_announcement message, returning true if it should be forwarded on, false
/// or returning an Err otherwise.
fn handle_channel_announcement(&self, msg: &ChannelAnnouncement) -> Result<bool, LightningError>;
/// Handle an incoming channel_update message, returning true if it should be forwarded on,
/// false or returning an Err otherwise.
fn handle_channel_update(&self, msg: &ChannelUpdate) -> Result<bool, LightningError>;
/// Gets a subset of the channel announcements and updates required to dump our routing table
/// to a remote node, starting at the short_channel_id indicated by starting_point and
/// including the batch_amount entries immediately higher in numerical value than starting_point.
fn get_next_channel_announcements(&self, starting_point: u64, batch_amount: u8) -> Vec<(ChannelAnnouncement, Option<ChannelUpdate>, Option<ChannelUpdate>)>;
/// Gets a subset of the node announcements required to dump our routing table to a remote node,
/// starting at the node *after* the provided publickey and including batch_amount entries
/// immediately higher (as defined by <PublicKey as Ord>::cmp) than starting_point.
/// If None is provided for starting_point, we start at the first node.
fn get_next_node_announcements(&self, starting_point: Option<&PublicKey>, batch_amount: u8) -> Vec<NodeAnnouncement>;
/// Called when a connection is established with a peer. This can be used to
/// perform routing table synchronization using a strategy defined by the
/// implementor.
fn peer_connected(&self, their_node_id: &PublicKey, init: &Init);
/// Handles the reply of a query we initiated to learn about channels
/// for a given range of blocks. We can expect to receive one or more
/// replies to a single query.
fn handle_reply_channel_range(&self, their_node_id: &PublicKey, msg: ReplyChannelRange) -> Result<(), LightningError>;
/// Handles the reply of a query we initiated asking for routing gossip
/// messages for a list of channels. We should receive this message when
/// a node has completed its best effort to send us the pertaining routing
/// gossip messages.
fn handle_reply_short_channel_ids_end(&self, their_node_id: &PublicKey, msg: ReplyShortChannelIdsEnd) -> Result<(), LightningError>;
/// Handles when a peer asks us to send a list of short_channel_ids
/// for the requested range of blocks.
fn handle_query_channel_range(&self, their_node_id: &PublicKey, msg: QueryChannelRange) -> Result<(), LightningError>;
/// Handles when a peer asks us to send routing gossip messages for a
/// list of short_channel_ids.
fn handle_query_short_channel_ids(&self, their_node_id: &PublicKey, msg: QueryShortChannelIds) -> Result<(), LightningError>;
}
mod fuzzy_internal_msgs {
use prelude::*;
use ln::{PaymentPreimage, PaymentSecret};
// These types aren't intended to be pub, but are exposed for direct fuzzing (as we deserialize
// them from untrusted input):
#[derive(Clone)]
pub(crate) struct FinalOnionHopData {
pub(crate) payment_secret: PaymentSecret,
/// The total value, in msat, of the payment as received by the ultimate recipient.
/// Message serialization may panic if this value is more than 21 million Bitcoin.
pub(crate) total_msat: u64,
}
pub(crate) enum OnionHopDataFormat {
Legacy { // aka Realm-0
short_channel_id: u64,
},
NonFinalNode {
short_channel_id: u64,
},
FinalNode {
payment_data: Option<FinalOnionHopData>,
keysend_preimage: Option<PaymentPreimage>,
},
}
pub struct OnionHopData {
pub(crate) format: OnionHopDataFormat,
/// The value, in msat, of the payment after this hop's fee is deducted.
/// Message serialization may panic if this value is more than 21 million Bitcoin.
pub(crate) amt_to_forward: u64,
pub(crate) outgoing_cltv_value: u32,
// 12 bytes of 0-padding for Legacy format
}
pub struct DecodedOnionErrorPacket {
pub(crate) hmac: [u8; 32],
pub(crate) failuremsg: Vec<u8>,
pub(crate) pad: Vec<u8>,
}
}
#[cfg(fuzzing)]
pub use self::fuzzy_internal_msgs::*;
#[cfg(not(fuzzing))]
pub(crate) use self::fuzzy_internal_msgs::*;
#[derive(Clone)]
pub(crate) struct OnionPacket {
pub(crate) version: u8,
/// In order to ensure we always return an error on Onion decode in compliance with BOLT 4, we
/// have to deserialize OnionPackets contained in UpdateAddHTLCs even if the ephemeral public
/// key (here) is bogus, so we hold a Result instead of a PublicKey as we'd like.
pub(crate) public_key: Result<PublicKey, secp256k1::Error>,
pub(crate) hop_data: [u8; 20*65],
pub(crate) hmac: [u8; 32],
}
impl PartialEq for OnionPacket {
fn eq(&self, other: &OnionPacket) -> bool {
for (i, j) in self.hop_data.iter().zip(other.hop_data.iter()) {
if i != j { return false; }
}