lnrpc 0.8.0.beta.rc1 → 0.11.1

data/lib/{lnrpc → grpc_services}/rpc_services_pb.rb

@@ -5,75 +5,25 @@ require 'grpc'
 require 'rpc_pb'
 
 module Lnrpc
-  module WalletUnlocker
-    # *
+  module Lightning
+    #
     # Comments in this file will be directly parsed into the API
     # Documentation as descriptions of the associated method, message, or field.
     # These descriptions should go right above the definition of the object, and
-    # can be in either block or /// comment format. 
-    # 
-    # One edge case exists where a // comment followed by a /// comment in the
-    # next line will cause the description not to show up in the documentation. In
-    # that instance, simply separate the two comments with a blank line.
-    # 
+    # can be in either block or // comment format.
+    #
     # An RPC method can be matched to an lncli command by placing a line in the
     # beginning of the description in exactly the following format:
     # lncli: `methodname`
-    # 
+    #
     # Failure to specify the exact name of the command will cause documentation
     # generation to fail.
-    # 
+    #
     # More information on how exactly the gRPC documentation is generated from
     # this proto file can be found here:
     # https://github.com/lightninglabs/lightning-api
     #
-    # The WalletUnlocker service is used to set up a wallet password for
-    # lnd at first startup, and unlock a previously set up wallet.
-    class Service
-
-      include GRPC::GenericService
-
-      self.marshal_class_method = :encode
-      self.unmarshal_class_method = :decode
-      self.service_name = 'lnrpc.WalletUnlocker'
-
-      # *
-      # GenSeed is the first method that should be used to instantiate a new lnd
-      # instance. This method allows a caller to generate a new aezeed cipher seed
-      # given an optional passphrase. If provided, the passphrase will be necessary
-      # to decrypt the cipherseed to expose the internal wallet seed.
-      #
-      # Once the cipherseed is obtained and verified by the user, the InitWallet
-      # method should be used to commit the newly generated seed, and create the
-      # wallet.
-      rpc :GenSeed, GenSeedRequest, GenSeedResponse
-      # * 
-      # InitWallet is used when lnd is starting up for the first time to fully
-      # initialize the daemon and its internal wallet. At the very least a wallet
-      # password must be provided. This will be used to encrypt sensitive material
-      # on disk.
-      #
-      # In the case of a recovery scenario, the user can also specify their aezeed
-      # mnemonic and passphrase. If set, then the daemon will use this prior state
-      # to initialize its internal wallet.
-      #
-      # Alternatively, this can be used along with the GenSeed RPC to obtain a
-      # seed, then present it to the user. Once it has been verified by the user,
-      # the seed can be fed into this RPC in order to commit the new wallet.
-      rpc :InitWallet, InitWalletRequest, InitWalletResponse
-      # * lncli: `unlock`
-      # UnlockWallet is used at startup of lnd to provide a password to unlock
-      # the wallet database.
-      rpc :UnlockWallet, UnlockWalletRequest, UnlockWalletResponse
-      # * lncli: `changepassword`
-      # ChangePassword changes the password of the encrypted wallet. This will
-      # automatically unlock the wallet database if successful.
-      rpc :ChangePassword, ChangePasswordRequest, ChangePasswordResponse
-    end
-
-    Stub = Service.rpc_stub_class
-  end
-  module Lightning
+    # Lightning is the main RPC server of the daemon.
     class Service
 
       include GRPC::GenericService
@@ -82,120 +32,150 @@ module Lnrpc
       self.unmarshal_class_method = :decode
       self.service_name = 'lnrpc.Lightning'
 
-      # * lncli: `walletbalance`
+      # lncli: `walletbalance`
       # WalletBalance returns total unspent outputs(confirmed and unconfirmed), all
       # confirmed unspent outputs and all unconfirmed unspent outputs under control
       # of the wallet.
       rpc :WalletBalance, WalletBalanceRequest, WalletBalanceResponse
-      # * lncli: `channelbalance`
+      # lncli: `channelbalance`
       # ChannelBalance returns the total funds available across all open channels
       # in satoshis.
       rpc :ChannelBalance, ChannelBalanceRequest, ChannelBalanceResponse
