lnd.xprv/autopilot/interface.go

219 lines
8.4 KiB
Go
Raw Normal View History

2017-08-11 07:14:41 +03:00
package autopilot
import (
"net"
"github.com/btcsuite/btcd/btcec"
"github.com/btcsuite/btcd/wire"
"github.com/btcsuite/btcutil"
2018-07-31 10:17:17 +03:00
"github.com/lightningnetwork/lnd/lnwire"
2017-08-11 07:14:41 +03:00
)
// DefaultConfTarget is the default confirmation target for autopilot channels.
// TODO(halseth): possibly make dynamic, going aggressive->lax as more channels
// are opened.
const DefaultConfTarget = 3
2017-08-11 07:14:41 +03:00
// Node node is an interface which represents n abstract vertex within the
// channel graph. All nodes should have at least a single edge to/from them
// within the graph.
//
// TODO(roasbeef): combine with routing.ChannelGraphSource
type Node interface {
// PubKey is the identity public key of the node. This will be used to
// attempt to target a node for channel opening by the main autopilot
// agent. The key will be returned in serialized compressed format.
PubKey() [33]byte
2017-08-11 07:14:41 +03:00
// Addrs returns a slice of publicly reachable public TCP addresses
// that the peer is known to be listening on.
Addrs() []net.Addr
// ForEachChannel is a higher-order function that will be used to
// iterate through all edges emanating from/to the target node. For
// each active channel, this function should be called with the
// populated ChannelEdge that describes the active channel.
ForEachChannel(func(ChannelEdge) error) error
}
// LocalChannel is a simple struct which contains relevant details of a
// particular channel the local node has. The fields in this struct may be used
// a signals for various AttachmentHeuristic implementations.
type LocalChannel struct {
2017-08-11 07:14:41 +03:00
// ChanID is the short channel ID for this channel as defined within
// BOLT-0007.
ChanID lnwire.ShortChannelID
// Balance is the local balance of the channel expressed in satoshis.
Balance btcutil.Amount
2017-08-11 07:14:41 +03:00
// Node is the peer that this channel has been established with.
Node NodeID
// TODO(roasbeef): also add other traits?
// * fee, timelock, etc
}
// ChannelEdge is a struct that holds details concerning a channel, but also
// contains a reference to the Node that this channel connects to as a directed
// edge within the graph. The existence of this reference to the connected node
2017-08-11 07:14:41 +03:00
// will allow callers to traverse the graph in an object-oriented manner.
type ChannelEdge struct {
// ChanID is the short channel ID for this channel as defined within
// BOLT-0007.
ChanID lnwire.ShortChannelID
// Capacity is the capacity of the channel expressed in satoshis.
Capacity btcutil.Amount
2017-08-11 07:14:41 +03:00
// Peer is the peer that this channel creates an edge to in the channel
// graph.
Peer Node
}
// ChannelGraph in an interface that represents a traversable channel graph.
// The autopilot agent will use this interface as its source of graph traits in
// order to make decisions concerning which channels should be opened, and to
// whom.
//
// TODO(roasbeef): abstract??
type ChannelGraph interface {
// ForEachNode is a higher-order function that should be called once
// for each connected node within the channel graph. If the passed
// callback returns an error, then execution should be terminated.
ForEachNode(func(Node) error) error
}
// NodeScore is a tuple mapping a NodeID to a score indicating the preference
// of opening a channel with it.
type NodeScore struct {
// NodeID is the serialized compressed pubkey of the node that is being
// scored.
NodeID NodeID
// Score is the score given by the heuristic for opening a channel of
// the given size to this node.
Score float64
}
2017-08-11 07:14:41 +03:00
// AttachmentDirective describes a channel attachment proscribed by an
// AttachmentHeuristic. It details to which node a channel should be created
// to, and also the parameters which should be used in the channel creation.
type AttachmentDirective struct {
// NodeID is the serialized compressed pubkey of the target node for
// this attachment directive. It can be identified by its public key,
// and therefore can be used along with a ChannelOpener implementation
// to execute the directive.
NodeID NodeID
2017-08-11 07:14:41 +03:00
// ChanAmt is the size of the channel that should be opened, expressed
// in satoshis.
ChanAmt btcutil.Amount
// Addrs is a list of addresses that the target peer may be reachable
// at.
Addrs []net.Addr
}
// AttachmentHeuristic is one of the primary interfaces within this package.
// Implementations of this interface will be used to implement a control system
// which automatically regulates channels of a particular agent, attempting to
// optimize channels opened/closed based on various heuristics. The purpose of
// the interface is to allow an auto-pilot agent to decide if it needs more
// channels, and if so, which exact channels should be opened.
type AttachmentHeuristic interface {
// Name returns the name of this heuristic.
Name() string
// NodeScores is a method that given the current channel graph and
// current set of local channels, scores the given nodes according to
// the preference of opening a channel of the given size with them. The
// returned channel candidates maps the NodeID to a NodeScore for the
// node.
//
// The returned scores will be in the range [0, 1.0], where 0 indicates
// no improvement in connectivity if a channel is opened to this node,
// while 1.0 is the maximum possible improvement in connectivity. The
// implementation of this interface must return scores in this range to
// properly allow the autopilot agent to make a reasonable choice based
// on the score from multiple heuristics.
//
// NOTE: A NodeID not found in the returned map is implicitly given a
// score of 0.
NodeScores(g ChannelGraph, chans []LocalChannel,
chanSize btcutil.Amount, nodes map[NodeID]struct{}) (
map[NodeID]*NodeScore, error)
2017-08-11 07:14:41 +03:00
}
// NodeMetric is a common interface for all graph metrics that are not
// directly used as autopilot node scores but may be used in compositional
// heuristics or statistical information exposed to users.
type NodeMetric interface {
// Name returns the unique name of this metric.
Name() string
// Refresh refreshes the metric values based on the current graph.
Refresh(graph ChannelGraph) error
// GetMetric returns the latest value of this metric. Values in the
// map are per node and can be in arbitrary domain. If normalize is
// set to true, then the returned values are normalized to either
// [0, 1] or [-1, 1] depending on the metric.
GetMetric(normalize bool) map[NodeID]float64
}
// ScoreSettable is an interface that indicates that the scores returned by the
// heuristic can be mutated by an external caller. The ExternalScoreAttachment
// currently implements this interface, and so should any heuristic that is
// using the ExternalScoreAttachment as a sub-heuristic, or keeps their own
// internal list of mutable scores, to allow access to setting the internal
// scores.
type ScoreSettable interface {
// SetNodeScores is used to set the internal map from NodeIDs to
// scores. The passed scores must be in the range [0, 1.0]. The fist
// parameter is the name of the targeted heuristic, to allow
// recursively target specific sub-heuristics. The returned boolean
// indicates whether the targeted heuristic was found.
SetNodeScores(string, map[NodeID]float64) (bool, error)
}
var (
// availableHeuristics holds all heuristics possible to combine for use
// with the autopilot agent.
availableHeuristics = []AttachmentHeuristic{
NewPrefAttachment(),
NewExternalScoreAttachment(),
NewTopCentrality(),
}
// AvailableHeuristics is a map that holds the name of available
// heuristics to the actual heuristic for easy lookup. It will be
// filled during init().
AvailableHeuristics = make(map[string]AttachmentHeuristic)
)
func init() {
// Fill the map from heuristic names to available heuristics for easy
// lookup.
for _, h := range availableHeuristics {
AvailableHeuristics[h.Name()] = h
}
}
2017-08-11 07:14:41 +03:00
// ChannelController is a simple interface that allows an auto-pilot agent to
// open a channel within the graph to a target peer, close targeted channels,
// or add/remove funds from existing channels via a splice in/out mechanisms.
type ChannelController interface {
// OpenChannel opens a channel to a target peer, using at most amt
// funds. This means that the resulting channel capacity might be
// slightly less to account for fees. This function should un-block
// immediately after the funding transaction that marks the channel
// open has been broadcast.
OpenChannel(target *btcec.PublicKey, amt btcutil.Amount) error
2017-08-11 07:14:41 +03:00
// CloseChannel attempts to close out the target channel.
//
// TODO(roasbeef): add force option?
CloseChannel(chanPoint *wire.OutPoint) error
}