htlcswitch: add receiver-side inbound fee support

Author: joostjager

channeldb/models/channel.go

@@ -115,6 +115,9 @@ type ForwardingPolicy struct {
 	// used to compute the required fee for a given HTLC.
 	FeeRate lnwire.MilliSatoshi
 
+	// InboundFee is the fee that must be paid for incoming HTLCs.
+	InboundFee InboundFee
+
 	// TimeLockDelta is the absolute time-lock value, expressed in blocks,
 	// that will be subtracted from an incoming HTLC's timelock value to
 	// create the time-lock value for the forwarded outgoing HTLC. The

channeldb/models/inbound_fee.go

@@ -0,0 +1,53 @@
+package models
+
+import "github.com/lightningnetwork/lnd/lnwire"
+
+const (
+	// maxFeeRate is the maximum fee rate that we allow. It is set to allow
+	// a variable fee component of up to 10x the payment amount.
+	maxFeeRate = 10 * feeRateParts
+)
+
+type InboundFee struct {
+	Base int32
+	Rate int32
+}
+
+// NewInboundFeeFromWire constructs an inbound fee structure from a wire fee.
+func NewInboundFeeFromWire(fee lnwire.Fee) InboundFee {
+	return InboundFee{
+		Base: fee.BaseFee,
+		Rate: fee.FeeRate,
+	}
+}
+
+// ToWire converts the inbound fee to a wire fee structure.
+func (i *InboundFee) ToWire() lnwire.Fee {
+	return lnwire.Fee{
+		BaseFee: i.Base,
+		FeeRate: i.Rate,
+	}
+}
+
+// CalcFee calculates what the inbound fee should minimally be for forwarding
+// the given amount. This amount is the total of the outgoing amount plus the
+// outbound fee, which is what the inbound fee is based on.
+func (i *InboundFee) CalcFee(amt lnwire.MilliSatoshi) int64 {
+	fee := int64(i.Base)
+	rate := int64(i.Rate)
+
+	// Cap the rate to prevent overflows.
+	switch {
+	case rate > maxFeeRate:
+		rate = maxFeeRate
+
+	case rate < -maxFeeRate:
+		rate = -maxFeeRate
+	}
+
+	// Calculate proportional component. To keep the integer math simple,
+	// positive fees are rounded down while negative fees are rounded up.
+	fee += rate * int64(amt) / feeRateParts
+
+	return fee
+}

channeldb/models/inbound_fee_test.go

@@ -0,0 +1,33 @@
+package models
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestInboundFee(t *testing.T) {
+	t.Parallel()
+
+	// Test positive fee.
+	i := InboundFee{
+		Base: 5,
+		Rate: 500000,
+	}
+
+	require.Equal(t, int64(6), i.CalcFee(2))
+
+	// Expect fee to be rounded down.
+	require.Equal(t, int64(6), i.CalcFee(3))
+
+	// Test negative fee.
+	i = InboundFee{
+		Base: -5,
+		Rate: -500000,
+	}
+
+	require.Equal(t, int64(-6), i.CalcFee(2))
+
+	// Expect fee to be rounded up.
+	require.Equal(t, int64(-6), i.CalcFee(3))
+}

htlcswitch/interfaces.go

@@ -203,6 +203,7 @@ type ChannelLink interface {
 	CheckHtlcForward(payHash [32]byte, incomingAmt lnwire.MilliSatoshi,
 		amtToForward lnwire.MilliSatoshi,
 		incomingTimeout, outgoingTimeout uint32,
+		inboundFee models.InboundFee,
 		heightNow uint32, scid lnwire.ShortChannelID) *LinkError
 
 	// CheckHtlcTransit should return a nil error if the passed HTLC details

htlcswitch/link.go

@@ -2546,28 +2546,43 @@ func (l *channelLink) UpdateForwardingPolicy(
 func (l *channelLink) CheckHtlcForward(payHash [32]byte,
 	incomingHtlcAmt, amtToForward lnwire.MilliSatoshi,
 	incomingTimeout, outgoingTimeout uint32,
+	inboundFee models.InboundFee,
 	heightNow uint32, originalScid lnwire.ShortChannelID) *LinkError {
 
 	l.RLock()
 	policy := l.cfg.FwrdingPolicy
 	l.RUnlock()
 
-	// Using the amount of the incoming HTLC, we'll calculate the expected
-	// fee this incoming HTLC must carry in order to satisfy the
-	// constraints of the outgoing link.
-	expectedFee := ExpectedFee(policy, amtToForward)
+	// Using the outgoing HTLC amount, we'll calculate the outgoing
+	// fee this incoming HTLC must carry in order to satisfy the constraints
+	// of the outgoing link.
+	outFee := ExpectedFee(policy, amtToForward)
+
+	// Then calculate the inbound fee that we charge based on the sum of
+	// outgoing HTLC amount and outgoing fee.
+	inFee := inboundFee.CalcFee(amtToForward + outFee)
+
+	// Add up both fee components. It is important to calculate both fees
+	// separately. An alternative way of calculating is to first determine
+	// an aggregate fee and apply that to the outgoing HTLC amount. However,
+	// rounding may cause the result to be slightly higher than in the case
+	// of separately rounded fee components. This potentially causes failed
+	// forwards for senders and is something to be avoided.
+	expectedFee := inFee + int64(outFee)
 
 	// If the actual fee is less than our expected fee, then we'll reject
 	// this HTLC as it didn't provide a sufficient amount of fees, or the
 	// values have been tampered with, or the send used incorrect/dated
 	// information to construct the forwarding information for this hop. In
-	// any case, we'll cancel this HTLC. We're checking for this case first
-	// to leak as little information as possible.
-	actualFee := incomingHtlcAmt - amtToForward
+	// any case, we'll cancel this HTLC.
+	actualFee := int64(incomingHtlcAmt) - int64(amtToForward)
 	if incomingHtlcAmt < amtToForward || actualFee < expectedFee {
 		l.log.Warnf("outgoing htlc(%x) has insufficient fee: "+
-			"expected %v, got %v",
-			payHash[:], int64(expectedFee), int64(actualFee))
+			"expected %v, got %v: incoming=%v, outgoing=%v, "+
+			"inboundFee=%v",
+			payHash[:], expectedFee, actualFee,
+			incomingHtlcAmt, amtToForward, inboundFee,
+		)
 
 		// As part of the returned error, we'll send our latest routing
 		// policy so the sending node obtains the most up to date data.
@@ -3114,6 +3129,8 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg,
 				// round of processing.
 				chanIterator.EncodeNextHop(buf)
 
+				inboundFee := l.cfg.FwrdingPolicy.InboundFee
+
 				updatePacket := &htlcPacket{
 					incomingChanID:  l.ShortChanID(),
 					incomingHTLCID:  pd.HtlcIndex,
@@ -3126,6 +3143,7 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg,
 					incomingTimeout: pd.Timeout,
 					outgoingTimeout: fwdInfo.OutgoingCTLV,
 					customRecords:   pld.CustomRecords(),
+					inboundFee:      inboundFee,
 				}
 				switchPackets = append(
 					switchPackets, updatePacket,
@@ -3178,6 +3196,8 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg,
 			// have been added to switchPackets at the top of this
 			// section.
 			if fwdPkg.State == channeldb.FwdStateLockedIn {
+				inboundFee := l.cfg.FwrdingPolicy.InboundFee
+
 				updatePacket := &htlcPacket{
 					incomingChanID:  l.ShortChanID(),
 					incomingHTLCID:  pd.HtlcIndex,
@@ -3190,6 +3210,7 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg,
 					incomingTimeout: pd.Timeout,
 					outgoingTimeout: fwdInfo.OutgoingCTLV,
 					customRecords:   pld.CustomRecords(),
+					inboundFee:      inboundFee,
 				}
 
 				fwdPkg.FwdFilter.Set(idx)