lnrpc: unify proto style by moving services to top of file

This commit is contained in:
Oliver Gugger 2020-05-06 16:41:47 +02:00
parent acd105fccb
commit 0800386138
No known key found for this signature in database
GPG Key ID: 8E4256593F177720
7 changed files with 315 additions and 300 deletions

@ -2,6 +2,44 @@ syntax = "proto3";
package chainrpc;
// ChainNotifier is a service that can be used to get information about the
// chain backend by registering notifiers for chain events.
service ChainNotifier {
/*
RegisterConfirmationsNtfn is a synchronous response-streaming RPC that
registers an intent for a client to be notified once a confirmation request
has reached its required number of confirmations on-chain.
A client can specify whether the confirmation request should be for a
particular transaction by its hash or for an output script by specifying a
zero hash.
*/
rpc RegisterConfirmationsNtfn (ConfRequest) returns (stream ConfEvent);
/*
RegisterSpendNtfn is a synchronous response-streaming RPC that registers an
intent for a client to be notification once a spend request has been spent
by a transaction that has confirmed on-chain.
A client can specify whether the spend request should be for a particular
outpoint or for an output script by specifying a zero outpoint.
*/
rpc RegisterSpendNtfn (SpendRequest) returns (stream SpendEvent);
/*
RegisterBlockEpochNtfn is a synchronous response-streaming RPC that
registers an intent for a client to be notified of blocks in the chain. The
stream will return a hash and height tuple of a block for each new/stale
block in the chain. It is the client's responsibility to determine whether
the tuple returned is for a new or stale block in the chain.
A client can also request a historical backlog of blocks from a particular
point. This allows clients to be idempotent by ensuring that they do not
missing processing a single block within the chain.
*/
rpc RegisterBlockEpochNtfn (BlockEpoch) returns (stream BlockEpoch);
}
message ConfRequest {
/*
The transaction hash for which we should request a confirmation notification
@ -140,39 +178,3 @@ message BlockEpoch {
// The height of the block.
uint32 height = 2;
}
service ChainNotifier {
/*
RegisterConfirmationsNtfn is a synchronous response-streaming RPC that
registers an intent for a client to be notified once a confirmation request
has reached its required number of confirmations on-chain.
A client can specify whether the confirmation request should be for a
particular transaction by its hash or for an output script by specifying a
zero hash.
*/
rpc RegisterConfirmationsNtfn (ConfRequest) returns (stream ConfEvent);
/*
RegisterSpendNtfn is a synchronous response-streaming RPC that registers an
intent for a client to be notification once a spend request has been spent
by a transaction that has confirmed on-chain.
A client can specify whether the spend request should be for a particular
outpoint or for an output script by specifying a zero outpoint.
*/
rpc RegisterSpendNtfn (SpendRequest) returns (stream SpendEvent);
/*
RegisterBlockEpochNtfn is a synchronous response-streaming RPC that
registers an intent for a client to be notified of blocks in the chain. The
stream will return a hash and height tuple of a block for each new/stale
block in the chain. It is the client's responsibility to determine whether
the tuple returned is for a new or stale block in the chain.
A client can also request a historical backlog of blocks from a particular
point. This allows clients to be idempotent by ensuring that they do not
missing processing a single block within the chain.
*/
rpc RegisterBlockEpochNtfn (BlockEpoch) returns (stream BlockEpoch);
}

