chanfunding

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2020 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type Assembler 

type Assembler interface {
	// ProvisionChannel returns a populated Intent that can be used to
	// further the channel funding workflow. Depending on the
	// implementation of Assembler, additional state machine (Intent)
	// actions may be required before the FundingOutput and ChanPoint are
	// made available to the caller.
	ProvisionChannel(*Request) (Intent, error)
}

Assembler is an abstract object that is capable of assembling everything needed to create a new funding output. As an example, this assembler may be our core backing wallet, an interactive PSBT based assembler, an assembler than can aggregate multiple intents into a single funding transaction, or an external protocol that creates a funding output out-of-band such as channel factories.

type CannedAssembler 

type CannedAssembler struct {
	// contains filtered or unexported fields
}

CannedAssembler is a type of chanfunding.Assembler wherein the funding transaction is constructed outside of lnd, and may already exist. This Assembler serves as a shim which gives the funding flow the only thing it actually needs to proceed: the channel point.

func NewCannedAssembler 

func NewCannedAssembler(chanPoint wire.OutPoint, fundingAmt btcutil.Amount,
	localKey *keychain.KeyDescriptor,
	remoteKey *btcec.PublicKey, initiator bool) *CannedAssembler

NewCannedAssembler creates a new CannedAssembler from the material required to construct a funding output and channel point.

func (*CannedAssembler) ProvisionChannel 

func (c *CannedAssembler) ProvisionChannel(req *Request) (Intent, error)

ProvisionChannel creates a new ShimIntent given the passed funding Request. The returned intent is immediately able to provide the channel point and funding output as they've already been created outside lnd.

NOTE: This method satisfies the chanfunding.Assembler interface.

type Coin 

type Coin struct {
	wire.TxOut

	wire.OutPoint
}

Coin represents a spendable UTXO which is available for channel funding. This UTXO need not reside in our internal wallet as an example, and instead may be derived from an existing watch-only wallet. It wraps both the output present within the UTXO set, and also the outpoint that generates this coin.

func CoinSelect 

func CoinSelect(feeRate chainfee.SatPerKWeight, amt btcutil.Amount,
	coins []Coin) ([]Coin, btcutil.Amount, error)

CoinSelect attempts to select a sufficient amount of coins, including a change output to fund amt satoshis, adhering to the specified fee rate. The specified fee rate should be expressed in sat/kw for coin selection to function properly.

func CoinSelectSubtractFees 

func CoinSelectSubtractFees(feeRate chainfee.SatPerKWeight, amt,
	dustLimit btcutil.Amount, coins []Coin) ([]Coin, btcutil.Amount,
	btcutil.Amount, error)

CoinSelectSubtractFees attempts to select coins such that we'll spend up to amt in total after fees, adhering to the specified fee rate. The selected coins, the final output and change values are returned.

type CoinSelectionLocker 

type CoinSelectionLocker interface {
	// WithCoinSelectLock will execute the passed function closure in a
	// synchronized manner preventing any coin selection operations from
	// proceeding while the closure if executing. This can be seen as the
	// ability to execute a function closure under an exclusive coin
	// selection lock.
	WithCoinSelectLock(func() error) error
}

CoinSelectionLocker is an interface that allows the caller to perform an operation, which is synchronized with all coin selection attempts. This can be used when an operation requires that all coin selection operations cease forward progress. Think of this as an exclusive lock on coin selection operations.

type CoinSource 

type CoinSource interface {
	// ListCoins returns all UTXOs from the source that have between
	// minConfs and maxConfs number of confirmations.
	ListCoins(minConfs, maxConfs int32) ([]Coin, error)

	// CoinFromOutPoint attempts to locate details pertaining to a coin
	// based on its outpoint. If the coin isn't under the control of the
	// backing CoinSource, then an error should be returned.
	CoinFromOutPoint(wire.OutPoint) (*Coin, error)
}

CoinSource is an interface that allows a caller to access a source of UTXOs to use when attempting to fund a new channel.

type ErrInsufficientFunds 

type ErrInsufficientFunds struct {
	// contains filtered or unexported fields
}

ErrInsufficientFunds is a type matching the error interface which is returned when coin selection for a new funding transaction fails to due having an insufficient amount of confirmed funds.

func (*ErrInsufficientFunds) Error 

func (e *ErrInsufficientFunds) Error() string

Error returns a human readable string describing the error.

type FullIntent 

type FullIntent struct {
	ShimIntent

	// InputCoins are the set of coins selected as inputs to this funding
	// transaction.
	InputCoins []Coin

	// ChangeOutputs are the set of outputs that the Assembler will use as
	// change from the main funding transaction.
	ChangeOutputs []*wire.TxOut
	// contains filtered or unexported fields
}

