lnd.xprv/lnrpc
Oliver Gugger 993167f14e
docs+lnrpc: enable bi-directional WebSockets
The grpc-gateway library that is used to transform REST calls into gRPC
uses a different method for reading a request body stream depending on
whether the RPC is a request-streaming one or not. We can't really find
out what kind of RPC the user is calling at runtime, so we add a new
parameter to the proxy that lists all request-streaming RPC calls.
In any case the client _has_ to send one request message initially to
kick off the request processing. Normally this can just be an empty
message. This can lead to problems if that empty message is not
expected by the gRPC server. But for the currently existing two
client-streaming RPCs this will only trigger a warning
(HTLC interceptor) or be ignored (channel acceptor).
2021-04-29 10:39:12 +02:00
..
autopilotrpc lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
chainrpc lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
invoicesrpc rpcserver+lnrpc: make Subscribe RPCs context aware 2021-04-22 07:49:29 +02:00
lnclipb lnrpc: extract or add REST annotations to yaml 2020-06-04 08:50:00 +02:00
routerrpc routerrpc+routing: set AMP options for payments specified as AMP in SendPayment 2021-04-27 09:47:23 +02:00
signrpc lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
verrpc lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
walletrpc walletrpc: minConfs and spendUnconfirmed for FundPtsb 2021-04-22 20:35:00 +02:00
watchtowerrpc lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
wtclientrpc wtclient: decrement pending tasks stats upon accepted task 2021-04-14 17:18:25 -07:00
.clang-format make+travis: verify compiled protos on travis 2020-03-10 13:03:01 +01:00
Dockerfile Merge pull request #5034 from Roasbeef/m1-go1.16 2021-04-21 08:59:46 -07:00
file_utils.go invoicesrpc: add SubscribeSingleInvoice rpc 2019-02-01 09:43:17 +01:00
gen_protos_docker.sh make: pass mobile subserver prefix to docker when generating mobile RPC 2021-04-06 12:52:27 +02:00
gen_protos.sh lnrpc: add StateService 2021-03-17 12:09:38 +01:00
marshall_utils.go rpc: refactor request validation and response marshal into functions 2020-06-03 18:50:11 -07:00
metadata.go docs+lnrpc: enable bi-directional WebSockets 2021-04-29 10:39:12 +02:00
README.md multi: remove proto install script 2021-01-28 10:29:01 +01:00
rest-annotations.yaml docs+lnrpc: enable bi-directional WebSockets 2021-04-29 10:39:12 +02:00
rpc_utils.go multi: move GetChanPointFundingTxid from lnd to lnrpc 2021-02-24 07:13:28 -08:00
rpc.pb.go lnrpc: add AMP feature bits 2021-04-27 09:47:23 +02:00
rpc.pb.gw.go docs+lnrpc: enable bi-directional WebSockets 2021-04-29 10:39:12 +02:00
rpc.proto lnrpc: add AMP feature bits 2021-04-27 09:47:23 +02:00
rpc.swagger.json docs+lnrpc: enable bi-directional WebSockets 2021-04-29 10:39:12 +02:00
stateservice.pb.go lnrpc: Change State -> state in SubscribeStateResponse 2021-04-05 15:26:37 +02:00
stateservice.pb.gw.go lnrpc: add StateService 2021-03-17 12:09:38 +01:00
stateservice.proto lnrpc: Change State -> state in SubscribeStateResponse 2021-04-05 15:26:37 +02:00
stateservice.swagger.json lnrpc: Change State -> state in SubscribeStateResponse 2021-04-05 15:26:37 +02:00
sub_server.go lnrpc: wrap subservers in GrpcHandler 2021-03-11 13:05:23 +01:00
walletunlocker.pb.go lnrpc: add arguments for stateless wallet initialization to wallet unlocker 2020-11-07 11:18:52 +01:00
walletunlocker.pb.gw.go lnrpc: extract or add REST annotations to yaml 2020-06-04 08:50:00 +02:00
walletunlocker.proto lnrpc: add arguments for stateless wallet initialization to wallet unlocker 2020-11-07 11:18:52 +01:00
walletunlocker.swagger.json lnrpc: add arguments for stateless wallet initialization to wallet unlocker 2020-11-07 11:18:52 +01:00
websocket_proxy.go docs+lnrpc: enable bi-directional WebSockets 2021-04-29 10:39:12 +02:00

lnrpc

Build Status MIT licensed GoDoc

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.
  • GetRecoveryInfo
    • Returns information about recovery process.
  • 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
  • ListMacaroonIDs
    • List all the macaroon root key IDs that are in use.
  • DeleteMacaroonID
    • Remove a specific macaroon root key ID from the database and invalidates all macaroons derived from the key with that ID.

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

To compile the lnrpc/**/*.proto files and generate the protobuf definitions, you need to have Docker and make installed.

Simply run make rpc to start the compilation process.

Format .proto files

We use clang-format to make sure the .proto files are formatted correctly.

When running the make rpc command, the .proto files are also formatted. To format the files without also compiling them, you can install the clang-format formatter on Ubuntu by running apt install clang-format or on Mac by running brew install clang-format. The make format command should then produce the correct result.

Consult this page to find binaries for other operating systems or distributions.

Makefile commands

The following commands are available with make:

  • rpc: Compile and format all .proto files using Docker (calls lnrpc/gen_protos_docker.sh).
  • rpc-format: Formats all .proto files according to our formatting rules. Requires clang-format, see previous chapter.
  • rpc-check: Runs both previous commands and makes sure the git work tree is not dirty. This can be used to check that the .proto files are formatted and compiled properly.