@ -6,6 +6,88 @@ package routerrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
// Router is a service that offers advanced interaction with the router
// subsystem of the daemon.
service Router {
/**
SendPaymentV2 attempts to route a payment described by the passed
PaymentRequest to the final destination. The call returns a stream of
payment updates.
*/
rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment);
/**
TrackPaymentV2 returns an update stream for the payment identified by the
payment hash.
*/
rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment);
/**
EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it
may cost to send an HTLC to the target end destination.
*/
rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse);
/**
SendToRoute attempts to make a payment via the specified route. 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 (SendToRouteRequest) returns (SendToRouteResponse);
/**
ResetMissionControl clears all mission control state and starts with a clean
slate.
*/
rpc ResetMissionControl (ResetMissionControlRequest)
returns (ResetMissionControlResponse);
/**
QueryMissionControl exposes the internal mission control state to callers.
It is a development feature.
*/
rpc QueryMissionControl (QueryMissionControlRequest)
returns (QueryMissionControlResponse);
/**
QueryProbability returns the current success probability estimate for a
given node pair and amount.
*/
rpc QueryProbability (QueryProbabilityRequest)
returns (QueryProbabilityResponse);
/**
BuildRoute builds a fully specified route based on a list of hop public
keys. It retrieves the relevant channel policies from the graph in order to
calculate the correct fees and time locks.
*/
rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);
/**
SubscribeHtlcEvents creates a uni-directional stream from the server to
the client which delivers a stream of htlc events.
*/
rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest)
returns (stream HtlcEvent);
/**
Deprecated, use SendPaymentV2. SendPayment attempts to route a payment
described by the passed PaymentRequest to the final destination. The call
returns a stream of payment status updates.
*/
rpc SendPayment (SendPaymentRequest) returns (stream PaymentStatus) {
option deprecated = true;
}
/**
Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for
the payment identified by the payment hash.
*/
rpc TrackPayment (TrackPaymentRequest) returns (stream PaymentStatus) {
option deprecated = true;
}
}
message SendPaymentRequest {
/// The identity pubkey of the payment recipient
bytes dest = 1;
@ -478,83 +560,3 @@ message PaymentStatus {
*/
repeated lnrpc.HTLCAttempt htlcs = 4;
}
service Router {
/**
SendPaymentV2 attempts to route a payment described by the passed
PaymentRequest to the final destination. The call returns a stream of
payment updates.
*/
rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment);
/**
TrackPaymentV2 returns an update stream for the payment identified by the
payment hash.
*/
rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment);
/**
EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it
may cost to send an HTLC to the target end destination.
*/
rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse);
/**
SendToRoute attempts to make a payment via the specified route. 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 (SendToRouteRequest) returns (SendToRouteResponse);
/**
ResetMissionControl clears all mission control state and starts with a clean
slate.
*/
rpc ResetMissionControl (ResetMissionControlRequest)
returns (ResetMissionControlResponse);
/**
QueryMissionControl exposes the internal mission control state to callers.
It is a development feature.
*/
rpc QueryMissionControl (QueryMissionControlRequest)
returns (QueryMissionControlResponse);
/**
QueryProbability returns the current success probability estimate for a
given node pair and amount.
*/
rpc QueryProbability (QueryProbabilityRequest)
returns (QueryProbabilityResponse);
/**
BuildRoute builds a fully specified route based on a list of hop public
keys. It retrieves the relevant channel policies from the graph in order to
calculate the correct fees and time locks.
*/
rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);
/**
SubscribeHtlcEvents creates a uni-directional stream from the server to
the client which delivers a stream of htlc events.
*/
rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest)
returns (stream HtlcEvent);
/**
Deprecated, use SendPaymentV2. SendPayment attempts to route a payment
described by the passed PaymentRequest to the final destination. The call
returns a stream of payment status updates.
*/
rpc SendPayment(SendPaymentRequest) returns (stream PaymentStatus) {
option deprecated = true;
}
/**
Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for
the payment identified by the payment hash.
*/
rpc TrackPayment(TrackPaymentRequest) returns (stream PaymentStatus) {
option deprecated = true;
}
}

