github.com/decred/dcrlnd@v0.7.6/lnrpc/README.md (about)

     1  lnrpc
     2  =====
     3  
     4  [![Build Status](http://img.shields.io/travis/decred/dcrlnd.svg)](https://travis-ci.org/decred/dcrlnd) 
     5  [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/decred/dcrlnd/blob/master/LICENSE)
     6  [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/decred/dcrlnd/lnrpc)
     7  
     8  This lnrpc package implements both a client and server for `dcrlnd`s RPC system
     9  which is based off of the high-performance cross-platform
    10  [gRPC](http://www.grpc.io/) RPC framework. By default, only the Go
    11  client+server libraries are compiled within the package. In order to compile
    12  the client side libraries for other supported languages, the `protoc` tool will
    13  need to be used to generate the compiled protos for a specific language.
    14  
    15  The following languages are supported as clients to `lnrpc`: C++, Go, Node.js,
    16  Java, Ruby, Android Java, PHP, Python, C#, Objective-C.
    17  
    18  ## Service: Lightning
    19  
    20  The list of defined RPCs on the service `Lightning` are the following (with a brief
    21  description):
    22  
    23    * WalletBalance
    24       * Returns the wallet's current confirmed balance in DCR.
    25    * ChannelBalance
    26       * Returns the daemons' available aggregate channel balance in DCR.
    27    * GetTransactions
    28       * Returns a list of on-chain transactions that pay to or are spends from
    29         `lnd`.
    30    * SendCoins
    31       * Sends an amount of satoshis to a specific address.
    32    * ListUnspent
    33       * Lists available utxos within a range of confirmations.
    34    * SubscribeTransactions
    35       * Returns a stream which sends async notifications each time a transaction
    36         is created or one is received that pays to us.
    37    * SendMany
    38       * Allows the caller to create a transaction with an arbitrary fan-out
    39         (many outputs).
    40    * NewAddress
    41       * Returns a new address, the following address types are supported:
    42         pay-to-witness-key-hash (p2wkh) and nested-pay-to-witness-key-hash
    43         (np2wkh).
    44    * SignMessage
    45       * Signs a message with the node's identity key and returns a
    46         zbase32 encoded signature.
    47    * VerifyMessage
    48       * Verifies a signature signed by another node on a message. The other node
    49         must be an active node in the channel database.
    50    * ConnectPeer
    51       * Connects to a peer identified by a public key and host.
    52    * DisconnectPeer
    53       * Disconnects a peer identified by a public key.
    54    * ListPeers
    55       * Lists all available connected peers.
    56    * GetInfo
    57       * Returns basic data concerning the daemon.
    58    * GetRecoveryInfo
    59       * Returns information about recovery process.
    60    * PendingChannels
    61       * List the number of pending (not fully confirmed) channels.
    62    * ListChannels
    63       * List all active channels the daemon manages.
    64    * OpenChannelSync
    65       * OpenChannelSync is a synchronous version of the OpenChannel RPC call.
    66    * OpenChannel
    67       * Attempts to open a channel to a target peer with a specific amount and
    68         push amount.
    69    * CloseChannel
    70       * Attempts to close a target channel. A channel can either be closed
    71         cooperatively if the channel peer is online, or using a "force" close to
    72         broadcast the latest channel state.
    73    * SendPayment
    74       * Send a payment over Lightning to a target peer.
    75    * SendPaymentSync
    76       * SendPaymentSync is the synchronous non-streaming version of SendPayment.
    77    * SendToRoute
    78      * Send a payment over Lightning to a target peer through a route explicitly
    79        defined by the user.
    80    * SendToRouteSync
    81      * SendToRouteSync is the synchronous non-streaming version of SendToRoute.
    82    * AddInvoice
    83       * Adds an invoice to the daemon. Invoices are automatically settled once
    84         seen as an incoming HTLC.
    85    * ListInvoices
    86       * Lists all stored invoices.
    87    * LookupInvoice
    88       * Attempts to look up an invoice by payment hash (r-hash).
    89    * SubscribeInvoices
    90       * Creates a uni-directional stream which receives async notifications as
    91         the daemon settles invoices
    92    * DecodePayReq
    93       * Decode a payment request, returning a full description of the conditions
    94         encoded within the payment request.
    95    * ListPayments
    96       * List all outgoing Lightning payments the daemon has made.
    97    * DeleteAllPayments
    98       * Deletes all outgoing payments from DB.
    99    * DescribeGraph
   100       * Returns a description of the known channel graph from the PoV of the
   101         node.
   102    * GetChanInfo
   103       * Returns information for a specific channel identified by channel ID.
   104    * GetNodeInfo
   105       * Returns information for a particular node identified by its identity
   106         public key.
   107    * QueryRoutes
   108       * Queries for a possible route to a target peer which can carry a certain
   109         amount of payment.
   110    * GetNetworkInfo
   111       * Returns some network level statistics.
   112    * StopDaemon
   113       * Sends a shutdown request to the interrupt handler, triggering a graceful
   114         shutdown of the daemon.
   115    * SubscribeChannelGraph
   116       * Creates a stream which receives async notifications upon any changes to the
   117         channel graph topology from the point of view of the responding node.
   118    * DebugLevel
   119       * Set logging verbosity of lnd programmatically
   120    * FeeReport
   121       * Allows the caller to obtain a report detailing the current fee schedule
   122         enforced by the node globally for each channel.
   123    * UpdateChannelPolicy
   124       * Allows the caller to update the fee schedule and channel policies for all channels
   125         globally, or a particular channel.
   126    * ForwardingHistory
   127       * ForwardingHistory allows the caller to query the htlcswitch for a
   128         record of all HTLCs forwarded.
   129    * BakeMacaroon
   130       * Bakes a new macaroon with the provided list of permissions and
   131         restrictions
   132    * ListMacaroonIDs
   133       * List all the macaroon root key IDs that are in use.
   134    * DeleteMacaroonID
   135       * Remove a specific macaroon root key ID from the database and invalidates
   136         all macaroons derived from the key with that ID. 
   137  
   138  ## Service: WalletUnlocker
   139  
   140  The list of defined RPCs on the service `WalletUnlocker` are the following (with a brief
   141  description):
   142  
   143    * CreateWallet
   144       * Set encryption password for the wallet database.
   145    * UnlockWallet
   146       * Provide a password to unlock the wallet database.
   147  
   148  ## Installation and Updating
   149  
   150  ```bash
   151  $ go get -u github.com/decred/dcrlnd/lnrpc
   152  ```
   153  
   154  ## Generate protobuf definitions
   155  
   156  ### MacOS / Unix like systems
   157  
   158  1. Download [v.3.4.0](https://github.com/google/protobuf/releases/tag/v3.4.0) of
   159  `protoc` for your operating system and add it to your `PATH`.
   160  For example, if using macOS:
   161  ```bash
   162  $ curl -LO https://github.com/google/protobuf/releases/download/v3.4.0/protoc-3.4.0-osx-x86_64.zip
   163  $ unzip protoc-3.4.0-osx-x86_64.zip -d protoc
   164  $ export PATH=$PWD/protoc/bin:$PATH
   165  ```
   166  
   167  2. Install `golang/protobuf` at commit `b5d812f8a3706043e23a9cd5babf2e5423744d30` (v1.3.1).
   168  ```bash
   169  $ git clone https://github.com/golang/protobuf $GOPATH/src/github.com/golang/protobuf
   170  $ cd $GOPATH/src/github.com/golang/protobuf
   171  $ git reset --hard v1.3.1
   172  $ make
   173  ```
   174  
   175  3. Install 'genproto' at commit `a8101f21cf983e773d0c1133ebc5424792003214`.
   176  ```bash
   177  $ go get google.golang.org/genproto
   178  $ cd $GOPATH/src/google.golang.org/genproto
   179  $ git reset --hard a8101f21cf983e773d0c1133ebc5424792003214
   180  ```
   181  
   182  4. Install `grpc-ecosystem/grpc-gateway` at version `v1.8.6`.
   183  ```bash
   184  $ git clone https://github.com/grpc-ecosystem/grpc-gateway $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway
   185  $ cd $GOPATH/src/github.com/grpc-ecosystem/grpc-gateway
   186  $ git reset --hard v1.8.6
   187  $ go install ./protoc-gen-grpc-gateway ./protoc-gen-swagger
   188  ```
   189  
   190  5. Run [`gen_protos.sh`](https://github.com/decred/dcrlnd/blob/master/lnrpc/gen_protos.sh)
   191  or `make rpc` to generate new protobuf definitions.
   192  
   193  ## Format .proto files
   194  
   195  We use `clang-format` to make sure the `.proto` files are formatted correctly.
   196  You can install the formatter on Ubuntu by running `apt install clang-format` or on Mac by running `brew install clang-format`.
   197  
   198  Consult [this page](http://releases.llvm.org/download.html) to find binaries
   199  for other operating systems or distributions.
   200  
   201  ## Makefile commands
   202  
   203  The following commands are available with `make`:
   204  
   205  * `rpc`: Compile `.proto` files (calls `lnrpc/gen_protos.sh`).
   206  * `rpc-format`: Formats all `.proto` files according to our formatting rules.
   207    Requires `clang-format`, see previous chapter.
   208  * `rpc-check`: Runs both previous commands and makes sure the git work tree is
   209    not dirty. This can be used to check that the `.proto` files are formatted
   210    and compiled properly.