Categorygithub.com/lightninglabs/lndclient
modulepackage
0.19.0-3
Repository: https://github.com/lightninglabs/lndclient.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
63
Dependents
78
Files
9.6k SLOC

# README

Golang client library for lnd

lndclient is a golang native wrapper for lnd's gRPC interface.

Compatibility matrix

This library depends heavily on lnd for obvious reasons. To support backward compatibility with older versions of lnd, we use different branches for different versions. There are two "levels" of depending on a version of lnd:

  • Code level dependency: This is the version of lnd that is pulled in when compiling lndclient. It is defined in go.mod. This usually is the latest released version of lnd, because its RPC definitions are kept backward compatible. This means that a new field added in the latest version of lnd might already be available in lndclient's code, but whether or not that field will actually be set at run time is dependent on the actual version of lnd that's being connected to.
  • RPC level dependency: This is defined in minimalCompatibleVersion in lnd_services.go. When connecting to lnd, the version returned by its version service is checked and if it doesn't meet the minimal required version defined in lnd_services.go, an error will be returned. Users of lndclient can also overwrite this minimum required version when creating a new client.

The current compatibility matrix reads as follows:

lndclient git taglnd version in go.modminimum required lnd version
master / v0.18.5-13v0.18.5-betav0.18.5-beta

By default, lndclient requires (and enforces) the following RPC subservers to be active in lnd:

  • signrpc
  • walletrpc
  • chainrpc
  • invoicesrpc

Branch strategy

We follow the following strategy to maintain different versions of this library that have different lnd compatibilities:

  1. The master is always backward compatible with the last major version.
  2. We create branches for all minor versions and future major versions and merge PRs to those branches, if the features require that version to work.
  3. We rebase the branches if needed and use tags to track versions that we depend on in other projects.
  4. Once a new major version of lnd is final, all branches of minor versions lower than that are merged into master.

# Functions

AssertVersionCompatible makes sure the detected lnd version is compatible with our current version requirements.
GetTLSCredentials gets the tls credentials, whether provided as straight-up data or a path to a certificate file.
Insecure allows the basic client to establish an insecure (non-TLS) connection to the RPC server.
IsUnlockError returns true if the given error is one that lnd returns when its wallet is locked, either before version 0.13 or after.
MacaroonData is a basic client option that sets macaroon data (encoded as hex string) directly instead of loading it from a file.
MacaroonRecipe returns a list of macaroon permissions that is required to use the full feature set of the given list of RPC package names.
MacFilename is a basic client option that sets the name of the macaroon file to use.
MarshalSignMethod turns the native sign method into the RPC counterpart.
MuSig2NonceOpt adds an optional set of nonces to a musig session request.
MuSig2TaprootTweakOpt adds an optional taproot tweak to the musig session request.
NewBasicClient creates a new basic gRPC client to lnd.
NewBasicConn creates a new basic gRPC connection to lnd.
NewBoltMacaroonStore returns a new bakery.RootKeyStore, backed by a bolt DB instance at the specified location.
NewHtlcAttempt creates a htlc attempt from its rpc counterpart.
NewHtlcFailure creates a htlc failure from its rpc counterpart.
NewLndServices creates a connection to the given lnd instance and creates a set of required RPC services.
NewMacaroonService checks the config values passed in and creates a MacaroonService object accordingly.
NewOutpointFromStr creates an outpoint from a string with the format txid:index.
NewPendingChannel creates a pending channel from the rpc struct.
SignCompact sets the flag for returning a compact signature in the message request.
SignSchnorr sets the flag for returning a Schnorr signature in the message request.
SystemCerts instructs the basic client to use the system's certificate trust store for verifying the TLS certificate of the RPC server.
TLSData is a basic client option that sets TLS data (encoded in PEM format) directly instead of loading them from a file.
RPCTransaction returns a rpc transaction.
UseLogger uses a specified Logger to output package logging info.
VerifySchnorr sets the flag for checking a Schnorr signature in the message request.
VersionString returns a nice, human-readable string of a version returned by the VersionerClient, including all build tags.
VersionStringShort returns a nice, human-readable string of a version returned by the VersionerClient.
WithBudget is an option for setting the budget of BumpFee.
WithCommitmentType is an option for specifying a commitment type for the open channel request.
WithFundingShim is an option for attaching a funding shim to an open channel request.
WithImmediate is an option for enabling the immediate mode of BumpFee.
WithIncludeBlock is an optional argument that allows the caller to specify that the block that mined a transaction should be included in the response.
WithRemoteMaxHtlc limits the number of htlcs the remote party can offer.
WithRemoteReserve signals that the channel open should set a remote reserve amount.
WithReOrgChan configures a channel that will be sent on if the transaction is re-organized out of the chain.
WithScid signals that the channel open should be an option-scid-alias one.
WithTargetConf is an option for setting the target_conf of BumpFee.
WithTransactionsAccount is an option for setting the account on a GetTransactionsRequest.
WithUnspentAccount is an option for setting the account on a ListUnspentRequest.
WithUnspentUnconfirmedOnly is an option for setting the UnconfirmedOnly flag on a ListUnspentRequest.
WithZeroConf is an option for setting the zero confirmation flag on an OpenChannelRequest.

