package
0.18.4-beta.rc2
Repository: https://github.com/lightningnetwork/lnd.git
Documentation: pkg.go.dev
# README
lnwallet
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 lnd 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
lnd 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/lightningnetwork/lnd/lnwallet
# Packages
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
# Functions
CalcFeeBuffer calculates a FeeBuffer in accordance with the recommended amount specified in BOLT 02.
CommitScriptAnchors return the scripts to use for the local and remote anchor.
CommitScriptToRemote derives the appropriate to_remote script based on the channel's commitment type.
CommitScriptToSelf constructs the public key script for the output on the commitment transaction paying to the "owner" of said commitment transaction.
CommitWeight returns the base commitment weight before adding HTLCs.
CoopCloseBalance returns the final balances that should be used to create the cooperative close tx, given the channel type and transaction fee.
CreateCommitmentTxns is a helper function that creates the initial commitment transaction for both parties.
CreateCommitTx creates a commitment transaction, spending from specified funding output.
CreateCooperativeCloseTx creates a transaction which if signed by both parties, then broadcast cooperatively closes an active channel.
CreateHtlcSuccessTx creates a transaction that spends the output on the commitment transaction of the peer that receives an HTLC.
CreateHtlcTimeoutTx creates a transaction that spends the HTLC output on the commitment transaction of the peer that created an HTLC (the sender).
CreateTestChannels creates to fully populated channels to be used within testing fixtures.
DefaultCommitSort is the default commitment sort function that sorts the commitment transaction inputs and outputs according to BIP69.
DefaultRoutingFeeLimitForAmount returns the default off-chain routing fee limit lnd uses if the user does not specify a limit manually.
DeriveCommitmentKeys generates a new commitment key set using the base points and commitment point.
DeriveStateHintObfuscator derives the bytes to be used for obfuscating the state hints from the root to be used for a new channel.
DisableLog disables all library log output.
DustLimitForSize retrieves the dust limit for a given pkscript size.
DustLimitUnknownWitness returns the dust limit for an UnknownWitnessSize.
EmptyMockJobHandler is a mock job handler that just sends an empty response to all jobs.
ErrChainMismatch returns an error indicating that the initiator tried to open a channel for an unknown chain.
ErrChanReserveTooLarge returns an error indicating that the chan reserve the remote is requiring, is too large to be accepted.
ErrChanReserveTooSmall returns an error indicating that the channel reserve the remote is requiring is too small to be accepted.
ErrChanTooLarge returns an error indicating that an incoming channel request was too large.
ErrChanTooSmall returns an error indicating that an incoming channel request was too small.
ErrCsvDelayTooLarge returns an error indicating that the CSV delay was to large to be accepted, along with the current max.
ErrFunderBalanceDust returns an error indicating the initial balance of the funder is considered dust at the current commitment fee.
ErrInvalidDustLimit returns an error indicating that a proposed DustLimit was rejected.
ErrMaxHtlcNumTooLarge returns an error indicating that the 'max HTLCs in flight' value the remote required is too large to be accepted.
ErrMaxHtlcNumTooSmall returns an error indicating that the 'max HTLCs in flight' value the remote required is too small to be accepted.
ErrMaxValueInFlightTooSmall returns an error indicating that the 'max HTLC value in flight' the remote required is too small to be accepted.
ErrMinHtlcTooLarge returns an error indicating that the MinHTLC value the remote required is too large to be accepted.
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.
ErrNumConfsTooLarge returns an error indicating that the number of confirmations required for a channel is too large.
ErrZeroCapacity returns an error indicating the funder attempted to put zero funds into the channel.
ForceStateTransition executes the necessary interaction between the two commitment state machines to transition to a new state locking in any pending updates.
GenTaprootHtlcScript generates the HTLC scripts for a taproot+musig2 channel.
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.
HtlcIsDust determines if an HTLC output is dust or not depending on two bits: if the HTLC is incoming and if the HTLC will be placed on our commitment transaction, or theirs.
HtlcSecondLevelInputSequence dictates the sequence number we must use on the input to a second level HTLC transaction.
HtlcSigHashType returns the sighash type to use for HTLC success and timeout transactions given the channel type.
HtlcSignDetails converts the passed parameters to a SignDetails valid for this channel type.
HtlcSuccessFee returns the fee in satoshis required for an HTLC success transaction based on the current fee rate.
HtlcTimeoutFee returns the fee in satoshis required for an HTLC timeout transaction based on the current fee rate.
InPlaceCommitSort performs an in-place sort of a commitment transaction, given an unsorted transaction and a list of CLTV values for the HTLCs.
InternalKeyForAddr returns the internal key associated with a taproot address.
NewAnchorResolution returns the information that is required to sweep the local anchor.
NewAuxChanState creates a new AuxChanState from the given channel state.
NewAuxSigJob creates a new AuxSigJob.
NewAuxSignerMock creates a new mock aux signer with the given job handler.
NewAuxVerifyJob creates a new AuxVerifyJob.
NewBreachRetribution creates a new fully populated BreachRetribution for the passed channel, at a particular revoked state number.
NewChannelReservation creates a new channel reservation.
NewCoinSource creates a new instance of the CoinSource wrapper struct.
NewCommitmentBuilder creates a new CommitmentBuilder from chanState.
No description provided by the author
NewLightningChannel creates a new, active payment channel given an implementation of the chain notifier, channel database, and the current settled channel state.
NewLightningWallet creates/opens and initializes a LightningWallet instance.
NewLocalForceCloseSummary generates a LocalForceCloseSummary from the given channel state.
NewMusigPairSession creates a new musig2 pair session.
NewMusigPartialSig creates a new MuSig2 partial signature.
NewPartialMusigSession creates a new musig2 session given only the verification nonce (local nonce), and the other information that has already been bound to the session.
NewSigPool creates a new signature pool with the specified number of workers.
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.
NewWalletPrevOutputFetcher creates a new WalletPrevOutputFetcher that fetches previous outputs from the given wallet controller.
RegisteredWallets returns a slice of all currently registered notifiers.
RegisterWallet registers a WalletDriver which is capable of driving a concrete WalletController interface.
SecondLevelHtlcScript derives the appropriate second level HTLC script based on the channel's commitment type.
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.
SupportedWallets returns a slice of strings that represents the wallet drivers that have been registered and are therefore supported.
TapscriptRootToTweak is a helper function that converts a tapscript root into a tweak that can be used with the MuSig2 API.
UseLogger uses a specified Logger to output package logging info.
ValidateUpfrontShutdown checks whether the provided upfront_shutdown_script is of a valid type that we accept.
VerifyConstraints is a helper function that can be used to check the sanity of various channel constraints.
WithAuxLeaves is a functional option that can be used to set the aux leaves for a new commitment transaction.
WithAuxResolver is used to specify a custom aux contract resolver for the channel.
WithAuxSigner is used to specify a custom aux signer for the channel.
WithCoopCloseMusigSession can be used to apply an existing musig2 session to the cooperative close process.
WithCustomCoopSort can be used to modify the way the co-op close transaction is sorted.
WithCustomTxSort can be used to modify the way the close transaction is sorted.
WithExtraCloseOutputs can be used to add extra outputs to the cooperative transaction.
WithExtraTxCloseOutputs can be used to add extra outputs to the cooperative transaction.
WithLeafStore is used to specify a custom leaf store for the channel.
WithLocalCounterNonce is used to generate local nonces based on the shachain producer and the current height.
WithLocalMusigNonces is used to bind an existing verification/local nonce to a new channel.
WithRBFCloseTx signals that the cooperative close tx should signal RBF.
WithRemoteMusigNonces is used to bind the remote party's local/verification nonce to a new channel.
WithSkipContractResolutions creates an option to skip the contract resolutions from the returned summary.
WithSkipNonceInit is used to modify the way nonces are handled during channel initialization for taproot channels.
# Constants
Add is an update type that adds a new HTLC entry into the log.
AdditionalHtlc just accounts for an additional htlc which is helpful when deciding about a fee update of the commitment transaction.
AnchorChanReservedValue is the amount we'll keep around in the wallet in case we have to fee bump anchor channels on force close.
AnchorSize is the constant anchor output size.
Breach represents a breach by the remote party.
CommitmentTypeAnchorsZeroFeeHtlcTx is a commitment type that is an extension of the outdated CommitmentTypeAnchors, which in addition requires second-level HTLC transactions to be signed using a zero-fee.
CommitmentTypeLegacy is the legacy commitment format with a tweaked to_remote key.
CommitmentTypeScriptEnforcedLease is a commitment type that builds upon CommitmentTypeTweakless and CommitmentTypeAnchorsZeroFeeHtlcTx, which in addition requires a CLTV clause to spend outputs paying to the channel initiator.
CommitmentTypeSimpleTaproot is the base commitment type for the channels that use a musig2 funding output and the tapscript tree where relevant for the commitment transaction pk scripts.
CommitmentTypeSimpleTaprootOverlay builds on the existing CommitmentTypeSimpleTaproot type but layers on a special overlay protocol.
CommitmentTypeTweakless is a newer commitment format where the to_remote key is static.
DefaultAccountName is the name for the default account used to manage on-chain funds within the wallet.
DefaultAnchorsCommitMaxFeeRateSatPerVByte is the default max fee rate in sat/vbyte the initiator will use for anchor channels.
DefaultRoutingFeePercentage is the default off-chain routing fee we allow to be charged for a payment over the RoutingFee100PercentUpTo size.
Fail is an update type which removes a prior HTLC entry from the log.
FeeBuffer accounts for several edge cases.
FeeUpdate is an update type sent by the channel initiator that updates the fee rate used when signing the commitment transaction.
LocalForceClose represents a local force close.
LocalMusigCommit denotes that this a session for the local commitment.
MalformedFail is an update type which removes a prior HTLC entry from the log.
MaxAnchorChanReservedValue is the maximum value we'll reserve for anchor channel fee bumping.
NestedWitnessPubKey represents a p2sh output which is itself a nested p2wkh output.
NoBuffer means no additional buffer is accounted for.
RemoteForceClose represents a remote force close.
RemoteMusigCommit denotes that this is a session for the remote commitment.
SentAcceptChannel is the state the fundee is in after sending the AcceptChannel message.
SentFundingCreated is the state the funder is in after sending the FundingCreated message.
SentOpenChannel is the state the funder is in after sending the OpenChannel message.
Settle is an update type which settles a prior HTLC crediting the balance of the receiving node.
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.
TaprootPubkey represents a p2tr key path spending address.
UnknownAddressType represents an output with an unknown or non-standard script.
WaitingToSend is the state either the funder/fundee is in after creating a reservation, but hasn't sent a message yet.
WitnessPubKey represents a p2wkh address.
# Variables
No description provided by the author
DefaultPrivatePassphrase is the default private passphrase used for the wallet.
DefaultPublicPassphrase is the default public passphrase used for the wallet.
ErrBelowChanReserve is returned when a proposed HTLC would cause one of the peer's funds to dip below the channel reserve limit.
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.
ErrCannotSyncCommitChains is returned if, upon receiving a ChanSync message, the state machine deems that is unable to properly synchronize states with the remote peer.
ErrChanClosing is returned when a caller attempts to close a channel that has already been closed or is in the process of being closed.
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.
ErrDoubleSpend is returned from PublishTransaction in case the tx being published is spending an output spent by a conflicting transaction.
ErrDuplicatePendingChanID is returned when an existing pending channel ID is registered again.
ErrEmptyPendingChanID is returned when an empty value is used for the pending channel ID.
ErrFeeBufferNotInitiator is returned when the FeeBuffer is enforced although the channel was not initiated (opened) locally.
ErrForceCloseLocalDataLoss is returned in the case a user (or another sub-system) attempts to force close when we've detected that we've likely lost data ourselves.
ErrInvalidHTLCAmt signals that a proposed HTLC has a value that is not positive.
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.
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.
ErrInvalidMinconf is returned if we try to create a transaction with invalid minConfs value.
ErrMaxHTLCNumber is returned when a proposed HTLC would exceed the maximum number of allowed HTLC's if committed in a state transition.
ErrMaxPendingAmount is returned when a proposed HTLC would exceed the overall maximum pending value of all HTLCs if committed in a state transition.
ErrMaxWeightCost is returned when the cost/weight (see segwit) exceeds the widely used maximum allowed policy weight limit.
ErrMempoolFee is returned from PublishTransaction in case the tx being published is not accepted into mempool because the fee requirements of the mempool backend are not met.
ErrNoOutputs is returned if we try to create a transaction with no outputs or send coins to a set of outputs that is empty.
ErrNoRevocationLogFound is returned when both the returned logs are nil from querying the revocation log bucket.
ErrNotMine is an error denoting that a WalletController instance is unable to spend a specified output.
ErrNoWindow is returned when revocation window is exhausted.
ErrOutputIndexOutOfRange is returned when an output index is greater than or equal to the length of a given transaction's outputs.
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.
ErrReservedValueInvalidated is returned if we try to publish a transaction that would take the walletbalance below what we require to keep around to fee bump our open anchor channels.
ErrRevLogDataMissing is returned when a certain wanted optional field in a revocation log entry is missing.
ErrSessionNotFinalized is returned when the SignCommit method is called for a local commitment, without the session being finalized (missing nonce).
RoutingFee100PercentUpTo is the cut-off amount we allow 100% fees to be charged up to.
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.
# Structs
AccountIdentifier contains information to uniquely identify an account.
AddressProperty contains wallet related information of an address.
AddrWithKey wraps a normal addr, but also includes the internal key for the delivery addr if known.
AnchorResolution holds the information necessary to spend our commitment tx anchor.
AnchorResolutions is a set of anchor resolutions that's being used when sweeping anchors during local channel force close.
AuxChanState is a struct that holds certain fields of the channeldb.OpenChannel struct that are used by the aux components.
AuxFundingDesc stores a series of attributes that may be used to modify the way the channel funding occurs.
AuxHtlcDescriptor is a struct that contains the information needed to sign or verify an HTLC for custom channels.
AuxSigDesc stores optional information related to 2nd level HTLCs for aux channels.
AuxSigJob is a struct that contains all the information needed to sign an HTLC for custom channels.
AuxSigJobResp is a struct that contains the result of a sign job.
AuxVerifyJob is a struct that contains all the information needed to verify an HTLC for custom channels.
BaseAuxJob is a struct that contains the common fields that are shared among the aux sign/verify jobs.
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.
ChannelContribution is the primary constituent of the funding workflow within lnwallet.
ChannelReservation represents an intent to open a lightning payment channel with a counterparty.
CheckReservedValueTxReq is the request struct used to call CheckReservedValueTx with.
CloseOutput wraps a normal tx out with additional metadata that indicates if the output belongs to the initiator of the channel or not.
CoinSource is a wrapper around the wallet that implements the chanfunding.CoinSource interface.
CommitAuxLeaves stores two potential auxiliary leaves for the remote and local output that may be used to augment the final tapscript trees of the commitment transaction.
CommitDiffAuxInput is the input required to compute the diff of the auxiliary leaves for a commitment transaction.
CommitDiffAuxResult is the result of computing the diff of the auxiliary leaves for a commitment transaction.
CommitmentBuilder is a type that wraps the type of channel we are dealing with, and abstracts the various ways of constructing commitment transactions.
CommitmentKeyRing holds all derived keys needed to construct commitment and HTLC transactions.
CommitOutputResolution carries the necessary information required to allow us to sweep our commitment output in the case that either party goes to chain.
CommitSigs holds the set of related signatures for a new commitment transaction state.
Config is a struct which houses configuration parameters which modify the behaviour of LightningWallet.
ContractResolutions contains all the data required for resolving the different output types of a commitment transaction.
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.
ErrInvalidSettlePreimage is returned when trying to settle an HTLC, but the preimage does not correspond to the payment hash.
ErrUnknownHtlcIndex is returned when locally settling or failing an HTLC, but the HTLC index is not known to the channel.
HtlcIndexErr is a special type of error that also includes a pointer to the original validation job.
HtlcResolutions contains the items necessary to sweep HTLC's on chain directly from a commitment transaction.
HtlcRetribution contains all the items necessary to seep a revoked HTLC transaction from a revoked commitment transaction broadcast by the remote party.
HtlcView represents the "active" HTLCs at a particular point within the history of the HTLC update log.
IncomingHtlcResolution houses the information required to sweep any incoming HTLC's that we know the preimage to.
InitFundingReserveMsg is the first message sent to initiate the workflow required to open a payment channel with a remote peer.
InvalidCommitSigError is a struct that implements the error interface to report a failure to validate a commitment signature for a remote peer.
InvalidHtlcSigError is a struct that implements the error interface to report a failure to validate an htlc signature from a remote peer.
InvalidPartialCommitSigError is used when we encounter an invalid musig2 partial signature.
LightningChannel implements the state machine which corresponds to the current commitment protocol wire spec.
LightningWallet is a domain specific, yet general Bitcoin wallet capable of executing workflow required to interact with the Lightning Network.
LocalForceCloseSummary describes the final commitment state before the channel is locked-down to initiate a force closure by broadcasting the latest state on-chain.
No description provided by the author
No description provided by the author
MockAuxSigner is a mock implementation of the AuxSigner interface.
MusigNoncePair holds the two nonces needed to sign/verify a new commitment state.
MusigPairSession houses the two musig2 sessions needed to do funding and drive forward the state machine.
MusigPartialSig is a wrapper around the base musig2.PartialSignature type that also includes information about the set of nonces used, and also the signer.
MusigSession abstracts over the details of a logical musig session.
MusigSessionCfg is used to create a new musig2 pair session.
NewCommitState wraps the various signatures needed to properly propose/accept a new commitment state.
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.
OutgoingHtlcResolution houses the information necessary to sweep any outgoing HTLC's after their contract has expired.
OutputDetail contains additional information on a destination address.
PreviousOutPoint contains information about the previous outpoint.
PsbtFundingRequired is a type that implements the error interface and contains the information needed to construct a PSBT.
ReservationError wraps certain errors returned during channel reservation that can be sent across the wire to the remote peer.
ResolutionReq is used to ask an outside sub-system for additional information needed to resolve a contract.
SignJob is a job sent to the sigPool sig pool to generate a valid signature according to the passed SignDescriptor for the passed transaction.
SignJobResp is the response to a sign job.
SigPool is a struct that is meant to allow the current channel state machine to parallelize all signature generation and verification.
TransactionDetail describes a transaction with either inputs which belong to the wallet, or has outputs that pay to the wallet.
UnilateralCloseSummary describes the details of a detected unilateral channel closure.
Utxo is an unspent output denoted by its outpoint, and output value of the original output.
VerifyJob is a job sent to the sigPool sig pool to verify a signature on a transaction.
WalletDriver represents a "driver" for a particular concrete WalletController implementation.
WalletPrevOutputFetcher is a txscript.PrevOutputFetcher that can fetch outputs from a given wallet controller.
WitnessScriptDesc holds the output script and the witness script for p2wsh outputs.
# Interfaces
AuxContractResolver is an interface that is used to resolve contracts that may need additional outside information to resolve correctly.
AuxLeafStore is used to optionally fetch auxiliary tapscript leaves for the commitment transaction given an opaque blob.
AuxSigner is an interface that is used to sign and verify HTLCs for custom channels.
BlockChainIO is a dedicated source which will be used to obtain queries related to the current state of the blockchain.
MessageSigner represents an abstract object capable of signing arbitrary messages.
Rebroadcaster is an abstract rebroadcaster instance that'll continually rebroadcast transactions in the background until they're confirmed.
TransactionSubscription is an interface which describes an object capable of receiving notifications of new transaction related to the underlying wallet.
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.
# Type aliases
AccountAddressMap maps the account properties to an array of address properties.
AddressType is an enum-like type which denotes the possible address types WalletController supports.
BufferType is used to determine what kind of additional buffer should be left when evaluating the usable balance of a channel.
ChanCloseOpt is a closure type that cen be used to modify the set of default options.
ChannelOpt is a functional option that lets callers modify how a new channel is created.
CloseSortFunc is a function type alias for a function that sorts the closing transaction.
CloseTxOpt is a functional option that allows us to modify how the closing transaction is created.
CloseType is an enum that represents the type of close that we are trying to resolve.
CommitmentType is an enum indicating the commitment type we should use for the channel we are opening.
CommitSortFunc is a function type alias for a function that sorts the commitment transaction outputs.
CreateCommitOpt is a functional option that can be used to modify the way a new commitment transaction is created.
ErrHtlcIndexAlreadyFailed is returned when the HTLC index has already been failed, but has not been committed by our commitment state.
ErrHtlcIndexAlreadySettled is returned when the HTLC index has already been settled, but has not been committed by our commitment state.
ForceCloseOpt is a functional option argument for the ForceClose method.
MusigCommitType is an enum that denotes if this is the local or remote commitment.
MusigSessionOpt is a functional option that can be used to modify calls to the musig session.
PaymentHash represents the sha256 of a random value.
ReservationState is a type that represents the current state of a channel reservation within the funding workflow.