@ -4,6 +4,65 @@ package signrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/signrpc";
// Signer is a service that gives access to the signing functionality of the
// daemon's wallet.
service Signer {
/**
SignOutputRaw is a method that can be used to generated a signature for a
set of inputs/outputs to a transaction. Each request specifies details
concerning how the outputs should be signed, which keys they should be
signed with, and also any optional tweaks. The return value is a fixed
64-byte signature (the same format as we use on the wire in Lightning).
If we are unable to sign using the specified keys, then an error will be
returned.
*/
rpc SignOutputRaw (SignReq) returns (SignResp);
/**
ComputeInputScript generates a complete InputIndex for the passed
transaction with the signature as defined within the passed SignDescriptor.
This method should be capable of generating the proper input script for
both regular p2wkh output and p2wkh outputs nested within a regular p2sh
output.
Note that when using this method to sign inputs belonging to the wallet,
the only items of the SignDescriptor that need to be populated are pkScript
in the TxOut field, the value in that same field, and finally the input
index.
*/
rpc ComputeInputScript (SignReq) returns (InputScriptResp);
/**
SignMessage signs a message with the key specified in the key locator. The
returned signature is fixed-size LN wire format encoded.
The main difference to SignMessage in the main RPC is that a specific key is
used to sign the message instead of the node identity private key.
*/
rpc SignMessage (SignMessageReq) returns (SignMessageResp);
/**
VerifyMessage verifies a signature over a message using the public key
provided. The signature must be fixed-size LN wire format encoded.
The main difference to VerifyMessage in the main RPC is that the public key
used to sign the message does not have to be a node known to the network.
*/
rpc VerifyMessage (VerifyMessageReq) returns (VerifyMessageResp);
/*
DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key
derivation between the ephemeral public key in the request and the node's
key specified in the key_loc parameter (or the node's identity private key
if no key locator is specified):
P_shared = privKeyNode * ephemeralPubkey
The resulting shared public key is serialized in the compressed format and
hashed with sha256, resulting in the final key length of 256bit.
*/
rpc DeriveSharedKey (SharedKeyRequest) returns (SharedKeyResponse);
}
message KeyLocator {
/// The family of key being identified.
int32 key_family = 1;
@ -167,60 +226,3 @@ message SharedKeyResponse {
// The shared public key, hashed with sha256.
bytes shared_key = 1;
}
service Signer {
/**
SignOutputRaw is a method that can be used to generated a signature for a
set of inputs/outputs to a transaction. Each request specifies details
concerning how the outputs should be signed, which keys they should be
signed with, and also any optional tweaks. The return value is a fixed
64-byte signature (the same format as we use on the wire in Lightning).
If we are unable to sign using the specified keys, then an error will be
returned.
*/
rpc SignOutputRaw (SignReq) returns (SignResp);
/**
ComputeInputScript generates a complete InputIndex for the passed
transaction with the signature as defined within the passed SignDescriptor.
This method should be capable of generating the proper input script for
both regular p2wkh output and p2wkh outputs nested within a regular p2sh
output.
Note that when using this method to sign inputs belonging to the wallet,
the only items of the SignDescriptor that need to be populated are pkScript
in the TxOut field, the value in that same field, and finally the input
index.
*/
rpc ComputeInputScript (SignReq) returns (InputScriptResp);
/**
SignMessage signs a message with the key specified in the key locator. The
returned signature is fixed-size LN wire format encoded.
The main difference to SignMessage in the main RPC is that a specific key is
used to sign the message instead of the node identity private key.
*/
rpc SignMessage (SignMessageReq) returns (SignMessageResp);
/**
VerifyMessage verifies a signature over a message using the public key
provided. The signature must be fixed-size LN wire format encoded.
The main difference to VerifyMessage in the main RPC is that the public key
used to sign the message does not have to be a node known to the network.
*/
rpc VerifyMessage (VerifyMessageReq) returns (VerifyMessageResp);
/*
DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key
derivation between the ephemeral public key in the request and the node's
key specified in the key_loc parameter (or the node's identity private key
if no key locator is specified):
P_shared = privKeyNode * ephemeralPubkey
The resulting shared public key is serialized in the compressed format and
hashed with sha256, resulting in the final key length of 256bit.
*/
rpc DeriveSharedKey (SharedKeyRequest) returns (SharedKeyResponse);
}

@ -4,12 +4,18 @@ package verrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/verrpc";
// Versioner is a service that can be used to get information about the version
// and build information of the running daemon.
service Versioner {
/* lncli: `version`
GetVersion returns the current version and build information of the running
daemon.
*/
rpc GetVersion (VersionRequest) returns (Version);
};
}
message VersionRequest {
};
}
message Version {
/// A verbose description of the daemon's commit.
@ -38,4 +44,4 @@ message Version {
/// The version of go that compiled the executable.
string go_version = 9;
};
}