# Constants

ActiveChannelUpdate indicates that the channel event holds information about a channel that became active.
No description provided by the author
No description provided by the author
ClosedChannelUpdate indicates that the channel event holds information about a closed channel.
CloseTypeAbandoned represents a channel that was abandoned.
CloseTypeBreach represents breach closes from our peer.
CloseTypeCooperative represents cooperative closes.
CloseTypeFundingCancelled represents channels which were never created because their funding transaction was cancelled.
CloseTypeLocalForce represents force closes that we initiated.
CloseTypeRemoteForce represents force closes that our peer initiated.
ForceCloseAnchorStateLimbo is set if the recovered_balance is zero and limbo_balance is non-zero.
ForceCloseAnchorStateLost indicates a state that is neither ForceCloseAnchorStateLimbo nor ForceCloseAnchorStateRecovered.
ForceCloseAnchorStateRecovered is set if the recovered_balance is non-zero.
FullyResolvedChannelUpdate indicates that the channel event holds information about a channel has been fully closed.
InactiveChannelUpdate indicates that the channel event holds information about a channel that became inactive.
InitiatorBoth is set in the case where both parties initiated a cooperative close (this is possible with multiple rounds of negotiation).
InitiatorLocal is set when we initiated a channel open or close.
InitiatorRemote is set when the remote party initiated a chanel open or close.
InitiatorUnrecorded is set when we do not know the open/close initiator for a channel, this is the case when the channel was closed before lnd started tracking initiators.
InterceptorActionFail indicates that an intercepted htlc should be failed.
InterceptorActionResume indicates that an intercepted hltc should be resumed as normal.
InterceptorActionResumeModified indicates that an intercepted hltc should be resumed as normal, but with modifications.
InterceptorActionSettle indicates that an intercepted htlc should be settled.
No description provided by the author
NetworkMainnet is bitcoin mainnet.
NetworkRegtest is bitcoin regtest.
NetworkSimnet is bitcoin signet.
NetworkSimnet is bitcoin simnet.
NetworkTestnet is bitcoin testnet.
OpenChannelUpdate indicates that the channel event holds information about a channel that has been opened.
PendingOpenChannelUpdate indicates that the channel event holds information about a recently opened channel still in pending state.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
WalletStateLocked denotes that a wallet exists in lnd but it has not yet been unlocked.
WalletStateNonExisting denotes that no wallet has been created in lnd so far.
WalletStateRPCActive denotes that lnd is now fully ready to receive RPC requests other than wallet unlocking operations.
WalletStateServerActive denotes that lnd's main server is now fully ready to receive calls.
WalletStateUnlocked denotes that a wallet exists in lnd and it has been unlocked but the RPC server isn't yet fully started up.
WalletStateWaitingToStart indicates that lnd is at the beginning of the startup process.

# Variables

DefaultBuildTags is the list of all subserver build tags that are required for lndclient to work.
ErrBuildTagsMissing is the error that is returned if the connected lnd instance does not have all built tags activated that are required.
ErrNoRouteFound is returned if we can't find a path with the passed parameters.
ErrRouterShuttingDown is returned when a long-lived call is killed because the router is shutting down.
ErrVersionCheckNotImplemented is the error that is returned if the version RPC is not implemented in lnd.
ErrVersionIncompatible is the error that is returned if the connected lnd instance is not supported.
PaymentResultAlreadyPaid is the string result returned by SendPayment when the payment was already completed in a previous SendPayment call.
PaymentResultInFlight is the string result returned by SendPayment when the payment was initiated in a previous SendPayment call and still in flight.
PaymentResultSuccess is the string result returned by SendPayment when the payment was successful.
PaymentResultUnknownPaymentHash is the string result returned by SendPayment when the final node indicates the hash is unknown.
SharedKeyLocator is a key locator that can be used for deriving a shared secret key with LND.
SharedKeyNUMS is the public key point that can be use for when we are deriving a shared secret key with LND.

# Structs