-      # * lncli: `listchaintxns`
+      # lncli: `listchaintxns`
       # GetTransactions returns a list describing all the known transactions
       # relevant to the wallet.
       rpc :GetTransactions, GetTransactionsRequest, TransactionDetails
-      # * lncli: `estimatefee`
+      # lncli: `estimatefee`
       # EstimateFee asks the chain backend to estimate the fee rate and total fees
       # for a transaction that pays to multiple specified outputs.
+      #
+      # When using REST, the `AddrToAmount` map type can be set by appending
+      # `&AddrToAmount[<address>]=<amount_to_send>` to the URL. Unfortunately this
+      # map type doesn't appear in the REST API documentation because of a bug in
+      # the grpc-gateway library.
       rpc :EstimateFee, EstimateFeeRequest, EstimateFeeResponse
-      # * lncli: `sendcoins`
+      # lncli: `sendcoins`
       # SendCoins executes a request to send coins to a particular address. Unlike
       # SendMany, this RPC call only allows creating a single output at a time. If
       # neither target_conf, or sat_per_byte are set, then the internal wallet will
       # consult its fee model to determine a fee for the default confirmation
       # target.
       rpc :SendCoins, SendCoinsRequest, SendCoinsResponse
-      # * lncli: `listunspent`
+      # lncli: `listunspent`
+      # Deprecated, use walletrpc.ListUnspent instead.
+      #
       # ListUnspent returns a list of all utxos spendable by the wallet with a
       # number of confirmations between the specified minimum and maximum.
       rpc :ListUnspent, ListUnspentRequest, ListUnspentResponse
-      # *
+      #
       # SubscribeTransactions creates a uni-directional stream from the server to
       # the client in which any newly discovered transactions relevant to the
       # wallet are sent over.
       rpc :SubscribeTransactions, GetTransactionsRequest, stream(Transaction)
-      # * lncli: `sendmany`
+      # lncli: `sendmany`
       # SendMany handles a request for a transaction that creates multiple specified
       # outputs in parallel. If neither target_conf, or sat_per_byte are set, then
       # the internal wallet will consult its fee model to determine a fee for the
       # default confirmation target.
       rpc :SendMany, SendManyRequest, SendManyResponse
-      # * lncli: `newaddress`
+      # lncli: `newaddress`
       # NewAddress creates a new address under control of the local wallet.
       rpc :NewAddress, NewAddressRequest, NewAddressResponse
-      # * lncli: `signmessage`
+      # lncli: `signmessage`
       # SignMessage signs a message with this node's private key. The returned
       # signature string is `zbase32` encoded and pubkey recoverable, meaning that
       # only the message digest and signature are needed for verification.
       rpc :SignMessage, SignMessageRequest, SignMessageResponse
-      # * lncli: `verifymessage`
+      # lncli: `verifymessage`
       # VerifyMessage verifies a signature over a msg. The signature must be
       # zbase32 encoded and signed by an active node in the resident node's
       # channel database. In addition to returning the validity of the signature,
       # VerifyMessage also returns the recovered pubkey from the signature.
       rpc :VerifyMessage, VerifyMessageRequest, VerifyMessageResponse
-      # * lncli: `connect`
+      # lncli: `connect`
       # ConnectPeer attempts to establish a connection to a remote peer. This is at
       # the networking level, and is used for communication between nodes. This is
       # distinct from establishing a channel with a peer.
       rpc :ConnectPeer, ConnectPeerRequest, ConnectPeerResponse
-      # * lncli: `disconnect`
+      # lncli: `disconnect`
       # DisconnectPeer attempts to disconnect one peer from another identified by a
       # given pubKey. In the case that we currently have a pending or active channel
       # with the target peer, then this action will be not be allowed.
       rpc :DisconnectPeer, DisconnectPeerRequest, DisconnectPeerResponse
-      # * lncli: `listpeers`
+      # lncli: `listpeers`
       # ListPeers returns a verbose listing of all currently active peers.
       rpc :ListPeers, ListPeersRequest, ListPeersResponse
