lnwallet

package
v0.3.6 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2022 License: MIT Imports: 44 Imported by: 0

README

lnwallet

Build Status MIT licensed GoDoc

The lnwallet package implements an abstracted wallet controller that is able to drive channel funding workflows, a number of script utilities, witness generation functions for the various Lightning scripts, revocation key derivation, and the commitment update state machine.

The package is used within dcrlnd as the core wallet of the daemon. The wallet itself is composed of several distinct interfaces that decouple the implementation of things like signing and blockchain access. This separation allows new WalletController implementations to be easily dropped into dcrlnd without disrupting the code base. A series of integration tests at the interface level are also in place to ensure conformance of the implementation with the interface.

Installation and Updating

$ go get -u github.com/decred/dcrlnd/lnwallet

Documentation

Index

Constants

View Source 
const (
	// Add is an update type that adds a new HTLC entry into the log.
	// Either side can add a new pending HTLC by adding a new Add entry
	// into their update log.
	Add updateType = iota

	// Fail is an update type which removes a prior HTLC entry from the
	// log. Adding a Fail entry to ones log will modify the _remote_
	// parties update log once a new commitment view has been evaluated
	// which contains the Fail entry.
	Fail

	// MalformedFail is an update type which removes a prior HTLC entry
	// from the log. Adding a MalformedFail entry to ones log will modify
	// the _remote_ parties update log once a new commitment view has been
	// evaluated which contains the MalformedFail entry. The difference
	// from Fail type lie in the different data we have to store.
	MalformedFail

	// Settle is an update type which settles a prior HTLC crediting the
	// balance of the receiving node. Adding a Settle entry to a log will
	// result in the settle entry being removed on the log as well as the
	// original add entry from the remote party's log after the next state
	// transition.
	Settle

	// FeeUpdate is an update type sent by the channel initiator that
	// updates the fee rate used when signing the commitment transaction.
	FeeUpdate
)
View Source 
const (
	// CommitmentTypeLegacy is the legacy commitment format with a tweaked
	// to_remote key.
	CommitmentTypeLegacy = iota

	// CommitmentTypeTweakless is a newer commitment format where the
	// to_remote key is static.
	CommitmentTypeTweakless

	// CommitmentTypeAnchors is a commitment type that is tweakless, and
	// has extra anchor ouputs in order to bump the fee of the commitment
	// transaction.
	CommitmentTypeAnchors
)
View Source 
const (
	// StateHintSize is the total number of bytes used between the sequence
	// number and locktime of the commitment transaction use to encode a hint
	// to the state number of a particular commitment transaction.
	StateHintSize = 6
)

Variables

View Source 
var (
	// ErrChanClosing is returned when a caller attempts to close a channel
	// that has already been closed or is in the process of being closed.
	ErrChanClosing = fmt.Errorf("channel is being closed, operation disallowed")

	// ErrNoWindow is returned when revocation window is exhausted.
	ErrNoWindow = fmt.Errorf("unable to sign new commitment, the current" +
		" revocation window is exhausted")

	// ErrMaxSizeCost is returned when the cost/size
	// exceeds the widely used maximum allowed policy size limit. In this
	// case the commitment transaction can't be propagated through the
	// network.
	ErrMaxSizeCost = fmt.Errorf("commitment transaction exceed max " +
		"available cost")

	// ErrMaxHTLCNumber is returned when a proposed HTLC would exceed the
	// maximum number of allowed HTLC's if committed in a state transition
	ErrMaxHTLCNumber = fmt.Errorf("commitment transaction exceed max " +
		"htlc number")

	// ErrMaxPendingAmount is returned when a proposed HTLC would exceed
	// the overall maximum pending value of all HTLCs if committed in a
	// state transition.
	ErrMaxPendingAmount = fmt.Errorf("commitment transaction exceed max" +
		"overall pending htlc value")

	// ErrBelowChanReserve is returned when a proposed HTLC would cause
	// one of the peer's funds to dip below the channel reserve limit.
	ErrBelowChanReserve = fmt.Errorf("commitment transaction dips peer " +
		"below chan reserve")

	// ErrBelowMinHTLC is returned when a proposed HTLC has a value that
	// is below the minimum HTLC value constraint for either us or our
	// peer depending on which flags are set.
	ErrBelowMinHTLC = fmt.Errorf("proposed HTLC value is below minimum " +
		"allowed HTLC value")

	// ErrInvalidHTLCAmt signals that a proposed HTLC has a value that is
	// not positive.
	ErrInvalidHTLCAmt = fmt.Errorf("proposed HTLC value must be positive")

	// ErrCannotSyncCommitChains is returned if, upon receiving a ChanSync
	// message, the state machine deems that is unable to properly
	// synchronize states with the remote peer. In this case we should fail
	// the channel, but we won't automatically force close.
	ErrCannotSyncCommitChains = fmt.Errorf("unable to sync commit chains")

	// ErrInvalidLastCommitSecret is returned in the case that the
	// commitment secret sent by the remote party in their
	// ChannelReestablish message doesn't match the last secret we sent.
	ErrInvalidLastCommitSecret = fmt.Errorf("commit secret is incorrect")

	// ErrInvalidLocalUnrevokedCommitPoint is returned in the case that the
	// commitment point sent by the remote party in their
	// ChannelReestablish message doesn't match the last unrevoked commit
	// point they sent us.
	ErrInvalidLocalUnrevokedCommitPoint = fmt.Errorf("unrevoked commit " +
		"point is invalid")

	// ErrCommitSyncRemoteDataLoss is returned in the case that we receive
	// a ChannelReestablish message from the remote that advertises a
	// NextLocalCommitHeight that is lower than what they have already
	// ACKed, or a RemoteCommitTailHeight that is lower than our revoked
	// height. In this case we should force close the channel such that
	// both parties can retrieve their funds.
	ErrCommitSyncRemoteDataLoss = fmt.Errorf("possible remote commitment " +
		"state data loss")
)
View Source 
var (
	// DefaultPublicPassphrase is the default public passphrase used for the
	// wallet.
	DefaultPublicPassphrase = []byte("public")

	// DefaultPrivatePassphrase is the default private passphrase used for
	// the wallet.
	DefaultPrivatePassphrase = []byte("hello")

	// ErrDoubleSpend is returned from PublishTransaction in case the
	// tx being published is spending an output spent by a conflicting
	// transaction.
	ErrDoubleSpend = errors.New("transaction rejected: output already spent")

	// ErrNotMine is an error denoting that a WalletController instance is
	// unable to spend a specified output.
	ErrNotMine = errors.New("the passed output doesn't belong to the wallet")
)
View Source 
var ErrNoOutputs = errors.New("no outputs")

ErrNoOutputs is returned if we try to create a transaction with no outputs or send coins to a set of outputs that is empty.

View Source 
var (
	// ErrPsbtFundingRequired is the error that is returned during the
	// contribution handling process if the process should be paused for
	// the construction of a PSBT outside of lnd's wallet.
	ErrPsbtFundingRequired = errors.New("PSBT funding required")
)
View Source 
var (
	// TimelockShift is used to make sure the commitment transaction is
	// spendable by setting the locktime with it so that it is larger than
	// 500,000,000, thus interpreting it as Unix epoch timestamp and not a
	// block height. It is also smaller than the current timestamp which
	// has bit (1 << 30) set, so there is no risk of having the commitment
	// transaction be rejected. This way we can safely use the lower 24
	// bits of the locktime field for part of the obscured commitment
	// transaction number.
	TimelockShift = uint32(1 << 29)
)

Functions

func CommitScriptAnchors added in v0.3.0 

func CommitScriptAnchors(localChanCfg,
	remoteChanCfg *channeldb.ChannelConfig) (*ScriptInfo,
	*ScriptInfo, error)

CommitScriptAnchors return the scripts to use for the local and remote anchor.

func CommitSize added in v0.3.0 

func CommitSize(chanType channeldb.ChannelType) int64

CommitSize returns the base commitment size before adding HTLCs.

func CoopCloseBalance added in v0.3.0 

func CoopCloseBalance(chanType channeldb.ChannelType, isInitiator bool,
	coopCloseFee dcrutil.Amount, localCommit channeldb.ChannelCommitment) (
	dcrutil.Amount, dcrutil.Amount, error)

CoopCloseBalance returns the final balances that should be used to create the cooperative close tx, given the channel type and transaction fee.

func CreateCommitTx 

func CreateCommitTx(chanType channeldb.ChannelType,
	fundingOutput wire.TxIn, keyRing *CommitmentKeyRing,
	localChanCfg, remoteChanCfg *channeldb.ChannelConfig,
	amountToLocal, amountToRemote dcrutil.Amount,
	numHTLCs int64) (*wire.MsgTx, error)

CreateCommitTx creates a commitment transaction, spending from specified funding output. The commitment transaction contains two outputs: one local output paying to the "owner" of the commitment transaction which can be spent after a relative block delay or revocation event, and a remote output paying the counterparty within the channel, which can be spent immediately or after a delay depending on the commitment type..

func CreateCommitmentTxns 

func CreateCommitmentTxns(localBalance, remoteBalance dcrutil.Amount,
	ourChanCfg, theirChanCfg *channeldb.ChannelConfig,
	localCommitPoint, remoteCommitPoint *secp256k1.PublicKey,
	fundingTxIn wire.TxIn, chanType channeldb.ChannelType,
	chainParams *chaincfg.Params) (*wire.MsgTx, *wire.MsgTx, error)

CreateCommitmentTxns is a helper function that creates the initial commitment transaction for both parties. This function is used during the initial funding workflow as both sides must generate a signature for the remote party's commitment transaction, and verify the signature for their version of the commitment transaction.

func CreateCooperativeCloseTx 

func CreateCooperativeCloseTx(fundingTxIn wire.TxIn,
	localDust, remoteDust, ourBalance, theirBalance dcrutil.Amount,
	ourDeliveryScript, theirDeliveryScript []byte) *wire.MsgTx

CreateCooperativeCloseTx creates a transaction which if signed by both parties, then broadcast cooperatively closes an active channel. The creation of the closure transaction is modified by a boolean indicating if the party constructing the channel is the initiator of the closure. Currently it is expected that the initiator pays the transaction fees for the closing transaction in full.

func CreateTestChannels 

func CreateTestChannels(chanType channeldb.ChannelType) (
	*LightningChannel, *LightningChannel, func(), error)

CreateTestChannels creates to fully populated channels to be used within testing fixtures. The channels will be returned as if the funding process has just completed. The channel itself is funded with 10 DCR, with 5 DCR allocated to each side. Within the channel, Alice is the initiator. The function also returns a "cleanup" function that is meant to be called once the test has been finalized. The clean up function will remote all temporary files created. If tweaklessCommits is true, then the commits within the channels will use the new format, otherwise the legacy format.

func DefaultDustLimit 

func DefaultDustLimit() dcrutil.Amount

DefaultDustLimit is used to calculate the default dust threshold limit, assuming the network uses the defaultRelayFeePerKb of the wallet.

func DeriveStateHintObfuscator 

func DeriveStateHintObfuscator(key1, key2 *secp256k1.PublicKey) [StateHintSize]byte

DeriveStateHintObfuscator derives the bytes to be used for obfuscating the state hints from the root to be used for a new channel. The obfuscator is generated via the following computation:

  • sha256(initiatorKey || responderKey)[26:]
  • where both keys are the multi-sig keys of the respective parties

The first 6 bytes of the resulting hash are used as the state hint.

func DisableLog 

func DisableLog()

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

func DustThresholdForRelayFee 

func DustThresholdForRelayFee(relayFeeRate chainfee.AtomPerKByte) dcrutil.Amount

DustThresholdForRelayFee returns the minimum amount an output of the given size should have in order to not be considered a dust output for networks using the provided relay fee.

It is assumed the output is paying to a P2PKH script.

func ErrNumConfsTooLarge added in v0.2.0 

func ErrNumConfsTooLarge(numConfs, maxNumConfs uint32) error

ErrNumConfsTooLarge returns an error indicating that the number of confirmations required for a channel is too large.

func ForceStateTransition added in v0.2.0 

func ForceStateTransition(chanA, chanB *LightningChannel) error

ForceStateTransition executes the necessary interaction between the two commitment state machines to transition to a new state locking in any pending updates. This method is useful when testing interactions between two live state machines.

func GetStateNumHint 

func GetStateNumHint(commitTx *wire.MsgTx, obfuscator [StateHintSize]byte) uint64

GetStateNumHint recovers the current state number given a commitment transaction which has previously had the state number encoded within it via setStateNumHint and a shared obfuscator.

See setStateNumHint for further details w.r.t exactly how the state-hints are encoded.

func HtlcSecondLevelInputSequence added in v0.3.0 

func HtlcSecondLevelInputSequence(chanType channeldb.ChannelType) uint32

HtlcSecondLevelInputSequence dictates the sequence number we must use on the input to a second level HTLC transaction.

func HtlcSigHashType added in v0.3.0 

func HtlcSigHashType(chanType channeldb.ChannelType) txscript.SigHashType

HtlcSigHashType returns the sighash type to use for HTLC success and timeout transactions given the channel type.

func HtlcSuccessFee added in v0.3.0 

func HtlcSuccessFee(chanType channeldb.ChannelType,
	feePerKB chainfee.AtomPerKByte) dcrutil.Amount

HtlcSuccessFee returns the fee in satoshis required for an HTLC success transaction based on the current fee rate.

func HtlcTimeoutFee added in v0.3.0 

func HtlcTimeoutFee(chanType channeldb.ChannelType,
	feePerKB chainfee.AtomPerKByte) dcrutil.Amount

HtlcTimeoutFee returns the fee in satoshis required for an HTLC timeout transaction based on the current fee rate.

func InPlaceCommitSort added in v0.2.0 