FullIntent is an intent that is fully backed by the internal wallet. This intent differs from the ShimIntent, in that the funding transaction will be constructed internally, and will consist of only inputs we wholly control. This Intent implements a basic state machine that must be executed in order before CompileFundingTx can be called.

Steps to final channel provisioning:

  1. Call BindKeys to notify the intent which keys to use when constructing the multi-sig output.
  2. Call CompileFundingTx afterwards to obtain the funding transaction.

If either of these steps fail, then the Cancel method MUST be called.

func (*FullIntent) BindKeys 

func (f *FullIntent) BindKeys(localKey *keychain.KeyDescriptor,
	remoteKey *btcec.PublicKey)

BindKeys is a method unique to the FullIntent variant. This allows the caller to decide precisely which keys are used in the final funding transaction. This is kept out of the main Assembler as these may may not necessarily be under full control of the wallet. Only after this method has been executed will CompileFundingTx succeed.

func (*FullIntent) Cancel 

func (f *FullIntent) Cancel()

Cancel allows the caller to cancel a funding Intent at any time. This will return any resources such as coins back to the eligible pool to be used in order channel fundings.

NOTE: Part of the chanfunding.Intent interface.

func (*FullIntent) CompileFundingTx 

func (f *FullIntent) CompileFundingTx(extraInputs []*wire.TxIn,
	extraOutputs []*wire.TxOut) (*wire.MsgTx, error)

CompileFundingTx is to be called after BindKeys on the sub-intent has been called. This method will construct the final funding transaction, and fully sign all inputs that are known by the backing CoinSource. After this method returns, the Intent is assumed to be complete, as the output can be created at any point.

type FundingKeys 

type FundingKeys struct {
	// LocalKey is our multi-sig key.
	LocalKey *keychain.KeyDescriptor

	// RemoteKey is the multi-sig key of the remote party.
	RemoteKey *btcec.PublicKey
}

FundingKeys couples our multi-sig key along with the remote party's key.

type FundingTxAssembler 

type FundingTxAssembler interface {
	Assembler

	// FundingTxAvailable is an empty method that an assembler can
	// implement to signal to callers that its able to provide the funding
	// transaction for the channel via the intent it returns.
	FundingTxAvailable()
}

FundingTxAssembler is a super-set of the regular Assembler interface that's also able to provide a fully populated funding transaction via the intents that it produuces.

type Intent 

type Intent interface {
	// FundingOutput returns the witness script, and the output that
	// creates the funding output.
	FundingOutput() ([]byte, *wire.TxOut, error)

	// ChanPoint returns the final outpoint that will create the funding
	// output described above.
	ChanPoint() (*wire.OutPoint, error)

	// RemoteFundingAmt is the amount the remote party put into the
	// channel.
	RemoteFundingAmt() btcutil.Amount

	// LocalFundingAmt is the amount we put into the channel. This may
	// differ from the local amount requested, as depending on coin
	// selection, we may bleed from of that LocalAmt into fees to minimize
	// change.
	LocalFundingAmt() btcutil.Amount

	// Cancel allows the caller to cancel a funding Intent at any time.
	// This will return any resources such as coins back to the eligible
	// pool to be used in order channel fundings.
	Cancel()
}

Intent is returned by an Assembler and represents the base functionality the caller needs to proceed with channel funding on a higher level. If the Cancel method is called, then all resources assembled to fund the channel will be released back to the eligible pool.

type OutpointLocker 

type OutpointLocker interface {
	// LockOutpoint locks a target outpoint, rendering it unusable for coin
	// selection.
	LockOutpoint(o wire.OutPoint)

	// UnlockOutpoint unlocks a target outpoint, allowing it to be used for
	// coin selection once again.
	UnlockOutpoint(o wire.OutPoint)
}

OutpointLocker allows a caller to lock/unlock an outpoint. When locked, the outpoints shouldn't be used for any sort of channel funding of coin selection. Locked outpoints are not expected to be persisted between restarts.

type Request 

type Request struct {
	// LocalAmt is the amount of coins we're placing into the funding
	// output.
	LocalAmt btcutil.Amount

	// RemoteAmt is the amount of coins the remote party is contributing to
	// the funding output.
	RemoteAmt btcutil.Amount

	// MinConfs controls how many confirmations a coin need to be eligible
	// to be used as an input to the funding transaction. If this value is
	// set to zero, then zero conf outputs may be spent.
	MinConfs int32

	// SubtractFees should be set if we intend to spend exactly LocalAmt
	// when opening the channel, subtracting the fees from the funding
	// output. This can be used for instance to use all our remaining funds
	// to open the channel, since it will take fees into
	// account.
	SubtractFees bool

	// FeeRate is the fee rate in sat/kw that the funding transaction
	// should carry.
	FeeRate chainfee.SatPerKWeight

	// ChangeAddr is a closure that will provide the Assembler with a
	// change address for the funding transaction if needed.
	ChangeAddr func() (btcutil.Address, error)
}