-      # * lncli: `getinfo`
+      #
+      # SubscribePeerEvents creates a uni-directional stream from the server to
+      # the client in which any events relevant to the state of peers are sent
+      # over. Events include peers going online and offline.
+      rpc :SubscribePeerEvents, PeerEventSubscription, stream(PeerEvent)
+      # lncli: `getinfo`
       # GetInfo returns general information concerning the lightning node including
       # it's identity pubkey, alias, the chains it is connected to, and information
       # concerning the number of open+pending channels.
       rpc :GetInfo, GetInfoRequest, GetInfoResponse
+      # * lncli: `getrecoveryinfo`
+      # GetRecoveryInfo returns information concerning the recovery mode including
+      # whether it's in a recovery mode, whether the recovery is finished, and the
+      # progress made so far.
+      rpc :GetRecoveryInfo, GetRecoveryInfoRequest, GetRecoveryInfoResponse
       # TODO(roasbeef): merge with below with bool?
       #
-      # * lncli: `pendingchannels`
+      # lncli: `pendingchannels`
       # PendingChannels returns a list of all the channels that are currently
       # considered "pending". A channel is pending if it has finished the funding
       # workflow and is waiting for confirmations for the funding txn, or is in the
       # process of closure, either initiated cooperatively or non-cooperatively.
       rpc :PendingChannels, PendingChannelsRequest, PendingChannelsResponse
-      # * lncli: `listchannels`
+      # lncli: `listchannels`
       # ListChannels returns a description of all the open channels that this node
       # is a participant in.
       rpc :ListChannels, ListChannelsRequest, ListChannelsResponse
-      # *
+      #
       # SubscribeChannelEvents creates a uni-directional stream from the server to
       # the client in which any updates relevant to the state of the channels are
       # sent over. Events include new active channels, inactive channels, and closed
       # channels.
       rpc :SubscribeChannelEvents, ChannelEventSubscription, stream(ChannelEventUpdate)
-      # * lncli: `closedchannels`
+      # lncli: `closedchannels`
       # ClosedChannels returns a description of all the closed channels that
       # this node was a participant in.
       rpc :ClosedChannels, ClosedChannelsRequest, ClosedChannelsResponse
-      # *
+      #
       # OpenChannelSync is a synchronous version of the OpenChannel RPC call. This
       # call is meant to be consumed by clients to the REST proxy. As with all
       # other sync calls, all byte slices are intended to be populated as hex
       # encoded strings.
       rpc :OpenChannelSync, OpenChannelRequest, ChannelPoint
-      # * lncli: `openchannel`
+      # lncli: `openchannel`
       # OpenChannel attempts to open a singly funded channel specified in the
       # request to a remote peer. Users are able to specify a target number of
       # blocks that the funding transaction should be confirmed in, or a manual fee
       # rate to us for the funding transaction. If neither are specified, then a
-      # lax block confirmation target is used.
+      # lax block confirmation target is used. Each OpenStatusUpdate will return
+      # the pending channel ID of the in-progress channel. Depending on the
+      # arguments specified in the OpenChannelRequest, this pending channel ID can
+      # then be used to manually progress the channel funding flow.
       rpc :OpenChannel, OpenChannelRequest, stream(OpenStatusUpdate)
-      # *
+      #
+      # FundingStateStep is an advanced funding related call that allows the caller
+      # to either execute some preparatory steps for a funding workflow, or
+      # manually progress a funding workflow. The primary way a funding flow is
+      # identified is via its pending channel ID. As an example, this method can be
+      # used to specify that we're expecting a funding flow for a particular
+      # pending channel ID, for which we need to use specific parameters.
+      # Alternatively, this can be used to interactively drive PSBT signing for
+      # funding for partially complete funding transactions.
+      rpc :FundingStateStep, FundingTransitionMsg, FundingStateStepResp
+      #
       # ChannelAcceptor dispatches a bi-directional streaming RPC in which
       # OpenChannel requests are sent to the client and the client responds with
       # a boolean that tells LND whether or not to accept the channel. This allows
       # node operators to specify their own criteria for accepting inbound channels
       # through a single persistent connection.
       rpc :ChannelAcceptor, stream(ChannelAcceptResponse), stream(ChannelAcceptRequest)
-      # * lncli: `closechannel`
+      # lncli: `closechannel`
       # CloseChannel attempts to close an active channel identified by its channel
       # outpoint (ChannelPoint). The actions of this method can additionally be
       # augmented to attempt a force close after a timeout period in the case of an