func InPlaceCommitSort(tx *wire.MsgTx, cltvs []uint32)

InPlaceCommitSort performs an in-place sort of a commitment transaction, given an unsorted transaction and a list of CLTV values for the HTLCs.

The sort applied is a modified BIP69 sort, that uses the CLTV values of HTLCs as a tie breaker in case two HTLC outputs have an identical amount and pkscript. The pkscripts can be the same if they share the same payment hash, but since the CLTV is enforced via the nLockTime of the second-layer transactions, the script does not directly commit to them. Instead, the CLTVs must be supplied separately to act as a tie-breaker, otherwise we may produce invalid HTLC signatures if the receiver produces an alternative ordering during verification.

NOTE: Commitment outputs should have a 0 CLTV corresponding to their index on the unsorted commitment transaction.

func RegisterWallet 

func RegisterWallet(driver *WalletDriver) error

RegisterWallet registers a WalletDriver which is capable of driving a concrete WalletController interface. In the case that this driver has already been registered, an error is returned.

NOTE: This function is safe for concurrent access.

func SetStateNumHint 

func SetStateNumHint(commitTx *wire.MsgTx, stateNum uint64,
	obfuscator [StateHintSize]byte) error

SetStateNumHint encodes the current state number within the passed commitment transaction by re-purposing the locktime and sequence fields in the commitment transaction to encode the obfuscated state number. The state number is encoded using 48 bits. The lower 24 bits of the lock time are the lower 24 bits of the obfuscated state number and the lower 24 bits of the sequence field are the higher 24 bits. Finally before encoding, the obfuscator is XOR'd against the state number in order to hide the exact state number from the PoV of outside parties.

func SupportedWallets 

func SupportedWallets() []string

SupportedWallets returns a slice of strings that represents the wallet drivers that have been registered and are therefore supported.

NOTE: This function is safe for concurrent access.

func UseLogger 

