@@ -535,6 +535,59 @@ impl_writeable_tlv_based_enum_upgradable!(ChannelMonitorUpdateStep,
535
535
} ,
536
536
) ;
537
537
538
+ /// Details about the balance(s) available for spending once the channel appears on chain.
539
+ ///
540
+ /// See [`ChannelMonitor::get_claimable_balances`] for more details on when these will or will not
541
+ /// be provided.
542
+ #[ derive( Clone , Debug , PartialEq , Eq ) ]
543
+ #[ cfg_attr( test, derive( PartialOrd , Ord ) ) ]
544
+ pub enum ClaimableBalance {
545
+ /// The channel is not yet closed (or the commitment or closing transaction has not yet
546
+ /// appeared in a block). The given balance is claimable (less on-chain fees) if the channel is
547
+ /// force-closed now.
548
+ ClaimableOnChannelClose {
549
+ /// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
550
+ /// required to do so.
551
+ claimable_amount_satoshis : u64 ,
552
+ } ,
553
+ /// The channel has been closed, and the given balance is ours but awaiting confirmations until
554
+ /// we consider it spendable.
555
+ ClaimableAwaitingConfirmations {
556
+ /// The amount available to claim, in satoshis, possibly ignoring the on-chain fees which
557
+ /// were spent in broadcasting the transaction.
558
+ claimable_amount_satoshis : u64 ,
559
+ /// The height at which an [`Event::SpendableOutputs`] event will be generated for this
560
+ /// amount.
561
+ confirmation_height : u32 ,
562
+ } ,
563
+ /// The channel has been closed, and the given balance should be ours but awaiting spending
564
+ /// transaction confirmation. If the spending transaction does not confirm in time, it is
565
+ /// possible our counterparty can take the funds by broadcasting an HTLC timeout on-chain.
566
+ ///
567
+ /// Once the spending transaction confirms, before it has reached enough confirmations to be
568
+ /// considered safe from chain reorganizations, the balance will instead be provided via
569
+ /// [`ClaimableBalance::ClaimableAwaitingConfirmations`].
570
+ ContentiousClaimable {
571
+ /// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
572
+ /// required to do so.
573
+ claimable_amount_satoshis : u64 ,
574
+ /// The height at which the counterparty may be able to claim the balance if we have not
575
+ /// done so.
576
+ timeout_height : u32 ,
577
+ } ,
578
+ /// HTLCs which we sent to our counterparty which are claimable after a timeout (less on-chain
579
+ /// fees) if the counterparty does not know the preimage for the HTLCs. These are somewhat
580
+ /// likely to be claimed by our counterparty before we do.
581
+ MaybeClaimableHTLCAwaitingTimeout {
582
+ /// The amount available to claim, in satoshis, ignoring the on-chain fees which will be
583
+ /// required to do so.
584
+ claimable_amount_satoshis : u64 ,
585
+ /// The height at which we will be able to claim the balance if our counterparty has not
586
+ /// done so.
587
+ claimable_height : u32 ,
588
+ } ,
589
+ }
590
+
538
591
/// An HTLC which has been irrevocably resolved on-chain, and has reached ANTI_REORG_DELAY.
539
592
#[ derive( PartialEq ) ]
540
593
struct HTLCIrrevocablyResolved {
@@ -1302,6 +1355,174 @@ impl<Signer: Sign> ChannelMonitor<Signer> {
1302
1355
pub fn current_best_block ( & self ) -> BestBlock {
1303
1356
self . inner . lock ( ) . unwrap ( ) . best_block . clone ( )
1304
1357
}
1358
+
1359
+ /// Gets the balances in this channel which are either claimable by us if we were to
1360
+ /// force-close the channel now or which are claimable on-chain or claims which are awaiting
1361
+ /// confirmation.
1362
+ ///
1363
+ /// Any balances in the channel which are available on-chain (ignoring on-chain fees) are
1364
+ /// included here until an [`Event::SpendableOutputs`] event has been generated for the
1365
+ /// balance, or until our counterparty has claimed the balance and accrued several
1366
+ /// confirmations on the claim transaction.
1367
+ ///
1368
+ /// Note that the balances available when you or your counterparty have broadcasted revoked
1369
+ /// state(s) may not be fully captured here.
1370
+ // TODO, fix that ^
1371
+ ///
1372
+ /// See [`ClaimableBalance`] for additional details on the types of claimable balances which
1373
+ /// may be returned here and their meanings.
1374
+ pub fn get_claimable_balances ( & self ) -> Vec < ClaimableBalance > {
1375
+ let mut res = Vec :: new ( ) ;
1376
+ let us = self . inner . lock ( ) . unwrap ( ) ;
1377
+
1378
+ let mut confirmed_txid = us. funding_spend_confirmed ;
1379
+ let mut pending_commitment_tx_conf_thresh = None ;
1380
+ if let Some ( ( txid, conf_thresh) ) = us. onchain_events_awaiting_threshold_conf . iter ( ) . find_map ( |event| {
1381
+ if let OnchainEvent :: FundingSpendConfirmation { txid, .. } = event. event {
1382
+ Some ( ( txid, event. confirmation_threshold ( ) ) )
1383
+ } else { None }
1384
+ } ) {
1385
+ debug_assert ! ( us. funding_spend_confirmed. is_none( ) , "We have a pending funding spend awaiting confirmation, we can't have confirmed it already!" ) ;
1386
+ confirmed_txid = Some ( txid) ;
1387
+ pending_commitment_tx_conf_thresh = Some ( conf_thresh) ;
1388
+ }
1389
+
1390
+ macro_rules! walk_htlcs {
1391
+ ( $holder_commitment: expr, $htlc_iter: expr) => {
1392
+ for htlc in $htlc_iter {
1393
+ if let Some ( htlc_input_idx) = htlc. transaction_output_index {
1394
+ if us. htlcs_resolved_on_chain. iter( ) . any( |v| v. input_idx == htlc_input_idx) {
1395
+ assert!( us. funding_spend_confirmed. is_some( ) ) ;
1396
+ } else if htlc. offered == $holder_commitment {
1397
+ // If the payment was outbound, check if there's an HTLCUpdate
1398
+ // indicating we have spent this HTLC with a timeout, claiming it back
1399
+ // and awaiting confirmations on it.
1400
+ if let Some ( conf_thresh) = us. onchain_events_awaiting_threshold_conf. iter( ) . find_map( |event| {
1401
+ if let OnchainEvent :: HTLCUpdate { input_idx: Some ( input_idx) , .. } = event. event {
1402
+ if input_idx == htlc_input_idx { Some ( event. confirmation_threshold( ) ) } else { None }
1403
+ } else { None }
1404
+ } ) {
1405
+ res. push( ClaimableBalance :: ClaimableAwaitingConfirmations {
1406
+ claimable_amount_satoshis: htlc. amount_msat / 1000 ,
1407
+ confirmation_height: conf_thresh,
1408
+ } ) ;
1409
+ } else {
1410
+ res. push( ClaimableBalance :: MaybeClaimableHTLCAwaitingTimeout {
1411
+ claimable_amount_satoshis: htlc. amount_msat / 1000 ,
1412
+ claimable_height: htlc. cltv_expiry,
1413
+ } ) ;
1414
+ }
1415
+ } else if us. payment_preimages. get( & htlc. payment_hash) . is_some( ) {
1416
+ // Otherwise (the payment was inbound), only expose it as claimable if
1417
+ // we know the preimage.
1418
+ // Note that if there is a pending claim, but it did not use the
1419
+ // preimage, we lost funds to our counterparty! We will then continue
1420
+ // to show it as ContentiousClaimable until ANTI_REORG_DELAY.
1421
+ if let Some ( ( conf_thresh, true ) ) =
1422
+ us. onchain_events_awaiting_threshold_conf. iter( ) . find_map( |event| {
1423
+ if let OnchainEvent :: HTLCSpendConfirmation { input_idx, preimage, .. } = event. event {
1424
+ if input_idx == htlc_input_idx {
1425
+ Some ( ( event. confirmation_threshold( ) , preimage. is_some( ) ) )
1426
+ } else { None }
1427
+ } else { None }
1428
+ }
1429
+ ) {
1430
+ res. push( ClaimableBalance :: ClaimableAwaitingConfirmations {
1431
+ claimable_amount_satoshis: htlc. amount_msat / 1000 ,
1432
+ confirmation_height: conf_thresh,
1433
+ } ) ;
1434
+ } else {
1435
+ res. push( ClaimableBalance :: ContentiousClaimable {
1436
+ claimable_amount_satoshis: htlc. amount_msat / 1000 ,
1437
+ timeout_height: htlc. cltv_expiry,
1438
+ } ) ;
1439
+ }
1440
+ }
1441
+ }
1442
+ }
1443
+ }
1444
+ }
1445
+
1446
+ if let Some ( txid) = confirmed_txid {
1447
+ let mut found_commitment_tx = false ;
1448
+ if Some ( txid) == us. current_counterparty_commitment_txid || Some ( txid) == us. prev_counterparty_commitment_txid {
1449
+ walk_htlcs ! ( false , us. counterparty_claimable_outpoints. get( & txid) . unwrap( ) . iter( ) . map( |( a, _) | a) ) ;
1450
+ if let Some ( conf_thresh) = pending_commitment_tx_conf_thresh {
1451
+ if let Some ( value) = us. onchain_events_awaiting_threshold_conf . iter ( ) . find_map ( |event| {
1452
+ if let OnchainEvent :: MaturingOutput {
1453
+ descriptor : SpendableOutputDescriptor :: StaticPaymentOutput ( descriptor)
1454
+ } = & event. event {
1455
+ Some ( descriptor. output . value )
1456
+ } else { None }
1457
+ } ) {
1458
+ res. push ( ClaimableBalance :: ClaimableAwaitingConfirmations {
1459
+ claimable_amount_satoshis : value,
1460
+ confirmation_height : conf_thresh,
1461
+ } ) ;
1462
+ } else {
1463
+ // If a counterparty commitment transaction is awaiting confirmation, we
1464
+ // should also have a StaticPaymentOutput MaturingOutput event awaiting
1465
+ // confirmation with the same height. Not having one implies something has
1466
+ // gone terribly wrong with our commitment txid tracking.
1467
+ debug_assert ! ( false ) ;
1468
+ }
1469
+ }
1470
+ found_commitment_tx = true ;
1471
+ } else if txid == us. current_holder_commitment_tx . txid {
1472
+ walk_htlcs ! ( true , us. current_holder_commitment_tx. htlc_outputs. iter( ) . map( |( a, _, _) | a) ) ;
1473
+ if let Some ( conf_thresh) = pending_commitment_tx_conf_thresh {
1474
+ res. push ( ClaimableBalance :: ClaimableAwaitingConfirmations {
1475
+ claimable_amount_satoshis : us. current_holder_commitment_tx . to_self_value_sat ,
1476
+ confirmation_height : conf_thresh,
1477
+ } ) ;
1478
+ }
1479
+ found_commitment_tx = true ;
1480
+ } else if let Some ( prev_commitment) = & us. prev_holder_signed_commitment_tx {
1481
+ if txid == prev_commitment. txid {
1482
+ walk_htlcs ! ( true , prev_commitment. htlc_outputs. iter( ) . map( |( a, _, _) | a) ) ;
1483
+ if let Some ( conf_thresh) = pending_commitment_tx_conf_thresh {
1484
+ res. push ( ClaimableBalance :: ClaimableAwaitingConfirmations {
1485
+ claimable_amount_satoshis : prev_commitment. to_self_value_sat ,
1486
+ confirmation_height : conf_thresh,
1487
+ } ) ;
1488
+ }
1489
+ found_commitment_tx = true ;
1490
+ }
1491
+ }
1492
+ if !found_commitment_tx {
1493
+ if let Some ( conf_thresh) = pending_commitment_tx_conf_thresh {
1494
+ // We blindly assume this is a cooperative close transaction here, and that the
1495
+ // counterparty didn't misbehave. At worst we've over-estimated the amount we can
1496
+ // claim as we'll punish a misbehaving counterparty (as long as we didn't
1497
+ // misbehave).
1498
+ res. push ( ClaimableBalance :: ClaimableAwaitingConfirmations {
1499
+ claimable_amount_satoshis : us. current_holder_commitment_tx . to_self_value_sat ,
1500
+ confirmation_height : conf_thresh,
1501
+ } ) ;
1502
+ }
1503
+ }
1504
+ // TODO: Add logic to provide claimable balances for counterparty broadcasting revoked
1505
+ // outputs.
1506
+ } else {
1507
+ let mut claimable_inbound_htlc_value_sat = 0 ;
1508
+ for ( htlc, _, _) in us. current_holder_commitment_tx . htlc_outputs . iter ( ) {
1509
+ if htlc. transaction_output_index . is_none ( ) { continue ; }
1510
+ if htlc. offered {
1511
+ res. push ( ClaimableBalance :: MaybeClaimableHTLCAwaitingTimeout {
1512
+ claimable_amount_satoshis : htlc. amount_msat / 1000 ,
1513
+ claimable_height : htlc. cltv_expiry ,
1514
+ } ) ;
1515
+ } else if us. payment_preimages . get ( & htlc. payment_hash ) . is_some ( ) {
1516
+ claimable_inbound_htlc_value_sat += htlc. amount_msat / 1000 ;
1517
+ }
1518
+ }
1519
+ res. push ( ClaimableBalance :: ClaimableOnChannelClose {
1520
+ claimable_amount_satoshis : us. current_holder_commitment_tx . to_self_value_sat + claimable_inbound_htlc_value_sat,
1521
+ } ) ;
1522
+ }
1523
+
1524
+ res
1525
+ }
1305
1526
}
1306
1527
1307
1528
/// Compares a broadcasted commitment transaction's HTLCs with those in the latest state,
0 commit comments