@@ -204,40 +184,42 @@ module Lnrpc
       # closure transaction is confirmed, or a manual fee rate. If neither are
       # specified, then a default lax, block confirmation target is used.
       rpc :CloseChannel, CloseChannelRequest, stream(CloseStatusUpdate)
-      # * lncli: `abandonchannel`
+      # lncli: `abandonchannel`
       # AbandonChannel removes all channel state from the database except for a
       # close summary. This method can be used to get rid of permanently unusable
       # channels due to bugs fixed in newer versions of lnd. Only available
       # when in debug builds of lnd.
       rpc :AbandonChannel, AbandonChannelRequest, AbandonChannelResponse
-      # * lncli: `sendpayment`
-      # SendPayment dispatches a bi-directional streaming RPC for sending payments
-      # through the Lightning Network. A single RPC invocation creates a persistent
-      # bi-directional stream allowing clients to rapidly send payments through the
-      # Lightning Network with a single persistent connection.
+      # lncli: `sendpayment`
+      # Deprecated, use routerrpc.SendPaymentV2. SendPayment dispatches a
+      # bi-directional streaming RPC for sending payments through the Lightning
+      # Network. A single RPC invocation creates a persistent bi-directional
+      # stream allowing clients to rapidly send payments through the Lightning
+      # Network with a single persistent connection.
       rpc :SendPayment, stream(SendRequest), stream(SendResponse)
-      # *
+      #
       # SendPaymentSync is the synchronous non-streaming version of SendPayment.
       # This RPC is intended to be consumed by clients of the REST proxy.
       # Additionally, this RPC expects the destination's public key and the payment
       # hash (if any) to be encoded as hex strings.
       rpc :SendPaymentSync, SendRequest, SendResponse
-      # * lncli: `sendtoroute`
-      # SendToRoute is a bi-directional streaming RPC for sending payment through
-      # the Lightning Network. This method differs from SendPayment in that it
-      # allows users to specify a full route manually. This can be used for things
-      # like rebalancing, and atomic swaps.
+      # lncli: `sendtoroute`
+      # Deprecated, use routerrpc.SendToRouteV2. SendToRoute is a bi-directional
+      # streaming RPC for sending payment through the Lightning Network. This
+      # method differs from SendPayment in that it allows users to specify a full
+      # route manually. This can be used for things like rebalancing, and atomic
+      # swaps.
       rpc :SendToRoute, stream(SendToRouteRequest), stream(SendResponse)
-      # *
+      #
       # SendToRouteSync is a synchronous version of SendToRoute. It Will block
       # until the payment either fails or succeeds.
       rpc :SendToRouteSync, SendToRouteRequest, SendResponse
-      # * lncli: `addinvoice`
+      # lncli: `addinvoice`
       # AddInvoice attempts to add a new invoice to the invoice database. Any
       # duplicated invoices are rejected, therefore all invoices *must* have a
       # unique payment preimage.
       rpc :AddInvoice, Invoice, AddInvoiceResponse
-      # * lncli: `listinvoices`
+      # lncli: `listinvoices`
       # ListInvoices returns a list of all the invoices currently stored within the
       # database. Any active debug invoices are ignored. It has full support for
       # paginated responses, allowing users to query for specific invoices through
@@ -246,67 +228,76 @@ module Lnrpc
       # next request. By default, the first 100 invoices created will be returned.
       # Backwards pagination is also supported through the Reversed flag.
       rpc :ListInvoices, ListInvoiceRequest, ListInvoiceResponse
-      # * lncli: `lookupinvoice`
+      # lncli: `lookupinvoice`
       # LookupInvoice attempts to look up an invoice according to its payment hash.
       # The passed payment hash *must* be exactly 32 bytes, if not, an error is
       # returned.
       rpc :LookupInvoice, PaymentHash, Invoice
-      # *
+      #
       # SubscribeInvoices returns a uni-directional stream (server -> client) for
       # notifying the client of newly added/settled invoices. The caller can
       # optionally specify the add_index and/or the settle_index. If the add_index
       # is specified, then we'll first start by sending add invoice events for all
-      # invoices with an add_index greater than the specified value.  If the
+      # invoices with an add_index greater than the specified value. If the
       # settle_index is specified, the next, we'll send out all settle events for
