]> git.bitcoin.ninja Git - rust-lightning/blob - lightning/src/util/events.rs
Merge pull request #641 from jkczyz/2020-06-deterministic-test-logging
[rust-lightning] / lightning / src / util / events.rs
1 //! Events are returned from various bits in the library which indicate some action must be taken
2 //! by the client.
3 //!
4 //! Because we don't have a built-in runtime, it's up to the client to call events at a time in the
5 //! future, as well as generate and broadcast funding transactions handle payment preimages and a
6 //! few other things.
7
8 use ln::msgs;
9 use ln::channelmanager::{PaymentPreimage, PaymentHash, PaymentSecret};
10 use chain::transaction::OutPoint;
11 use chain::keysinterface::SpendableOutputDescriptor;
12 use util::ser::{Writeable, Writer, MaybeReadable, Readable};
13
14 use bitcoin::blockdata::script::Script;
15
16 use bitcoin::secp256k1::key::PublicKey;
17
18 use std::time::Duration;
19
20 /// An Event which you should probably take some action in response to.
21 ///
22 /// Note that while Writeable and Readable are implemented for Event, you probably shouldn't use
23 /// them directly as they don't round-trip exactly (for example FundingGenerationReady is never
24 /// written as it makes no sense to respond to it after reconnecting to peers).
25 pub enum Event {
26         /// Used to indicate that the client should generate a funding transaction with the given
27         /// parameters and then call ChannelManager::funding_transaction_generated.
28         /// Generated in ChannelManager message handling.
29         /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your
30         /// counterparty can steal your funds!
31         FundingGenerationReady {
32                 /// The random channel_id we picked which you'll need to pass into
33                 /// ChannelManager::funding_transaction_generated.
34                 temporary_channel_id: [u8; 32],
35                 /// The value, in satoshis, that the output should have.
36                 channel_value_satoshis: u64,
37                 /// The script which should be used in the transaction output.
38                 output_script: Script,
39                 /// The value passed in to ChannelManager::create_channel
40                 user_channel_id: u64,
41         },
42         /// Used to indicate that the client may now broadcast the funding transaction it created for a
43         /// channel. Broadcasting such a transaction prior to this event may lead to our counterparty
44         /// trivially stealing all funds in the funding transaction!
45         FundingBroadcastSafe {
46                 /// The output, which was passed to ChannelManager::funding_transaction_generated, which is
47                 /// now safe to broadcast.
48                 funding_txo: OutPoint,
49                 /// The value passed in to ChannelManager::create_channel
50                 user_channel_id: u64,
51         },
52         /// Indicates we've received money! Just gotta dig out that payment preimage and feed it to
53         /// ChannelManager::claim_funds to get it....
54         /// Note that if the preimage is not known or the amount paid is incorrect, you should call
55         /// ChannelManager::fail_htlc_backwards to free up resources for this HTLC and avoid
56         /// network congestion.
57         /// The amount paid should be considered 'incorrect' when it is less than or more than twice
58         /// the amount expected.
59         /// If you fail to call either ChannelManager::claim_funds or
60         /// ChannelManager::fail_htlc_backwards within the HTLC's timeout, the HTLC will be
61         /// automatically failed.
62         PaymentReceived {
63                 /// The hash for which the preimage should be handed to the ChannelManager.
64                 payment_hash: PaymentHash,
65                 /// The "payment secret". This authenticates the sender to the recipient, preventing a
66                 /// number of deanonymization attacks during the routing process.
67                 /// As nodes upgrade, the invoices you provide should likely migrate to setting the
68                 /// payment_secret feature to required, at which point you should fail_backwards any HTLCs
69                 /// which have a None here.
70                 /// Until then, however, values of None should be ignored, and only incorrect Some values
71                 /// should result in an HTLC fail_backwards.
72                 /// Note that, in any case, this value must be passed as-is to any fail or claim calls as
73                 /// the HTLC index includes this value.
74                 payment_secret: Option<PaymentSecret>,
75                 /// The value, in thousandths of a satoshi, that this payment is for. Note that you must
76                 /// compare this to the expected value before accepting the payment (as otherwise you are
77                 /// providing proof-of-payment for less than the value you expected!).
78                 amt: u64,
79         },
80         /// Indicates an outbound payment we made succeeded (ie it made it all the way to its target
81         /// and we got back the payment preimage for it).
82         /// Note that duplicative PaymentSent Events may be generated - it is your responsibility to
83         /// deduplicate them by payment_preimage (which MUST be unique)!
84         PaymentSent {
85                 /// The preimage to the hash given to ChannelManager::send_payment.
86                 /// Note that this serves as a payment receipt, if you wish to have such a thing, you must
87                 /// store it somehow!
88                 payment_preimage: PaymentPreimage,
89         },
90         /// Indicates an outbound payment we made failed. Probably some intermediary node dropped
91         /// something. You may wish to retry with a different route.
92         /// Note that duplicative PaymentFailed Events may be generated - it is your responsibility to
93         /// deduplicate them by payment_hash (which MUST be unique)!
94         PaymentFailed {
95                 /// The hash which was given to ChannelManager::send_payment.
96                 payment_hash: PaymentHash,
97                 /// Indicates the payment was rejected for some reason by the recipient. This implies that
98                 /// the payment has failed, not just the route in question. If this is not set, you may
99                 /// retry the payment via a different route.
100                 rejected_by_dest: bool,
101 #[cfg(test)]
102                 error_code: Option<u16>,
103 #[cfg(test)]
104                 error_data: Option<Vec<u8>>,
105         },
106         /// Used to indicate that ChannelManager::process_pending_htlc_forwards should be called at a
107         /// time in the future.
108         PendingHTLCsForwardable {
109                 /// The minimum amount of time that should be waited prior to calling
110                 /// process_pending_htlc_forwards. To increase the effort required to correlate payments,
111                 /// you should wait a random amount of time in roughly the range (now + time_forwardable,
112                 /// now + 5*time_forwardable).
113                 time_forwardable: Duration,
114         },
115         /// Used to indicate that an output was generated on-chain which you should know how to spend.
116         /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
117         /// counterparty spending them due to some kind of timeout. Thus, you need to store them
118         /// somewhere and spend them when you create on-chain transactions.
119         SpendableOutputs {
120                 /// The outputs which you should store as spendable by you.
121                 outputs: Vec<SpendableOutputDescriptor>,
122         },
123 }
124
125 impl Writeable for Event {
126         fn write<W: Writer>(&self, writer: &mut W) -> Result<(), ::std::io::Error> {
127                 match self {
128                         &Event::FundingGenerationReady { .. } => {
129                                 0u8.write(writer)?;
130                                 // We never write out FundingGenerationReady events as, upon disconnection, peers
131                                 // drop any channels which have not yet exchanged funding_signed.
132                         },
133                         &Event::FundingBroadcastSafe { ref funding_txo, ref user_channel_id } => {
134                                 1u8.write(writer)?;
135                                 funding_txo.write(writer)?;
136                                 user_channel_id.write(writer)?;
137                         },
138                         &Event::PaymentReceived { ref payment_hash, ref payment_secret, ref amt } => {
139                                 2u8.write(writer)?;
140                                 payment_hash.write(writer)?;
141                                 payment_secret.write(writer)?;
142                                 amt.write(writer)?;
143                         },
144                         &Event::PaymentSent { ref payment_preimage } => {
145                                 3u8.write(writer)?;
146                                 payment_preimage.write(writer)?;
147                         },
148                         &Event::PaymentFailed { ref payment_hash, ref rejected_by_dest,
149                                 #[cfg(test)]
150                                 ref error_code,
151                                 #[cfg(test)]
152                                 ref error_data,
153                         } => {
154                                 4u8.write(writer)?;
155                                 payment_hash.write(writer)?;
156                                 rejected_by_dest.write(writer)?;
157                                 #[cfg(test)]
158                                 error_code.write(writer)?;
159                                 #[cfg(test)]
160                                 error_data.write(writer)?;
161                         },
162                         &Event::PendingHTLCsForwardable { time_forwardable: _ } => {
163                                 5u8.write(writer)?;
164                                 // We don't write the time_fordwardable out at all, as we presume when the user
165                                 // deserializes us at least that much time has elapsed.
166                         },
167                         &Event::SpendableOutputs { ref outputs } => {
168                                 6u8.write(writer)?;
169                                 (outputs.len() as u64).write(writer)?;
170                                 for output in outputs.iter() {
171                                         output.write(writer)?;
172                                 }
173                         },
174                 }
175                 Ok(())
176         }
177 }
178 impl MaybeReadable for Event {
179         fn read<R: ::std::io::Read>(reader: &mut R) -> Result<Option<Self>, msgs::DecodeError> {
180                 match Readable::read(reader)? {
181                         0u8 => Ok(None),
182                         1u8 => Ok(Some(Event::FundingBroadcastSafe {
183                                         funding_txo: Readable::read(reader)?,
184                                         user_channel_id: Readable::read(reader)?,
185                                 })),
186                         2u8 => Ok(Some(Event::PaymentReceived {
187                                         payment_hash: Readable::read(reader)?,
188                                         payment_secret: Readable::read(reader)?,
189                                         amt: Readable::read(reader)?,
190                                 })),
191                         3u8 => Ok(Some(Event::PaymentSent {
192                                         payment_preimage: Readable::read(reader)?,
193                                 })),
194                         4u8 => Ok(Some(Event::PaymentFailed {
195                                         payment_hash: Readable::read(reader)?,
196                                         rejected_by_dest: Readable::read(reader)?,
197                                         #[cfg(test)]
198                                         error_code: Readable::read(reader)?,
199                                         #[cfg(test)]
200                                         error_data: Readable::read(reader)?,
201                                 })),
202                         5u8 => Ok(Some(Event::PendingHTLCsForwardable {
203                                         time_forwardable: Duration::from_secs(0)
204                                 })),
205                         6u8 => {
206                                 let outputs_len: u64 = Readable::read(reader)?;
207                                 let mut outputs = Vec::new();
208                                 for _ in 0..outputs_len {
209                                         outputs.push(Readable::read(reader)?);
210                                 }
211                                 Ok(Some(Event::SpendableOutputs { outputs }))
212                         },
213                         _ => Err(msgs::DecodeError::InvalidValue)
214                 }
215         }
216 }
217
218 /// An event generated by ChannelManager which indicates a message should be sent to a peer (or
219 /// broadcast to most peers).
220 /// These events are handled by PeerManager::process_events if you are using a PeerManager.
221 #[derive(Clone)]
222 pub enum MessageSendEvent {
223         /// Used to indicate that we've accepted a channel open and should send the accept_channel
224         /// message provided to the given peer.
225         SendAcceptChannel {
226                 /// The node_id of the node which should receive this message
227                 node_id: PublicKey,
228                 /// The message which should be sent.
229                 msg: msgs::AcceptChannel,
230         },
231         /// Used to indicate that we've initiated a channel open and should send the open_channel
232         /// message provided to the given peer.
233         SendOpenChannel {
234                 /// The node_id of the node which should receive this message
235                 node_id: PublicKey,
236                 /// The message which should be sent.
237                 msg: msgs::OpenChannel,
238         },
239         /// Used to indicate that a funding_created message should be sent to the peer with the given node_id.
240         SendFundingCreated {
241                 /// The node_id of the node which should receive this message
242                 node_id: PublicKey,
243                 /// The message which should be sent.
244                 msg: msgs::FundingCreated,
245         },
246         /// Used to indicate that a funding_signed message should be sent to the peer with the given node_id.
247         SendFundingSigned {
248                 /// The node_id of the node which should receive this message
249                 node_id: PublicKey,
250                 /// The message which should be sent.
251                 msg: msgs::FundingSigned,
252         },
253         /// Used to indicate that a funding_locked message should be sent to the peer with the given node_id.
254         SendFundingLocked {
255                 /// The node_id of the node which should receive these message(s)
256                 node_id: PublicKey,
257                 /// The funding_locked message which should be sent.
258                 msg: msgs::FundingLocked,
259         },
260         /// Used to indicate that an announcement_signatures message should be sent to the peer with the given node_id.
261         SendAnnouncementSignatures {
262                 /// The node_id of the node which should receive these message(s)
263                 node_id: PublicKey,
264                 /// The announcement_signatures message which should be sent.
265                 msg: msgs::AnnouncementSignatures,
266         },
267         /// Used to indicate that a series of HTLC update messages, as well as a commitment_signed
268         /// message should be sent to the peer with the given node_id.
269         UpdateHTLCs {
270                 /// The node_id of the node which should receive these message(s)
271                 node_id: PublicKey,
272                 /// The update messages which should be sent. ALL messages in the struct should be sent!
273                 updates: msgs::CommitmentUpdate,
274         },
275         /// Used to indicate that a revoke_and_ack message should be sent to the peer with the given node_id.
276         SendRevokeAndACK {
277                 /// The node_id of the node which should receive this message
278                 node_id: PublicKey,
279                 /// The message which should be sent.
280                 msg: msgs::RevokeAndACK,
281         },
282         /// Used to indicate that a closing_signed message should be sent to the peer with the given node_id.
283         SendClosingSigned {
284                 /// The node_id of the node which should receive this message
285                 node_id: PublicKey,
286                 /// The message which should be sent.
287                 msg: msgs::ClosingSigned,
288         },
289         /// Used to indicate that a shutdown message should be sent to the peer with the given node_id.
290         SendShutdown {
291                 /// The node_id of the node which should receive this message
292                 node_id: PublicKey,
293                 /// The message which should be sent.
294                 msg: msgs::Shutdown,
295         },
296         /// Used to indicate that a channel_reestablish message should be sent to the peer with the given node_id.
297         SendChannelReestablish {
298                 /// The node_id of the node which should receive this message
299                 node_id: PublicKey,
300                 /// The message which should be sent.
301                 msg: msgs::ChannelReestablish,
302         },
303         /// Used to indicate that a channel_announcement and channel_update should be broadcast to all
304         /// peers (except the peer with node_id either msg.contents.node_id_1 or msg.contents.node_id_2).
305         ///
306         /// Note that after doing so, you very likely (unless you did so very recently) want to call
307         /// ChannelManager::broadcast_node_announcement to trigger a BroadcastNodeAnnouncement event.
308         /// This ensures that any nodes which see our channel_announcement also have a relevant
309         /// node_announcement, including relevant feature flags which may be important for routing
310         /// through or to us.
311         BroadcastChannelAnnouncement {
312                 /// The channel_announcement which should be sent.
313                 msg: msgs::ChannelAnnouncement,
314                 /// The followup channel_update which should be sent.
315                 update_msg: msgs::ChannelUpdate,
316         },
317         /// Used to indicate that a node_announcement should be broadcast to all peers.
318         BroadcastNodeAnnouncement {
319                 /// The node_announcement which should be sent.
320                 msg: msgs::NodeAnnouncement,
321         },
322         /// Used to indicate that a channel_update should be broadcast to all peers.
323         BroadcastChannelUpdate {
324                 /// The channel_update which should be sent.
325                 msg: msgs::ChannelUpdate,
326         },
327         /// Broadcast an error downstream to be handled
328         HandleError {
329                 /// The node_id of the node which should receive this message
330                 node_id: PublicKey,
331                 /// The action which should be taken.
332                 action: msgs::ErrorAction
333         },
334         /// When a payment fails we may receive updates back from the hop where it failed. In such
335         /// cases this event is generated so that we can inform the network graph of this information.
336         PaymentFailureNetworkUpdate {
337                 /// The channel/node update which should be sent to NetGraphMsgHandler
338                 update: msgs::HTLCFailChannelUpdate,
339         }
340 }
341
342 /// A trait indicating an object may generate message send events
343 pub trait MessageSendEventsProvider {
344         /// Gets the list of pending events which were generated by previous actions, clearing the list
345         /// in the process.
346         fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
347 }
348
349 /// A trait indicating an object may generate events
350 pub trait EventsProvider {
351         /// Gets the list of pending events which were generated by previous actions, clearing the list
352         /// in the process.
353         fn get_and_clear_pending_events(&self) -> Vec<Event>;
354 }