@ -7,6 +7,98 @@ package walletrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/walletrpc";
// WalletKit is a service that gives access to the core functionalities of the
// daemon's wallet.
service WalletKit {
/**
DeriveNextKey attempts to derive the *next* key within the key family
(account in BIP43) specified. This method should return the next external
child within this branch.
*/
rpc DeriveNextKey (KeyReq) returns (signrpc.KeyDescriptor);
/**
DeriveKey attempts to derive an arbitrary key specified by the passed
KeyLocator.
*/
rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor);
/**
NextAddr returns the next unused address within the wallet.
*/
rpc NextAddr (AddrRequest) returns (AddrResponse);
/**
PublishTransaction attempts to publish the passed transaction to the
network. Once this returns without an error, the wallet will continually
attempt to re-broadcast the transaction on start up, until it enters the
chain.
*/
rpc PublishTransaction (Transaction) returns (PublishResponse);
/**
SendOutputs is similar to the existing sendmany call in Bitcoind, and
allows the caller to create a transaction that sends to several outputs at
once. This is ideal when wanting to batch create a set of transactions.
*/
rpc SendOutputs (SendOutputsRequest) returns (SendOutputsResponse);
/**
EstimateFee attempts to query the internal fee estimator of the wallet to
determine the fee (in sat/kw) to attach to a transaction in order to
achieve the confirmation target.
*/
rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse);
/*
PendingSweeps returns lists of on-chain outputs that lnd is currently
attempting to sweep within its central batching engine. Outputs with similar
fee rates are batched together in order to sweep them within a single
transaction.
NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to
remain supported. This is an advanced API that depends on the internals of
the UtxoSweeper, so things may change.
*/
rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);
/*
BumpFee bumps the fee of an arbitrary input within a transaction. This RPC
takes a different approach than bitcoind's bumpfee command. lnd has a
central batching engine in which inputs with similar fee rates are batched
together to save on transaction fees. Due to this, we cannot rely on
bumping the fee on a specific transaction, since transactions can change at
any point with the addition of new inputs. The list of inputs that
currently exist within lnd's central batching engine can be retrieved
through the PendingSweeps RPC.
When bumping the fee of an input that currently exists within lnd's central
batching engine, a higher fee transaction will be created that replaces the
lower fee transaction through the Replace-By-Fee (RBF) policy. If it
This RPC also serves useful when wanting to perform a Child-Pays-For-Parent
(CPFP), where the child transaction pays for its parent's fee. This can be
done by specifying an outpoint within the low fee transaction that is under
the control of the wallet.
The fee preference can be expressed either as a specific fee rate or a delta
of blocks in which the output should be swept on-chain within. If a fee
preference is not explicitly specified, then an error is returned.
Note that this RPC currently doesn't perform any validation checks on the
fee preference being provided. For now, the responsibility of ensuring that
the new fee preference is sufficient is delegated to the user.
*/
rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse);
/**
ListSweeps returns a list of the sweep transactions our node has produced.
Note that these sweeps may not be confirmed yet, as we record sweeps on
broadcast, not confirmation.
*/
rpc ListSweeps (ListSweepsRequest) returns (ListSweepsResponse);
}
message KeyReq {
/**
Is the key finger print of the root pubkey that this request is targeting.
@ -244,7 +336,6 @@ message BumpFeeRequest {
message BumpFeeResponse {
}
message ListSweepsRequest {
/*
Retrieve the full sweep transaction details. If false, only the sweep txids
@ -268,95 +359,3 @@ message ListSweepsResponse {
TransactionIDs transaction_ids = 2;
}
}
service WalletKit {
/**
DeriveNextKey attempts to derive the *next* key within the key family
(account in BIP43) specified. This method should return the next external
child within this branch.
*/
rpc DeriveNextKey (KeyReq) returns (signrpc.KeyDescriptor);
/**
DeriveKey attempts to derive an arbitrary key specified by the passed
KeyLocator.
*/
rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor);
/**
NextAddr returns the next unused address within the wallet.
*/
rpc NextAddr (AddrRequest) returns (AddrResponse);
/**
PublishTransaction attempts to publish the passed transaction to the
network. Once this returns without an error, the wallet will continually
attempt to re-broadcast the transaction on start up, until it enters the
chain.
*/
rpc PublishTransaction (Transaction) returns (PublishResponse);
/**
SendOutputs is similar to the existing sendmany call in Bitcoind, and
allows the caller to create a transaction that sends to several outputs at
once. This is ideal when wanting to batch create a set of transactions.
*/
rpc SendOutputs (SendOutputsRequest) returns (SendOutputsResponse);
/**
EstimateFee attempts to query the internal fee estimator of the wallet to
determine the fee (in sat/kw) to attach to a transaction in order to
achieve the confirmation target.
*/
rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse);
/*
PendingSweeps returns lists of on-chain outputs that lnd is currently
attempting to sweep within its central batching engine. Outputs with similar
fee rates are batched together in order to sweep them within a single
transaction.
NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to
remain supported. This is an advanced API that depends on the internals of
the UtxoSweeper, so things may change.
*/
rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);
/*
BumpFee bumps the fee of an arbitrary input within a transaction. This RPC
takes a different approach than bitcoind's bumpfee command. lnd has a
central batching engine in which inputs with similar fee rates are batched
together to save on transaction fees. Due to this, we cannot rely on
bumping the fee on a specific transaction, since transactions can change at
any point with the addition of new inputs. The list of inputs that
currently exist within lnd's central batching engine can be retrieved
through the PendingSweeps RPC.
When bumping the fee of an input that currently exists within lnd's central
batching engine, a higher fee transaction will be created that replaces the
lower fee transaction through the Replace-By-Fee (RBF) policy. If it
This RPC also serves useful when wanting to perform a Child-Pays-For-Parent
(CPFP), where the child transaction pays for its parent's fee. This can be
done by specifying an outpoint within the low fee transaction that is under
the control of the wallet.
The fee preference can be expressed either as a specific fee rate or a delta
of blocks in which the output should be swept on-chain within. If a fee
preference is not explicitly specified, then an error is returned.
Note that this RPC currently doesn't perform any validation checks on the
fee preference being provided. For now, the responsibility of ensuring that
the new fee preference is sufficient is delegated to the user.
*/
rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse);
/**
ListSweeps returns a list of the sweep transactions our node has produced.
Note that these sweeps may not be confirmed yet, as we record sweeps on
broadcast, not confirmation.
*/
rpc ListSweeps (ListSweepsRequest) returns (ListSweepsResponse) {}
}