-      # invoices with a settle_index greater than the specified value.  One or both
+      # invoices with a settle_index greater than the specified value. One or both
       # of these fields can be set. If no fields are set, then we'll only send out
       # the latest add/settle events.
       rpc :SubscribeInvoices, InvoiceSubscription, stream(Invoice)
-      # * lncli: `decodepayreq`
+      # lncli: `decodepayreq`
       # DecodePayReq takes an encoded payment request string and attempts to decode
       # it, returning a full description of the conditions encoded within the
       # payment request.
       rpc :DecodePayReq, PayReqString, PayReq
-      # * lncli: `listpayments`
+      # lncli: `listpayments`
       # ListPayments returns a list of all outgoing payments.
       rpc :ListPayments, ListPaymentsRequest, ListPaymentsResponse
-      # *
+      #
       # DeleteAllPayments deletes all outgoing payments from DB.
       rpc :DeleteAllPayments, DeleteAllPaymentsRequest, DeleteAllPaymentsResponse
-      # * lncli: `describegraph`
+      # lncli: `describegraph`
       # DescribeGraph returns a description of the latest graph state from the
       # point of view of the node. The graph information is partitioned into two
       # components: all the nodes/vertexes, and all the edges that connect the
-      # vertexes themselves.  As this is a directed graph, the edges also contain
+      # vertexes themselves. As this is a directed graph, the edges also contain
       # the node directional specific routing policy which includes: the time lock
       # delta, fee information, etc.
       rpc :DescribeGraph, ChannelGraphRequest, ChannelGraph
-      # * lncli: `getchaninfo`
+      # lncli: `getnodemetrics`
+      # GetNodeMetrics returns node metrics calculated from the graph. Currently
+      # the only supported metric is betweenness centrality of individual nodes.
+      rpc :GetNodeMetrics, NodeMetricsRequest, NodeMetricsResponse
+      # lncli: `getchaninfo`
       # GetChanInfo returns the latest authenticated network announcement for the
       # given channel identified by its channel ID: an 8-byte integer which
       # uniquely identifies the location of transaction's funding output within the
       # blockchain.
       rpc :GetChanInfo, ChanInfoRequest, ChannelEdge
-      # * lncli: `getnodeinfo`
+      # lncli: `getnodeinfo`
       # GetNodeInfo returns the latest advertised, aggregated, and authenticated
       # channel information for the specified node identified by its public key.
       rpc :GetNodeInfo, NodeInfoRequest, NodeInfo
-      # * lncli: `queryroutes`
+      # lncli: `queryroutes`
       # QueryRoutes attempts to query the daemon's Channel Router for a possible
       # route to a target destination capable of carrying a specific amount of
       # satoshis. The returned route contains the full details required to craft and
       # send an HTLC, also including the necessary information that should be
       # present within the Sphinx packet encapsulated within the HTLC.
+      #
+      # When using REST, the `dest_custom_records` map type can be set by appending
+      # `&dest_custom_records[<record_number>]=<record_data_base64_url_encoded>`
+      # to the URL. Unfortunately this map type doesn't appear in the REST API
+      # documentation because of a bug in the grpc-gateway library.
       rpc :QueryRoutes, QueryRoutesRequest, QueryRoutesResponse
-      # * lncli: `getnetworkinfo`
+      # lncli: `getnetworkinfo`
       # GetNetworkInfo returns some basic stats about the known channel graph from
       # the point of view of the node.
       rpc :GetNetworkInfo, NetworkInfoRequest, NetworkInfo
-      # * lncli: `stop`
+      # lncli: `stop`
       # StopDaemon will send a shutdown request to the interrupt handler, triggering
       # a graceful shutdown of the daemon.
       rpc :StopDaemon, StopRequest, StopResponse
-      # *
+      #
       # SubscribeChannelGraph launches a streaming RPC that allows the caller to
       # receive notifications upon any changes to the channel graph topology from
       # the point of view of the responding node. Events notified include: new
@@ -314,21 +305,21 @@ module Lnrpc
       # channels being advertised, updates in the routing policy for a directional
       # channel edge, and when channels are closed on-chain.
       rpc :SubscribeChannelGraph, GraphTopologySubscription, stream(GraphTopologyUpdate)
