lnrpc

README

lnrpc

This lnrpc package implements both a client and server for lnds RPC system which is based off of the high-performance cross-platform gRPC RPC framework. By default, only the Go client+server libraries are compiled within the package. In order to compile the client side libraries for other supported languages, the protoc tool will need to be used to generate the compiled protos for a specific language.

The following languages are supported as clients to lnrpc: C++, Go, Node.js, Java, Ruby, Android Java, PHP, Python, C#, Objective-C.

Service: Lightning

The list of defined RPCs on the service Lightning are the following (with a brief description):

• WalletBalance
  • Returns the wallet's current confirmed balance in BTC.
• ChannelBalance
  • Returns the daemons' available aggregate channel balance in BTC.
• GetTransactions
  • Returns a list of on-chain transactions that pay to or are spends from lnd.
• SendCoins
  • Sends an amount of satoshis to a specific address.
• ListUnspent
  • Lists available utxos within a range of confirmations.
• SubscribeTransactions
  • Returns a stream which sends async notifications each time a transaction is created or one is received that pays to us.
• SendMany
  • Allows the caller to create a transaction with an arbitrary fan-out (many outputs).
• NewAddress
  • Returns a new address, the following address types are supported: pay-to-witness-key-hash (p2wkh) and nested-pay-to-witness-key-hash (np2wkh).
• SignMessage
  • Signs a message with the node's identity key and returns a zbase32 encoded signature.
• VerifyMessage
  • Verifies a signature signed by another node on a message. The other node must be an active node in the channel database.
• ConnectPeer
  • Connects to a peer identified by a public key and host.
• DisconnectPeer
  • Disconnects a peer identified by a public key.
• ListPeers
  • Lists all available connected peers.
• GetInfo
  • Returns basic data concerning the daemon.
• PendingChannels
  • List the number of pending (not fully confirmed) channels.
• ListChannels
  • List all active channels the daemon manages.
• OpenChannelSync
  • OpenChannelSync is a synchronous version of the OpenChannel RPC call.
• OpenChannel
  • Attempts to open a channel to a target peer with a specific amount and push amount.
• CloseChannel
  • Attempts to close a target channel. A channel can either be closed cooperatively if the channel peer is online, or using a "force" close to broadcast the latest channel state.
• SendPayment
  • Send a payment over Lightning to a target peer.
• SendPaymentSync
  • SendPaymentSync is the synchronous non-streaming version of SendPayment.
• SendToRoute
  • Send a payment over Lightning to a target peer through a route explicitly defined by the user.
• SendToRouteSync
  • SendToRouteSync is the synchronous non-streaming version of SendToRoute.
• AddInvoice
  • Adds an invoice to the daemon. Invoices are automatically settled once seen as an incoming HTLC.
• ListInvoices
  • Lists all stored invoices.
• LookupInvoice
  • Attempts to look up an invoice by payment hash (r-hash).
• SubscribeInvoices
  • Creates a uni-directional stream which receives async notifications as the daemon settles invoices
• DecodePayReq
  • Decode a payment request, returning a full description of the conditions encoded within the payment request.
• ListPayments
  • List all outgoing Lightning payments the daemon has made.
• DeleteAllPayments
  • Deletes all outgoing payments from DB.
• DescribeGraph
  • Returns a description of the known channel graph from the PoV of the node.
• GetChanInfo
  • Returns information for a specific channel identified by channel ID.
• GetNodeInfo
  • Returns information for a particular node identified by its identity public key.
• QueryRoutes
  • Queries for a possible route to a target peer which can carry a certain amount of payment.
• GetNetworkInfo
  • Returns some network level statistics.
• StopDaemon
  • Sends a shutdown request to the interrupt handler, triggering a graceful shutdown of the daemon.
• SubscribeChannelGraph
  • Creates a stream which receives async notifications upon any changes to the channel graph topology from the point of view of the responding node.
• DebugLevel
  • Set logging verbosity of lnd programmatically
• FeeReport
  • Allows the caller to obtain a report detailing the current fee schedule enforced by the node globally for each channel.
• UpdateChannelPolicy
  • Allows the caller to update the fee schedule and channel policies for all channels globally, or a particular channel.
• ForwardingHistory
  • ForwardingHistory allows the caller to query the htlcswitch for a record of all HTLCs forwarded.
• BakeMacaroon
  • Bakes a new macaroon with the provided list of permissions and restrictions

Service: WalletUnlocker

The list of defined RPCs on the service WalletUnlocker are the following (with a brief description):

• CreateWallet
  • Set encryption password for the wallet database.
• UnlockWallet
  • Provide a password to unlock the wallet database.

Installation and Updating

$ go get -u github.com/lightningnetwork/lnd/lnrpc

Generate protobuf definitions

1. Download v.3.4.0 of protoc for your operating system and add it to your PATH. For example, if using macOS:

$ curl -LO https://github.com/google/protobuf/releases/download/v3.4.0/protoc-3.4.0-osx-x86_64.zip
$ unzip protoc-3.4.0-osx-x86_64.zip -d protoc
$ export PATH=$PWD/protoc/bin:$PATH

1. Install golang/protobuf at commit b5d812f8a3706043e23a9cd5babf2e5423744d30 (v1.3.1).

$ git clone https://github.com/golang/protobuf $GOPATH/src/github.com/golang/protobuf
$ cd $GOPATH/src/github.com/golang/protobuf
$ git reset --hard v1.3.1
$ make

