@@ -439,15 +439,6 @@ const CHECK_CLTV_EXPIRY_SANITY: u32 = CLTV_EXPIRY_DELTA as u32 - LATENCY_GRACE_P
439
439
#[ allow( dead_code) ]
440
440
const CHECK_CLTV_EXPIRY_SANITY_2 : u32 = CLTV_EXPIRY_DELTA as u32 - LATENCY_GRACE_PERIOD_BLOCKS - 2 * CLTV_CLAIM_BUFFER ;
441
441
442
- macro_rules! secp_call {
443
- ( $res: expr, $err: expr ) => {
444
- match $res {
445
- Ok ( key) => key,
446
- Err ( _) => return Err ( $err) ,
447
- }
448
- } ;
449
- }
450
-
451
442
/// Details of a channel, as returned by ChannelManager::list_channels and ChannelManager::list_usable_channels
452
443
pub struct ChannelDetails {
453
444
/// The channel's ID (prior to funding transaction generation, this is a random 32 bytes,
@@ -484,6 +475,32 @@ pub struct ChannelDetails {
484
475
pub is_live : bool ,
485
476
}
486
477
478
+ /// If a payment fails to send, it can be in one of several states. This enum is returned as the
479
+ /// Err() type describing which state the payment is in, see the description of individual enum
480
+ /// states for more.
481
+ #[ derive( Debug ) ]
482
+ pub enum PaymentSendFailure {
483
+ /// A parameter which was passed to send_payment was invalid, preventing us from attempting to
484
+ /// send the payment at all. No channel state has been changed or messages sent to peers, and
485
+ /// once you've changed the parameter at error, you can freely retry the payment in full.
486
+ ParameterError ( APIError ) ,
487
+ /// All paths which were attempted failed to send, with no channel state change taking place.
488
+ /// You can freely retry the payment in full (though you probably want to do so over different
489
+ /// paths than the ones selected).
490
+ AllFailedRetrySafe ( Vec < APIError > ) ,
491
+ /// Some paths which were attempted failed to send, though possibly not all. At least some
492
+ /// paths have irrevocably committed to the HTLC and retrying the payment in full would result
493
+ /// in over-/re-payment.
494
+ ///
495
+ /// The results here are ordered the same as the paths in the route object which was passed to
496
+ /// send_payment, and any Errs which are not APIError::MonitorUpdateFailed can be safely
497
+ /// retried.
498
+ ///
499
+ /// Any entries which contain Err(APIError::MonitorUpdateFailed) or Ok(()) MUST NOT be retried
500
+ /// as they will result in over-/re-payment.
501
+ PartialFailure ( Vec < Result < ( ) , APIError > > ) ,
502
+ }
503
+
487
504
macro_rules! handle_error {
488
505
( $self: ident, $internal: expr, $their_node_id: expr, $locked_channel_state: expr) => {
489
506
match $internal {
@@ -1180,109 +1197,154 @@ impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref> ChannelMan
1180
1197
/// payment_preimage tracking (which you should already be doing as they represent "proof of
1181
1198
/// payment") and prevent double-sends yourself.
1182
1199
///
1183
- /// May generate a SendHTLCs message event on success, which should be relayed.
1200
+ /// May generate SendHTLCs message(s) event on success, which should be relayed.
1201
+ ///
1202
+ /// Each path may have a different return value, and PaymentSendValue may return a Vec with
1203
+ /// each entry matching the corresponding-index entry in the route paths.
1184
1204
///
1185
- /// Raises APIError::RoutError when invalid route or forward parameter
1186
- /// (cltv_delta, fee, node public key) is specified.
1187
- /// Raises APIError::ChannelUnavailable if the next-hop channel is not available for updates
1188
- /// (including due to previous monitor update failure or new permanent monitor update failure).
1189
- /// Raised APIError::MonitorUpdateFailed if a new monitor update failure prevented sending the
1190
- /// relevant updates.
1205
+ /// In general, a path may raise:
1206
+ /// * APIError::RouteError when an invalid route or forwarding parameter (cltv_delta, fee,
1207
+ /// node public key) is specified.
1208
+ /// * APIError::ChannelUnavailable if the next-hop channel is not available for updates
1209
+ /// (including due to previous monitor update failure or new permanent monitor update
1210
+ /// failure).
1211
+ /// * APIError::MonitorUpdateFailed if a new monitor update failure prevented sending the
1212
+ /// relevant updates.
1191
1213
///
1192
- /// In case of APIError::RouteError/APIError::ChannelUnavailable, the payment send has failed
1193
- /// and you may wish to retry via a different route immediately.
1194
- /// In case of APIError::MonitorUpdateFailed, the commitment update has been irrevocably
1195
- /// committed on our end and we're just waiting for a monitor update to send it. Do NOT retry
1196
- /// the payment via a different route unless you intend to pay twice!
1214
+ /// Note that depending on the type of the PaymentSendFailure the HTLC may have been
1215
+ /// irrevocably committed to on our end. In such a case, do NOT retry the payment with a
1216
+ /// different route unless you intend to pay twice!
1197
1217
///
1198
1218
/// payment_secret is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate
1199
1219
/// the sender to the recipient and prevent payment-probing (deanonymization) attacks. For
1200
1220
/// newer nodes, it will be provided to you in the invoice. If you do not have one, the Route
1201
1221
/// must not contain multiple paths as otherwise the multipath data cannot be sent.
1202
1222
/// If a payment_secret *is* provided, we assume that the invoice had the basic_mpp feature bit
1203
1223
/// set (either as required or as available).
1204
- pub fn send_payment ( & self , route : Route , payment_hash : PaymentHash , payment_secret : Option < & [ u8 ; 32 ] > ) -> Result < ( ) , APIError > {
1205
- if route. paths . len ( ) < 1 || route . paths . len ( ) > 1 {
1206
- return Err ( APIError :: RouteError { err : "We currently don't support MPP, and we need at least one path" } ) ;
1224
+ pub fn send_payment ( & self , route : Route , payment_hash : PaymentHash , payment_secret : Option < & [ u8 ; 32 ] > ) -> Result < ( ) , PaymentSendFailure > {
1225
+ if route. paths . len ( ) < 1 {
1226
+ return Err ( PaymentSendFailure :: ParameterError ( APIError :: RouteError { err : "There must be at least one path to send over" } ) ) ;
1207
1227
}
1208
- if route. paths [ 0 ] . len ( ) < 1 || route . paths [ 0 ] . len ( ) > 20 {
1209
- return Err ( APIError :: RouteError { err : "Path didn't go anywhere/had bogus size" } ) ;
1228
+ if route. paths . len ( ) > 10 {
1229
+ return Err ( PaymentSendFailure :: ParameterError ( APIError :: RouteError { err : "Sending over more than 10 paths is not currently supported" } ) ) ;
1210
1230
}
1231
+ let mut total_value = 0 ;
1211
1232
let our_node_id = self . get_our_node_id ( ) ;
1212
- for ( idx, hop) in route. paths [ 0 ] . iter ( ) . enumerate ( ) {
1213
- if idx != route. paths [ 0 ] . len ( ) - 1 && hop. pubkey == our_node_id {
1214
- return Err ( APIError :: RouteError { err : "Path went through us but wasn't a simple rebalance loop to us" } ) ;
1233
+ for path in route. paths . iter ( ) {
1234
+ if path. len ( ) < 1 || path. len ( ) > 20 {
1235
+ return Err ( PaymentSendFailure :: ParameterError ( APIError :: RouteError { err : "Path didn't go anywhere/had bogus size" } ) ) ;
1236
+ }
1237
+ for ( idx, hop) in path. iter ( ) . enumerate ( ) {
1238
+ if idx != path. len ( ) - 1 && hop. pubkey == our_node_id {
1239
+ return Err ( PaymentSendFailure :: ParameterError ( APIError :: RouteError { err : "Path went through us but wasn't a simple rebalance loop to us" } ) ) ;
1240
+ }
1215
1241
}
1242
+ total_value += path. last ( ) . unwrap ( ) . fee_msat ;
1216
1243
}
1217
-
1218
- let ( session_priv, prng_seed) = self . keys_manager . get_onion_rand ( ) ;
1219
-
1220
1244
let cur_height = self . latest_block_height . load ( Ordering :: Acquire ) as u32 + 1 ;
1245
+ let mut results = Vec :: new ( ) ;
1246
+ ' path_loop: for path in route. paths . iter ( ) {
1247
+ macro_rules! check_res_push {
1248
+ ( $res: expr) => { match $res {
1249
+ Ok ( r) => r,
1250
+ Err ( e) => {
1251
+ results. push( Err ( e) ) ;
1252
+ continue ' path_loop;
1253
+ } ,
1254
+ }
1255
+ }
1256
+ }
1221
1257
1222
- let onion_keys = secp_call ! ( onion_utils:: construct_onion_keys( & self . secp_ctx, & route. paths[ 0 ] , & session_priv) ,
1223
- APIError :: RouteError { err: "Pubkey along hop was maliciously selected" } ) ;
1224
- let ( onion_payloads, htlc_msat, htlc_cltv) = onion_utils:: build_onion_payloads ( & route. paths [ 0 ] , payment_secret, cur_height) ?;
1225
- if onion_utils:: route_size_insane ( & onion_payloads) {
1226
- return Err ( APIError :: RouteError { err : "Route size too large considering onion data" } ) ;
1227
- }
1228
- let onion_packet = onion_utils:: construct_onion_packet ( onion_payloads, onion_keys, prng_seed, & payment_hash) ;
1258
+ log_trace ! ( self , "Attempting to send payment for path with next hop {}" , path. first( ) . unwrap( ) . short_channel_id) ;
1259
+ let ( session_priv, prng_seed) = self . keys_manager . get_onion_rand ( ) ;
1229
1260
1230
- let _ = self . total_consistency_lock . read ( ) . unwrap ( ) ;
1261
+ let onion_keys = check_res_push ! ( onion_utils:: construct_onion_keys( & self . secp_ctx, & path, & session_priv)
1262
+ . map_err( |_| APIError :: RouteError { err: "Pubkey along hop was maliciously selected" } ) ) ;
1263
+ let ( onion_payloads, htlc_msat, htlc_cltv) = check_res_push ! ( onion_utils:: build_onion_payloads( & path, total_value, payment_secret, cur_height) ) ;
1264
+ if onion_utils:: route_size_insane ( & onion_payloads) {
1265
+ check_res_push ! ( Err ( APIError :: RouteError { err: "Route size too large considering onion data" } ) ) ;
1266
+ }
1267
+ let onion_packet = onion_utils:: construct_onion_packet ( onion_payloads, onion_keys, prng_seed, & payment_hash) ;
1231
1268
1232
- let mut channel_lock = self . channel_state . lock ( ) . unwrap ( ) ;
1233
- let err: Result < ( ) , _ > = loop {
1269
+ let _ = self . total_consistency_lock . read ( ) . unwrap ( ) ;
1234
1270
1235
- let id = match channel_lock. short_to_id . get ( & route. paths [ 0 ] . first ( ) . unwrap ( ) . short_channel_id ) {
1236
- None => return Err ( APIError :: ChannelUnavailable { err : "No channel available with first hop!" } ) ,
1237
- Some ( id) => id. clone ( ) ,
1238
- } ;
1271
+ let mut channel_lock = self . channel_state . lock ( ) . unwrap ( ) ;
1272
+ let err: Result < ( ) , _ > = loop {
1273
+ let id = match channel_lock. short_to_id . get ( & path. first ( ) . unwrap ( ) . short_channel_id ) {
1274
+ None => check_res_push ! ( Err ( APIError :: ChannelUnavailable { err: "No channel available with first hop!" } ) ) ,
1275
+ Some ( id) => id. clone ( ) ,
1276
+ } ;
1239
1277
1240
- let channel_state = & mut * channel_lock;
1241
- if let hash_map:: Entry :: Occupied ( mut chan) = channel_state. by_id . entry ( id) {
1242
- match {
1243
- if chan. get ( ) . get_their_node_id ( ) != route. paths [ 0 ] . first ( ) . unwrap ( ) . pubkey {
1244
- return Err ( APIError :: RouteError { err : "Node ID mismatch on first hop!" } ) ;
1245
- }
1246
- if !chan. get ( ) . is_live ( ) {
1247
- return Err ( APIError :: ChannelUnavailable { err : "Peer for first hop currently disconnected/pending monitor update!" } ) ;
1248
- }
1249
- break_chan_entry ! ( self , chan. get_mut( ) . send_htlc_and_commit( htlc_msat, payment_hash. clone( ) , htlc_cltv, HTLCSource :: OutboundRoute {
1250
- path: route. paths[ 0 ] . clone( ) ,
1251
- session_priv: session_priv. clone( ) ,
1252
- first_hop_htlc_msat: htlc_msat,
1253
- } , onion_packet) , channel_state, chan)
1254
- } {
1255
- Some ( ( update_add, commitment_signed, monitor_update) ) => {
1256
- if let Err ( e) = self . monitor . update_monitor ( chan. get ( ) . get_funding_txo ( ) . unwrap ( ) , monitor_update) {
1257
- maybe_break_monitor_err ! ( self , e, channel_state, chan, RAACommitmentOrder :: CommitmentFirst , false , true ) ;
1258
- // Note that MonitorUpdateFailed here indicates (per function docs)
1259
- // that we will resent the commitment update once we unfree monitor
1260
- // updating, so we have to take special care that we don't return
1261
- // something else in case we will resend later!
1262
- return Err ( APIError :: MonitorUpdateFailed ) ;
1278
+ let channel_state = & mut * channel_lock;
1279
+ if let hash_map:: Entry :: Occupied ( mut chan) = channel_state. by_id . entry ( id) {
1280
+ match {
1281
+ if chan. get ( ) . get_their_node_id ( ) != path. first ( ) . unwrap ( ) . pubkey {
1282
+ check_res_push ! ( Err ( APIError :: RouteError { err: "Node ID mismatch on first hop!" } ) ) ;
1283
+ }
1284
+ if !chan. get ( ) . is_live ( ) {
1285
+ check_res_push ! ( Err ( APIError :: ChannelUnavailable { err: "Peer for first hop currently disconnected/pending monitor update!" } ) ) ;
1263
1286
}
1287
+ break_chan_entry ! ( self , chan. get_mut( ) . send_htlc_and_commit( htlc_msat, payment_hash. clone( ) , htlc_cltv, HTLCSource :: OutboundRoute {
1288
+ path: path. clone( ) ,
1289
+ session_priv: session_priv. clone( ) ,
1290
+ first_hop_htlc_msat: htlc_msat,
1291
+ } , onion_packet) , channel_state, chan)
1292
+ } {
1293
+ Some ( ( update_add, commitment_signed, monitor_update) ) => {
1294
+ if let Err ( e) = self . monitor . update_monitor ( chan. get ( ) . get_funding_txo ( ) . unwrap ( ) , monitor_update) {
1295
+ maybe_break_monitor_err ! ( self , e, channel_state, chan, RAACommitmentOrder :: CommitmentFirst , false , true ) ;
1296
+ // Note that MonitorUpdateFailed here indicates (per function docs)
1297
+ // that we will resent the commitment update once we unfree monitor
1298
+ // updating, so we have to take special care that we don't return
1299
+ // something else in case we will resend later!
1300
+ check_res_push ! ( Err ( APIError :: MonitorUpdateFailed ) ) ;
1301
+ }
1264
1302
1265
- channel_state. pending_msg_events . push ( events:: MessageSendEvent :: UpdateHTLCs {
1266
- node_id : route. paths [ 0 ] . first ( ) . unwrap ( ) . pubkey ,
1267
- updates : msgs:: CommitmentUpdate {
1268
- update_add_htlcs : vec ! [ update_add] ,
1269
- update_fulfill_htlcs : Vec :: new ( ) ,
1270
- update_fail_htlcs : Vec :: new ( ) ,
1271
- update_fail_malformed_htlcs : Vec :: new ( ) ,
1272
- update_fee : None ,
1273
- commitment_signed,
1274
- } ,
1275
- } ) ;
1276
- } ,
1277
- None => { } ,
1278
- }
1279
- } else { unreachable ! ( ) ; }
1280
- return Ok ( ( ) ) ;
1281
- } ;
1303
+ channel_state. pending_msg_events . push ( events:: MessageSendEvent :: UpdateHTLCs {
1304
+ node_id : path. first ( ) . unwrap ( ) . pubkey ,
1305
+ updates : msgs:: CommitmentUpdate {
1306
+ update_add_htlcs : vec ! [ update_add] ,
1307
+ update_fulfill_htlcs : Vec :: new ( ) ,
1308
+ update_fail_htlcs : Vec :: new ( ) ,
1309
+ update_fail_malformed_htlcs : Vec :: new ( ) ,
1310
+ update_fee : None ,
1311
+ commitment_signed,
1312
+ } ,
1313
+ } ) ;
1314
+ } ,
1315
+ None => { } ,
1316
+ }
1317
+ } else { unreachable ! ( ) ; }
1318
+ results. push ( Ok ( ( ) ) ) ;
1319
+ continue ' path_loop;
1320
+ } ;
1282
1321
1283
- match handle_error ! ( self , err, route. paths[ 0 ] . first( ) . unwrap( ) . pubkey, channel_lock) {
1284
- Ok ( _) => unreachable ! ( ) ,
1285
- Err ( e) => { Err ( APIError :: ChannelUnavailable { err : e. err } ) }
1322
+ match handle_error ! ( self , err, path. first( ) . unwrap( ) . pubkey, channel_lock) {
1323
+ Ok ( _) => unreachable ! ( ) ,
1324
+ Err ( e) => {
1325
+ check_res_push ! ( Err ( APIError :: ChannelUnavailable { err: e. err } ) ) ;
1326
+ } ,
1327
+ }
1328
+ }
1329
+ let mut has_ok = false ;
1330
+ let mut has_err = false ;
1331
+ for res in results. iter ( ) {
1332
+ if res. is_ok ( ) { has_ok = true ; }
1333
+ if res. is_err ( ) { has_err = true ; }
1334
+ if let & Err ( APIError :: MonitorUpdateFailed ) = res {
1335
+ // MonitorUpdateFailed is inherently unsafe to retry, so we call it a
1336
+ // PartialFailure.
1337
+ has_err = true ;
1338
+ has_ok = true ;
1339
+ break ;
1340
+ }
1341
+ }
1342
+ if has_err && has_ok {
1343
+ Err ( PaymentSendFailure :: PartialFailure ( results) )
1344
+ } else if has_err {
1345
+ Err ( PaymentSendFailure :: AllFailedRetrySafe ( results. drain ( ..) . map ( |r| r. unwrap_err ( ) ) . collect ( ) ) )
1346
+ } else {
1347
+ Ok ( ( ) )
1286
1348
}
1287
1349
}
1288
1350
0 commit comments