Merge pull request #333 from carlaKC/autoloop-3-peerrules

autoloop: add peer level rules for aggregate liquidity management

Author: carlaKC

cmd/loop/liquidity.go

@@ -1,13 +1,15 @@
 package main
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
 	"strconv"
 
 	"github.com/lightninglabs/loop/liquidity"
 	"github.com/lightninglabs/loop/looprpc"
+	"github.com/lightningnetwork/lnd/routing/route"
 	"github.com/urfave/cli"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
@@ -42,9 +44,9 @@ func getParams(ctx *cli.Context) error {
 
 var setLiquidityRuleCommand = cli.Command{
 	Name:        "setrule",
-	Usage:       "set liquidity manager rule for a channel",
-	Description: "Update or remove the liquidity rule for a channel.",
-	ArgsUsage:   "shortchanid",
+	Usage:       "set liquidity manager rule for a channel/peer",
+	Description: "Update or remove the liquidity rule for a channel/peer.",
+	ArgsUsage:   "{shortchanid |  peerpubkey}",
 	Flags: []cli.Flag{
 		cli.IntFlag{
 			Name: "incoming_threshold",
@@ -58,8 +60,9 @@ var setLiquidityRuleCommand = cli.Command{
 				"that we do not want to drop below.",
 		},
 		cli.BoolFlag{
-			Name:  "clear",
-			Usage: "remove the rule currently set for the channel.",
+			Name: "clear",
+			Usage: "remove the rule currently set for the " +
+				"channel/peer.",
 		},
 	},
 	Action: setRule,
@@ -68,13 +71,22 @@ var setLiquidityRuleCommand = cli.Command{
 func setRule(ctx *cli.Context) error {
 	// We require that a channel ID is set for this rule update.
 	if ctx.NArg() != 1 {
-		return fmt.Errorf("please set a channel id for the rule " +
-			"update")
+		return fmt.Errorf("please set a channel id or peer pubkey " +
+			"for the rule update")
 	}
 
+	var (
+		pubkey     route.Vertex
+		pubkeyRule bool
+	)
 	chanID, err := strconv.ParseUint(ctx.Args().First(), 10, 64)
 	if err != nil {
-		return fmt.Errorf("could not parse channel ID: %v", err)
+		pubkey, err = route.NewVertexFromStr(ctx.Args().First())
+		if err != nil {
+			return fmt.Errorf("please provide a valid pubkey: "+
+				"%v, or short channel ID", err)
+		}
+		pubkeyRule = true
 	}
 
 	client, cleanup, err := getClient(ctx)
@@ -101,11 +113,20 @@ func setRule(ctx *cli.Context) error {
 	)
 
 	// Run through our current set of rules and check whether we have a rule
-	// currently set for this channel. We also track a slice containing all
-	// of the rules we currently have set for other channels, because we
-	// want to leave these rules untouched.
+	// currently set for this channel or peer. We also track a slice
+	// containing all of the rules we currently have set for other channels,
+	// and peers because we want to leave these rules untouched.
 	for _, rule := range params.Rules {
-		if rule.ChannelId == chanID {
+		var (
+			channelRuleSet = rule.ChannelId != 0 &&
+				rule.ChannelId == chanID
+
+			peerRuleSet = rule.Pubkey != nil && bytes.Equal(
+				rule.Pubkey, pubkey[:],
+			)
+		)
+
+		if channelRuleSet || peerRuleSet {
 			ruleSet = true
 		} else {
 			otherRules = append(otherRules, rule)
@@ -149,6 +170,10 @@ func setRule(ctx *cli.Context) error {
 		Type:      looprpc.LiquidityRuleType_THRESHOLD,
 	}
 
+	if pubkeyRule {
+		newRule.Pubkey = pubkey[:]
+	}
+
 	if inboundSet {
 		newRule.IncomingThreshold = uint32(
 			ctx.Int("incoming_threshold"),

docs/autoloop.md

@@ -23,27 +23,35 @@ Note that autoloop parameters and rules are not persisted, so must be set on
 restart. We recommend running loopd with `--debuglevel=debug` when using this 
 feature.
 
-### Channel Thresholds 
-To setup the autolooper to dispatch swaps on your behalf, you need to tell it 
-which channels you would like it to perform swaps on, and the liquidity balance 
-you would like on each channel. Desired liqudity balance is expressed using 
-threshold incoming and outgoing percentages of channel capacity. The incoming 
-threshold you specify indicates the minimum percentage of your channel capacity
-that you would like in incoming capacity. The outgoing thresold allows you to 
-reserve a percentage of your balance for outgoing capacity, but may be set to 
-zero if you are only concerned with incoming capcity.
-
-The autolooper will perform swaps that push your incoming channel capacity to 
-at least the incoming threshold you specify, while reserving at least the 
-outgoing capacity threshold. Rules can be set as follows:
+### Liquidity Targets
+Autoloop can be configured to manage liquidity for individual channels, or for
+a peer as a whole. Peer-level liquidity management will examine the liquidity 
+balance of all the channels you have with a peer. This differs from channel-level
+liquidity, where each channel's individual balance is checked. Note that if you
+set a liquidity rule for a peer, you cannot also set a specific rule for one of
+its channels.
+
+### Liqudity Thresholds 
+To setup the autolooper to dispatch swaps on your behalf, you need to set the 
+liquidity balance you would like for each channel or peer. Desired liquidity 
+balance is expressed using threshold incoming and outgoing percentages of 
+capacity. The incoming threshold you specify indicates the minimum percentage 
+of your capacity that you would like in incoming capacity. The outgoing 
+threshold allows you to reserve a percentage of your balance for outgoing 
+capacity, but may be set to zero if you are only concerned with incoming 
+capacity.
+
+The autolooper will perform swaps that push your incoming capacity to at least 
+the incoming threshold you specify, while reserving at least the outgoing 
+capacity threshold. Rules can be set as follows:
 
 ```
-loop setrule {short channel id} --incoming_threshold={minimum % incoming} --outgoing_threshold={minimum % outgoing}
+loop setrule {short channel id/ peer pubkey} --incoming_threshold={minimum % incoming} --outgoing_threshold={minimum % outgoing}
 ```
 
-To remove a channel from consideration, its rule can simply be cleared:
+To remove a rule from consideration, its rule can simply be cleared:
 ```
-loop setrule {short channel id} --clear
+loop setrule {short channel id/ peer pubkey} --clear
 ```
 
 ## Fees

liquidity/autoloop_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/btcsuite/btcutil"
 	"github.com/lightninglabs/lndclient"
 	"github.com/lightninglabs/loop"
 	"github.com/lightninglabs/loop/labels"
@@ -12,6 +13,7 @@ import (
 	"github.com/lightninglabs/loop/test"
 	"github.com/lightningnetwork/lnd/lntypes"
 	"github.com/lightningnetwork/lnd/lnwire"
+	"github.com/lightningnetwork/lnd/routing/route"
 )
 
 // TestAutoLoopDisabled tests the case where we need to perform a swap, but
@@ -266,6 +268,161 @@ func TestAutoLoopEnabled(t *testing.T) {
 	c.stop()
 }
 
+// TestCompositeRules tests the case where we have rules set on a per peer
+// and per channel basis, and perform swaps for both targets.
+func TestCompositeRules(t *testing.T) {
+	defer test.Guard(t)()
+
+	// Setup our channels so that we have two channels with peer 2, and
+	// a single channel with peer 1.
+	channel3 := lndclient.ChannelInfo{
+		ChannelID:     chanID3.ToUint64(),
+		PubKeyBytes:   peer2,
+		LocalBalance:  10000,
+		RemoteBalance: 0,
+		Capacity:      10000,
+	}
+
+	channels := []lndclient.ChannelInfo{
+		channel1, channel2, channel3,
+	}
+
+	// Create a set of parameters with autoloop enabled, set our budget to
+	// a value that will easily accommodate our two swaps.
+	params := Parameters{
+		Autoloop:                   true,
+		AutoFeeBudget:              100000,
+		AutoFeeStartDate:           testTime,
+		MaxAutoInFlight:            2,
+		FailureBackOff:             time.Hour,
+		SweepFeeRateLimit:          20000,
+		SweepConfTarget:            10,
+		MaximumPrepay:              20000,
+		MaximumSwapFeePPM:          1000,
+		MaximumRoutingFeePPM:       1000,
+		MaximumPrepayRoutingFeePPM: 1000,
+		MaximumMinerFee:            20000,
+		ChannelRules: map[lnwire.ShortChannelID]*ThresholdRule{
+			chanID1: chanRule,
+		},
+		PeerRules: map[route.Vertex]*ThresholdRule{
+			peer2: chanRule,
+		},
+	}
+
+	c := newAutoloopTestCtx(t, params, channels, testRestrictions)
+	c.start()
+
+	// Calculate our maximum allowed fees and create quotes that fall within
+	// our budget.
+	var (
+		// Create a quote for our peer level swap that is within
+		// our budget, with an amount which would balance the peer
+		/// across all of its channels.
+		peerAmount     = btcutil.Amount(15000)
+		maxPeerSwapFee = ppmToSat(peerAmount, params.MaximumSwapFeePPM)
+
+		peerSwapQuote = &loop.LoopOutQuote{
+			SwapFee:      maxPeerSwapFee,
+			PrepayAmount: params.MaximumPrepay - 20,
+		}
+
+		peerSwapQuoteRequest = &loop.LoopOutQuoteRequest{
+			Amount:          peerAmount,
+			SweepConfTarget: params.SweepConfTarget,
+		}
+
+		maxPeerRouteFee = ppmToSat(
+			peerAmount, params.MaximumRoutingFeePPM,
+		)
+
+		peerSwap = &loop.OutRequest{
+			Amount:            peerAmount,
+			MaxSwapRoutingFee: maxPeerRouteFee,
+			MaxPrepayRoutingFee: ppmToSat(
+				peerSwapQuote.PrepayAmount,
+				params.MaximumPrepayRoutingFeePPM,
+			),
+			MaxSwapFee:      peerSwapQuote.SwapFee,
+			MaxPrepayAmount: peerSwapQuote.PrepayAmount,
+			MaxMinerFee:     params.MaximumMinerFee,
+			SweepConfTarget: params.SweepConfTarget,
+			OutgoingChanSet: loopdb.ChannelSet{
+				chanID2.ToUint64(), chanID3.ToUint64(),
+			},
+			Label:     labels.AutoloopLabel(swap.TypeOut),
+			Initiator: autoloopSwapInitiator,
+		}
+		// Create a quote for our single channel swap that is within
+		// our budget.
+		chanAmount     = chan1Rec.Amount
+		maxChanSwapFee = ppmToSat(chanAmount, params.MaximumSwapFeePPM)
+
+		channelSwapQuote = &loop.LoopOutQuote{
+			SwapFee:      maxChanSwapFee,
+			PrepayAmount: params.MaximumPrepay - 10,
+		}
+
+		chanSwapQuoteRequest = &loop.LoopOutQuoteRequest{
+			Amount:          chanAmount,
+			SweepConfTarget: params.SweepConfTarget,
+		}
+
+		maxChanRouteFee = ppmToSat(
+			chanAmount, params.MaximumRoutingFeePPM,
+		)
+
+		chanSwap = &loop.OutRequest{
+			Amount:            chanAmount,
+			MaxSwapRoutingFee: maxChanRouteFee,
+			MaxPrepayRoutingFee: ppmToSat(
+				channelSwapQuote.PrepayAmount,
+				params.MaximumPrepayRoutingFeePPM,
+			),
+			MaxSwapFee:      channelSwapQuote.SwapFee,
+			MaxPrepayAmount: channelSwapQuote.PrepayAmount,
+			MaxMinerFee:     params.MaximumMinerFee,
+			SweepConfTarget: params.SweepConfTarget,
+			OutgoingChanSet: loopdb.ChannelSet{chanID1.ToUint64()},
+			Label:           labels.AutoloopLabel(swap.TypeOut),
+			Initiator:       autoloopSwapInitiator,
+		}
+		quotes = []quoteRequestResp{
+			{
+				request: peerSwapQuoteRequest,
+				quote:   peerSwapQuote,
+			},
+			{
+				request: chanSwapQuoteRequest,
+				quote:   channelSwapQuote,
+			},
+		}
+
+		loopOuts = []loopOutRequestResp{
+			{
+				request: peerSwap,
+				response: &loop.LoopOutSwapInfo{
+					SwapHash: lntypes.Hash{2},
+				},
+			},
+			{
+				request: chanSwap,
+				response: &loop.LoopOutSwapInfo{
+					SwapHash: lntypes.Hash{1},
+				},
+			},
+		}
+	)
+
+	// Tick our autolooper with no existing swaps, we expect a loop out
+	// swap to be dispatched for each of our rules. We set our server side
+	// maximum to be greater than the swap amount for our peer swap (which
+	// is the larger of the two swaps).
+	c.autoloop(1, peerAmount+1, nil, quotes, loopOuts)
+
+	c.stop()
+}
+
 // existingSwapFromRequest is a helper function which returns the db
 // representation of a loop out request with the event set provided.
 func existingSwapFromRequest(request *loop.OutRequest, initTime time.Time,

liquidity/balances.go

@@ -4,6 +4,7 @@ import (
 	"github.com/btcsuite/btcutil"
 	"github.com/lightninglabs/lndclient"
 	"github.com/lightningnetwork/lnd/lnwire"
+	"github.com/lightningnetwork/lnd/routing/route"
 )
 
 // balances summarizes the state of the balances of a channel. Channel reserve,
@@ -18,16 +19,24 @@ type balances struct {
 	// outgoing is the local balance of the channel.
 	outgoing btcutil.Amount
 
-	// channelID is the channel that has these balances.
-	channelID lnwire.ShortChannelID
+	// channels is the channel that has these balances represent. This may
+	// be more than one channel in the case where we are examining a peer's
+	// liquidity as a whole.
+	channels []lnwire.ShortChannelID
+
+	// pubkey is the public key of the peer we have this balances set with.
+	pubkey route.Vertex
 }
 
 // newBalances creates a balances struct from lndclient channel information.
 func newBalances(info lndclient.ChannelInfo) *balances {
 	return &balances{
-		capacity:  info.Capacity,
-		incoming:  info.RemoteBalance,
-		outgoing:  info.LocalBalance,
-		channelID: lnwire.NewShortChanIDFromInt(info.ChannelID),
+		capacity: info.Capacity,
+		incoming: info.RemoteBalance,
+		outgoing: info.LocalBalance,
+		channels: []lnwire.ShortChannelID{
+			lnwire.NewShortChanIDFromInt(info.ChannelID),
+		},
+		pubkey: info.PubKeyBytes,
 	}
 }