Request is a new request for funding a channel. The items in the struct governs how the final channel point will be provisioned by the target Assembler.

type ShimIntent 

type ShimIntent struct {
	// contains filtered or unexported fields
}

ShimIntent is an intent created by the CannedAssembler which represents a funding output to be created that was constructed outside the wallet. This might be used when a hardware wallet, or a channel factory is the entity crafting the funding transaction, and not lnd.

func (*ShimIntent) Cancel 

func (s *ShimIntent) Cancel()

Cancel allows the caller to cancel a funding Intent at any time. This will return any resources such as coins back to the eligible pool to be used in order channel fundings.

NOTE: This method satisfies the chanfunding.Intent interface.

func (*ShimIntent) ChanPoint 

func (s *ShimIntent) ChanPoint() (*wire.OutPoint, error)

ChanPoint returns the final outpoint that will create the funding output described above.

NOTE: This method satisfies the chanfunding.Intent interface.

func (*ShimIntent) FundingOutput 

func (s *ShimIntent) FundingOutput() ([]byte, *wire.TxOut, error)

FundingOutput returns the witness script, and the output that creates the funding output.

NOTE: This method satisfies the chanfunding.Intent interface.

func (*ShimIntent) LocalFundingAmt 

func (s *ShimIntent) LocalFundingAmt() btcutil.Amount

RemoteFundingAmt is the amount the remote party put into the channel.

NOTE: This method satisfies the chanfunding.Intent interface.

func (*ShimIntent) MultiSigKeys 

func (s *ShimIntent) MultiSigKeys() (*FundingKeys, error)

MultiSigKeys returns the committed multi-sig keys, but only if they've been specified/provided.

func (*ShimIntent) RemoteFundingAmt 

func (s *ShimIntent) RemoteFundingAmt() btcutil.Amount

LocalFundingAmt is the amount we put into the channel. This may differ from the local amount requested, as depending on coin selection, we may bleed from of that LocalAmt into fees to minimize change.

NOTE: This method satisfies the chanfunding.Intent interface.

type WalletAssembler 

type WalletAssembler struct {
	// contains filtered or unexported fields
}

WalletAssembler is an instance of the Assembler interface that is backed by a full wallet. This variant of the Assembler interface will produce the entirety of the funding transaction within the wallet. This implements the typical funding flow that is initiated either on the p2p level or using the CLi.

func NewWalletAssembler 

func NewWalletAssembler(cfg WalletConfig) *WalletAssembler

NewWalletAssembler creates a new instance of the WalletAssembler from a fully populated wallet config.

func (*WalletAssembler) FundingTxAvailable 

func (w *WalletAssembler) FundingTxAvailable()

FundingTxAvailable is an empty method that an assembler can implement to signal to callers that its able to provide the funding transaction for the channel via the intent it returns.

NOTE: This method is a part of the FundingTxAssembler interface.

func (*WalletAssembler) ProvisionChannel 

func (w *WalletAssembler) ProvisionChannel(r *Request) (Intent, error)

ProvisionChannel is the main entry point to begin a funding workflow given a fully populated request. The internal WalletAssembler will perform coin selection in a goroutine safe manner, returning an Intent that will allow the caller to finalize the funding process.

NOTE: To cancel the funding flow the Cancel() method on the returned Intent, MUST be called.

NOTE: This is a part of the chanfunding.Assembler interface.

type WalletConfig 

type WalletConfig struct {
	// CoinSource is what the WalletAssembler uses to list/locate coins.
	CoinSource CoinSource

	// CoinSelectionLocker allows the WalletAssembler to gain exclusive
	// access to the current set of coins returned by the CoinSource.
	CoinSelectLocker CoinSelectionLocker

	// CoinLocker is what the WalletAssembler uses to lock coins that may
	// be used as inputs for a new funding transaction.
	CoinLocker OutpointLocker

	// Signer allows the WalletAssembler to sign inputs on any potential
	// funding transactions.
	Signer input.Signer

	// DustLimit is the current dust limit. We'll use this to ensure that
	// we don't make dust outputs on the funding transaction.
	DustLimit btcutil.Amount
}

WalletConfig is the main config of the WalletAssembler.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.