@ -4,6 +4,8 @@ package watchtowerrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/watchtowerrpc";
// Watchtower is a service that grants access to the watchtower server
// functionality of the daemon.
service Watchtower {
/** lncli: tower info
GetInfo returns general information concerning the companion watchtower

@ -4,6 +4,38 @@ package wtclientrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/wtclientrpc";
// WatchtowerClient is a service that grants access to the watchtower client
// functionality of the daemon.
service WatchtowerClient {
/*
AddTower adds a new watchtower reachable at the given address and
considers it for new sessions. If the watchtower already exists, then
any new addresses included will be considered when dialing it for
session negotiations and backups.
*/
rpc AddTower (AddTowerRequest) returns (AddTowerResponse);
/*
RemoveTower removes a watchtower from being considered for future session
negotiations and from being used for any subsequent backups until it's added
again. If an address is provided, then this RPC only serves as a way of
removing the address from the watchtower instead.
*/
rpc RemoveTower (RemoveTowerRequest) returns (RemoveTowerResponse);
// ListTowers returns the list of watchtowers registered with the client.
rpc ListTowers (ListTowersRequest) returns (ListTowersResponse);
// GetTowerInfo retrieves information for a registered watchtower.
rpc GetTowerInfo (GetTowerInfoRequest) returns (Tower);
// Stats returns the in-memory statistics of the client since startup.
rpc Stats (StatsRequest) returns (StatsResponse);
// Policy returns the active watchtower client policy configuration.
rpc Policy (PolicyRequest) returns (PolicyResponse);
}
message AddTowerRequest {
// The identifying public key of the watchtower to add.
bytes pubkey = 1;
@ -133,33 +165,3 @@ message PolicyResponse {
*/
uint32 sweep_sat_per_byte = 2;
}
service WatchtowerClient {
/*
AddTower adds a new watchtower reachable at the given address and
considers it for new sessions. If the watchtower already exists, then
any new addresses included will be considered when dialing it for
session negotiations and backups.
*/
rpc AddTower (AddTowerRequest) returns (AddTowerResponse);
/*
RemoveTower removes a watchtower from being considered for future session
negotiations and from being used for any subsequent backups until it's added
again. If an address is provided, then this RPC only serves as a way of
removing the address from the watchtower instead.
*/
rpc RemoveTower (RemoveTowerRequest) returns (RemoveTowerResponse);
// ListTowers returns the list of watchtowers registered with the client.
rpc ListTowers (ListTowersRequest) returns (ListTowersResponse);
// GetTowerInfo retrieves information for a registered watchtower.
rpc GetTowerInfo (GetTowerInfoRequest) returns (Tower);
// Stats returns the in-memory statistics of the client since startup.
rpc Stats (StatsRequest) returns (StatsResponse);
// Policy returns the active watchtower client policy configuration.
rpc Policy (PolicyRequest) returns (PolicyResponse);
}