-      # * lncli: `debuglevel`
+      # lncli: `debuglevel`
       # DebugLevel allows a caller to programmatically set the logging verbosity of
       # lnd. The logging can be targeted according to a coarse daemon-wide logging
       # level, or in a granular fashion to specify the logging for a target
       # sub-system.
       rpc :DebugLevel, DebugLevelRequest, DebugLevelResponse
-      # * lncli: `feereport`
+      # lncli: `feereport`
       # FeeReport allows the caller to obtain a report detailing the current fee
       # schedule enforced by the node globally for each channel.
       rpc :FeeReport, FeeReportRequest, FeeReportResponse
-      # * lncli: `updatechanpolicy`
+      # lncli: `updatechanpolicy`
       # UpdateChannelPolicy allows the caller to update the fee schedule and
       # channel policies for all channels globally, or a particular channel.
       rpc :UpdateChannelPolicy, PolicyUpdateRequest, PolicyUpdateResponse
-      # * lncli: `fwdinghistory`
+      # lncli: `fwdinghistory`
       # ForwardingHistory allows the caller to query the htlcswitch for a record of
       # all HTLCs forwarded within the target time range, and integer offset
       # within that time range. If no time-range is specified, then the first chunk
@@ -336,11 +327,11 @@ module Lnrpc
       #
       # A list of forwarding events are returned. The size of each forwarding event
       # is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB.
-      # As a result each message can only contain 50k entries.  Each response has
+      # As a result each message can only contain 50k entries. Each response has
       # the index offset of the last entry. The index offset can be provided to the
       # request to allow the caller to skip a series of records.
       rpc :ForwardingHistory, ForwardingHistoryRequest, ForwardingHistoryResponse
-      # * lncli: `exportchanbackup`
+      # lncli: `exportchanbackup`
       # ExportChannelBackup attempts to return an encrypted static channel backup
       # for the target channel identified by it channel point. The backup is
       # encrypted with a key generated from the aezeed seed of the user. The
@@ -348,25 +339,25 @@ module Lnrpc
       # method once lnd is running, or via the InitWallet and UnlockWallet methods
       # from the WalletUnlocker service.
       rpc :ExportChannelBackup, ExportChannelBackupRequest, ChannelBackup
-      # *
+      #
       # ExportAllChannelBackups returns static channel backups for all existing
       # channels known to lnd. A set of regular singular static channel backups for
       # each channel are returned. Additionally, a multi-channel backup is returned
       # as well, which contains a single encrypted blob containing the backups of
       # each channel.
       rpc :ExportAllChannelBackups, ChanBackupExportRequest, ChanBackupSnapshot
-      # *
+      #
       # VerifyChanBackup allows a caller to verify the integrity of a channel backup
       # snapshot. This method will accept either a packed Single or a packed Multi.
       # Specifying both will result in an error.
       rpc :VerifyChanBackup, ChanBackupSnapshot, VerifyChanBackupResponse
-      # * lncli: `restorechanbackup`
+      # lncli: `restorechanbackup`
       # RestoreChannelBackups accepts a set of singular channel backups, or a
       # single encrypted multi-chan backup and attempts to recover any funds
       # remaining within the channel. If we are able to unpack the backup, then the
       # new channel will be shown under listchannels, as well as pending channels.
       rpc :RestoreChannelBackups, RestoreChanBackupRequest, RestoreBackupResponse
-      # *
+      #
       # SubscribeChannelBackups allows a client to sub-subscribe to the most up to
       # date information concerning the state of all channel backups. Each time a
       # new channel is added, we return the new set of channels, along with a
@@ -375,6 +366,11 @@ module Lnrpc
       # ups, but the updated set of encrypted multi-chan backups with the closed
       # channel(s) removed.
       rpc :SubscribeChannelBackups, ChannelBackupSubscription, stream(ChanBackupSnapshot)
+      # lncli: `bakemacaroon`
+      # BakeMacaroon allows the creation of a new macaroon with custom read and
+      # write permissions. No first-party caveats are added since this can be done
+      # offline.
+      rpc :BakeMacaroon, BakeMacaroonRequest, BakeMacaroonResponse
     end
 
     Stub = Service.rpc_stub_class