AcceptorRequest contains the details of an incoming channel that has been proposed to our node.
AcceptorResponse contains the response to a channel acceptor request.
ChannelBalance contains information about our channel balances.
ChannelClosedUpdate indicates that our channel close has confirmed on chain.
ChannelCloseUpdate holds a channel close graph topology update.
ChannelConstraints contains information about the restraints place on a channel commit for a particular node.
ChannelEdge holds the channel edge information and routing policies.
ChannelEdgeUpdate holds a channel edge graph topology update.
ChannelEventUpdate holds the data fields and type for a particular channel update event.
ChannelInfo stores unpacked per-channel info.
ClosedChannel represents a channel that has been closed.
CustomMessage describes custom messages exchanged with peers.
ForceCloseChannel describes a channel that pending force close.
ForwardingEvent represents a htlc that was forwarded through our node.
ForwardingHistoryRequest contains the request parameters for a paginated forwarding history call.
ForwardingHistoryResponse contains the response to a forwarding history query, including last index offset required for paginated queries.
Graph describes our view of the graph.
GraphTopologyUpdate encapsulates a streamed graph update.
GrpcLndServices constitutes a set of required RPC services.
Hop holds details about a single hop along a route.
HtlcAttempt provides information about a htlc sent as part of a payment.
HtlcFailure provides information about a htlc attempt failure.
No description provided by the author
Info contains info about the connected lnd node.
InterceptedHtlc contains information about a htlc that was intercepted in lnd's switch.
InterceptedHtlcResponse contains the actions that must be taken for an intercepted htlc.
Invoice represents an invoice in lnd.
InvoiceHtlc represents a htlc that was used to pay an invoice.
InvoiceHtlcModifyRequest is a request to modify an HTLC that is attempting to settle an invoice.
InvoiceHtlcModifyResponse is a response to an HTLC modification request.
InvoiceSubscriptionRequest holds the parameters to specify from which update to start streaming.
InvoiceUpdate contains a state update for an invoice.
LeaseDescriptor contains information about a locked output.
ListInvoicesRequest contains the request parameters for a paginated list invoices call.
ListInvoicesResponse contains the response to a list invoices query, including the index offsets required for paginated queries.
ListPaymentsRequest contains the request parameters for a paginated list payments call.
ListPaymentsResponse contains the response to a list payments query, including the index offsets required for paginated queries.
LndServices constitutes a set of required services.
LndServicesConfig holds all configuration settings that are needed to connect to an lnd node.
MacaroonPermission is a struct that holds a permission entry, consisting of an entity and an action.
MacaroonService handles the creatation and unlocking of a macaroon DB file.
MacaroonServiceConfig holds configuration values used by the MacaroonService.
MissionControlEntry contains a mission control entry for a node pair.
NetworkInfo describes the structure of our view of the graph.
Node describes a node in the network.
NodeInfo contains information about a node and its channels.
NodeUpdate holds a node announcement graph topology update.
OpenStatusUpdate is a wrapper for channel status updates following a channel open attempt.
Payment represents a payment made by our node.
PaymentRequest represents a request for payment from a node.
PaymentResult signals the result of a payment.
PaymentStatus describe the state of a payment.
Peer contains information about a peer we are connected to.
PendingChannel contains the information common to all pending channels.
PendingChannels contains lnd's channels that are pending open and close.
PendingCloseUpdate indicates that our closing transaction has been broadcast.
PendingHtlc represents a HTLC that is currently pending on some channel.
PolicyUpdateRequest holds UpdateChanPolicy request data.
QueryRoutesRequest is the request of a QueryRoutes call.
QueryRoutesResponse is the response of a QueryRoutes call.
RoutingPolicy holds the edge routing policy for a channel edge.
SendPaymentRequest defines the payment parameters for a new payment.
SignDescriptor houses the necessary information required to successfully sign a given segwit output.
Transaction represents an on chain transaction.
WaitingCloseChannel describes a channel that we are waiting to be closed on chain.
WalletBalance describes our wallet's current balance.

# Interfaces

ChainKitClient exposes chain functionality.
ChainNotifierClient exposes base lightning functionality.
CloseChannelUpdate is an interface implemented by channel close updates.
InvoicesClient exposes invoice functionality.
LightningClient exposes base lightning functionality.
RouterClient exposes payment functionality.
ServiceClient is an interface that all lnd service clients need to implement.
SignerClient exposes sign functionality.
StateClient exposes base lightning functionality.
VersionerClient exposes the version of lnd.
WalletKitClient exposes wallet functionality.

# Type aliases

AcceptorFunction is the signature used for functions passed to our channel acceptor.
BasicClientOption is a functional option argument that allows adding arbitrary lnd basic client configuration overrides, without forcing existing users of NewBasicClient to update their invocation.
BumpFeeOption customizes a BumpFee call.
ChannelUpdateType encodes the type of update for a channel update event.
CloseType is an enum which represents the types of closes our channels may have.
DialerFunc is a function that is used as grpc.WithContextDialer().
ForceCloseAnchorState indicates the resolution state for the anchor.
HtlcInterceptHandler is a function signature for handling code for htlc interception.
Initiator indicates the party that opened or closed a channel.
InterceptFunction is a function type for intercepting RPC calls from a middleware.
InterceptorAction represents the different actions we can take for an intercepted htlc.
InvoiceHtlcModifyHandler is a function that handles an HTLC modification request.
ListTransactionsOption is a functional type for an option that modifies a GetTransactionsRequest.
ListUnspentOption is a functional type for an option that modifies a ListUnspentRequest.
LnrpcServiceMac is the name of a macaroon that can be used to authenticate with a specific lnrpc service.
MuSig2SessionOpts is the signature used to apply functional options to musig session requests.
Network defines the chain that we operate on.
NotifierOption is a functional option that allows a caller to modify the events received from the notifier.
OpenChannelOption is a functional type for an option that modifies an OpenChannelRequest.
SignMessageOption is a function type that allows the customization of a SignMessage RPC request.
VerifyMessageOption is a function type that allows the customization of a VerifyMessage RPC request.
WalletState is a type that represents all states the lnd wallet can be in.