# 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 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
# Functions
CommitSpendNoDelay constructs a valid witness allowing a node to spend their settled no-delay output on the counterparty's commitment transaction.
CommitSpendRevoke constructs a valid witness allowing a node to sweep the settled output of a malicious counterparty who broadcasts a revoked commitment transaction.
CommitSpendTimeout constructs a valid witness allowing the owner of a particular commitment transaction to spend the output returning settled funds back to themselves after a relative block timeout.
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.
DefaultDustLimit is used to calculate the dust HTLC amount which will be send to other node during funding process.
DeriveRevocationPrivKey derives the revocation private key given a node's commitment private key, and the preimage to a previously seen revocation hash.
DeriveRevocationPubkey derives the revocation public key given the counterparty's commitment key, and revocation preimage derived via a pseudo-random-function.
DisableLog disables all library log output.
FindScriptOutputIndex finds the index of the public key script output matching 'script'.
GenFundingPkScript creates a redeem script, and its matching p2wsh output for the funding transaction.
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 obsfucator.
NewChannelReservation creates a new channel reservation.
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.
NewMessageSigner returns the new instance of message signer.
RegisteredWallets returns a slice of all currently registered notifiers.
RegisterWallet registers a WalletDriver which is capable of driving a concrete WalletController interface.
SetLogWriter uses a specified io.Writer to output package logging info.
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.
SpendMultiSig generates the witness stack required to redeem the 2-of-2 p2wsh multi-sig output.
SupportedWallets returns a slice of strings that represents the wallet drivers that have been registered and are therefore supported.
UseLogger uses a specified Logger to output package logging info.
# Constants
Add is an update type that adds a new HTLC entry into the log.
BaseCommitmentTxCost 500 weight.
BaseCommitmentTxSize 125 43 * num-htlc-outputs bytes - Version: 4 bytes - WitnessHeader <---- part of the witness data - CountTxIn: 1 byte - TxIn: 41 bytes FundingInput - CountTxOut: 1 byte - TxOut: 74 + 43 * num-htlc-outputs bytes OutputPayingToThem, OutputPayingToUs, ....HTLCOutputs..
CommitmentDelayOutput 43 bytes - Value: 8 bytes - VarInt: 1 byte (PkScript length) - PkScript (P2WSH).
CommitmentKeyHashOutput 31 bytes - Value: 8 bytes - VarInt: 1 byte (PkScript length) - PkScript (P2WPKH).
Fail is an update type which removes a prior HTLC entry from the log.
FundingInputSize 41 bytes - PreviousOutPoint: - Hash: 32 bytes - Index: 4 bytes - OP_DATA: 1 byte (ScriptSigLength) - ScriptSig: 0 bytes - Witness <---- we use "Witness" instead of "ScriptSig" for transaction validation, but "Witness" is stored separately and cost for it size is smaller.
HTLCCost 172 weight.
HTLCSize 43 bytes - Value: 8 bytes - VarInt: 1 byte (PkScript length) - PkScript (PW2SH).
InitialRevocationWindow is the number of revoked commitment transactions allowed within the commitment chain.
MaxHTLCNumber shows as the maximum number HTLCs which can be included in commitment transaction.
MultiSigSize 71 bytes - OP_2: 1 byte - OP_DATA: 1 byte (pubKeyAlice length) - pubKeyAlice: 33 bytes - OP_DATA: 1 byte (pubKeyBob length) - pubKeyBob: 33 bytes - OP_2: 1 byte - OP_CHECKMULTISIG: 1 byte.
NestedWitnessPubKey represents a p2sh output which is itself a nested p2wkh output.
P2WPKHSize 22 bytes - OP_0: 1 byte - OP_DATA: 1 byte (PublicKeyHASH160 length) - PublicKeyHASH160: 20 bytes.
P2WSHSize 34 bytes - OP_0: 1 byte - OP_DATA: 1 byte (WitnessScriptSHA256 length) - WitnessScriptSHA256: 32 bytes.
PubKeyHash represents a regular p2pkh output.
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.
WitnessCommitmentTxCost 224 weight.
WitnessHeaderSize 2 bytes - Flag: 1 byte - Marker: 1 byte.
WitnessPubKey represents a p2wkh address.
WitnessSize 222 bytes - NumberOfWitnessElements: 1 byte - NilLength: 1 byte - sigAliceLength: 1 byte - sigAlice: 73 bytes - sigBobLength: 1 byte - sigBob: 73 bytes - WitnessScriptLength: 1 byte - WitnessScript (MultiSig).
# Variables
ErrChanClosing is returned when a caller attempts to close a channel that has already been closed or is in the process of being closed.
ErrMaxHTLCNumber is returned when a proposed HTLC would exceed the maximum number of allowed HTLC's if committed in a state transition.
ErrMaxWeightCost is returned when the cost/weight (see segwit) exceeds the widely used maximum allowed policy weight limit.
ErrNotMine is an error denoting that a WalletController instance is unable to spend a specifid output.
ErrNoWindow is returned when revocation window is exausted.
No description provided by the author
SequenceLockTimeSeconds is the 22nd bit which indicates the lock time is in seconds.
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
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 a counterparty.
Config is a struct which houses configuration parameters which modify the behaviour of LightningWallet.
ErrInsufficientFunds is a type matching the error interface which is returned when coin selection for a new funding transaction fails to due having an insufficient amount of confirmed funds.
ForceCloseSummary describes the final commitment state before the channel is locked-down to initiate a force closure by broadcasting the latest state on-chain.
InputScript represents any script inputs required to redeem a previous output.
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.
MessageSigner is used for creation the signatures using the node identity key.
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.
PaymentDescriptor represents a commitment state update which either adds, settles, or removes an HTLC.
SignDescriptor houses the necessary information required to successfully sign a given output.
TransactionDetail describes a transaction with either inputs which belong to the wallet, or has outputs that pay to the wallet.
Utxo is an unspent output denoted by its outpoint, and output value of the original output.
WalletDriver represents a "driver" for a particular concrete WalletController implementation.
# Interfaces
BlockChainIO is a dedicated source which will be used to obtain queries related to the current state of the blockchain.
Signer represents an abstract object capable of generating raw signatures as well as full complete input scripts given a valid SignDescriptor and transaction.
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
AddressType is a enum-like type which denotes the possible address types WalletController supports.
PaymentHash represents the sha256 of a random value.