Documentation
¶
Index ¶
- Variables
- func DisableLog()
- func UseLogger(logger btclog.Logger)
- type Agent
- func (a *Agent) OnBalanceChange()
- func (a *Agent) OnChannelClose(closedChans ...lnwire.ShortChannelID)
- func (a *Agent) OnChannelOpen(c Channel)
- func (a *Agent) OnChannelOpenFailure()
- func (a *Agent) OnChannelPendingOpen()
- func (a *Agent) OnNodeUpdates()
- func (a *Agent) Start() error
- func (a *Agent) Stop() error
- type AttachmentDirective
- type AttachmentHeuristic
- type Channel
- type ChannelController
- type ChannelEdge
- type ChannelGraph
- type Config
- type ConstrainedPrefAttachment
- type HeuristicConstraints
- type Manager
- type ManagerCfg
- type Node
- type NodeID
Constants ¶
This section is empty.
Variables ¶
var ErrNoPositive = errors.New("no positive weights left")
ErrNoPositive is returned from weightedChoice when there are no positive weights left to choose from.
Functions ¶
func DisableLog ¶
func DisableLog()
DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent implements a closed-loop control system which seeks to autonomously optimize the allocation of satoshis within channels throughput the network's channel graph. An agent is configurable by swapping out different AttachmentHeuristic strategies. The agent uses external signals such as the wallet balance changing, or new channels being opened/closed for the local node as an indicator to re-examine its internal state, and the amount of available funds in order to make updated decisions w.r.t the channel graph. The Agent will automatically open, close, and splice in/out channel as necessary for it to step closer to its optimal state.
TODO(roasbeef): prob re-word
func New ¶
New creates a new instance of the Agent instantiated using the passed configuration and initial channel state. The initial channel state slice should be populated with the set of Channels that are currently opened by the backing Lightning Node.
func (*Agent) OnBalanceChange ¶
func (a *Agent) OnBalanceChange()
OnBalanceChange is a callback that should be executed each time the balance of the backing wallet changes.
func (*Agent) OnChannelClose ¶
func (a *Agent) OnChannelClose(closedChans ...lnwire.ShortChannelID)
OnChannelClose is a callback that should be executed each time a prior channel has been closed for any reason. This includes regular closes, force closes, and channel breaches.
func (*Agent) OnChannelOpen ¶
OnChannelOpen is a callback that should be executed each time a new channel is manually opened by the user or any system outside the autopilot agent.
func (*Agent) OnChannelOpenFailure ¶
func (a *Agent) OnChannelOpenFailure()
OnChannelOpenFailure is a callback that should be executed when the autopilot has attempted to open a channel, but failed. In this case we can retry channel creation with a different node.
func (*Agent) OnChannelPendingOpen ¶
func (a *Agent) OnChannelPendingOpen()
OnChannelPendingOpen is a callback that should be executed each time a new channel is opened, either by the agent or an external subsystems, but is still pending.
func (*Agent) OnNodeUpdates ¶
func (a *Agent) OnNodeUpdates()
OnNodeUpdates is a callback that should be executed each time our channel graph has new nodes or their node announcements are updated.
type AttachmentDirective ¶
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
// ChanAmt is the size of the channel that should be opened, expressed
// in satoshis.
ChanAmt pfcutil.Amount
// Addrs is a list of addresses that the target peer may be reachable
// at.
Addrs []net.Addr
// Score is the score given by the heuristic for opening a channel of
// the given size to this node.
Score float64
}
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 AttachmentHeuristic ¶
type AttachmentHeuristic interface {
// NeedMoreChans is a predicate that should return true if, given the
// passed parameters, and its internal state, more channels should be
// opened within the channel graph. If the heuristic decides that we do
// indeed need more channels, then the second argument returned will
// represent the amount of additional funds to be used towards creating
// channels. This method should also return the exact *number* of
// additional channels that are needed in order to converge towards our
// ideal state.
NeedMoreChans(chans []Channel, balance pfcutil.Amount) (pfcutil.Amount, uint32, bool)
// NodeScores is a method that given the current channel graph, current
// set of local channels and funds available, scores the given nodes
// according to the preference of opening a channel with them. The
// returned channel candidates maps the NodeID to an attachemnt
// directive containing a score and a channel size.
//
// The scores will be in the range [0, M], where 0 indicates no
// improvement in connectivity if a channel is opened to this node,
// while M is the maximum possible improvement in connectivity. The
// size of M is up to the implementation of this interface, so scores
// must be normalized if compared against other implementations.
//
// NOTE: A NodeID not found in the returned map is implicitly given a
// score of 0.
NodeScores(g ChannelGraph, chans []Channel,
fundsAvailable pfcutil.Amount, nodes map[NodeID]struct{}) (
map[NodeID]*AttachmentDirective, error)
}
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 Channel ¶
type Channel 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 pfcutil.Amount
// FundedAmt is the amount the local node funded into the target
// channel.
//
// TODO(roasbeef): need this?
FundedAmt pfcutil.Amount
// Node is the peer that this channel has been established with.
Node NodeID
}
Channel is a simple struct which contains relevant details of a particular channel within the channel graph. The fields in this struct may be used a signals for various AttachmentHeuristic implementations.
type ChannelController ¶
type ChannelController interface {
// OpenChannel opens a channel to a target peer, with a capacity of the
// specified amount. This function should un-block immediately after
// the funding transaction that marks the channel open has been
// broadcast.
OpenChannel(target *pfcec.PublicKey, amt pfcutil.Amount) error
// CloseChannel attempts to close out the target channel.
//
// TODO(roasbeef): add force option?
CloseChannel(chanPoint *wire.OutPoint) error
// SpliceIn attempts to add additional funds to the target channel via
// a splice in mechanism. The new channel with an updated capacity
// should be returned.
SpliceIn(chanPoint *wire.OutPoint, amt pfcutil.Amount) (*Channel, error)
// SpliceOut attempts to remove funds from an existing channels using a
// splice out mechanism. The removed funds from the channel should be
// returned to an output under the control of the backing wallet.
SpliceOut(chanPoint *wire.OutPoint, amt pfcutil.Amount) (*Channel, error)
}
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 ChannelEdge ¶
type ChannelEdge struct {
// Channel contains the attributes of this channel.
Channel
// Peer is the peer that this channel creates an edge to in the channel
// graph.
Peer Node
}
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 will allow callers to traverse the graph in an object-oriented manner.
type ChannelGraph ¶
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
}
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??
func ChannelGraphFromDatabase ¶
func ChannelGraphFromDatabase(db *channeldb.ChannelGraph) ChannelGraph
ChannelGraphFromDatabase returns an instance of the autopilot.ChannelGraph backed by a live, open channeldb instance.
type Config ¶
type Config struct {
// Self is the identity public key of the Lightning Network node that
// is being driven by the agent. This is used to ensure that we don't
// accidentally attempt to open a channel with ourselves.
Self *pfcec.PublicKey
// Heuristic is an attachment heuristic which will govern to whom we
// open channels to, and also what those channels look like in terms of
// desired capacity. The Heuristic will take into account the current
// state of the graph, our set of open channels, and the amount of
// available funds when determining how channels are to be opened.
// Additionally, a heuristic make also factor in extra-graph
// information in order to make more pertinent recommendations.
Heuristic AttachmentHeuristic
// ChanController is an interface that is able to directly manage the
// creation, closing and update of channels within the network.
ChanController ChannelController
// ConnectToPeer attempts to connect to the peer using one of its
// advertised addresses. The boolean returned signals whether the peer
// was already connected.
ConnectToPeer func(*pfcec.PublicKey, []net.Addr) (bool, error)
// DisconnectPeer attempts to disconnect the peer with the given public
// key.
DisconnectPeer func(*pfcec.PublicKey) error
// WalletBalance is a function closure that should return the current
// available balance of the backing wallet.
WalletBalance func() (pfcutil.Amount, error)
// Graph is an abstract channel graph that the Heuristic and the Agent
// will use to make decisions w.r.t channel allocation and placement
// within the graph.
Graph ChannelGraph
// Constraints is the set of constraints the autopilot must adhere to
// when opening channels.
Constraints *HeuristicConstraints
}
Config couples all the items that an autopilot agent needs to function. All items within the struct MUST be populated for the Agent to be able to carry out its duties.
type ConstrainedPrefAttachment ¶
type ConstrainedPrefAttachment struct {
// contains filtered or unexported fields
}
ConstrainedPrefAttachment is an implementation of the AttachmentHeuristic interface that implement a constrained non-linear preferential attachment heuristic. This means that given a threshold to allocate to automatic channel establishment, the heuristic will attempt to favor connecting to nodes which already have a set amount of links, selected by sampling from a power law distribution. The attachment is non-linear in that it favors nodes with a higher in-degree but less so that regular linear preferential attachment. As a result, this creates smaller and less clusters than regular linear preferential attachment.
TODO(roasbeef): BA, with k=-3
func NewConstrainedPrefAttachment ¶
func NewConstrainedPrefAttachment( cfg *HeuristicConstraints) *ConstrainedPrefAttachment
NewConstrainedPrefAttachment creates a new instance of a ConstrainedPrefAttachment heuristics given bounds on allowed channel sizes, and an allocation amount which is interpreted as a percentage of funds that is to be committed to channels at all times.
func (*ConstrainedPrefAttachment) NeedMoreChans ¶
func (p *ConstrainedPrefAttachment) NeedMoreChans(channels []Channel, funds pfcutil.Amount) (pfcutil.Amount, uint32, bool)
NeedMoreChans is a predicate that should return true if, given the passed parameters, and its internal state, more channels should be opened within the channel graph. If the heuristic decides that we do indeed need more channels, then the second argument returned will represent the amount of additional funds to be used towards creating channels.
NOTE: This is a part of the AttachmentHeuristic interface.
func (*ConstrainedPrefAttachment) NodeScores ¶
func (p *ConstrainedPrefAttachment) NodeScores(g ChannelGraph, chans []Channel, fundsAvailable pfcutil.Amount, nodes map[NodeID]struct{}) ( map[NodeID]*AttachmentDirective, error)
NodeScores is a method that given the current channel graph, current set of local channels and funds available, scores the given nodes according the the preference of opening a channel with them.
The heuristic employed by this method is one that attempts to promote a scale-free network globally, via local attachment preferences for new nodes joining the network with an amount of available funds to be allocated to channels. Specifically, we consider the degree of each node (and the flow in/out of the node available via its open channels) and utilize the Barabási–Albert model to drive our recommended attachment heuristics. If implemented globally for each new participant, this results in a channel graph that is scale-free and follows a power law distribution with k=-3.
The returned scores will be in the range [0.0, 1.0], where higher scores are given to nodes already having high connectivity in the graph.
NOTE: This is a part of the AttachmentHeuristic interface.
type HeuristicConstraints ¶
type HeuristicConstraints struct {
// MinChanSize is the smallest channel that the autopilot agent should
// create.
MinChanSize pfcutil.Amount
// MaxChanSize the largest channel that the autopilot agent should
// create.
MaxChanSize pfcutil.Amount
// ChanLimit the maximum number of channels that should be created.
ChanLimit uint16
// Allocation the percentage of total funds that should be committed to
// automatic channel establishment.
Allocation float64
// MaxPendingOpens is the maximum number of pending channel
// establishment goroutines that can be lingering. We cap this value in
// order to control the level of parallelism caused by the autopilot
// agent.
MaxPendingOpens uint16
}
HeuristicConstraints is a struct that indicate the constraints an autopilot heuristic must adhere to when opening channels.
type Manager ¶
Manager is struct that manages an autopilot agent, making it possible to enable and disable it at will, and hand it relevant external information. It implements the autopilot grpc service, which is used to get data about the running autopilot, and give it relevant information.
func NewManager ¶
func NewManager(cfg *ManagerCfg) (*Manager, error)
NewManager creates a new instance of the Manager from the passed config.
func (*Manager) StartAgent ¶
StartAgent creates and starts an autopilot agent from the Manager's config.
type ManagerCfg ¶
type ManagerCfg struct {
// Self is the public key of the lnd instance. It is used to making
// sure the autopilot is not opening channels to itself.
Self *pfcec.PublicKey
// PilotCfg is the config of the autopilot agent managed by the
// Manager.
PilotCfg *Config
// ChannelState is a function closure that returns the current set of
// channels managed by this node.
ChannelState func() ([]Channel, error)
// SubscribeTransactions is used to get a subscription for transactions
// relevant to this node's wallet.
SubscribeTransactions func() (lnwallet.TransactionSubscription, error)
// SubscribeTopology is used to get a subscription for topology changes
// on the network.
SubscribeTopology func() (*routing.TopologyClient, error)
}
ManagerCfg houses a set of values and methods that is passed to the Manager for it to properly manage its autopilot agent.
type Node ¶
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
// 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
}
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
Source Files