feature: expose preimage in forward+settle event

Until now, clients of SubscribeHTLCEvents didn't have access to the settled preimage. The API allows to intercept forward event and to be updated on forward events however the forward+settle event does not include the payment preimage. This pr changes allows it.

htlcswitch/htlcnotifier.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/lightningnetwork/lnd/channeldb"
 	"github.com/lightningnetwork/lnd/htlcswitch/hop"
+	"github.com/lightningnetwork/lnd/lntypes"
 	"github.com/lightningnetwork/lnd/lnwire"
 	"github.com/lightningnetwork/lnd/subscribe"
 )
@@ -281,6 +282,9 @@ type SettleEvent struct {
 	// forwards with their corresponding forwarding event.
 	HtlcKey
 
+	// Preimage that was released for settling the htlc.
+	Preimage lntypes.Preimage
+
 	// HtlcEventType classifies the event as part of a local send or
 	// receive, or as part of a forward.
 	HtlcEventType
@@ -360,9 +364,12 @@ func (h *HtlcNotifier) NotifyForwardingFailEvent(key HtlcKey,
 // to as part of a forward or a receive to our node has been settled.
 //
 // Note this is part of the htlcNotifier interface.
-func (h *HtlcNotifier) NotifySettleEvent(key HtlcKey, eventType HtlcEventType) {
+func (h *HtlcNotifier) NotifySettleEvent(key HtlcKey,
+	preimage lntypes.Preimage, eventType HtlcEventType) {
+
 	event := &SettleEvent{
 		HtlcKey:       key,
+		Preimage:      preimage,
 		HtlcEventType: eventType,
 		Timestamp:     h.now(),
 	}

htlcswitch/interfaces.go

@@ -282,5 +282,6 @@ type htlcNotifier interface {
 	// NotifySettleEvent notifies the HtlcNotifier that a htlc that we
 	// committed to as part of a forward or a receive to our node has been
 	// settled.
-	NotifySettleEvent(key HtlcKey, eventType HtlcEventType)
+	NotifySettleEvent(key HtlcKey, preimage lntypes.Preimage,
+		eventType HtlcEventType)
 }

htlcswitch/link.go

@@ -1449,6 +1449,7 @@ func (l *channelLink) handleDownstreamPkt(pkt *htlcPacket) {
 		// Send a settle event notification to htlcNotifier.
 		l.cfg.HtlcNotifier.NotifySettleEvent(
 			newHtlcKey(pkt),
+			htlc.PaymentPreimage,
 			getEventType(pkt),
 		)
 
@@ -2982,6 +2983,7 @@ func (l *channelLink) settleHTLC(preimage lntypes.Preimage,
 				HtlcID: pd.HtlcIndex,
 			},
 		},
+		preimage,
 		HtlcEventTypeReceive,
 	)
 

htlcswitch/mock.go

@@ -950,5 +950,6 @@ func (h *mockHTLCNotifier) NotifyForwardingFailEvent(key HtlcKey,
 	eventType HtlcEventType) {
 }
 
-func (h *mockHTLCNotifier) NotifySettleEvent(key HtlcKey, eventType HtlcEventType) {
+func (h *mockHTLCNotifier) NotifySettleEvent(key HtlcKey,
+	preimage lntypes.Preimage, eventType HtlcEventType) {
 }

htlcswitch/switch.go

@@ -848,9 +848,10 @@ func (s *Switch) handleLocalResponse(pkt *htlcPacket) {
 	key := newHtlcKey(pkt)
 	eventType := getEventType(pkt)
 
-	switch pkt.htlc.(type) {
+	switch htlc := pkt.htlc.(type) {
 	case *lnwire.UpdateFulfillHTLC:
-		s.cfg.HtlcNotifier.NotifySettleEvent(key, eventType)
+		s.cfg.HtlcNotifier.NotifySettleEvent(key, htlc.PaymentPreimage,
+			eventType)
 
 	case *lnwire.UpdateFailHTLC:
 		s.cfg.HtlcNotifier.NotifyForwardingFailEvent(key, eventType)

htlcswitch/switch_test.go

@@ -2762,7 +2762,8 @@ func TestInvalidFailure(t *testing.T) {
 // these tests.
 type htlcNotifierEvents func(channels *clusterChannels, htlcID uint64,
 	ts time.Time, htlc *lnwire.UpdateAddHTLC,
-	hops []*hop.Payload) ([]interface{}, []interface{}, []interface{})
+	hops []*hop.Payload,
+	preimage *lntypes.Preimage) ([]interface{}, []interface{}, []interface{})
 
 // TestHtlcNotifier tests the notifying of htlc events that are routed over a
 // three hop network. It sets up an Alice -> Bob -> Carol network and routes
@@ -2793,11 +2794,12 @@ func TestHtlcNotifier(t *testing.T) {
 			expectedEvents: func(channels *clusterChannels,
 				htlcID uint64, ts time.Time,
 				htlc *lnwire.UpdateAddHTLC,
-				hops []*hop.Payload) ([]interface{},
+				hops []*hop.Payload,
+				preimage *lntypes.Preimage) ([]interface{},
 				[]interface{}, []interface{}) {
 
 				return getThreeHopEvents(
-					channels, htlcID, ts, htlc, hops, nil,
+					channels, htlcID, ts, htlc, hops, nil, preimage,
 				)
 			},
 			iterations: 2,
@@ -2812,7 +2814,8 @@ func TestHtlcNotifier(t *testing.T) {
 			expectedEvents: func(channels *clusterChannels,
 				htlcID uint64, ts time.Time,
 				htlc *lnwire.UpdateAddHTLC,
-				hops []*hop.Payload) ([]interface{},
+				hops []*hop.Payload,
+				preimage *lntypes.Preimage) ([]interface{},
 				[]interface{}, []interface{}) {
 
 				return getThreeHopEvents(
@@ -2821,6 +2824,7 @@ func TestHtlcNotifier(t *testing.T) {
 						msg:           &lnwire.FailChannelDisabled{},
 						FailureDetail: OutgoingFailureForwardsDisabled,
 					},
+					preimage,
 				)
 			},
 			iterations: 1,
@@ -2942,11 +2946,12 @@ func testHtcNotifier(t *testing.T, testOpts []serverOption, iterations int,
 	// of htlc ids.
 	for i := 0; i < iterations; i++ {
 		// We'll start off by making a payment from
-		// Alice -> Bob -> Carol.
-		htlc, hops := n.sendThreeHopPayment(t)
+		// Alice -> Bob -> Carol. The preimage, generated
+		// by Carol's Invoice is expected in the Settle events
+		htlc, hops, preimage := n.sendThreeHopPayment(t)
 
 		alice, bob, carol := getEvents(
-			channels, uint64(i), now, htlc, hops,
+			channels, uint64(i), now, htlc, hops, preimage,
 		)
 
 		checkHtlcEvents(t, aliceEvents.Updates(), alice)
@@ -2981,7 +2986,7 @@ func checkHtlcEvents(t *testing.T, events <-chan interface{},
 // Alice -> Bob -> Carol in a three hop network and returns Alice's first htlc
 // and the remainder of the hops.
 func (n *threeHopNetwork) sendThreeHopPayment(t *testing.T) (*lnwire.UpdateAddHTLC,
-	[]*hop.Payload) {
+	[]*hop.Payload, *lntypes.Preimage) {
 
 	amount := lnwire.NewMSatFromSatoshis(btcutil.SatoshiPerBitcoin)
 
@@ -3009,7 +3014,7 @@ func (n *threeHopNetwork) sendThreeHopPayment(t *testing.T) (*lnwire.UpdateAddHT
 		t.Fatalf("could not send htlc")
 	}
 
-	return htlc, hops
+	return htlc, hops, invoice.Terms.PaymentPreimage
 }
 
 // getThreeHopEvents gets the set of htlc events that we expect for a payment
@@ -3017,7 +3022,8 @@ func (n *threeHopNetwork) sendThreeHopPayment(t *testing.T) (*lnwire.UpdateAddHT
 // of events will fail on Bob's outgoing link.
 func getThreeHopEvents(channels *clusterChannels, htlcID uint64,
 	ts time.Time, htlc *lnwire.UpdateAddHTLC, hops []*hop.Payload,
-	linkError *LinkError) ([]interface{}, []interface{}, []interface{}) {
+	linkError *LinkError,
+	preimage *lntypes.Preimage) ([]interface{}, []interface{}, []interface{}) {
 
 	aliceKey := HtlcKey{
 		IncomingCircuit: zeroCircuit,
@@ -3091,6 +3097,7 @@ func getThreeHopEvents(channels *clusterChannels, htlcID uint64,
 		aliceEvents,
 		&SettleEvent{
 			HtlcKey:       aliceKey,
+			Preimage:      *preimage,
 			HtlcEventType: HtlcEventTypeSend,
 			Timestamp:     ts,
 		},
@@ -3105,6 +3112,7 @@ func getThreeHopEvents(channels *clusterChannels, htlcID uint64,
 		},
 		&SettleEvent{
 			HtlcKey:       bobKey,
+			Preimage:      *preimage,
 			HtlcEventType: HtlcEventTypeForward,
 			Timestamp:     ts,
 		},
@@ -3119,6 +3127,7 @@ func getThreeHopEvents(channels *clusterChannels, htlcID uint64,
 				},
 				OutgoingCircuit: zeroCircuit,
 			},
+			Preimage:      *preimage,
 			HtlcEventType: HtlcEventTypeReceive,
 			Timestamp:     ts,
 		},