func UseLogger(logger slog.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 slog.

Types

type AddressType 

type AddressType uint8

AddressType is an enum-like type which denotes the possible address types WalletController supports. 

const (
	// WitnessPubKey represents a p2wkh address.
	// TODO(decred) remove this type of address
	WitnessPubKey AddressType = iota

	// NestedWitnessPubKey represents a p2sh output which is itself a
	// nested p2wkh output.
	// TODO(decred) remove this type of address
	NestedWitnessPubKey

	// PubKeyHash represents a p2pkh address
	PubKeyHash

	// ScriptHash represents a p2sh address
	ScriptHash

	// UnknownAddressType represents an output with an unknown or non-standard
	// script.
	UnknownAddressType
)

type AnchorResolution added in v0.3.0 

type AnchorResolution struct {
	// AnchorSignDescriptor is the sign descriptor for our anchor.
	AnchorSignDescriptor input.SignDescriptor

	// CommitAnchor is the anchor outpoint on the commit tx.
	CommitAnchor wire.OutPoint
}

AnchorResolution holds the information necessary to spend our commitment tx anchor.

func NewAnchorResolution added in v0.3.0 

func NewAnchorResolution(chanState *channeldb.OpenChannel,
	commitTx *wire.MsgTx) (*AnchorResolution, error)

NewAnchorResolution returns the information that is required to sweep the local anchor.

type BlockChainIO 

type BlockChainIO interface {
	// GetBestBlock returns the current height and block hash of the valid
	// most-work chain the implementation is aware of.
	GetBestBlock() (*chainhash.Hash, int32, error)

	// GetUtxo attempts to return the passed outpoint if it's still a
	// member of the utxo set. The passed height hint should be the "birth
	// height" of the passed outpoint. The script passed should be the
	// script that the outpoint creates. In the case that the output is in
	// the UTXO set, then the output corresponding to that output is
	// returned.  Otherwise, a non-nil error will be returned.
	// As for some backends this call can initiate a rescan, the passed
	// cancel channel can be closed to abort the call.
	GetUtxo(op *wire.OutPoint, pkScript []byte, heightHint uint32,
		cancel <-chan struct{}) (*wire.TxOut, error)

	// GetBlockHash returns the hash of the block in the best blockchain
	// at the given height.
	GetBlockHash(blockHeight int64) (*chainhash.Hash, error)

	// GetBlock returns the block in the main chain identified by the given
	// hash.
	GetBlock(blockHash *chainhash.Hash) (*wire.MsgBlock, error)
}

BlockChainIO is a dedicated source which will be used to obtain queries related to the current state of the blockchain. The data returned by each of the defined methods within this interface should always return the most up to date data possible.

TODO(roasbeef): move to diff package perhaps? TODO(roasbeef): move publish txn here?

type BreachRetribution 

type BreachRetribution struct {
	// BreachTransaction is the transaction which breached the channel
	// contract by spending from the funding multi-sig with a revoked
	// commitment transaction.
	BreachTransaction *wire.MsgTx

	// BreachHeight records the block height confirming the breach
	// transaction, used as a height hint when registering for
	// confirmations.
	BreachHeight uint32

	// ChainHash is the chain that the contract beach was identified
	// within. This is also the resident chain of the contract (the chain
	// the contract was created on).
	ChainHash chainhash.Hash

	// RevokedStateNum is the revoked state number which was broadcast.
	RevokedStateNum uint64

	// PendingHTLCs is a slice of the HTLCs which were pending at this
	// point within the channel's history transcript.
	PendingHTLCs []channeldb.HTLC

	// LocalOutputSignDesc is a input.SignDescriptor which is capable of
	// generating the signature necessary to sweep the output within the
	// BreachTransaction that pays directly us.
	//
	// NOTE: A nil value indicates that the local output is considered dust
	// according to the remote party's dust limit.
	LocalOutputSignDesc *input.SignDescriptor

	// LocalOutpoint is the outpoint of the output paying to us (the local
	// party) within the breach transaction.
	LocalOutpoint wire.OutPoint

	// LocalDelay is the CSV delay for the to_remote script on the breached
	// commitment.
	LocalDelay uint32

	// RemoteOutputSignDesc is a SignDescriptor which is capable of
	// generating the signature required to claim the funds as described
	// within the revocation clause of the remote party's commitment
	// output.
	//
	// NOTE: A nil value indicates that the local output is considered dust
	// according to the remote party's dust limit.
	RemoteOutputSignDesc *input.SignDescriptor

	// RemoteOutpoint is the outpoint of the output paying to the remote
	// party within the breach transaction.
	RemoteOutpoint wire.OutPoint

	// RemoteDelay specifies the CSV delay applied to to-local scripts on
	// the breaching commitment transaction.
	RemoteDelay uint32

	// HtlcRetributions is a slice of HTLC retributions for each output
	// active HTLC output within the breached commitment transaction.
	HtlcRetributions []HtlcRetribution

	// KeyRing contains the derived public keys used to construct the
	// breaching commitment transaction. This allows downstream clients to
	// have access to the public keys used in the scripts.
	KeyRing *CommitmentKeyRing
}

BreachRetribution contains all the data necessary to bring a channel counterparty to justice claiming ALL lingering funds within the channel in the scenario that they broadcast a revoked commitment transaction. A BreachRetribution is created by the closeObserver if it detects an uncooperative close of the channel which uses a revoked commitment transaction. The BreachRetribution is then sent over the ContractBreach channel in order to allow the subscriber of the channel to dispatch justice.

func NewBreachRetribution 

func NewBreachRetribution(chanState *channeldb.OpenChannel, stateNum uint64,
	breachHeight uint32) (*BreachRetribution, error)

NewBreachRetribution creates a new fully populated BreachRetribution for the passed channel, at a particular revoked state number, and one which targets the passed commitment transaction.

type ChannelContribution 

type ChannelContribution struct {
	// FundingOutpoint is the amount of funds contributed to the funding
	// transaction.
	FundingAmount dcrutil.Amount

	// Inputs to the funding transaction.
	Inputs []*wire.TxIn

	// ChangeOutputs are the Outputs to be used in the case that the total
	// value of the funding inputs is greater than the total potential
	// channel capacity.
	ChangeOutputs []*wire.TxOut

	// FirstCommitmentPoint is the first commitment point that will be used
	// to create the revocation key in the first commitment transaction we
	// send to the remote party.
	FirstCommitmentPoint *secp256k1.PublicKey

	// ChannelConfig is the concrete contribution that this node is
	// offering to the channel. This includes all the various constraints
	// such as the min HTLC, and also all the keys which will be used for
	// the duration of the channel.
	*channeldb.ChannelConfig

	// UpfrontShutdown is an optional address to which the channel should be
	// paid out to on cooperative close.
	UpfrontShutdown lnwire.DeliveryAddress
}

ChannelContribution is the primary constituent of the funding workflow within lnwallet. Each side first exchanges their respective contributions along with channel specific parameters like the min fee/kB. Once contributions have been exchanged, each side will then produce signatures for all their inputs to the funding transactions, and finally a signature for the other party's version of the commitment transaction.

type ChannelReservation 

type ChannelReservation struct {
	// This mutex MUST be held when either reading or modifying any of the
	// fields below.
	sync.RWMutex
	// contains filtered or unexported fields
}

ChannelReservation represents an intent to open a lightning payment channel with a counterparty. The funding processes from reservation to channel opening is a 3-step process. In order to allow for full concurrency during the reservation workflow, resources consumed by a contribution are "locked" themselves. This prevents a number of race conditions such as two funding transactions double-spending the same input. A reservation can also be canceled, which removes the resources from limbo, allowing another reservation to claim them.

The reservation workflow consists of the following three steps:

  1. lnwallet.InitChannelReservation * One requests the wallet to allocate the necessary resources for a channel reservation. These resources are put in limbo for the lifetime of a reservation. * Once completed the reservation will have the wallet's contribution accessible via the .OurContribution() method. This contribution contains the necessary items to allow the remote party to build both the funding, and commitment transactions.
  2. ChannelReservation.ProcessContribution/ChannelReservation.ProcessSingleContribution * The counterparty presents their contribution to the payment channel. This allows us to build the funding, and commitment transactions ourselves. * We're now able to sign our inputs to the funding transactions, and the counterparty's version of the commitment transaction. * All signatures crafted by us, are now available via .OurSignatures().
  3. ChannelReservation.CompleteReservation/ChannelReservation.CompleteReservationSingle * The final step in the workflow. The counterparty presents the signatures for all their inputs to the funding transaction, as well as a signature to our version of the commitment transaction. * We then verify the validity of all signatures before considering the channel "open".

func NewChannelReservation 

func NewChannelReservation(capacity, localFundingAmt dcrutil.Amount,
	commitFeePerKB chainfee.AtomPerKByte, wallet *LightningWallet,
	id uint64, pushMAtoms lnwire.MilliAtom, chainHash *chainhash.Hash,
	flags lnwire.FundingFlag, commitType CommitmentType,
	fundingAssembler chanfunding.Assembler,
	pendingChanID [32]byte, thawHeight uint32) (*ChannelReservation, error)

NewChannelReservation creates a new channel reservation. This function is used only internally by lnwallet. In order to concurrent safety, the creation of all channel reservations should be carried out via the lnwallet.InitChannelReservation interface.

func (*ChannelReservation) Cancel 

func (r *ChannelReservation) Cancel() error

Cancel abandons this channel reservation. This method should be called in the scenario that communications with the counterparty break down. Upon cancellation, all resources previously reserved for this pending payment channel are returned to the free pool, allowing subsequent reservations to utilize the now freed resources.

func (*ChannelReservation) Capacity added in v0.2.0 

func (r *ChannelReservation) Capacity() dcrutil.Amount

Capacity returns the channel capacity for this reservation.

func (*ChannelReservation) CommitConstraints 

func (r *ChannelReservation) CommitConstraints(c *channeldb.ChannelConstraints) error

CommitConstraints takes the constraints that the remote party specifies for the type of commitments that we can generate for them. These constraints include several parameters that serve as flow control restricting the amount of atoms that can be transferred in a single commitment. This function will also attempt to verify the constraints for sanity, returning an error if the parameters are seemed unsound.

func (*ChannelReservation) CompleteReservation 

func (r *ChannelReservation) CompleteReservation(fundingInputScripts []*input.Script,
	commitmentSig input.Signature) (*channeldb.OpenChannel, error)

CompleteReservation finalizes the pending channel reservation, transitioning from a pending payment channel, to an open payment channel. All passed signatures to the counterparty's inputs to the funding transaction will be fully verified. Signatures are expected to be passed in sorted order according to BIP-69: https://github.com/bitcoin/bips/blob/master/bip-0069.mediawiki. Additionally, verification is performed in order to ensure that the counterparty supplied a valid signature to our version of the commitment transaction. Once this method returns, callers should broadcast the created funding transaction, then call .WaitForChannelOpen() which will block until the funding transaction obtains the configured number of confirmations. Once the method unblocks, a LightningChannel instance is returned, marking the channel available for updates.

func (*ChannelReservation) CompleteReservationSingle 

func (r *ChannelReservation) CompleteReservationSingle(fundingPoint *wire.OutPoint,
	commitSig input.Signature) (*channeldb.OpenChannel, error)

CompleteReservationSingle finalizes the pending single funder channel reservation. Using the funding outpoint of the constructed funding transaction, and the initiator's signature for our version of the commitment transaction, we are able to verify the correctness of our commitment transaction as crafted by the initiator. Once this method returns, our signature for the initiator's version of the commitment transaction is available via the .OurSignatures() method. As this method should only be called as a response to a single funder channel, only a commitment signature will be populated.

func (*ChannelReservation) FinalFundingTx 

func (r *ChannelReservation) FinalFundingTx() *wire.MsgTx

FinalFundingTx returns the finalized, fully signed funding transaction for this reservation.

NOTE: If this reservation was created as the non-initiator to a single funding workflow, then the full funding transaction will not be available. Instead we will only have the final outpoint of the funding transaction.

func (*ChannelReservation) FundingOutpoint 

func (r *ChannelReservation) FundingOutpoint() *wire.OutPoint

FundingOutpoint returns the outpoint of the funding transaction.

NOTE: The pointer returned will only be set once the .ProcessContribution() method is called in the case of the initiator of a single funder workflow, and after the .CompleteReservationSingle() method is called in the case of a responder to a single funder workflow.

func (*ChannelReservation) IsCannedShim added in v0.3.0 

func (r *ChannelReservation) IsCannedShim() bool

IsCannedShim returns true if there is a canned shim funding intent mapped to this reservation.

func (*ChannelReservation) IsPsbt added in v0.3.0 

func (r *ChannelReservation) IsPsbt() bool

IsPsbt returns true if there is a PSBT funding intent mapped to this reservation.

func (*ChannelReservation) OurContribution 

func (r *ChannelReservation) OurContribution() *ChannelContribution

OurContribution returns the wallet's fully populated contribution to the pending payment channel. See 'ChannelContribution' for further details regarding the contents of a contribution.

NOTE: This SHOULD NOT be modified. TODO(roasbeef): make copy?

func (*ChannelReservation) OurSignatures 

func (r *ChannelReservation) OurSignatures() ([]*input.Script,
	input.Signature)

OurSignatures retrieves the wallet's signatures to all inputs to the funding transaction belonging to itself, and also a signature for the counterparty's version of the commitment transaction. The signatures for the wallet's inputs to the funding transaction are returned in sorted order according to BIP-69: https://github.com/bitcoin/bips/blob/master/bip-0069.mediawiki.

NOTE: These signatures will only be populated after a call to .ProcessContribution()

func (*ChannelReservation) ProcessContribution 

func (r *ChannelReservation) ProcessContribution(theirContribution *ChannelContribution) error

ProcessContribution verifies the counterparty's contribution to the pending payment channel. As a result of this incoming message, lnwallet is able to build the funding transaction, and both commitment transactions. Once this message has been processed, all signatures to inputs to the funding transaction belonging to the wallet are available. Additionally, the wallet will generate a signature to the counterparty's version of the commitment transaction.

func (*ChannelReservation) ProcessPsbt added in v0.3.0 

func (r *ChannelReservation) ProcessPsbt() error

ProcessPsbt continues a previously paused funding flow that involves PSBT to construct the funding transaction. This method can be called once the PSBT is finalized and the signed transaction is available.

func (*ChannelReservation) ProcessSingleContribution 

func (r *ChannelReservation) ProcessSingleContribution(theirContribution *ChannelContribution) error

ProcessSingleContribution verifies, and records the initiator's contribution to this pending single funder channel. Internally, no further action is taken other than recording the initiator's contribution to the single funder channel.

func (*ChannelReservation) RemoteCanceled added in v0.3.0 

func (r *ChannelReservation) RemoteCanceled()

RemoteCanceled informs the PSBT funding state machine that the remote peer has canceled the pending reservation, likely due to a timeout.

func (*ChannelReservation) SetNumConfsRequired 

func (r *ChannelReservation) SetNumConfsRequired(numConfs uint16)

SetNumConfsRequired sets the number of confirmations that are required for the ultimate funding transaction before the channel can be considered open. This is distinct from the main reservation workflow as it allows implementations a bit more flexibility w.r.t to if the responder of the initiator sets decides the number of confirmations needed.

func (*ChannelReservation) SetOurUpfrontShutdown added in v0.3.0 

func (r *ChannelReservation) SetOurUpfrontShutdown(shutdown lnwire.DeliveryAddress)

SetOurUpfrontShutdown sets the upfront shutdown address on our contribution.

func (*ChannelReservation) TheirContribution 

func (r *ChannelReservation) TheirContribution() *ChannelContribution

TheirContribution returns the counterparty's pending contribution to the payment channel. See 'ChannelContribution' for further details regarding the contents of a contribution. This attribute will ONLY be available after a call to .ProcessContribution().

NOTE: This SHOULD NOT be modified.

func (*ChannelReservation) TheirSignatures 

func (r *ChannelReservation) TheirSignatures() ([]*input.Script,
	input.Signature)

TheirSignatures returns the counterparty's signatures to all inputs to the funding transaction belonging to them, as well as their signature for the wallet's version of the commitment transaction. This methods is provided for additional verification, such as needed by tests.

NOTE: These attributes will be unpopulated before a call to .CompleteReservation().

type CoinSource added in v0.3.0 

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

CoinSource is a wrapper around the wallet that implements the chanfunding.CoinSource interface.

func NewCoinSource added in v0.3.0 

func NewCoinSource(w *LightningWallet) *CoinSource

NewCoinSource creates a new instance of the CoinSource wrapper struct.

func (*CoinSource) CoinFromOutPoint added in v0.3.0 

func (c *CoinSource) CoinFromOutPoint(op wire.OutPoint) (*chanfunding.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.

func (*CoinSource) ListCoins added in v0.3.0 

func (c *CoinSource) ListCoins(minConfs int32,
	maxConfs int32) ([]chanfunding.Coin, error)

ListCoins returns all UTXOs from the source that have between minConfs and maxConfs number of confirmations.

type CommitOutputResolution 

type CommitOutputResolution struct {
	// SelfOutPoint is the full outpoint that points to out pay-to-self
	// output within the closing commitment transaction.
	SelfOutPoint wire.OutPoint

	// SelfOutputSignDesc is a fully populated sign descriptor capable of
	// generating a valid signature to sweep the output paying to us.
	SelfOutputSignDesc input.SignDescriptor

	// MaturityDelay is the relative time-lock, in blocks for all outputs
	// that pay to the local party within the broadcast commitment
	// transaction.
	MaturityDelay uint32
}

CommitOutputResolution carries the necessary information required to allow us to sweep our commitment output in the case that either party goes to chain.

type CommitmentBuilder added in v0.3.0 

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

CommitmentBuilder is a type that wraps the type of channel we are dealing with, and abstracts the various ways of constructing commitment transactions.

func NewCommitmentBuilder added in v0.3.0 

func NewCommitmentBuilder(chanState *channeldb.OpenChannel, netParams *chaincfg.Params) *CommitmentBuilder

NewCommitmentBuilder creates a new CommitmentBuilder from chanState.

type CommitmentKeyRing 

type CommitmentKeyRing struct {
	// CommitPoint is the "per commitment point" used to derive the tweak
	// for each base point.
	CommitPoint *secp256k1.PublicKey

	// LocalCommitKeyTweak is the tweak used to derive the local public key
	// from the local payment base point or the local private key from the
	// base point secret. This may be included in a SignDescriptor to
	// generate signatures for the local payment key.
	//
	// NOTE: This will always refer to "our" local key, regardless of
	// whether this is our commit or not.
	LocalCommitKeyTweak []byte

	// LocalHtlcKeyTweak is the tweak used to derive the local HTLC key
	// from the local HTLC base point. This value is needed in order to
	// derive the final key used within the HTLC scripts in the commitment
	// transaction.
	//
	// NOTE: This will always refer to "our" local HTLC key, regardless of
	// whether this is our commit or not.
	LocalHtlcKeyTweak []byte

	// LocalHtlcKey is the key that will be used in any clause paying to
	// our node of any HTLC scripts within the commitment transaction for
	// this key ring set.
	//
	// NOTE: This will always refer to "our" local HTLC key, regardless of
	// whether this is our commit or not.
	LocalHtlcKey *secp256k1.PublicKey

	// RemoteHtlcKey is the key that will be used in clauses within the
	// HTLC script that send money to the remote party.
	//
	// NOTE: This will always refer to "their" remote HTLC key, regardless
	// of whether this is our commit or not.
	RemoteHtlcKey *secp256k1.PublicKey

	// ToLocalKey is the commitment transaction owner's key which is
	// included in HTLC success and timeout transaction scripts. This is
	// the public key used for the to_local output of the commitment
	// transaction.
	//
	// NOTE: Who's key this is depends on the current perspective. If this
	// is our commitment this will be our key.
	ToLocalKey *secp256k1.PublicKey

	// ToRemoteKey is the non-owner's payment key in the commitment tx.
	// This is the key used to generate the to_remote output within the
	// commitment transaction.
	//
	// NOTE: Who's key this is depends on the current perspective. If this
	// is our commitment this will be their key.
	ToRemoteKey *secp256k1.PublicKey

	// RevocationKey is the key that can be used by the other party to
	// redeem outputs from a revoked commitment transaction if it were to
	// be published.
	//
	// NOTE: Who can sign for this key depends on the current perspective.
	// If this is our commitment, it means the remote node can sign for
	// this key in case of a breach.
	RevocationKey *secp256k1.PublicKey
}

CommitmentKeyRing holds all derived keys needed to construct commitment and HTLC transactions. The keys are derived differently depending whether the commitment transaction is ours or the remote peer's. Private keys associated with each key may belong to the commitment owner or the "other party" which is referred to in the field comments, regardless of which is local and which is remote.

func DeriveCommitmentKeys added in v0.2.0 

func DeriveCommitmentKeys(commitPoint *secp256k1.PublicKey,
	isOurCommit bool, chanType channeldb.ChannelType,
	localChanCfg, remoteChanCfg *channeldb.ChannelConfig) *CommitmentKeyRing

DeriveCommitmentKeys generates a new commitment key set using the base points and commitment point. The keys are derived differently depending on the type of channel, and whether the commitment transaction is ours or the remote peer's.

type CommitmentType added in v0.3.0 

type CommitmentType int

CommitmentType is an enum indicating the commitment type we should use for the channel we are opening.

func (CommitmentType) String added in v0.3.0 

func (c CommitmentType) String() string

String returns the name of the CommitmentType.

type Config 

type Config struct {
	// Database is a wrapper around a namespace within bboltdb reserved for
	// ln-based wallet metadata. See the 'channeldb' package for further
	// information.
	Database *channeldb.DB

	// Notifier is used by in order to obtain notifications about funding
	// transaction reaching a specified confirmation depth, and to catch
	// counterparty's broadcasting revoked commitment states.
	Notifier chainntnfs.ChainNotifier

	// SecretKeyRing is used by the wallet during the funding workflow
	// process to obtain keys to be used directly within contracts. Usage
	// of this interface ensures that all key derivation is itself fully
	// deterministic.
	SecretKeyRing keychain.SecretKeyRing

	// WalletController is the core wallet, all non Lightning Network
	// specific interaction is proxied to the internal wallet.
	WalletController WalletController

	// input.Signer is the wallet's current input.Signer implementation. This input.Signer is
	// used to generate signature for all inputs to potential funding
	// transactions, as well as for spends from the funding transaction to
	// update the commitment state.
	Signer input.Signer

	// FeeEstimator is the implementation that the wallet will use for the
	// calculation of on-chain transaction fees.
	FeeEstimator chainfee.Estimator

	// ChainIO is an instance of the BlockChainIO interface. ChainIO is
	// used to lookup the existence of outputs within the UTXO set.
	ChainIO BlockChainIO

	// DefaultConstraints is the set of default constraints that will be
	// used for any incoming or outgoing channel reservation requests.
	DefaultConstraints channeldb.ChannelConstraints

	// NetParams is the set of parameters that tells the wallet which chain
	// it will be operating on.
	NetParams chaincfg.Params
}

Config is a struct which houses configuration parameters which modify the behaviour of LightningWallet.

NOTE: The passed channeldb, and ChainNotifier should already be fully initialized/started before being passed as a function argument.

type ErrCommitSyncLocalDataLoss 

type ErrCommitSyncLocalDataLoss struct {
	// ChannelPoint is the identifier for the channel that experienced data
	// loss.
	ChannelPoint wire.OutPoint

	// CommitPoint is the last unrevoked commit point, sent to us by the
	// remote when we determined we had lost state.
	CommitPoint *secp256k1.PublicKey
}

ErrCommitSyncLocalDataLoss is returned in the case that we receive a valid commit secret within the ChannelReestablish message from the remote node AND they advertise a RemoteCommitTailHeight higher than our current known height. This means we have lost some critical data, and must fail the channel and MUST NOT force close it. Instead we should wait for the remote to force close it, such that we can attempt to sweep our funds. The commitment point needed to sweep the remote's force close is encapsuled.

func (*ErrCommitSyncLocalDataLoss) Error added in v0.2.0 

func (e *ErrCommitSyncLocalDataLoss) Error() string

Error returns a string representation of the local data loss error.

type ErrHtlcIndexAlreadyFailed 

type ErrHtlcIndexAlreadyFailed uint64

ErrHtlcIndexAlreadyFailed is returned when the HTLC index has already been failed, but has not been committed by our commitment state.

func (ErrHtlcIndexAlreadyFailed) Error 

func (e ErrHtlcIndexAlreadyFailed) Error() string

Error returns a message indicating the index that had already been failed.

type ErrHtlcIndexAlreadySettled 

type ErrHtlcIndexAlreadySettled uint64

ErrHtlcIndexAlreadySettled is returned when the HTLC index has already been settled, but has not been committed by our commitment state.

func (ErrHtlcIndexAlreadySettled) Error 

func (e ErrHtlcIndexAlreadySettled) Error() string

Error returns a message indicating the index that had already been settled.

type ErrInvalidSettlePreimage 

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

ErrInvalidSettlePreimage is returned when trying to settle an HTLC, but the preimage does not correspond to the payment hash.

func (ErrInvalidSettlePreimage) Error 

func (e ErrInvalidSettlePreimage) Error() string

Error returns an error message with the offending preimage and intended payment hash.

type ErrUnknownHtlcIndex 

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

ErrUnknownHtlcIndex is returned when locally settling or failing an HTLC, but the HTLC index is not known to the channel. This typically indicates that the HTLC was already settled in a prior commitment.

func (ErrUnknownHtlcIndex) Error 

func (e ErrUnknownHtlcIndex) Error() string

Error returns an error logging the channel and HTLC index that was unknown.

type HtlcIndexErr 

type HtlcIndexErr struct {
	*VerifyJob
	// contains filtered or unexported fields
}

HtlcIndexErr is a special type of error that also includes a pointer to the original validation job. This error message allows us to craft more detailed errors at upper layers.

type HtlcResolutions 

type HtlcResolutions struct {
	// IncomingHTLCs contains a set of structs that can be used to sweep
	// all the incoming HTL'C that we know the preimage to.
	IncomingHTLCs []IncomingHtlcResolution

	// OutgoingHTLCs contains a set of structs that contains all the info
	// needed to sweep an outgoing HTLC we've sent to the remote party
	// after an absolute delay has expired.
	OutgoingHTLCs []OutgoingHtlcResolution
}

HtlcResolutions contains the items necessary to sweep HTLC's on chain directly from a commitment transaction. We'll use this in case either party goes broadcasts a commitment transaction with live HTLC's.

type HtlcRetribution 

type HtlcRetribution struct {
	// SignDesc is a design descriptor capable of generating the necessary
	// signatures to satisfy the revocation clause of the HTLC's public key
	// script.
	SignDesc input.SignDescriptor

	// OutPoint is the target outpoint of this HTLC pointing to the
	// breached commitment transaction.
	OutPoint wire.OutPoint

	// SecondLevelWitnessScript is the witness script that will be created
	// if the second level HTLC transaction for this output is
	// broadcast/confirmed. We provide this as if the remote party attempts
	// to go to the second level to claim the HTLC then we'll need to
	// update the SignDesc above accordingly to sweep properly.
	SecondLevelWitnessScript []byte

	// IsIncoming is a boolean flag that indicates whether or not this
	// HTLC was accepted from the counterparty. A false value indicates that
	// this HTLC was offered by us. This flag is used determine the exact
	// witness type should be used to sweep the output.
	IsIncoming bool
}

HtlcRetribution contains all the items necessary to seep a revoked HTLC transaction from a revoked commitment transaction broadcast by the remote party.

type IncomingHtlcResolution 

type IncomingHtlcResolution struct {
	// Preimage is the preimage that will be used to satisfy the contract of
	// the HTLC.
	//
	// NOTE: This field will only be populated in the incoming contest
	// resolver.
	Preimage [32]byte

	// SignedSuccessTx is the fully signed HTLC success transaction. This
	// transaction (if non-nil) can be broadcast immediately. After a csv
	// delay (included below), then the output created by this transactions
	// can be swept on-chain.
	//
	// NOTE: If this field is nil, then this indicates that we don't need
	// to go to the second level to claim this HTLC. Instead, it can be
	// claimed directly from the outpoint listed below.
	SignedSuccessTx *wire.MsgTx

	// CsvDelay is the relative time lock (expressed in blocks) that must
	// pass after the SignedSuccessTx is confirmed in the chain before the
	// output can be swept.
	//
	// NOTE: If SignedTimeoutTx is nil, then this field denotes the CSV
	// delay needed to spend from the commitment transaction.
	CsvDelay uint32

	// ClaimOutpoint is the final outpoint that needs to be spent in order
	// to fully sweep the HTLC. The input.SignDescriptor below should be used to
	// spend this outpoint. In the case of a second-level HTLC (non-nil
	// SignedTimeoutTx), then we'll be spending a new transaction.
	// Otherwise, it'll be an output in the commitment transaction.
	ClaimOutpoint wire.OutPoint

	// SweepSignDesc is a sign descriptor that has been populated with the
	// necessary items required to spend the sole output of the above
	// transaction.
	SweepSignDesc input.SignDescriptor
}

IncomingHtlcResolution houses the information required to sweep any incoming HTLC's that we know the preimage to. We'll need to sweep an HTLC manually using this struct if we need to go on-chain for any reason, or if we detect that the remote party broadcasts their commitment transaction.

func (*IncomingHtlcResolution) HtlcPoint added in v0.2.0 

func (r *IncomingHtlcResolution) HtlcPoint() wire.OutPoint

HtlcPoint returns the htlc's outpoint on the commitment tx.

type InitFundingReserveMsg 

type InitFundingReserveMsg struct {
	// ChainHash denotes that chain to be used to ultimately open the
	// target channel.
	ChainHash *chainhash.Hash

	// PendingChanID is the pending channel ID for this funding flow as
	// used in the wire protocol.
	PendingChanID [32]byte

	// NodeID is the ID of the remote node we would like to open a channel
	// with.
	NodeID *secp256k1.PublicKey

	// NodeAddr is the address port that we used to either establish or
	// accept the connection which led to the negotiation of this funding
	// workflow.
	NodeAddr net.Addr

	// SubtractFees should be set if we intend to spend exactly
	// LocalFundingAmt 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

	// LocalFundingAmt is the amount of funds requested from us for this
	// channel.
	LocalFundingAmt dcrutil.Amount

	// RemoteFundingAmt is the amount of funds the remote will contribute
	// to this channel.
	RemoteFundingAmt dcrutil.Amount

	// CommitFeePerKB is the starting accepted atom/kB fee for the set of
	// initial commitment transactions. In order to ensure timely
	// confirmation, it is recommended that this fee should be generous,
	// paying some multiple of the accepted base fee rate of the network.
	CommitFeePerKB chainfee.AtomPerKByte

	// FundingFeePerKB is the fee rate in atom/kB to use for the initial
	// funding transaction.
	FundingFeePerKB chainfee.AtomPerKByte

	// PushMAtoms is the number of milli-atoms that should be pushed over
	// the responder as part of the initial channel creation.
	PushMAtoms lnwire.MilliAtom

	// Flags are the channel flags specified by the initiator in the
	// open_channel message.
	Flags lnwire.FundingFlag

	// MinConfs indicates the minimum number of confirmations that each
	// output selected to fund the channel should satisfy.
	MinConfs int32

	// CommitType indicates what type of commitment type the channel should
	// be using, like tweakless or anchors.
	CommitType CommitmentType

	// ChanFunder is an optional channel funder that allows the caller to
	// control exactly how the channel funding is carried out. If not
	// specified, then the default chanfunding.WalletAssembler will be
	// used.
	ChanFunder chanfunding.Assembler
	// contains filtered or unexported fields
}

InitFundingReserveMsg is the first message sent to initiate the workflow required to open a payment channel with a remote peer. The initial required parameters are configurable across channels. These parameters are to be chosen depending on the fee climate within the network, and time value of funds to be locked up within the channel. Upon success a ChannelReservation will be created in order to track the lifetime of this pending channel. Outputs selected will be 'locked', making them unavailable, for any other pending reservations. Therefore, all channels in reservation limbo will be periodically timed out after an idle period in order to avoid "exhaustion" attacks.

type InvalidCommitSigError 

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

InvalidCommitSigError is a struct that implements the error interface to report a failure to validate a commitment signature for a remote peer. We'll use the items in this struct to generate a rich error message for the remote peer when we receive an invalid signature from it. Doing so can greatly aide in debugging cross implementation issues.

func (*InvalidCommitSigError) Error 

func (i *InvalidCommitSigError) Error() string

Error returns a detailed error string including the exact transaction that caused an invalid commitment signature.

type InvalidHtlcSigError 

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

InvalidHtlcSigError is a struct that implements the error interface to report a failure to validate an htlc signature from a remote peer. We'll use the items in this struct to generate a rich error message for the remote peer when we receive an invalid signature from it. Doing so can greatly aide in debugging across implementation issues.

func (*InvalidHtlcSigError) Error 

func (i *InvalidHtlcSigError) Error() string

Error returns a detailed error string including the exact transaction that caused an invalid htlc signature.

type LightningChannel 

type LightningChannel struct {
	// input.Signer is the main signer instances that will be responsible for
	// signing any HTLC and commitment transaction generated by the state
	// machine.
	Signer input.Signer

	// ChanPoint is the funding outpoint of this channel.
	ChanPoint *wire.OutPoint

	// Capacity is the total capacity of this channel.
	Capacity dcrutil.Amount

	// LocalFundingKey is the public key under control by the wallet that
	// was used for the 2-of-2 funding output which created this channel.
	LocalFundingKey *secp256k1.PublicKey

	// RemoteFundingKey is the public key for the remote channel counter
	// party  which used for the 2-of-2 funding output which created this
	// channel.
	RemoteFundingKey *secp256k1.PublicKey

	sync.RWMutex
	// contains filtered or unexported fields
}

LightningChannel implements the state machine which corresponds to the current commitment protocol wire spec. The state machine implemented allows for asynchronous fully desynchronized, batched+pipelined updates to commitment transactions allowing for a high degree of non-blocking bi-directional payment throughput.

In order to allow updates to be fully non-blocking, either side is able to create multiple new commitment states up to a pre-determined window size. This window size is encoded within InitialRevocationWindow. Before the start of a session, both side should send out revocation messages with nil preimages in order to populate their revocation window for the remote party.

The state machine has for main methods:

  • .SignNextCommitment()
  • Called one one wishes to sign the next commitment, either initiating a new state update, or responding to a received commitment.
  • .ReceiveNewCommitment()
  • Called upon receipt of a new commitment from the remote party. If the new commitment is valid, then a revocation should immediately be generated and sent.
  • .RevokeCurrentCommitment()
  • Revokes the current commitment. Should be called directly after receiving a new commitment.
  • .ReceiveRevocation()
  • Processes a revocation from the remote party. If successful creates a new defacto broadcastable state.

See the individual comments within the above methods for further details.

func NewLightningChannel 

func NewLightningChannel(signer input.Signer,
	state *channeldb.OpenChannel,
	sigPool *SigPool,
	netParams *chaincfg.Params) (*LightningChannel, error)

NewLightningChannel creates a new, active payment channel given an implementation of the chain notifier, channel database, and the current settled channel state. Throughout state transitions, then channel will automatically persist pertinent state to the database in an efficient manner.

func (*LightningChannel) AckAddHtlcs 

func (lc *LightningChannel) AckAddHtlcs(addRef channeldb.AddRef) error

AckAddHtlcs sets a bit in the FwdFilter of a forwarding package belonging to this channel, that corresponds to the given AddRef. This method also succeeds if no forwarding package is found.

func (*LightningChannel) AckSettleFails 

func (lc *LightningChannel) AckSettleFails(
	settleFailRefs ...channeldb.SettleFailRef) error

AckSettleFails sets a bit in the SettleFailFilter of a forwarding package belonging to this channel, that corresponds to the given SettleFailRef. This method also succeeds if no forwarding package is found.

func (*LightningChannel) ActiveHtlcs 

func (lc *LightningChannel) ActiveHtlcs() []channeldb.HTLC

ActiveHtlcs returns a slice of HTLC's which are currently active on *both* commitment transactions.

func (*LightningChannel) AddHTLC 

func (lc *LightningChannel) AddHTLC(htlc *lnwire.UpdateAddHTLC,
	openKey *channeldb.CircuitKey) (uint64, error)

AddHTLC adds an HTLC to the state machine's local update log. This method should be called when preparing to send an outgoing HTLC.

The additional openKey argument corresponds to the incoming CircuitKey of the committed circuit for this HTLC. This value should never be nil.

Note that AddHTLC doesn't reserve the HTLC fee for future payment (like AvailableBalance does), so one could get into the "stuck channel" state by sending dust HTLCs. TODO(halseth): fix this either by using additional reserve, or better commit format. See https://github.com/lightningnetwork/lightning-rfc/issues/728

NOTE: It is okay for sourceRef to be nil when unit testing the wallet.

func (*LightningChannel) AvailableBalance 

func (lc *LightningChannel) AvailableBalance() lnwire.MilliAtom

AvailableBalance returns the current balance available for sending within the channel. By available balance, we mean that if at this very instance a new commitment were to be created which evals all the log entries, what would our available balance for adding an additional HTLC be. It takes into account the fee that must be paid for adding this HTLC (if we're the initiator), and that we cannot spend from the channel reserve. This method is useful when deciding if a given channel can accept an HTLC in the multi-hop forwarding scenario.

func (*LightningChannel) CalcFee 

func (lc *LightningChannel) CalcFee(feeRate chainfee.AtomPerKByte) dcrutil.Amount

CalcFee returns the commitment fee to use for the given fee rate (fee-per-kw).

func (*LightningChannel) ChannelPoint 

func (lc *LightningChannel) ChannelPoint() *wire.OutPoint

ChannelPoint returns the outpoint of the original funding transaction which created this active channel. This outpoint is used throughout various subsystems to uniquely identify an open channel.

func (*LightningChannel) CommitFeeRate 

func (lc *LightningChannel) CommitFeeRate() chainfee.AtomPerKByte

CommitFeeRate returns the current fee rate of the commitment transaction in units of atom-per-kb.

func (*LightningChannel) CompleteCooperativeClose 

func (lc *LightningChannel) CompleteCooperativeClose(
	localSig, remoteSig input.Signature,
	localDeliveryScript, remoteDeliveryScript []byte,
	proposedFee dcrutil.Amount) (*wire.MsgTx, dcrutil.Amount, error)

CompleteCooperativeClose completes the cooperative closure of the target active lightning channel. A fully signed closure transaction as well as the signature itself are returned. Additionally, we also return our final settled balance, which reflects any fees we may have paid.

NOTE: The passed local and remote sigs are expected to be fully complete signatures including the proper sighash byte.

func (*LightningChannel) CreateCloseProposal 

func (lc *LightningChannel) CreateCloseProposal(proposedFee dcrutil.Amount,
	localDeliveryScript []byte,
	remoteDeliveryScript []byte) (input.Signature, *chainhash.Hash,
	dcrutil.Amount, error)

CreateCloseProposal is used by both parties in a cooperative channel close workflow to generate proposed close transactions and signatures. This method should only be executed once all pending HTLCs (if any) on the channel have been cleared/removed. Upon completion, the source channel will shift into the "closing" state, which indicates that all incoming/outgoing HTLC requests should be rejected. A signature for the closing transaction is returned.

TODO(roasbeef): caller should initiate signal to reject all incoming HTLCs, settle any in flight.

func (*LightningChannel) FailHTLC 

func (lc *LightningChannel) FailHTLC(htlcIndex uint64, reason []byte,
	sourceRef *channeldb.AddRef, destRef *channeldb.SettleFailRef,
	closeKey *channeldb.CircuitKey) error

FailHTLC attempts to fail a targeted HTLC by its payment hash, inserting an entry which will remove the target log entry within the next commitment update. This method is intended to be called in order to cancel in _incoming_ HTLC.

The additional arguments correspond to:

  • sourceRef: specifies the location of the Add HTLC within a forwarding package that this HTLC is failing. Every Fail fails exactly one Add, so this should never be empty in practice.

  • destRef: specifies the location of the Fail HTLC within another channel's forwarding package. This value can be nil if the corresponding Add HTLC was never locked into an outgoing commitment txn, or this HTLC does not originate as a response from the peer on the outgoing link, e.g. on-chain resolutions.

  • closeKey: identifies the circuit that should be deleted after this Fail HTLC is included in a commitment txn. This value should only be nil if the HTLC was failed locally before committing a circuit to the circuit map.

NOTE: It is okay for sourceRef, destRef, and closeKey to be nil when unit testing the wallet.

func (*LightningChannel) ForceClose 

func (lc *LightningChannel) ForceClose() (*LocalForceCloseSummary, error)

ForceClose executes a unilateral closure of the transaction at the current lowest commitment height of the channel. Following a force closure, all state transitions, or modifications to the state update logs will be rejected. Additionally, this function also returns a LocalForceCloseSummary which includes the necessary details required to sweep all the time-locked outputs within the commitment transaction.

TODO(roasbeef): all methods need to abort if in dispute state TODO(roasbeef): method to generate CloseSummaries for when the remote peer does a unilateral close

func (*LightningChannel) FwdMinHtlc 

func (lc *LightningChannel) FwdMinHtlc() lnwire.MilliAtom

FwdMinHtlc returns the minimum HTLC value required by the remote node, i.e. the minimum value HTLC we can forward on this channel.

func (*LightningChannel) InitNextRevocation 

func (lc *LightningChannel) InitNextRevocation(revKey *secp256k1.PublicKey) error

InitNextRevocation inserts the passed commitment point as the _next_ revocation to be used when creating a new commitment state for the remote party. This function MUST be called before the channel can accept or propose any new states.

func (*LightningChannel) IsInitiator 

func (lc *LightningChannel) IsInitiator() bool

IsInitiator returns true if we were the ones that initiated the funding workflow which led to the creation of this channel. Otherwise, it returns false.

func (*LightningChannel) IsPending 

func (lc *LightningChannel) IsPending() bool

IsPending returns true if the channel's funding transaction has been fully confirmed, and false otherwise.

func (*LightningChannel) LoadFwdPkgs 

func (lc *LightningChannel) LoadFwdPkgs() ([]*channeldb.FwdPkg, error)

LoadFwdPkgs loads any pending log updates from disk and returns the payment descriptors to be processed by the link.

func (*LightningChannel) LocalChanReserve 

func (lc *LightningChannel) LocalChanReserve() dcrutil.Amount

LocalChanReserve returns our local ChanReserve requirement for the remote party.

func (*LightningChannel) LocalUpfrontShutdownScript added in v0.3.0 

func (lc *LightningChannel) LocalUpfrontShutdownScript() lnwire.DeliveryAddress

LocalUpfrontShutdownScript returns the local upfront shutdown script for the channel. If it was not set, an empty byte array is returned.

func (*LightningChannel) MalformedFailHTLC 

func (lc *LightningChannel) MalformedFailHTLC(htlcIndex uint64,
	failCode lnwire.FailCode, shaOnionBlob [sha256.Size]byte,
	sourceRef *channeldb.AddRef) error

MalformedFailHTLC attempts to fail a targeted HTLC by its payment hash, inserting an entry which will remove the target log entry within the next commitment update. This method is intended to be called in order to cancel in _incoming_ HTLC.

The additional sourceRef specifies the location of the Add HTLC within a forwarding package that this HTLC is failing. This value should never be empty.

NOTE: It is okay for sourceRef to be nil when unit testing the wallet.

func (*LightningChannel) MarkBorked added in v0.2.0 

func (lc *LightningChannel) MarkBorked() error

MarkBorked marks the event when the channel as reached an irreconcilable state, such as a channel breach or state desynchronization. Borked channels should never be added to the switch.

func (*LightningChannel) MarkCommitmentBroadcasted 

func (lc *LightningChannel) MarkCommitmentBroadcasted(tx *wire.MsgTx,
	locallyInitiated bool) error

MarkCommitmentBroadcasted marks the channel as a commitment transaction has been broadcast, either our own or the remote, and we should watch the chain for it to confirm before taking any further action. It takes a boolean which indicates whether we initiated the close.

func (*LightningChannel) MarkCoopBroadcasted added in v0.3.0 

func (lc *LightningChannel) MarkCoopBroadcasted(tx *wire.MsgTx,
	localInitiated bool) error

MarkCoopBroadcasted marks the channel as a cooperative close transaction has been broadcast, and that we should watch the chain for it to confirm before taking any further action. It takes a locally initiated bool which is true if we initiated the cooperative close.

func (*LightningChannel) MarkDataLoss added in v0.2.0 

func (lc *LightningChannel) MarkDataLoss(commitPoint *secp256k1.PublicKey) error

MarkDataLoss marks sets the channel status to LocalDataLoss and stores the passed commitPoint for use to retrieve funds in case the remote force closes the channel.

func (*LightningChannel) MaxFeeRate added in v0.2.0 

func (lc *LightningChannel) MaxFeeRate(maxAllocation float64) chainfee.AtomPerKByte

MaxFeeRate returns the maximum fee rate given an allocation of the channel initiator's spendable balance. This can be useful to determine when we should stop proposing fee updates that exceed our maximum allocation.

NOTE: This should only be used for channels in which the local commitment is the initiator.

func (*LightningChannel) NewAnchorResolutions added in v0.3.0 

func (lc *LightningChannel) NewAnchorResolutions() ([]*AnchorResolution,
	error)

NewAnchorResolutions returns the anchor resolutions for all currently valid commitment transactions. Because we have no view on the mempool, we can only blindly anchor all of these txes down.

func (*LightningChannel) NextLocalHtlcIndex 

func (lc *LightningChannel) NextLocalHtlcIndex() (uint64, error)

NextLocalHtlcIndex returns the next unallocated local htlc index. To ensure this always returns the next index that has been not been allocated, this will first try to examine any pending commitments, before falling back to the last locked-in local commitment.

func (*LightningChannel) NextRevocationKey 

func (lc *LightningChannel) NextRevocationKey() (*secp256k1.PublicKey, error)

NextRevocationKey returns the commitment point for the _next_ commitment height. The pubkey returned by this function is required by the remote party along with their revocation base to extend our commitment chain with a new commitment.

func (*LightningChannel) OweCommitment added in v0.3.0 

func (lc *LightningChannel) OweCommitment(local bool) bool

OweCommitment returns a boolean value reflecting whether we need to send out a commitment signature because there are outstanding local updates and/or updates in the local commit tx that aren't reflected in the remote commit tx yet.

func (*LightningChannel) PendingLocalUpdateCount added in v0.3.0 

func (lc *LightningChannel) PendingLocalUpdateCount() uint64

PendingLocalUpdateCount returns the number of local updates that still need to be applied to the remote commitment tx.

func (*LightningChannel) ProcessChanSyncMsg 

func (lc *LightningChannel) ProcessChanSyncMsg(
	msg *lnwire.ChannelReestablish) ([]lnwire.Message, []channeldb.CircuitKey,
	[]channeldb.CircuitKey, error)

ProcessChanSyncMsg processes a ChannelReestablish message sent by the remote connection upon re establishment of our connection with them. This method will return a single message if we are currently out of sync, otherwise a nil lnwire.Message will be returned. If it is decided that our level of de-synchronization is irreconcilable, then an error indicating the issue will be returned. In this case that an error is returned, the channel should be force closed, as we cannot continue updates.

One of two message sets will be returned:

  • CommitSig+Updates: if we have a pending remote commit which they claim to have not received
  • RevokeAndAck: if we sent a revocation message that they claim to have not received

If we detect a scenario where we need to send a CommitSig+Updates, this method also returns two sets channeldb.CircuitKeys identifying the circuits that were opened and closed, respectively, as a result of signing the previous commitment txn. This allows the link to clear its mailbox of those circuits in case they are still in memory, and ensure the switch's circuit map has been updated by deleting the closed circuits.

func (*LightningChannel) ReceiveFailHTLC 

func (lc *LightningChannel) ReceiveFailHTLC(htlcIndex uint64, reason []byte,
) error

ReceiveFailHTLC attempts to cancel a targeted HTLC by its log index, inserting an entry which will remove the target log entry within the next commitment update. This method should be called in response to the upstream party cancelling an outgoing HTLC. The value of the failed HTLC is returned along with an error indicating success.

func (*LightningChannel) ReceiveHTLC 

func (lc *LightningChannel) ReceiveHTLC(htlc *lnwire.UpdateAddHTLC) (uint64, error)

ReceiveHTLC adds an HTLC to the state machine's remote update log. This method should be called in response to receiving a new HTLC from the remote party.

func (*LightningChannel) ReceiveHTLCSettle 

func (lc *LightningChannel) ReceiveHTLCSettle(preimage lntypes.Preimage, htlcIndex uint64) error

ReceiveHTLCSettle attempts to settle an existing outgoing HTLC indexed by an index into the local log. If the specified index doesn't exist within the log, and error is returned. Similarly if the preimage is invalid w.r.t to the referenced of then a distinct error is returned.

func (*LightningChannel) ReceiveNewCommitment 

func (lc *LightningChannel) ReceiveNewCommitment(commitSig lnwire.Sig,
	htlcSigs []lnwire.Sig) error

ReceiveNewCommitment process a signature for a new commitment state sent by the remote party. This method should be called in response to the remote party initiating a new change, or when the remote party sends a signature fully accepting a new state we've initiated. If we are able to successfully validate the signature, then the generated commitment is added to our local commitment chain. Once we send a revocation for our prior state, then this newly added commitment becomes our current accepted channel state.

func (*LightningChannel) ReceiveRevocation 

func (lc *LightningChannel) ReceiveRevocation(revMsg *lnwire.RevokeAndAck) (
	*channeldb.FwdPkg, []*PaymentDescriptor, []*PaymentDescriptor,
	[]channeldb.HTLC, error)

ReceiveRevocation processes a revocation sent by the remote party for the lowest unrevoked commitment within their commitment chain. We receive a revocation either during the initial session negotiation wherein revocation windows are extended, or in response to a state update that we initiate. If successful, then the remote commitment chain is advanced by a single commitment, and a log compaction is attempted.

The returned values correspond to:

  1. The forwarding package corresponding to the remote commitment height that was revoked.
  2. The PaymentDescriptor of any Add HTLCs that were locked in by this revocation.
  3. The PaymentDescriptor of any Settle/Fail HTLCs that were locked in by this revocation.
  4. The set of HTLCs present on the current valid commitment transaction for the remote party.

func (*LightningChannel) ReceiveUpdateFee 

func (lc *LightningChannel) ReceiveUpdateFee(feePerKB chainfee.AtomPerKByte) error

ReceiveUpdateFee handles an updated fee sent from remote. This method will return an error if called as channel initiator.

func (*LightningChannel) RemoteNextRevocation 

func (lc *LightningChannel) RemoteNextRevocation() *secp256k1.PublicKey

RemoteNextRevocation returns the channelState's RemoteNextRevocation.

func (*LightningChannel) RemoteUpfrontShutdownScript added in v0.3.0 

func (lc *LightningChannel) RemoteUpfrontShutdownScript() lnwire.DeliveryAddress

RemoteUpfrontShutdownScript returns the remote upfront shutdown script for the channel. If it was not set, an empty byte array is returned.

func (*LightningChannel) RemoveFwdPkg 

func (lc *LightningChannel) RemoveFwdPkg(height uint64) error

RemoveFwdPkg permanently deletes the forwarding package at the given height.

func (*LightningChannel) ResetState 

func (lc *LightningChannel) ResetState()

ResetState resets the state of the channel back to the default state. This ensures that any active goroutines which need to act based on on-chain events do so properly.

func (*LightningChannel) RevokeCurrentCommitment 

func (lc *LightningChannel) RevokeCurrentCommitment() (*lnwire.RevokeAndAck, []channeldb.HTLC, error)

RevokeCurrentCommitment revokes the next lowest unrevoked commitment transaction in the local commitment chain. As a result the edge of our revocation window is extended by one, and the tail of our local commitment chain is advanced by a single commitment. This now lowest unrevoked commitment becomes our currently accepted state within the channel. This method also returns the set of HTLC's currently active within the commitment transaction. This return value allows callers to act once an HTLC has been locked into our commitment transaction.

func (*LightningChannel) SetFwdFilter 

func (lc *LightningChannel) SetFwdFilter(height uint64,
	fwdFilter *channeldb.PkgFilter) error

SetFwdFilter writes the forwarding decision for a given remote commitment height.

func (*LightningChannel) SettleHTLC 

func (lc *LightningChannel) SettleHTLC(preimage lntypes.Preimage,
	htlcIndex uint64, sourceRef *channeldb.AddRef,
	destRef *channeldb.SettleFailRef, closeKey *channeldb.CircuitKey) error

SettleHTLC attempts to settle an existing outstanding received HTLC. The remote log index of the HTLC settled is returned in order to facilitate creating the corresponding wire message. In the case the supplied preimage is invalid, an error is returned.

The additional arguments correspond to:

  • sourceRef: specifies the location of the Add HTLC within a forwarding package that this HTLC is settling. Every Settle fails exactly one Add, so this should never be empty in practice.

  • destRef: specifies the location of the Settle HTLC within another channel's forwarding package. This value can be nil if the corresponding Add HTLC was never locked into an outgoing commitment txn, or this HTLC does not originate as a response from the peer on the outgoing link, e.g. on-chain resolutions.

  • closeKey: identifies the circuit that should be deleted after this Settle HTLC is included in a commitment txn. This value should only be nil if the HTLC was settled locally before committing a circuit to the circuit map.

NOTE: It is okay for sourceRef, destRef, and closeKey to be nil when unit testing the wallet.

func (*LightningChannel) ShortChanID 

func (lc *LightningChannel) ShortChanID() lnwire.ShortChannelID

ShortChanID returns the short channel ID for the channel. The short channel ID encodes the exact location in the main chain that the original funding output can be found.

func (*LightningChannel) SignNextCommitment 

func (lc *LightningChannel) SignNextCommitment() (lnwire.Sig, []lnwire.Sig, []channeldb.HTLC, error)

SignNextCommitment signs a new commitment which includes any previous unsettled HTLCs, any new HTLCs, and any modifications to prior HTLCs committed in previous commitment updates. Signing a new commitment decrements the available revocation window by 1. After a successful method call, the remote party's commitment chain is extended by a new commitment which includes all updates to the HTLC log prior to this method invocation. The first return parameter is the signature for the commitment transaction itself, while the second parameter is a slice of all HTLC signatures (if any). The HTLC signatures are sorted according to the BIP 69 order of the HTLC's on the commitment transaction. Finally, the new set of pending HTLCs for the remote party's commitment are also returned.

func (*LightningChannel) State 

func (lc *LightningChannel) State() *channeldb.OpenChannel

State provides access to the channel's internal state.

func (*LightningChannel) StateSnapshot 

func (lc *LightningChannel) StateSnapshot() *channeldb.ChannelSnapshot

StateSnapshot returns a snapshot of the current fully committed state within the channel.

func (*LightningChannel) UpdateFee 

func (lc *LightningChannel) UpdateFee(feePerKB chainfee.AtomPerKByte) error

UpdateFee initiates a fee update for this channel. Must only be called by the channel initiator, and must be called before sending update_fee to the remote.

type LightningWallet 

type LightningWallet struct {

	// Cfg is the configuration struct that will be used by the wallet to
	// access the necessary interfaces and default it needs to carry on its
	// duties.
	Cfg Config

	// WalletController is the core wallet, all non Lightning Network
	// specific interaction is proxied to the internal wallet.
	WalletController

	// SecretKeyRing is the interface we'll use to derive any keys related
	// to our purpose within the network including: multi-sig keys, node
	// keys, revocation keys, etc.
	keychain.SecretKeyRing
	// contains filtered or unexported fields
}

LightningWallet is a domain specific, yet general wallet capable of executing workflow required to interact with the Lightning Network. It is domain specific in the sense that it understands all the fancy scripts used within the Lightning Network, channel lifetimes, etc. However, it embeds a general purpose wallet within it. Therefore, it is also able to serve as a regular wallet which uses HD keys. The wallet is highly concurrent internally. All communication, and requests towards the wallet are dispatched as messages over channels, ensuring thread safety across all operations. Interaction has been designed independent of any peer-to-peer communication protocol, allowing the wallet to be self-contained and embeddable within future projects interacting with the Lightning Network.

NOTE: At the moment the wallet requires a dcrd full node, as it's dependent on dcrd's websockets notifications as event triggers during the lifetime of a channel. Eventually, the wallet won't require a full-node at all, as SPV support is integrated into dcrwallet.

func NewLightningWallet 

func NewLightningWallet(cfg Config) (*LightningWallet, error)

NewLightningWallet creates/opens and initializes a LightningWallet instance. If the wallet has never been created (according to the passed dataDir), first-time setup is executed.

func (*LightningWallet) ActiveReservations 

func (l *LightningWallet) ActiveReservations() []*ChannelReservation

ActiveReservations returns a slice of all the currently active (non-canceled) reservations.

func (*LightningWallet) CancelFundingIntent added in v0.3.0 

func (l *LightningWallet) CancelFundingIntent(pid [32]byte) error

CancelFundingIntent allows a caller to cancel a previously registered funding intent. If no intent was found, then an error will be returned.

func (*LightningWallet) ConfirmedBalance added in v0.3.0 

func (l *LightningWallet) ConfirmedBalance(confs int32) (dcrutil.Amount, error)

ConfirmedBalance returns the current confirmed balance of the wallet. This methods wraps the interal WalletController method so we're able to properly hold the coin select mutex while we compute the balance.

func (*LightningWallet) InitChannelReservation 

func (l *LightningWallet) InitChannelReservation(
	req *InitFundingReserveMsg) (*ChannelReservation, error)

InitChannelReservation kicks off the 3-step workflow required to successfully open a payment channel with a remote node. As part of the funding reservation, the inputs selected for the funding transaction are 'locked'. This ensures that multiple channel reservations aren't double spending the same inputs in the funding transaction. If reservation initialization is successful, a ChannelReservation containing our completed contribution is returned. Our contribution contains all the items necessary to allow the counterparty to build the funding transaction, and both versions of the commitment transaction. Otherwise, an error occurred and a nil pointer along with an error are returned.

Once a ChannelReservation has been obtained, two additional steps must be processed before a payment channel can be considered 'open'. The second step validates, and processes the counterparty's channel contribution. The third, and final step verifies all signatures for the inputs of the funding transaction, and that the signature we record for our version of the commitment transaction is valid.

func (*LightningWallet) LockedOutpoints 

func (l *LightningWallet) LockedOutpoints() []*wire.OutPoint

LockedOutpoints returns a list of all currently locked outpoint.

func (*LightningWallet) PsbtFundingFinalize added in v0.3.0 

func (l *LightningWallet) PsbtFundingFinalize(pid [32]byte, packet *psbt.Packet,
	rawTx *wire.MsgTx) error

PsbtFundingFinalize looks up a previously registered funding intent by its pending channel ID and tries to advance the state machine by finalizing the passed PSBT.

func (*LightningWallet) PsbtFundingVerify added in v0.3.0 

func (l *LightningWallet) PsbtFundingVerify(pid [32]byte,
	packet *psbt.Packet) error

PsbtFundingVerify looks up a previously registered funding intent by its pending channel ID and tries to advance the state machine by verifying the passed PSBT.

func (*LightningWallet) RegisterFundingIntent added in v0.3.0 

func (l *LightningWallet) RegisterFundingIntent(expectedID [32]byte,
	shimIntent chanfunding.Intent) error

RegisterFundingIntent allows a caller to signal to the wallet that if a pending channel ID of expectedID is found, then it can skip constructing a new chanfunding.Assembler, and instead use the specified chanfunding.Intent. As an example, this lets some of the parameters for funding transaction to be negotiated outside the regular funding protocol.

func (*LightningWallet) ResetReservations 

func (l *LightningWallet) ResetReservations()

ResetReservations reset the volatile wallet state which tracks all currently active reservations.

func (*LightningWallet) Shutdown 

func (l *LightningWallet) Shutdown() error

Shutdown gracefully stops the wallet, and all active goroutines.

func (*LightningWallet) Startup 

func (l *LightningWallet) Startup() error

Startup establishes a connection to the RPC source, and spins up all goroutines required to handle incoming messages.

func (*LightningWallet) ValidateChannel added in v0.2.0 

func (l *LightningWallet) ValidateChannel(channelState *channeldb.OpenChannel,
	fundingTx *wire.MsgTx) error

ValidateChannel will attempt to fully validate a newly mined channel, given its funding transaction and existing channel state. If this method returns an error, then the mined channel is invalid, and shouldn't be used.

func (*LightningWallet) WithCoinSelectLock added in v0.2.0 

func (l *LightningWallet) WithCoinSelectLock(f func() error) error

WithCoinSelectLock will execute the passed function closure in a synchronized manner preventing any coin selection operations from proceeding while the closure is executing. This can be seen as the ability to execute a function closure under an exclusive coin selection lock.

type LocalForceCloseSummary 

type LocalForceCloseSummary struct {
	// ChanPoint is the outpoint that created the channel which has been
	// force closed.
	ChanPoint wire.OutPoint

	// CloseTx is the transaction which can be used to close the channel
	// on-chain. When we initiate a force close, this will be our latest
	// commitment state.
	CloseTx *wire.MsgTx

	// CommitResolution contains all the data required to sweep the output
	// to ourselves. Since this is our commitment transaction, we'll need
	// to wait a time delay before we can sweep the output.
	//
	// NOTE: If our commitment delivery output is below the dust limit,
	// then this will be nil.
	CommitResolution *CommitOutputResolution

	// HtlcResolutions contains all the data required to sweep any outgoing
	// HTLC's and incoming HTLc's we know the preimage to. For each of these
	// HTLC's, we'll need to go to the second level to sweep them fully.
	HtlcResolutions *HtlcResolutions

	// ChanSnapshot is a snapshot of the final state of the channel at the
	// time the summary was created.
	ChanSnapshot channeldb.ChannelSnapshot

	// AnchorResolution contains the data required to sweep the anchor
	// output. If the channel type doesn't include anchors, the value of
	// this field will be nil.
	AnchorResolution *AnchorResolution
}

LocalForceCloseSummary describes the final commitment state before the channel is locked-down to initiate a force closure by broadcasting the latest state on-chain. If we intend to broadcast this this state, the channel should not be used after generating this close summary. The summary includes all the information required to claim all rightfully owned outputs when the commitment gets confirmed.

func NewLocalForceCloseSummary 

func NewLocalForceCloseSummary(chanState *channeldb.OpenChannel, signer input.Signer,
	commitTx *wire.MsgTx, localCommit channeldb.ChannelCommitment) (
	*LocalForceCloseSummary, error)

NewLocalForceCloseSummary generates a LocalForceCloseSummary from the given channel state. The passed commitTx must be a fully signed commitment transaction corresponding to localCommit.

type LockID added in v0.3.0 

type LockID [32]byte

LockID is equivalent to btcsuite/btcwallet/wtxmgr LockID type.

type MessageSigner 

type MessageSigner interface {
	// SignMessage attempts to sign a target message with the private key
	// that corresponds to the passed public key. If the target private key
	// is unable to be found, then an error will be returned. The actual
	// digest signed is the double SHA-256 of the passed message.
	SignMessage(pubKey *secp256k1.PublicKey, msg []byte) (input.Signature, error)
}

Messageinput.Signer represents an abstract object capable of signing arbitrary messages. The capabilities of this interface are used to sign announcements to the network, or just arbitrary messages that leverage the wallet's keys to attest to some message.

type OpenChannelDetails 

type OpenChannelDetails struct {
	// Channel is the active channel created by an instance of a
	// ChannelReservation and the required funding workflow.
	Channel *LightningChannel

	// ConfirmationHeight is the block height within the chain that
	// included the channel.
	ConfirmationHeight uint32

	// TransactionIndex is the index within the confirming block that the
	// transaction resides.
	TransactionIndex uint32
}

OpenChannelDetails wraps the finalized fully confirmed channel which resulted from a ChannelReservation instance with details concerning exactly _where_ in the chain the channel was ultimately opened.

type OutgoingHtlcResolution 

type OutgoingHtlcResolution struct {
	// Expiry the absolute timeout of the HTLC. This value is expressed in
	// block height, meaning after this height the HLTC can be swept.
	Expiry uint32

	// SignedTimeoutTx is the fully signed HTLC timeout transaction. This
	// must be broadcast immediately after timeout has passed. Once this
	// has been confirmed, the HTLC output will transition into the
	// delay+claim state.
	//
	// NOTE: If this field is nil, then this indicates that we don't need
	// to go to the second level to claim this HTLC. Instead, it can be
	// claimed directly from the outpoint listed below.
	SignedTimeoutTx *wire.MsgTx

	// CsvDelay is the relative time lock (expressed in blocks) that must
	// pass after the SignedTimeoutTx is confirmed in the chain before the
	// output can be swept.
	//
	// NOTE: If SignedTimeoutTx is nil, then this field denotes the CSV
	// delay needed to spend from the commitment transaction.
	CsvDelay uint32

	// ClaimOutpoint is the final outpoint that needs to be spent in order
	// to fully sweep the HTLC. The input.SignDescriptor below should be used to
	// spend this outpoint. In the case of a second-level HTLC (non-nil
	// SignedTimeoutTx), then we'll be spending a new transaction.
	// Otherwise, it'll be an output in the commitment transaction.
	ClaimOutpoint wire.OutPoint

	// SweepSignDesc is a sign descriptor that has been populated with the
	// necessary items required to spend the sole output of the above
	// transaction.
	SweepSignDesc input.SignDescriptor
}

OutgoingHtlcResolution houses the information necessary to sweep any outgoing HTLC's after their contract has expired. This struct will be needed in one of two cases: the local party force closes the commitment transaction or the remote party unilaterally closes with their version of the commitment transaction.

func (*OutgoingHtlcResolution) HtlcPoint added in v0.2.0 

func (r *OutgoingHtlcResolution) HtlcPoint() wire.OutPoint

HtlcPoint returns the htlc's outpoint on the commitment tx.

type PaymentDescriptor 

type PaymentDescriptor struct {
	// RHash is the payment hash for this HTLC. The HTLC can be settled iff
	// the preimage to this hash is presented.
	RHash PaymentHash

	// RPreimage is the preimage that settles the HTLC pointed to within the
	// log by the ParentIndex.
	RPreimage lntypes.Preimage

	// Timeout is the absolute timeout in blocks, after which this HTLC
	// expires.
	Timeout uint32

	// Amount is the HTLC amount in milli-atoms.
	Amount lnwire.MilliAtom

	// LogIndex is the log entry number that his HTLC update has within the
	// log. Depending on if IsIncoming is true, this is either an entry the
	// remote party added, or one that we added locally.
	LogIndex uint64

	// HtlcIndex is the index within the main update log for this HTLC.
	// Entries within the log of type Add will have this field populated,
	// as other entries will point to the entry via this counter.
	//
	// NOTE: This field will only be populate if EntryType is Add.
	HtlcIndex uint64

	// ParentIndex is the HTLC index of the entry that this update settles or
	// times out.
	//
	// NOTE: This field will only be populate if EntryType is Fail or
	// Settle.
	ParentIndex uint64

	// SourceRef points to an Add update in a forwarding package owned by
	// this channel.
	//
	// NOTE: This field will only be populated if EntryType is Fail or
	// Settle.
	SourceRef *channeldb.AddRef

	// DestRef points to a Fail/Settle update in another link's forwarding
	// package.
	//
	// NOTE: This field will only be populated if EntryType is Fail or
	// Settle, and the forwarded Add successfully included in an outgoing
	// link's commitment txn.
	DestRef *channeldb.SettleFailRef

	// OpenCircuitKey references the incoming Chan/HTLC ID of an Add HTLC
	// packet delivered by the switch.
	//
	// NOTE: This field is only populated for payment descriptors in the
	// *local* update log, and if the Add packet was delivered by the
	// switch.
	OpenCircuitKey *channeldb.CircuitKey

	// ClosedCircuitKey references the incoming Chan/HTLC ID of the Add HTLC
	// that opened the circuit.
	//
	// NOTE: This field is only populated for payment descriptors in the
	// *local* update log, and if settle/fails have a committed circuit in
	// the circuit map.
	ClosedCircuitKey *channeldb.CircuitKey

	// OnionBlob is an opaque blob which is used to complete multi-hop
	// routing.
	//
	// NOTE: Populated only on add payment descriptor entry types.
	OnionBlob []byte

	// ShaOnionBlob is a sha of the onion blob.
	//
	// NOTE: Populated only in payment descriptor with MalformedFail type.
	ShaOnionBlob [sha256.Size]byte

	// FailReason stores the reason why a particular payment was canceled.
	//
	// NOTE: Populate only in fail payment descriptor entry types.
	FailReason []byte

	// FailCode stores the code why a particular payment was canceled.
	//
	// NOTE: Populated only in payment descriptor with MalformedFail type.
	FailCode lnwire.FailCode

	// EntryType denotes the exact type of the PaymentDescriptor. In the
	// case of a Timeout, or Settle type, then the Parent field will point
	// into the log to the HTLC being modified.
	EntryType updateType
	// contains filtered or unexported fields
}

PaymentDescriptor represents a commitment state update which either adds, settles, or removes an HTLC. PaymentDescriptors encapsulate all necessary metadata w.r.t to an HTLC, and additional data pairing a settle message to the original added HTLC.

TODO(roasbeef): LogEntry interface??

  • need to separate attrs for cancel/add/settle/feeupdate

func PayDescsFromRemoteLogUpdates 

func PayDescsFromRemoteLogUpdates(chanID lnwire.ShortChannelID, height uint64,
	logUpdates []channeldb.LogUpdate) ([]*PaymentDescriptor, error)

PayDescsFromRemoteLogUpdates converts a slice of LogUpdates received from the remote peer into PaymentDescriptors to inform a link's forwarding decisions.

NOTE: The provided `logUpdates` MUST corresponding exactly to either the Adds or SettleFails in this channel's forwarding package at `height`.

type PaymentHash 

type PaymentHash [32]byte

PaymentHash represents the sha256 of a random value. This hash is used to uniquely track incoming/outgoing payments within this channel, as well as payments requested by the wallet/daemon.

type PsbtFundingRequired added in v0.3.0 

type PsbtFundingRequired struct {
	// Intent is the pending PSBT funding intent that needs to be funded
	// if the wrapping error is returned.
	Intent *chanfunding.PsbtIntent
}

PsbtFundingRequired is a type that implements the error interface and contains the information needed to construct a PSBT.

func (*PsbtFundingRequired) Error added in v0.3.0 

func (p *PsbtFundingRequired) Error() string

Error returns the underlying error.

NOTE: This method is part of the error interface.

type ReservationError 

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

ReservationError wraps certain errors returned during channel reservation that can be sent across the wire to the remote peer. Errors not being ReservationErrors will not be sent to the remote in case of a failed channel reservation, as they may contain private information.

func ErrChainMismatch 

func ErrChainMismatch(knownChain,
	unknownChain *chainhash.Hash) ReservationError

ErrChainMismatch returns an error indicating that the initiator tried to open a channel for an unknown chain.

func ErrChanReserveTooLarge 

func ErrChanReserveTooLarge(reserve,
	maxReserve dcrutil.Amount) ReservationError

ErrChanReserveTooLarge returns an error indicating that the chan reserve the remote is requiring, is too large to be accepted.

func ErrChanReserveTooSmall 

func ErrChanReserveTooSmall(reserve, dustLimit dcrutil.Amount) ReservationError

ErrChanReserveTooSmall returns an error indicating that the channel reserve the remote is requiring is too small to be accepted.

func ErrChanTooLarge added in v0.3.0 

func ErrChanTooLarge(chanSize, maxChanSize dcrutil.Amount) ReservationError

ErrChanTooLarge returns an error indicating that an incoming channel request was too large. We'll reject any incoming channels if they're above our configured value for the max channel size we'll accept.

func ErrChanTooSmall 

func ErrChanTooSmall(chanSize, minChanSize dcrutil.Amount) ReservationError

ErrChanTooSmall returns an error indicating that an incoming channel request was too small. We'll reject any incoming channels if they're below our configured value for the min channel size we'll accept.

func ErrCsvDelayTooLarge 

func ErrCsvDelayTooLarge(remoteDelay, maxDelay uint16) ReservationError

ErrCsvDelayTooLarge returns an error indicating that the CSV delay was to large to be accepted, along with the current max.

func ErrFunderBalanceDust 

func ErrFunderBalanceDust(commitFee, funderBalance,
	minBalance int64) ReservationError

ErrFunderBalanceDust returns an error indicating the initial balance of the funder is considered dust at the current commitment fee.

func ErrMaxHtlcNumTooLarge 

func ErrMaxHtlcNumTooLarge(maxHtlc, maxMaxHtlc uint16) ReservationError

ErrMaxHtlcNumTooLarge returns an error indicating that the 'max HTLCs in flight' value the remote required is too large to be accepted.

func ErrMaxHtlcNumTooSmall 

func ErrMaxHtlcNumTooSmall(maxHtlc, minMaxHtlc uint16) ReservationError

ErrMaxHtlcNumTooSmall returns an error indicating that the 'max HTLCs in flight' value the remote required is too small to be accepted.

func ErrMaxValueInFlightTooSmall 

func ErrMaxValueInFlightTooSmall(maxValInFlight,
	minMaxValInFlight lnwire.MilliAtom) ReservationError

ErrMaxValueInFlightTooSmall returns an error indicating that the 'max HTLC value in flight' the remote required is too small to be accepted.

func ErrMinHtlcTooLarge 

func ErrMinHtlcTooLarge(minHtlc,
	maxMinHtlc lnwire.MilliAtom) ReservationError

ErrMinHtlcTooLarge returns an error indicating that the MinHTLC value the remote required is too large to be accepted.

func ErrNonZeroPushAmount 

func ErrNonZeroPushAmount() ReservationError

ErrNonZeroPushAmount is returned by a remote peer that receives a FundingOpen request for a channel with non-zero push amount while they have 'rejectpush' enabled.

func ErrZeroCapacity 

func ErrZeroCapacity() ReservationError

ErrZeroCapacity returns an error indicating the funder attempted to put zero funds into the channel.

type ScriptInfo added in v0.3.0 

type ScriptInfo struct {
	// PkScript is the output's PkScript.
	PkScript []byte

	// WitnessScript is the full script required to properly redeem the
	// output. This field should be set to the full script if a p2wsh
	// output is being signed. For p2wkh it should be set equal to the
	// PkScript.
	WitnessScript []byte
}

ScriptInfo holds a redeem script and hash.

func CommitScriptToRemote added in v0.3.0 

func CommitScriptToRemote(chanType channeldb.ChannelType,
	key *secp256k1.PublicKey) (*ScriptInfo, uint32, error)

CommitScriptToRemote creates the script that will pay to the non-owner of the commitment transaction, adding a delay to the script based on the channel type. The second return value is the CSV deleay of the output script, what must be satisfied in order to spend the output.

type SigPool 

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

SigPool is a struct that is meant to allow the current channel state machine to parallelize all signature generation and verification. This struct is needed as _each_ HTLC when creating a commitment transaction requires a signature, and similarly a receiver of a new commitment must verify all the HTLC signatures included within the CommitSig message. A pool of workers will be maintained by the sigPool. Batches of jobs (either to sign or verify) can be sent to the pool of workers which will asynchronously perform the specified job.

func NewSigPool 

func NewSigPool(numWorkers int, signer input.Signer) *SigPool

NewSigPool creates a new signature pool with the specified number of workers. The recommended parameter for the number of works is the number of physical CPU cores available on the target machine.

func (*SigPool) Start 

func (s *SigPool) Start() error

Start starts of all goroutines that the sigPool sig pool needs to carry out its duties.

func (*SigPool) Stop 

func (s *SigPool) Stop() error

Stop signals any active workers carrying out jobs to exit so the sigPool can gracefully shutdown.

func (*SigPool) SubmitSignBatch 

func (s *SigPool) SubmitSignBatch(signJobs []SignJob)

SubmitSignBatch submits a batch of signature jobs to the sigPool. The response and cancel channels for each of the SignJob's are expected to be fully populated, as the response for each job will be sent over the response channel within the job itself.

func (*SigPool) SubmitVerifyBatch 

func (s *SigPool) SubmitVerifyBatch(verifyJobs []VerifyJob,
	cancelChan chan struct{}) <-chan *HtlcIndexErr

SubmitVerifyBatch submits a batch of verification jobs to the sigPool. For each job submitted, an error will be passed into the returned channel denoting if signature verification was valid or not. The passed cancelChan allows the caller to cancel all pending jobs in the case that they wish to bail early.

type SignJob 

type SignJob struct {
	// SignDesc is intended to be a full populated input.SignDescriptor which
	// encodes the necessary material (keys, witness script, etc) required
	// to generate a valid signature for the specified input.
	SignDesc input.SignDescriptor

	// Tx is the transaction to be signed. This is required to generate the
	// proper sighash for the input to be signed.
	Tx *wire.MsgTx

	// OutputIndex is the output index of the HTLC on the commitment
	// transaction being signed.
	OutputIndex int32

	// Cancel is a channel that should be closed if the caller wishes to
	// abandon all pending sign jobs part of a single batch.
	Cancel chan struct{}

	// Resp is the channel that the response to this particular SignJob
	// will be sent over.
	//
	// TODO(roasbeef): actually need to allow caller to set, need to retain
	// order mark commit sig as special
	Resp chan SignJobResp
}

SignJob is a job sent to the sigPool sig pool to generate a valid signature according to the passed input.SignDescriptor for the passed transaction. Jobs are intended to be sent in batches in order to parallelize the job of generating signatures for a new commitment transaction.

type SignJobResp 

type SignJobResp struct {
	// Sig is the generated signature for a particular SignJob In the case
	// of an error during signature generation, then this value sent will
	// be nil.
	Sig lnwire.Sig

	// Err is the error that occurred when executing the specified
	// signature job. In the case that no error occurred, this value will
	// be nil.
	Err error
}

SignJobResp is the response to a sign job. Both channels are to be read in order to ensure no unnecessary goroutine blocking occurs. Additionally, both channels should be buffered.

type TransactionDetail 

type TransactionDetail struct {
	// Hash is the transaction hash of the transaction.
	Hash chainhash.Hash

	// Value is the net value of this transaction (in atoms) from the
	// PoV of the wallet. If this transaction purely spends from the
	// wallet's funds, then this value will be negative. Similarly, if this
	// transaction credits the wallet, then this value will be positive.
	Value dcrutil.Amount

	// NumConfirmations is the number of confirmations this transaction
	// has. If the transaction is unconfirmed, then this value will be
	// zero.
	NumConfirmations int32

	// BlockHeight is the hash of the block which includes this
	// transaction. Unconfirmed transactions will have a nil value for this
	// field.
	BlockHash *chainhash.Hash

	// BlockHeight is the height of the block including this transaction.
	// Unconfirmed transaction will show a height of zero.
	BlockHeight int32

	// Timestamp is the unix timestamp of the block including this
	// transaction. If the transaction is unconfirmed, then this will be a
	// timestamp of txn creation.
	Timestamp int64

	// TotalFees is the total fee in atoms paid by this transaction.
	TotalFees int64

	// DestAddresses are the destinations for a transaction
	DestAddresses []stdaddr.Address

	// RawTx returns the raw serialized transaction.
	RawTx []byte

	// Label is an optional transaction label.
	Label string
}

TransactionDetail describes a transaction with either inputs which belong to the wallet, or has outputs that pay to the wallet.

type TransactionSubscription 

type TransactionSubscription interface {
	// ConfirmedTransactions returns a channel which will be sent on as new
	// relevant transactions are confirmed.
	ConfirmedTransactions() chan *TransactionDetail

	// UnconfirmedTransactions returns a channel which will be sent on as
	// new relevant transactions are seen within the network.
	UnconfirmedTransactions() chan *TransactionDetail

	// Cancel finalizes the subscription, cleaning up any resources
	// allocated.
	Cancel()
}

TransactionSubscription is an interface which describes an object capable of receiving notifications of new transaction related to the underlying wallet. TODO(roasbeef): add balance updates?

type UnilateralCloseSummary 

type UnilateralCloseSummary struct {
	// SpendDetail is a struct that describes how and when the funding
	// output was spent.
	*chainntnfs.SpendDetail

	// ChannelCloseSummary is a struct describing the final state of the
	// channel and in which state is was closed.
	channeldb.ChannelCloseSummary

	// CommitResolution contains all the data required to sweep the output
	// to ourselves. If this is our commitment transaction, then we'll need
	// to wait a time delay before we can sweep the output.
	//
	// NOTE: If our commitment delivery output is below the dust limit,
	// then this will be nil.
	CommitResolution *CommitOutputResolution

	// HtlcResolutions contains a fully populated HtlcResolutions struct
	// which contains all the data required to sweep any outgoing HTLC's,
	// and also any incoming HTLC's that we know the pre-image to.
	HtlcResolutions *HtlcResolutions

	// RemoteCommit is the exact commitment state that the remote party
	// broadcast.
	RemoteCommit channeldb.ChannelCommitment

	// AnchorResolution contains the data required to sweep our anchor
	// output. If the channel type doesn't include anchors, the value of
	// this field will be nil.
	AnchorResolution *AnchorResolution
}

UnilateralCloseSummary describes the details of a detected unilateral channel closure. This includes the information about with which transactions, and block the channel was unilaterally closed, as well as summarization details concerning the _state_ of the channel at the point of channel closure. Additionally, if we had a commitment output above dust on the remote party's commitment transaction, the necessary a input.SignDescriptor with the material necessary to seep the output are returned. Finally, if we had any outgoing HTLC's within the commitment transaction, then an OutgoingHtlcResolution for each output will included.

func NewUnilateralCloseSummary 

func NewUnilateralCloseSummary(chanState *channeldb.OpenChannel, signer input.Signer,
	commitSpend *chainntnfs.SpendDetail,
	remoteCommit channeldb.ChannelCommitment,
	commitPoint *secp256k1.PublicKey) (*UnilateralCloseSummary, error)

NewUnilateralCloseSummary creates a new summary that provides the caller with all the information required to claim all funds on chain in the event that the remote party broadcasts their commitment. The commitPoint argument should be set to the per_commitment_point corresponding to the spending commitment.

NOTE: The remoteCommit argument should be set to the stored commitment for this particular state. If we don't have the commitment stored (should only happen in case we have lost state) it should be set to an empty struct, in which case we will attempt to sweep the non-HTLC output using the passed commitPoint.

type Utxo 

type Utxo struct {
	AddressType   AddressType
	Value         dcrutil.Amount
	Confirmations int64
	PkScript      []byte
	wire.OutPoint
}

Utxo is an unspent output denoted by its outpoint, and output value of the original output.

type VerifyJob 

type VerifyJob struct {
	// PubKey is the public key that was used to generate the purported
	// valid signature. Note that with the current channel construction,
	// this public key will likely have been tweaked using the current per
	// commitment point for a particular commitment transactions.
	PubKey *secp256k1.PublicKey

	// Sig is the raw signature generated using the above public key.  This
	// is the signature to be verified.
	Sig *ecdsa.Signature

	// SigHash is a function closure generates the sighashes that the
	// passed signature is known to have signed.
	SigHash func() ([]byte, error)

	// HtlcIndex is the index of the HTLC from the PoV of the remote
	// party's update log.
	HtlcIndex uint64

	// Cancel is a channel that should be closed if the caller wishes to
	// cancel all pending verification jobs part of a single batch. This
	// channel is to be closed in the case that a single signature in a
	// batch has been returned as invalid, as there is no need to verify
	// the remainder of the signatures.
	Cancel chan struct{}

	// ErrResp is the channel that the result of the signature verification
	// is to be sent over. In the see that the signature is valid, a nil
	// error will be passed. Otherwise, a concrete error detailing the
	// issue will be passed.
	ErrResp chan *HtlcIndexErr
}

VerifyJob is a job sent to the sigPool sig pool to verify a signature on a transaction. The items contained in the struct are necessary and sufficient to verify the full signature. The passed sigHash closure function should be set to a function that generates the relevant sighash.

TODO(roasbeef): when we move to ecschnorr, make into batch signature verification using bos-coster (or pip?).

type WalletController 

type WalletController interface {
	// FetchInputInfo queries for the WalletController's knowledge of the
	// passed outpoint. If the base wallet determines this output is under
	// its control, then the original txout should be returned.  Otherwise,
	// a non-nil error value of ErrNotMine should be returned instead.
	FetchInputInfo(prevOut *wire.OutPoint) (*Utxo, error)

	// ConfirmedBalance returns the sum of all the wallet's unspent outputs
	// that have at least confs confirmations. If confs is set to zero,
	// then all unspent outputs, including those currently in the mempool
	// will be included in the final sum.
	//
	// NOTE: Only witness outputs should be included in the computation of
	// the total spendable balance of the wallet. We require this as only
	// witness inputs can be used for funding channels.
	ConfirmedBalance(confs int32) (dcrutil.Amount, error)

	// NewAddress returns the next external or internal address for the
	// wallet dictated by the value of the `change` parameter. If change is
	// true, then an internal address should be used, otherwise an external
	// address should be returned. The type of address returned is dictated
	// by the wallet's capabilities, and may be of type: p2sh, p2pkh,
	// etc.
	NewAddress(addrType AddressType, change bool) (stdaddr.Address, error)

	// LastUnusedAddress returns the last *unused* address known by the
	// wallet. An address is unused if it hasn't received any payments.
	// This can be useful in UIs in order to continually show the
	// "freshest" address without having to worry about "address inflation"
	// caused by continual refreshing. Similar to NewAddress it can derive
	// a specified address type. By default, this is a non-change address.
	LastUnusedAddress(addrType AddressType) (stdaddr.Address, error)

	// IsOurAddress checks if the passed address belongs to this wallet
	IsOurAddress(a stdaddr.Address) bool

	// SendOutputs funds, signs, and broadcasts a Decred transaction paying
	// out to the specified outputs. In the case the wallet has insufficient
	// funds, or the outputs are non-standard, an error should be returned.
	// This method also takes the target fee expressed in atoms/kB that should
	// be used when crafting the transaction.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	SendOutputs(outputs []*wire.TxOut,
		feeRate chainfee.AtomPerKByte, label string) (*wire.MsgTx, error)

	// CreateSimpleTx creates a Bitcoin transaction paying to the specified
	// outputs. The transaction is not broadcasted to the network. In the
	// case the wallet has insufficient funds, or the outputs are
	// non-standard, an error should be returned. This method also takes
	// the target fee expressed in sat/kw that should be used when crafting
	// the transaction.
	//
	// NOTE: The dryRun argument can be set true to create a tx that
	// doesn't alter the database. A tx created with this set to true
	// SHOULD NOT be broadcasted.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	CreateSimpleTx(outputs []*wire.TxOut, feeRate chainfee.AtomPerKByte,
		dryRun bool) (*txauthor.AuthoredTx, error)

	// ListUnspentWitness returns all unspent outputs which are version 0
	// witness programs. The 'minconfirms' and 'maxconfirms' parameters
	// indicate the minimum and maximum number of confirmations an output
	// needs in order to be returned by this method. Passing -1 as
	// 'minconfirms' indicates that even unconfirmed outputs should be
	// returned. Using MaxInt32 as 'maxconfirms' implies returning all
	// outputs with at least 'minconfirms'.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	ListUnspentWitness(minconfirms, maxconfirms int32) ([]*Utxo, error)

	// ListTransactionDetails returns a list of all transactions which are
	// relevant to the wallet over [startHeight;endHeight]. If start height
	// is greater than end height, the transactions will be retrieved in
	// reverse order. To include unconfirmed transactions, endHeight should
	// be set to the special value -1. This will return transactions from
	// the tip of the chain until the start height (inclusive) and
	// unconfirmed transactions.
	ListTransactionDetails(startHeight,
		endHeight int32) ([]*TransactionDetail, error)

	// LockOutpoint marks an outpoint as locked meaning it will no longer
	// be deemed as eligible for coin selection. Locking outputs are
	// utilized in order to avoid race conditions when selecting inputs for
	// usage when funding a channel.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	LockOutpoint(o wire.OutPoint)

	// UnlockOutpoint unlocks a previously locked output, marking it
	// eligible for coin selection.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	UnlockOutpoint(o wire.OutPoint)

	// LeaseOutput locks an output to the given ID, preventing it from being
	// available for any future coin selection attempts. The absolute time
	// of the lock's expiration is returned. The expiration of the lock can
	// be extended by successive invocations of this call. Outputs can be
	// unlocked before their expiration through `ReleaseOutput`.
	//
	// If the output is not known, wtxmgr.ErrUnknownOutput is returned. If
	// the output has already been locked to a different ID, then
	// wtxmgr.ErrOutputAlreadyLocked is returned.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	LeaseOutput(id LockID, op wire.OutPoint) (time.Time, error)

	// ReleaseOutput unlocks an output, allowing it to be available for coin
	// selection if it remains unspent. The ID should match the one used to
	// originally lock the output.
	//
	// NOTE: This method requires the global coin selection lock to be held.
	ReleaseOutput(id LockID, op wire.OutPoint) error

	// PublishTransaction performs cursory validation (dust checks, etc),
	// then finally broadcasts the passed transaction to the Decred network.
	// If the transaction is rejected because it is conflicting with an
	// already known transaction, ErrDoubleSpend is returned. If the
	// transaction is already known (published already), no error will be
	// returned. Other error returned depends on the currently active chain
	// backend. It takes an optional label which will save a label with the
	// published transaction.
	PublishTransaction(tx *wire.MsgTx, label string) error

	// AbandonDoubleSpends removes all unconfirmed transactions that also
	// spend any of the specified outpoints from the wallet. This is used
	// to fix issues when an input used in multiple different sweep
	// transactions gets confirmed in one of them (rendering the other
	// transactions invalid).
	AbandonDoubleSpends(spentOutpoints ...*wire.OutPoint) error

	// LabelTransaction adds a label to a transaction. If the tx already
	// has a label, this call will fail unless the overwrite parameter is
	// set. Labels must not be empty, and they are limited to 500 chars.
	LabelTransaction(hash chainhash.Hash, label string, overwrite bool) error

	// SubscribeTransactions returns a TransactionSubscription client which
	// is capable of receiving async notifications as new transactions
	// related to the wallet are seen within the network, or found in
	// blocks.
	//
	// NOTE: a non-nil error should be returned if notifications aren't
	// supported.
	//
	// TODO(roasbeef): make distinct interface?
	SubscribeTransactions() (TransactionSubscription, error)

	// IsSynced returns a boolean indicating if from the PoV of the wallet,
	// it has fully synced to the current best block in the main chain.
	// It also returns an int64 indicating the timestamp of the best block
	// known to the wallet, expressed in Unix epoch time
	IsSynced() (bool, int64, error)

	// InitialSyncChannel returns a channel that is closed once the wallet
	// has performed its initial sync procedures, is caught up to the
	// network and potentially ready for use.
	InitialSyncChannel() <-chan struct{}

	// BestBlock returns the block height, block hash and timestamp for the
	// tip of the main chain as viewed by the internal wallet controller.
	BestBlock() (int64, chainhash.Hash, int64, error)

	// GetRecoveryInfo returns a boolean indicating whether the wallet is
	// started in recovery mode. It also returns a float64 indicating the
	// recovery progress made so far.
	GetRecoveryInfo() (bool, float64, error)

	// Start initializes the wallet, making any necessary connections,
	// starting up required goroutines etc.
	Start() error

	// Stop signals the wallet for shutdown. Shutdown may entail closing
	// any active sockets, database handles, stopping goroutines, etc.
	Stop() error

	// BackEnd returns a name for the wallet's backing chain service,
	// which could be e.g. dcrd or another consensus service.
	BackEnd() string
}

WalletController defines an abstract interface for controlling a local Pure Go wallet, a local or remote wallet via an RPC mechanism, or possibly even a daemon assisted hardware wallet. This interface serves the purpose of allowing LightningWallet to be seamlessly compatible with several wallets such as: uspv, dcrwallet, etc. This interface then serves as a "base wallet", with Lightning Network awareness taking place at a "higher" level of abstraction. Essentially, an overlay wallet. Implementors of this interface must closely adhere to the documented behavior of all interface methods in order to ensure identical behavior across all concrete implementations.

type WalletDriver 

type WalletDriver struct {
	// WalletType is a string which uniquely identifies the
	// WalletController that this driver, drives.
	WalletType string

	// New creates a new instance of a concrete WalletController
	// implementation given a variadic set up arguments. The function takes
	// a variadic number of interface parameters in order to provide
	// initialization flexibility, thereby accommodating several potential
	// WalletController implementations.
	New func(args ...interface{}) (WalletController, error)

	// BackEnds returns a list of available chain service drivers for the
	// wallet driver.
	BackEnds func() []string
}

WalletDriver represents a "driver" for a particular concrete WalletController implementation. A driver is identified by a globally unique string identifier along with a 'New()' method which is responsible for initializing a particular WalletController concrete implementation.

func RegisteredWallets 

func RegisteredWallets() []*WalletDriver

RegisteredWallets returns a slice of all currently registered notifiers.

NOTE: This function is safe for concurrent access.

Source Files

View all Source files

Directories

Path Synopsis
loader
Package loader provides a concurrent safe implementation of a wallet loader.
 Package loader provides a concurrent safe implementation of a wallet loader.

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.