1. Install 'genproto' at commit a8101f21cf983e773d0c1133ebc5424792003214.

$ go get google.golang.org/genproto
$ cd $GOPATH/src/google.golang.org/genproto
$ git reset --hard a8101f21cf983e773d0c1133ebc5424792003214

1. Install grpc-ecosystem/grpc-gateway at version v1.8.6.

$ git clone https://github.com/grpc-ecosystem/grpc-gateway $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway
$ cd $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway
$ git reset --hard v1.8.6
$ go install ./protoc-gen-grpc-gateway ./protoc-gen-swagger

1. Run gen_protos.sh to generate new protobuf definitions.

Documentation

Index

• Variables
• func CalculateFeeLimit(feeLimit *api.FeeLimit, amount lnwire.MilliSatoshi) lnwire.MilliSatoshi
• func FileExists(name string) bool
• func RegisterSubServer(driver *SubServerDriver) error
• func SupportedServers() []string
• func UnmarshallAmt(amtSat, amtMsat int64) (lnwire.MilliSatoshi, error)
• type MacaroonPerms
• type SubServer
• type SubServerConfigDispatcher
• type SubServerDriver
  • func RegisteredSubServers() []*SubServerDriver

Variables

var (
	// ErrSatMsatMutualExclusive is returned when both a sat and an msat
	// amount are set.
	ErrSatMsatMutualExclusive = errors.New(
		"sat and msat arguments are mutually exclusive",
	)
)

Functions

func CalculateFeeLimit

func CalculateFeeLimit(feeLimit *api.FeeLimit,
	amount lnwire.MilliSatoshi) lnwire.MilliSatoshi

CalculateFeeLimit returns the fee limit in millisatoshis. If a percentage based fee limit has been requested, we'll factor in the ratio provided with the amount of the payment.

func FileExists

func FileExists(name string) bool

FileExists reports whether the named file or directory exists.

func RegisterSubServer

func RegisterSubServer(driver *SubServerDriver) error

RegisterSubServer should be called by a sub-server within its package's init() method to register its existence with the main sub-server map. Each sub-server, if active, is meant to register via this method in their init() method. This allows callers to easily initialize and register all sub-servers without knowing any details beyond that the fact that they satisfy the necessary interfaces.

NOTE: This function is safe for concurrent access.

func SupportedServers

func SupportedServers() []string

SupportedServers returns slice of the names of all registered sub-servers.

NOTE: This function is safe for concurrent access.

func UnmarshallAmt

func UnmarshallAmt(amtSat, amtMsat int64) (lnwire.MilliSatoshi, error)

UnmarshallAmt returns a strong msat type for a sat/msat pair of rpc fields.

Types

type MacaroonPerms

type MacaroonPerms map[string][]bakery.Op

MacaroonPerms is a map from the FullMethod of an invoked gRPC command. It maps the set of operations that the macaroon presented with the command MUST satisfy. With this map, all sub-servers are able to communicate to the primary macaroon service what type of macaroon must be passed with each method present on the service of the sub-server.

type SubServer

type SubServer interface {
	// Start starts the sub-server and all goroutines it needs to operate.
	Start() error

	// Stop signals that the sub-server should wrap up any lingering
	// requests, and being a graceful shutdown.
	Stop() error

	// Name returns a unique string representation of the sub-server. This
	// can be used to identify the sub-server and also de-duplicate them.
	Name() string

	// RegisterWithRootServer will be called by the root gRPC server to
	// direct a sub RPC server to register itself with the main gRPC root
	// server. Until this is called, each sub-server won't be able to have
	// requests routed towards it.
	RegisterWithRootServer(*grpc.Server) error
}

SubServer is a child server of the main lnrpc gRPC server. Sub-servers allow lnd to expose discrete services that can be used with or independent of the main RPC server. The main rpcserver will create, start, stop, and manage each sub-server in a generalized manner.

type SubServerConfigDispatcher

type SubServerConfigDispatcher interface {
	// FetchConfig attempts to locate an existing configuration file mapped
	// to the target sub-server. If we're unable to find a config file
	// matching the subServerName name, then false will be returned for the
	// second parameter.
	FetchConfig(subServerName string) (interface{}, bool)
}

SubServerConfigDispatcher is an interface that all sub-servers will use to dynamically locate their configuration files. This abstraction will allow the primary RPC sever to initialize all sub-servers in a generic manner without knowing of each individual sub server.

type SubServerDriver

type SubServerDriver struct {
	// SubServerName is the full name of a sub-sever.
	//
	// NOTE: This MUST be unique.
	SubServerName string

	// New creates, and fully initializes a new sub-server instance with
	// the aide of the SubServerConfigDispatcher. This closure should
	// return the SubServer, ready for action, along with the set of
	// macaroon permissions that the sub-server wishes to pass on to the
	// root server for all methods routed towards it.
	New func(subCfgs SubServerConfigDispatcher) (SubServer, MacaroonPerms, error)
}

SubServerDriver is a template struct that allows the root server to create a sub-server with minimal knowledge. The root server only need a fully populated SubServerConfigDispatcher and with the aide of the RegisterSubServers method, it's able to create and initialize all sub-servers.

func RegisteredSubServers

func RegisteredSubServers() []*SubServerDriver

RegisteredSubServers returns all registered sub-servers.

NOTE: This function is safe for concurrent access.