Skip to content

Instantly share code, notes, and snippets.

@mrfelton

mrfelton/lnd-0.8-0.9.diff

Last active Feb 4, 2020
Embed
What would you like to do?
lnd grpc 0.8 - 0.9 diff
diff -Naur proto/0.8.0-beta/invoicesrpc/invoices.proto proto/0.9.0-beta/invoicesrpc/invoices.proto
--- proto/0.8.0-beta/invoicesrpc/invoices.proto 2019-10-18 09:43:05.000000000 +0200
+++ proto/0.9.0-beta/invoicesrpc/invoices.proto 2020-02-04 11:22:37.000000000 +0100
@@ -55,10 +55,21 @@
/// The hash of the preimage
bytes hash = 2 [json_name = "hash"];
- /// The value of this invoice in satoshis
+ /**
+ The value of this invoice in satoshis
+
+ The fields value and value_msat are mutually exclusive.
+ */
int64 value = 3 [json_name = "value"];
/**
+ The value of this invoice in millisatoshis
+
+ The fields value and value_msat are mutually exclusive.
+ */
+ int64 value_msat = 10 [json_name = "value_msat"];
+
+ /**
Hash (SHA-256) of a description of the payment. Used if the description of
payment (memo) is too long to naturally fit within the description field
of an encoded payment request.
diff -Naur proto/0.8.0-beta/lnrpc/rpc.proto proto/0.9.0-beta/lnrpc/rpc.proto
--- proto/0.8.0-beta/lnrpc/rpc.proto 2019-11-13 14:29:42.000000000 +0100
+++ proto/0.9.0-beta/lnrpc/rpc.proto 2020-02-04 11:23:05.000000000 +0100
@@ -19,7 +19,7 @@
* 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.
*
@@ -94,13 +94,15 @@
message GenSeedRequest {
/**
aezeed_passphrase is an optional user provided passphrase that will be used
- to encrypt the generated aezeed cipher seed.
+ to encrypt the generated aezeed cipher seed. When using REST, this field
+ must be encoded as base64.
*/
bytes aezeed_passphrase = 1;
/**
seed_entropy is an optional 16-bytes generated via CSPRNG. If not
specified, then a fresh set of randomness will be used to create the seed.
+ When using REST, this field must be encoded as base64.
*/
bytes seed_entropy = 2;
}
@@ -125,7 +127,8 @@
/**
wallet_password is the passphrase that should be used to encrypt the
wallet. This MUST be at least 8 chars in length. After creation, this
- password is required to unlock the daemon.
+ password is required to unlock the daemon. When using REST, this field
+ must be encoded as base64.
*/
bytes wallet_password = 1;
@@ -138,7 +141,8 @@
/**
aezeed_passphrase is an optional user provided passphrase that will be used
- to encrypt the generated aezeed cipher seed.
+ to encrypt the generated aezeed cipher seed. When using REST, this field
+ must be encoded as base64.
*/
bytes aezeed_passphrase = 3;
@@ -168,7 +172,7 @@
/**
wallet_password should be the current valid passphrase for the daemon. This
will be required to decrypt on-disk material that the daemon requires to
- function properly.
+ function properly. When using REST, this field must be encoded as base64.
*/
bytes wallet_password = 1;
@@ -196,13 +200,13 @@
message ChangePasswordRequest {
/**
current_password should be the current valid passphrase used to unlock the
- daemon.
+ daemon. When using REST, this field must be encoded as base64.
*/
bytes current_password = 1;
/**
new_password should be the new passphrase that will be needed to unlock the
- daemon.
+ daemon. When using REST, this field must be encoded as base64.
*/
bytes new_password = 2;
}
@@ -355,6 +359,13 @@
};
}
+ /**
+ 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) returns (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
@@ -426,10 +437,34 @@
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) returns (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) returns (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) returns (stream ChannelAcceptRequest);
+
/** lncli: `closechannel`
CloseChannel attempts to close an active channel identified by its channel
outpoint (ChannelPoint). The actions of this method can additionally be
@@ -541,9 +576,9 @@
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.
*/
@@ -586,7 +621,7 @@
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.
*/
@@ -694,7 +729,7 @@
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.
*/
@@ -768,6 +803,18 @@
*/
rpc SubscribeChannelBackups(ChannelBackupSubscription) returns (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) returns (BakeMacaroonResponse) {
+ option (google.api.http) = {
+ post: "/v1/macaroon"
+ body: "*"
+ };
+ };
}
message Utxo {
@@ -827,32 +874,66 @@
message FeeLimit {
oneof limit {
- /// The fee limit expressed as a fixed amount of satoshis.
+ /**
+ The fee limit expressed as a fixed amount of satoshis.
+
+ The fields fixed and fixed_msat are mutually exclusive.
+ */
int64 fixed = 1;
+ /**
+ The fee limit expressed as a fixed amount of millisatoshis.
+
+ The fields fixed and fixed_msat are mutually exclusive.
+ */
+ int64 fixed_msat = 3;
+
/// The fee limit expressed as a percentage of the payment amount.
int64 percent = 2;
}
}
message SendRequest {
- /// The identity pubkey of the payment recipient
+ /**
+ The identity pubkey of the payment recipient. When using REST, this field
+ must be encoded as base64.
+ */
bytes dest = 1;
- /// The hex-encoded identity pubkey of the payment recipient
- string dest_string = 2;
+ /**
+ The hex-encoded identity pubkey of the payment recipient. Deprecated now
+ that the REST gateway supports base64 encoding of bytes fields.
+ */
+ string dest_string = 2 [deprecated = true];
+
+ /**
+ The amount to send expressed in satoshis.
- /// Number of satoshis to send.
+ The fields amt and amt_msat are mutually exclusive.
+ */
int64 amt = 3;
- /// The hash to use within the payment's HTLC
+ /**
+ The amount to send expressed in millisatoshis.
+
+ The fields amt and amt_msat are mutually exclusive.
+ */
+ int64 amt_msat = 12;
+
+ /**
+ The hash to use within the payment's HTLC. When using REST, this field
+ must be encoded as base64.
+ */
bytes payment_hash = 4;
- /// The hex-encoded hash to use within the payment's HTLC
- string payment_hash_string = 5;
+ /**
+ The hex-encoded hash to use within the payment's HTLC. Deprecated now
+ that the REST gateway supports base64 encoding of bytes fields.
+ */
+ string payment_hash_string = 5 [deprecated = true];
/**
- A bare-bones invoice for a payment within the Lightning Network. With the
+ A bare-bones invoice for a payment within the Lightning Network. With the
details of the invoice, the sender has all the data necessary to send a
payment to the recipient.
*/
@@ -876,20 +957,40 @@
The channel id of the channel that must be taken to the first hop. If zero,
any channel may be used.
*/
- uint64 outgoing_chan_id = 9;
+ uint64 outgoing_chan_id = 9 [jstype = JS_STRING];
+
+ /**
+ The pubkey of the last hop of the route. If empty, any hop may be used.
+ */
+ bytes last_hop_pubkey = 13;
/**
- An optional maximum total time lock for the route. If zero, there is no
- maximum enforced.
+ An optional maximum total time lock for the route. This should not exceed
+ lnd's `--max-cltv-expiry` setting. If zero, then the value of
+ `--max-cltv-expiry` is enforced.
*/
uint32 cltv_limit = 10;
/**
An optional field that can be used to pass an arbitrary set of TLV records
to a peer which understands the new records. This can be used to pass
- application specific data during the payment attempt.
+ application specific data during the payment attempt. Record types are
+ required to be in the custom range >= 65536. When using REST, the values
+ must be encoded as base64.
+ */
+ map<uint64, bytes> dest_custom_records = 11;
+
+ /// If set, circular payments to self are permitted.
+ bool allow_self_payment = 14;
+
+ /**
+ Features assumed to be supported by the final node. All transitive feature
+ depdencies must also be set properly. For a given feature bit pair, either
+ optional or remote may be set, but not both. If this field is nil or empty,
+ the router will try to load destination features from the graph as a
+ fallback.
*/
- map<uint64, bytes> dest_tlv = 11;
+ repeated FeatureBit dest_features = 15;
}
message SendResponse {
@@ -900,11 +1001,17 @@
}
message SendToRouteRequest {
- /// The payment hash to use for the HTLC.
+ /**
+ The payment hash to use for the HTLC. When using REST, this field must be
+ encoded as base64.
+ */
bytes payment_hash = 1;
- /// An optional hex-encoded payment hash to be used for the HTLC.
- string payment_hash_string = 2;
+ /**
+ An optional hex-encoded payment hash to be used for the HTLC. Deprecated now
+ that the REST gateway supports base64 encoding of bytes fields.
+ */
+ string payment_hash_string = 2 [deprecated = true];
reserved 3;
@@ -912,12 +1019,70 @@
Route route = 4;
}
+message ChannelAcceptRequest {
+ /// The pubkey of the node that wishes to open an inbound channel.
+ bytes node_pubkey = 1;
+
+ /// The hash of the genesis block that the proposed channel resides in.
+ bytes chain_hash = 2;
+
+ /// The pending channel id.
+ bytes pending_chan_id = 3;
+
+ /// The funding amount in satoshis that initiator wishes to use in the channel.
+ uint64 funding_amt = 4;
+
+ /// The push amount of the proposed channel in millisatoshis.
+ uint64 push_amt = 5;
+
+ /// The dust limit of the initiator's commitment tx.
+ uint64 dust_limit = 6;
+
+ /// The maximum amount of coins in millisatoshis that can be pending in this channel.
+ uint64 max_value_in_flight = 7;
+
+ /// The minimum amount of satoshis the initiator requires us to have at all times.
+ uint64 channel_reserve = 8;
+
+ /// The smallest HTLC in millisatoshis that the initiator will accept.
+ uint64 min_htlc = 9;
+
+ /// The initial fee rate that the initiator suggests for both commitment transactions.
+ uint64 fee_per_kw = 10;
+
+ /**
+ The number of blocks to use for the relative time lock in the pay-to-self output
+ of both commitment transactions.
+ */
+ uint32 csv_delay = 11;
+
+ /// The total number of incoming HTLC's that the initiator will accept.
+ uint32 max_accepted_htlcs = 12;
+
+ /// A bit-field which the initiator uses to specify proposed channel behavior.
+ uint32 channel_flags = 13;
+}
+
+message ChannelAcceptResponse {
+ /// Whether or not the client accepts the channel.
+ bool accept = 1;
+
+ /// The pending channel id to which this response applies.
+ bytes pending_chan_id = 2;
+}
+
message ChannelPoint {
oneof funding_txid {
- /// Txid of the funding transaction
+ /**
+ Txid of the funding transaction. When using REST, this field must be
+ encoded as base64.
+ */
bytes funding_txid_bytes = 1 [json_name = "funding_txid_bytes"];
- /// Hex-encoded string representing the funding transaction
+ /**
+ Hex-encoded string representing the byte-reversed hash of the funding
+ transaction.
+ */
string funding_txid_str = 2 [json_name = "funding_txid_str"];
}
@@ -1035,7 +1200,10 @@
}
message SignMessageRequest {
- /// The message to be signed
+ /**
+ The message to be signed. When using REST, this field must be encoded as
+ base64.
+ */
bytes msg = 1 [ json_name = "msg" ];
}
message SignMessageResponse {
@@ -1044,7 +1212,10 @@
}
message VerifyMessageRequest {
- /// The message over which the signature is to be verified
+ /**
+ The message over which the signature is to be verified. When using REST,
+ this field must be encoded as base64.
+ */
bytes msg = 1 [ json_name = "msg" ];
/// The signature to be verified over the given message
@@ -1063,7 +1234,7 @@
LightningAddress addr = 1;
/** If set, the daemon will attempt to persistently connect to the target
- * peer. Otherwise, the call will be synchronous. */
+ * peer. Otherwise, the call will be synchronous. */
bool perm = 2;
}
message ConnectPeerResponse {
@@ -1102,7 +1273,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 chan_id = 4 [json_name = "chan_id"];
+ uint64 chan_id = 4 [json_name = "chan_id", jstype = JS_STRING];
/// The total amount of funds held in this channel
int64 capacity = 5 [json_name = "capacity"];
@@ -1176,6 +1347,36 @@
The minimum satoshis the other node is required to reserve in its balance.
*/
int64 remote_chan_reserve_sat = 21 [json_name = "remote_chan_reserve_sat"];
+
+ /**
+ If true, then this channel uses the modern commitment format where the key
+ in the output of the remote party does not change each state. This makes
+ back up and recovery easier as when the channel is closed, the funds go
+ directly to that key.
+ */
+ bool static_remote_key = 22 [json_name = "static_remote_key"];
+
+ /**
+ The number of seconds that the channel has been monitored by the channel
+ scoring system. Scores are currently not persisted, so this value may be
+ less than the lifetime of the channel [EXPERIMENTAL].
+ */
+ int64 lifetime = 23 [json_name = "lifetime"];
+
+ /**
+ The number of seconds that the remote peer has been observed as being online
+ by the channel scoring system over the lifetime of the channel [EXPERIMENTAL].
+ */
+ int64 uptime = 24 [json_name = "uptime"];
+
+ /**
+ Close address is the address that we will enforce payout to on cooperative
+ close if the channel was opened utilizing option upfront shutdown. This
+ value can be set on channel open by setting close_address in an open channel
+ request. If this value is not set, you can still choose a payout address by
+ cooperatively closing with the delivery_address field set.
+ */
+ string close_address = 25 [json_name ="close_address"];
}
@@ -1195,7 +1396,7 @@
string channel_point = 1 [json_name = "channel_point"];
/// The unique channel ID for the channel.
- uint64 chan_id = 2 [json_name = "chan_id"];
+ uint64 chan_id = 2 [json_name = "chan_id", jstype = JS_STRING];
/// The hash of the genesis block that this channel resides within.
string chain_hash = 3 [json_name = "chain_hash"];
@@ -1288,6 +1489,9 @@
// The type of sync we are currently performing with this peer.
SyncType sync_type = 10 [json_name = "sync_type"];
+
+ /// Features advertised by the remote peer in their init message.
+ map<uint32, Feature> features = 11 [json_name = "features"];
}
message ListPeersRequest {
@@ -1297,22 +1501,46 @@
repeated Peer peers = 1 [json_name = "peers"];
}
+message PeerEventSubscription {
+}
+
+message PeerEvent {
+ /// The identity pubkey of the peer.
+ string pub_key = 1 [json_name = "pub_key"];
+
+ enum EventType {
+ PEER_ONLINE = 0;
+ PEER_OFFLINE = 1;
+ }
+
+ EventType type = 2 [ json_name = "type" ];
+}
+
message GetInfoRequest {
}
message GetInfoResponse {
+ /// The version of the LND software that the node is running.
+ string version = 14 [ json_name = "version" ];
+
/// The identity pubkey of the current node.
string identity_pubkey = 1 [json_name = "identity_pubkey"];
/// If applicable, the alias of the current node, e.g. "bob"
string alias = 2 [json_name = "alias"];
+ /// The color of the current node in hex code format
+ string color = 17 [json_name = "color"];
+
/// Number of pending channels
uint32 num_pending_channels = 3 [json_name = "num_pending_channels"];
/// Number of active channels
uint32 num_active_channels = 4 [json_name = "num_active_channels"];
+ /// Number of inactive channels
+ uint32 num_inactive_channels = 15 [json_name = "num_inactive_channels"];
+
/// Number of peers
uint32 num_peers = 5 [json_name = "num_peers"];
@@ -1322,9 +1550,15 @@
/// The node's current view of the hash of the best block
string block_hash = 8 [json_name = "block_hash"];
+ /// Timestamp of the block best known to the wallet
+ int64 best_header_timestamp = 13 [ json_name = "best_header_timestamp" ];
+
/// Whether the wallet's view is synced to the main chain
bool synced_to_chain = 9 [json_name = "synced_to_chain"];
+ // Whether we consider ourselves synced with the public channel graph.
+ bool synced_to_graph = 18 [json_name = "synced_to_graph"];
+
/**
Whether the current node is connected to testnet. This field is
deprecated and the network field should be used instead
@@ -1333,26 +1567,17 @@
reserved 11;
- /// The URIs of the current node.
- repeated string uris = 12 [json_name = "uris"];
-
- /// Timestamp of the block best known to the wallet
- int64 best_header_timestamp = 13 [ json_name = "best_header_timestamp" ];
-
- /// The version of the LND software that the node is running.
- string version = 14 [ json_name = "version" ];
-
- /// Number of inactive channels
- uint32 num_inactive_channels = 15 [json_name = "num_inactive_channels"];
-
/// A list of active chains the node is connected to
repeated Chain chains = 16 [json_name = "chains"];
- /// The color of the current node in hex code format
- string color = 17 [json_name = "color"];
+ /// The URIs of the current node.
+ repeated string uris = 12 [json_name = "uris"];
- // Whether we consider ourselves synced with the public channel graph.
- bool synced_to_graph = 18 [json_name = "synced_to_graph"];
+ /*
+ Features that our node has advertised in our init message, node
+ announcements and invoices.
+ */
+ map<uint32, Feature> features = 19 [json_name = "features"];
}
message Chain {
@@ -1396,6 +1621,14 @@
/// A manual fee rate set in sat/byte that should be used when crafting the closure transaction.
int64 sat_per_byte = 4;
+
+ /*
+ An optional address to send funds to in the case of a cooperative close.
+ If the channel was opened with an upfront shutdown script and this field
+ is set, the request to close will fail because the channel must pay out
+ to the upfront shutdown addresss.
+ */
+ string delivery_address = 5 [json_name = "delivery_address"];
}
message CloseStatusUpdate {
@@ -1411,11 +1644,17 @@
}
message OpenChannelRequest {
- /// The pubkey of the node to open a channel with
+ /**
+ The pubkey of the node to open a channel with. When using REST, this field
+ must be encoded as base64.
+ */
bytes node_pubkey = 2 [json_name = "node_pubkey"];
- /// The hex encoded pubkey of the node to open a channel with
- string node_pubkey_string = 3 [json_name = "node_pubkey_string"];
+ /**
+ The hex encoded pubkey of the node to open a channel with. Deprecated now
+ that the REST gateway supports base64 encoding of bytes fields.
+ */
+ string node_pubkey_string = 3 [json_name = "node_pubkey_string", deprecated = true];
/// The number of satoshis the wallet should commit to the channel
int64 local_funding_amount = 4 [json_name = "local_funding_amount"];
@@ -1444,16 +1683,113 @@
/// Whether unconfirmed outputs should be used as inputs for the funding transaction.
bool spend_unconfirmed = 12 [json_name = "spend_unconfirmed"];
- /// Whether this channel lets the push amount to be spent while unconfirmed.
- bool trusted_push = 13 [json_name = "trusted_push"];
+ /*
+ Close address is an optional address which specifies the address to which
+ funds should be paid out to upon cooperative close. This field may only be
+ set if the peer supports the option upfront feature bit (call listpeers
+ to check). The remote peer will only accept cooperative closes to this
+ address if it is set.
+
+ Note: If this value is set on channel creation, you will *not* be able to
+ cooperatively close out to a different address.
+ */
+ string close_address = 13 [json_name = "close_address"];
+
+ /**
+ Funding shims are an optional argument that allow the caller to intercept
+ certain funding functionality. For example, a shim can be provided to use a
+ particular key for the commitment key (ideally cold) rather than use one
+ that is generated by the wallet as normal, or signal that signing will be
+ carried out in an interactive manner (PSBT based).
+ */
+ FundingShim funding_shim = 14 [json_name = "funding_shim"];
}
message OpenStatusUpdate {
oneof update {
PendingUpdate chan_pending = 1 [json_name = "chan_pending"];
ChannelOpenUpdate chan_open = 3 [json_name = "chan_open"];
+ }
+
+ /**
+ The pending channel ID of the created channel. This value may be used to
+ further the funding flow manually via the FundingStateStep method.
+ */
+ bytes pending_chan_id = 4 [json_name = "pending_chan_id"];
+}
+
+message KeyLocator {
+ /// The family of key being identified.
+ int32 key_family = 1;
+
+ /// The precise index of the key being identified.
+ int32 key_index = 2;
+}
+
+message KeyDescriptor {
+ /**
+ The raw bytes of the key being identified.
+ */
+ bytes raw_key_bytes = 1;
+
+ /**
+ The key locator that identifies which key to use for signing.
+ */
+ KeyLocator key_loc = 2;
+}
+
+message ChanPointShim {
+ /**
+ The size of the pre-crafted output to be used as the channel point for this
+ channel funding.
+ */
+ int64 amt = 1;
+
+ /// The target channel point to refrence in created commitment transactions.
+ ChannelPoint chan_point = 2;
+
+ /// Our local key to use when creating the multi-sig output.
+ KeyDescriptor local_key = 3;
+
+ /// The key of the remote party to use when creating the multi-sig output.
+ bytes remote_key = 4;
+
+ /**
+ If non-zero, then this will be used as the pending channel ID on the wire
+ protocol to initate the funding request. This is an optional field, and
+ should only be set if the responder is already expecting a specific pending
+ channel ID.
+ */
+ bytes pending_chan_id = 5;
+}
+
+message FundingShim {
+ oneof shim {
+ ChanPointShim chan_point_shim = 1;
+ }
+}
+
+message FundingShimCancel {
+ /// The pending channel ID of the channel to cancel the funding shim for.
+ bytes pending_chan_id = 1;
+}
+
+message FundingTransitionMsg {
+ oneof trigger {
+ /**
+ The funding shim to regsiter. This should be used before any
+ channel funding has began by the remote party, as it is intended as a
+ prepatory step for the full channel funding.
+ */
+ FundingShim shim_register = 1;
+
+ /// Used to cancel an existing registered funding shim.
+ FundingShimCancel shim_cancel = 2;
}
}
+message FundingStateStepResp {
+}
+
message PendingHTLC {
/// The direction within the channel that the htlc was sent
@@ -1633,12 +1969,29 @@
/// The 33-byte hex-encoded public key for the payment destination
string pub_key = 1;
- /// The amount to send expressed in satoshis
+ /**
+ The amount to send expressed in satoshis.
+
+ The fields amt and amt_msat are mutually exclusive.
+ */
int64 amt = 2;
+ /**
+ The amount to send expressed in millisatoshis.
+
+ The fields amt and amt_msat are mutually exclusive.
+ */
+ int64 amt_msat = 12;
+
reserved 3;
- /// An optional CLTV delta from the current height that should be used for the timelock of the final hop
+ /**
+ An optional CLTV delta from the current height that should be used for the
+ timelock of the final hop. Note that unlike SendPayment, QueryRoutes does
+ not add any additional block padding on top of final_ctlv_delta. This
+ padding of a few blocks needs to be added manually or otherwise failures may
+ happen when a block comes in while the payment is in flight.
+ */
int32 final_cltv_delta = 4;
/**
@@ -1650,7 +2003,8 @@
FeeLimit fee_limit = 5;
/**
- A list of nodes to ignore during path finding.
+ A list of nodes to ignore during path finding. When using REST, these fields
+ must be encoded as base64.
*/
repeated bytes ignored_nodes = 6;
@@ -1677,25 +2031,65 @@
repeated NodePair ignored_pairs = 10;
/**
+ An optional maximum total time lock for the route. If the source is empty or
+ ourselves, this should not exceed lnd's `--max-cltv-expiry` setting. If
+ zero, then the value of `--max-cltv-expiry` is used as the limit.
+ */
+ uint32 cltv_limit = 11;
+
+ /**
An optional field that can be used to pass an arbitrary set of TLV records
to a peer which understands the new records. This can be used to pass
application specific data during the payment attempt. If the destination
does not support the specified recrods, and error will be returned.
+ Record types are required to be in the custom range >= 65536. When using
+ REST, the values must be encoded as base64.
+ */
+ map<uint64, bytes> dest_custom_records = 13;
+
+ /**
+ The channel id of the channel that must be taken to the first hop. If zero,
+ any channel may be used.
+ */
+ uint64 outgoing_chan_id = 14 [jstype = JS_STRING];
+
+ /**
+ The pubkey of the last hop of the route. If empty, any hop may be used.
*/
- map<uint64, bytes> dest_tlv = 11;
+ bytes last_hop_pubkey = 15;
+
+ /**
+ Optional route hints to reach the destination through private channels.
+ */
+ repeated lnrpc.RouteHint route_hints = 16;
+
+ /**
+ Features assumed to be supported by the final node. All transitive feature
+ depdencies must also be set properly. For a given feature bit pair, either
+ optional or remote may be set, but not both. If this field is nil or empty,
+ the router will try to load destination features from the graph as a
+ fallback.
+ */
+ repeated lnrpc.FeatureBit dest_features = 17;
}
message NodePair {
- /// The sending node of the pair.
+ /**
+ The sending node of the pair. When using REST, this field must be encoded as
+ base64.
+ */
bytes from = 1;
- /// The receiving node of the pair.
+ /**
+ The receiving node of the pair. When using REST, this field must be encoded
+ as base64.
+ */
bytes to = 2;
}
message EdgeLocator {
/// The short channel id of this edge.
- uint64 channel_id = 1;
+ uint64 channel_id = 1 [jstype = JS_STRING];
/**
The direction of this edge. If direction_reverse is false, the direction
@@ -1726,7 +2120,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 chan_id = 1 [json_name = "chan_id"];
+ uint64 chan_id = 1 [json_name = "chan_id", jstype = JS_STRING];
int64 chan_capacity = 2 [json_name = "chan_capacity"];
int64 amt_to_forward = 3 [json_name = "amt_to_forward", deprecated = true];
int64 fee = 4 [json_name = "fee", deprecated = true];
@@ -1748,11 +2142,37 @@
bool tlv_payload = 9 [json_name = "tlv_payload"];
/**
+ An optional TLV record tha singals the use of an MPP payment. If present,
+ the receiver will enforce that that the same mpp_record is included in the
+ final hop payload of all non-zero payments in the HTLC set. If empty, a
+ regular single-shot payment is or was attempted.
+ */
+ MPPRecord mpp_record = 10 [json_name = "mpp_record"];
+
+ /**
An optional set of key-value TLV records. This is useful within the context
of the SendToRoute call as it allows callers to specify arbitrary K-V pairs
to drop off at each hop within the onion.
*/
- map<uint64, bytes> tlv_records = 10 [json_name = "tlv_records"];
+ map<uint64, bytes> custom_records = 11 [json_name = "custom_records"];
+}
+
+message MPPRecord {
+ /**
+ A unique, random identifier used to authenticate the sender as the intended
+ payer of a multi-path payment. The payment_addr must be the same for all
+ subpayments, and match the payment_addr provided in the receiver's invoice.
+ The same payment_addr must be used on all subpayments.
+ */
+ bytes payment_addr = 11 [json_name = "payment_addr"];
+
+ /**
+ The total amount in milli-satoshis being sent as part of a larger multi-path
+ payment. The caller is responsible for ensuring subpayments to the same node
+ and payment_hash sum exactly to total_amt_msat. The same
+ total_amt_msat must be used on all subpayments.
+ */
+ int64 total_amt_msat = 10 [json_name = "total_amt_msat"];
}
/**
@@ -1765,7 +2185,7 @@
message Route {
/**
- The cumulative (final) time lock across the entire route. This is the CLTV
+ The cumulative (final) time lock across the entire route. This is the CLTV
value that should be extended to the first hop in the route. All other hops
will decrement the time-lock as advertised, leaving enough time for all
hops to wait for or present the payment preimage to complete the payment.
@@ -1773,7 +2193,7 @@
uint32 total_time_lock = 1 [json_name = "total_time_lock"];
/**
- The sum of the fees paid at each hop within the final route. In the case
+ The sum of the fees paid at each hop within the final route. In the case
of a one-hop payment, this value will be zero as we don't need to pay a fee
to ourselves.
*/
@@ -1844,6 +2264,7 @@
string alias = 3 [ json_name = "alias" ];
repeated NodeAddress addresses = 4 [ json_name = "addresses" ];
string color = 5 [ json_name = "color" ];
+ map<uint32, Feature> features = 6 [ json_name = "features" ];
}
message NodeAddress {
@@ -1875,7 +2296,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 channel_id = 1 [json_name = "channel_id"];
+ uint64 channel_id = 1 [json_name = "channel_id", jstype = JS_STRING];
string chan_point = 2 [json_name = "chan_point"];
uint32 last_update = 3 [json_name = "last_update", deprecated = true];
@@ -1913,7 +2334,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 chan_id = 1;
+ uint64 chan_id = 1 [jstype = JS_STRING];
}
message NetworkInfoRequest {
@@ -1962,7 +2383,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 chan_id = 1;
+ uint64 chan_id = 1 [jstype = JS_STRING];
ChannelPoint chan_point = 2;
@@ -1979,7 +2400,7 @@
height, the next 3 the index within the block, and the last 2 bytes are the
output index for the channel.
*/
- uint64 chan_id = 1;
+ uint64 chan_id = 1 [jstype = JS_STRING];
int64 capacity = 2;
uint32 closed_height = 3;
ChannelPoint chan_point = 4;
@@ -1990,7 +2411,7 @@
string node_id = 1 [json_name = "node_id"];
/// The unique identifier of the channel.
- uint64 chan_id = 2 [json_name = "chan_id"];
+ uint64 chan_id = 2 [json_name = "chan_id", jstype = JS_STRING];
/// The base fee of the channel denominated in millisatoshis.
uint32 fee_base_msat = 3 [json_name = "fee_base_msat"];
@@ -2022,23 +2443,35 @@
*/
string memo = 1 [json_name = "memo"];
- /** Deprecated. An optional cryptographic receipt of payment which is not
- implemented.
- */
- bytes receipt = 2 [json_name = "receipt", deprecated = true];
+ reserved 2;
/**
The hex-encoded preimage (32 byte) which will allow settling an incoming
- HTLC payable to this preimage
+ HTLC payable to this preimage. When using REST, this field must be encoded
+ as base64.
*/
bytes r_preimage = 3 [json_name = "r_preimage"];
- /// The hash of the preimage
+ /**
+ The hash of the preimage. When using REST, this field must be encoded as
+ base64.
+ */
bytes r_hash = 4 [json_name = "r_hash"];
- /// The value of this invoice in satoshis
+ /**
+ The value of this invoice in satoshis
+
+ The fields value and value_msat are mutually exclusive.
+ */
int64 value = 5 [json_name = "value"];
+ /**
+ The value of this invoice in millisatoshis
+
+ The fields value and value_msat are mutually exclusive.
+ */
+ int64 value_msat = 23 [json_name = "value_msat"];
+
/// Whether this invoice has been fulfilled
bool settled = 6 [json_name = "settled", deprecated = true];
@@ -2049,7 +2482,7 @@
int64 settle_date = 8 [json_name = "settle_date"];
/**
- A bare-bones invoice for a payment within the Lightning Network. With the
+ A bare-bones invoice for a payment within the Lightning Network. With the
details of the invoice, the sender has all the data necessary to send a
payment to the recipient.
*/
@@ -2058,7 +2491,8 @@
/**
Hash (SHA-256) of a description of the payment. Used if the description of
payment (memo) is too long to naturally fit within the description field
- of an encoded payment request.
+ of an encoded payment request. When using REST, this field must be encoded
+ as base64.
*/
bytes description_hash = 10 [json_name = "description_hash"];
@@ -2133,18 +2567,27 @@
/// List of HTLCs paying to this invoice [EXPERIMENTAL].
repeated InvoiceHTLC htlcs = 22 [json_name = "htlcs"];
+
+ /// List of features advertised on the invoice.
+ map<uint32, Feature> features = 24 [json_name = "features"];
+
+ /**
+ Indicates if this invoice was a spontaneous payment that arrived via keysend
+ [EXPERIMENTAL].
+ */
+ bool is_keysend = 25 [json_name = "is_keysend"];
}
enum InvoiceHTLCState {
ACCEPTED = 0;
SETTLED = 1;
- CANCELLED = 2;
+ CANCELED = 2;
}
/// Details of an HTLC that paid to an invoice
message InvoiceHTLC {
/// Short channel id over which the htlc was received.
- uint64 chan_id = 1 [json_name = "chan_id"];
+ uint64 chan_id = 1 [json_name = "chan_id", jstype = JS_STRING];
/// Index identifying the htlc on the channel.
uint64 htlc_index = 2 [json_name = "htlc_index"];
@@ -2158,7 +2601,7 @@
/// Time at which this htlc was accepted.
int64 accept_time = 5 [json_name = "accept_time"];
- /// Time at which this htlc was settled or cancelled.
+ /// Time at which this htlc was settled or canceled.
int64 resolve_time = 6 [json_name = "resolve_time"];
/// Block height at which this htlc expires.
@@ -2166,13 +2609,19 @@
/// Current state the htlc is in.
InvoiceHTLCState state = 8 [json_name = "state"];
+
+ /// Custom tlv records.
+ map<uint64, bytes> custom_records = 9 [json_name = "custom_records"];
+
+ /// The total amount of the mpp payment in msat.
+ uint64 mpp_total_amt_msat = 10 [json_name = "mpp_total_amt_msat"];
}
message AddInvoiceResponse {
bytes r_hash = 1 [json_name = "r_hash"];
/**
- A bare-bones invoice for a payment within the Lightning Network. With the
+ A bare-bones invoice for a payment within the Lightning Network. With the
details of the invoice, the sender has all the data necessary to send a
payment to the recipient.
*/
@@ -2190,15 +2639,23 @@
/**
The hex-encoded payment hash of the invoice to be looked up. The passed
payment hash must be exactly 32 bytes, otherwise an error is returned.
+ Deprecated now that the REST gateway supports base64 encoding of bytes
+ fields.
*/
- string r_hash_str = 1 [json_name = "r_hash_str"];
+ string r_hash_str = 1 [json_name = "r_hash_str", deprecated = true];
- /// The payment hash of the invoice to be looked up.
+ /**
+ The payment hash of the invoice to be looked up. When using REST, this field
+ must be encoded as base64.
+ */
bytes r_hash = 2 [json_name = "r_hash"];
}
message ListInvoiceRequest {
- /// If set, only unsettled invoices will be returned in the response.
+ /**
+ If set, only invoices that are not settled and not canceled will be returned
+ in the response.
+ */
bool pending_only = 1 [json_name = "pending_only"];
/**
@@ -2262,11 +2719,11 @@
/// Deprecated, use value_sat or value_msat.
int64 value = 2 [json_name = "value", deprecated = true];
- /// The date of this payment
- int64 creation_date = 3 [json_name = "creation_date"];
+ /// Deprecated, use creation_time_ns
+ int64 creation_date = 3 [json_name = "creation_date", deprecated = true];
- /// The path this payment took
- repeated string path = 4 [ json_name = "path" ];
+ /// The path this payment took.
+ repeated string path = 4 [json_name = "path", deprecated = true];
/// Deprecated, use fee_sat or fee_msat.
int64 fee = 5 [json_name = "fee", deprecated = true];
@@ -2298,6 +2755,35 @@
/// The fee paid for this payment in milli-satoshis
int64 fee_msat = 12 [json_name = "fee_msat"];
+
+ /// The time in UNIX nanoseconds at which the payment was created.
+ int64 creation_time_ns = 13 [json_name = "creation_time_ns"];
+
+ /// The HTLCs made in attempt to settle the payment [EXPERIMENTAL].
+ repeated HTLCAttempt htlcs = 14 [json_name = "htlcs"];
+}
+
+message HTLCAttempt {
+ enum HTLCStatus {
+ IN_FLIGHT = 0;
+ SUCCEEDED = 1;
+ FAILED = 2;
+ }
+
+ /// The status of the HTLC.
+ HTLCStatus status = 1 [json_name = "status"];
+
+ /// The route taken by this HTLC.
+ Route route = 2 [json_name = "route"];
+
+ /// The time in UNIX nanoseconds at which this HTLC was sent.
+ int64 attempt_time_ns = 3 [json_name = "attempt_time_ns"];
+
+ /**
+ The time in UNIX nanoseconds at which this HTLC was settled or failed.
+ This value will not be set if the HTLC is still IN_FLIGHT.
+ */
+ int64 resolve_time_ns = 4 [json_name = "resolve_time_ns"];
}
message ListPaymentsRequest {
@@ -2351,6 +2837,35 @@
string fallback_addr = 8 [json_name = "fallback_addr"];
int64 cltv_expiry = 9 [json_name = "cltv_expiry"];
repeated RouteHint route_hints = 10 [json_name = "route_hints"];
+ bytes payment_addr = 11 [json_name = "payment_addr"];
+ int64 num_msat = 12 [json_name = "num_msat"];
+ map<uint32, Feature> features = 13 [json_name = "features"];
+}
+
+enum FeatureBit {
+ DATALOSS_PROTECT_REQ = 0;
+ DATALOSS_PROTECT_OPT = 1;
+ INITIAL_ROUING_SYNC = 3;
+ UPFRONT_SHUTDOWN_SCRIPT_REQ = 4;
+ UPFRONT_SHUTDOWN_SCRIPT_OPT = 5;
+ GOSSIP_QUERIES_REQ = 6;
+ GOSSIP_QUERIES_OPT = 7;
+ TLV_ONION_REQ = 8;
+ TLV_ONION_OPT = 9;
+ EXT_GOSSIP_QUERIES_REQ = 10;
+ EXT_GOSSIP_QUERIES_OPT = 11;
+ STATIC_REMOTE_KEY_REQ = 12;
+ STATIC_REMOTE_KEY_OPT = 13;
+ PAYMENT_ADDR_REQ = 14;
+ PAYMENT_ADDR_OPT = 15;
+ MPP_REQ = 16;
+ MPP_OPT = 17;
+}
+
+message Feature {
+ string name = 2 [json_name = "name"];
+ bool is_required = 3 [json_name = "is_required"];
+ bool is_known = 4 [json_name = "is_known"];
}
message FeeReportRequest {}
@@ -2398,6 +2913,15 @@
/// The required timelock delta for HTLCs forwarded over the channel.
uint32 time_lock_delta = 5 [json_name = "time_lock_delta"];
+
+ /// If set, the maximum HTLC size in milli-satoshis. If unset, the maximum HTLC will be unchanged.
+ uint64 max_htlc_msat = 6 [json_name = "max_htlc_msat"];
+
+ /// The minimum HTLC size in milli-satoshis. Only applied if min_htlc_msat_specified is true.
+ uint64 min_htlc_msat = 7 [json_name = "min_htlc_msat"];
+
+ /// If true, min_htlc_msat is applied.
+ bool min_htlc_msat_specified = 8 [json_name = "set_min_htlc_msat"];
}
message PolicyUpdateResponse {
}
@@ -2420,10 +2944,10 @@
uint64 timestamp = 1 [json_name = "timestamp"];
/// The incoming channel ID that carried the HTLC that created the circuit.
- uint64 chan_id_in = 2 [json_name = "chan_id_in"];
+ uint64 chan_id_in = 2 [json_name = "chan_id_in", jstype = JS_STRING];
/// The outgoing channel ID that carried the preimage that completed the circuit.
- uint64 chan_id_out = 4 [json_name = "chan_id_out"];
+ uint64 chan_id_out = 4 [json_name = "chan_id_out", jstype = JS_STRING];
/// The total amount (in satoshis) of the incoming HTLC that created half the circuit.
uint64 amt_in = 5 [json_name = "amt_in"];
@@ -2437,6 +2961,13 @@
/// The total fee (in milli-satoshis) that this payment circuit carried.
uint64 fee_msat = 8 [json_name = "fee_msat"];
+ /// The total amount (in milli-satoshis) of the incoming HTLC that created half the circuit.
+ uint64 amt_in_msat = 9 [json_name = "amt_in_msat"];
+
+ /// The total amount (in milli-satoshis) of the outgoing HTLC that created the second half of the circuit.
+ uint64 amt_out_msat = 10 [json_name = "amt_out_msat"];
+
+
// TODO(roasbeef): add settlement latency?
// * use FPE on the chan id?
// * also list failures?
@@ -2463,7 +2994,8 @@
/**
Is an encrypted single-chan backup. this can be passed to
RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in
- order to trigger the recovery protocol.
+ order to trigger the recovery protocol. When using REST, this field must be
+ encoded as base64.
*/
bytes chan_backup = 2 [ json_name = "chan_backup" ];
}
@@ -2477,7 +3009,8 @@
/**
A single encrypted blob containing all the static channel backups of the
channel listed above. This can be stored as a single file or blob, and
- safely be replaced with any prior/future versions.
+ safely be replaced with any prior/future versions. When using REST, this
+ field must be encoded as base64.
*/
bytes multi_chan_backup = 2 [ json_name = "multi_chan_backup" ];
}
@@ -2506,8 +3039,15 @@
message RestoreChanBackupRequest {
oneof backup {
+ /**
+ The channels to restore as a list of channel/backup pairs.
+ */
ChannelBackups chan_backups = 1 [ json_name = "chan_backups" ];
+ /**
+ The channels to restore in the packed multi backup format. When using
+ REST, this field must be encoded as base64.
+ */
bytes multi_chan_backup = 2 [ json_name = "multi_chan_backup" ];
}
}
@@ -2517,3 +3057,19 @@
message VerifyChanBackupResponse {
}
+
+message MacaroonPermission {
+ /// The entity a permission grants access to.
+ string entity = 1 [json_name = "entity"];
+
+ /// The action that is granted.
+ string action = 2 [json_name = "action"];
+}
+message BakeMacaroonRequest {
+ /// The list of permissions the new macaroon should grant.
+ repeated MacaroonPermission permissions = 1 [json_name = "permissions"];
+}
+message BakeMacaroonResponse {
+ /// The hex encoded macaroon, serialized in binary format.
+ string macaroon = 1 [json_name = "macaroon"];
+}
diff -Naur proto/0.8.0-beta/routerrpc/router.proto proto/0.9.0-beta/routerrpc/router.proto
--- proto/0.8.0-beta/routerrpc/router.proto 2019-11-13 13:00:13.000000000 +0100
+++ proto/0.9.0-beta/routerrpc/router.proto 2020-02-04 11:23:37.000000000 +0100
@@ -10,9 +10,20 @@
/// The identity pubkey of the payment recipient
bytes dest = 1;
- /// Number of satoshis to send.
+ /**
+ Number of satoshis to send.
+
+ The fields amt and amt_msat are mutually exclusive.
+ */
int64 amt = 2;
+ /**
+ Number of millisatoshis to send.
+
+ The fields amt and amt_msat are mutually exclusive.
+ */
+ int64 amt_msat = 12;
+
/// The hash to use within the payment's HTLC
bytes payment_hash = 3;
@@ -44,18 +55,37 @@
If this field is left to the default value of 0, only zero-fee routes will
be considered. This usually means single hop routes connecting directly to
the destination. To send the payment without a fee limit, use max int here.
+
+ The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
*/
int64 fee_limit_sat = 7;
+ /**
+ The maximum number of millisatoshis that will be paid as a fee of the
+ payment. If this field is left to the default value of 0, only zero-fee
+ routes will be considered. This usually means single hop routes connecting
+ directly to the destination. To send the payment without a fee limit, use
+ max int here.
+
+ The fields fee_limit_sat and fee_limit_msat are mutually exclusive.
+ */
+ int64 fee_limit_msat = 13;
+
/**
The channel id of the channel that must be taken to the first hop. If zero,
any channel may be used.
*/
- uint64 outgoing_chan_id = 8;
+ uint64 outgoing_chan_id = 8 [jstype = JS_STRING];
+
+ /**
+ The pubkey of the last hop of the route. If empty, any hop may be used.
+ */
+ bytes last_hop_pubkey = 14;
/**
- An optional maximum total time lock for the route. If zero, there is no
- maximum enforced.
+ An optional maximum total time lock for the route. This should not exceed
+ lnd's `--max-cltv-expiry` setting. If zero, then the value of
+ `--max-cltv-expiry` is enforced.
*/
int32 cltv_limit = 9;
@@ -67,9 +97,23 @@
/**
An optional field that can be used to pass an arbitrary set of TLV records
to a peer which understands the new records. This can be used to pass
- application specific data during the payment attempt.
+ application specific data during the payment attempt. Record types are
+ required to be in the custom range >= 65536. When using REST, the values
+ must be encoded as base64.
*/
- map<uint64, bytes> dest_tlv = 11;
+ map<uint64, bytes> dest_custom_records = 11;
+
+ /// If set, circular payments to self are permitted.
+ bool allow_self_payment = 15;
+
+ /**
+ Features assumed to be supported by the final node. All transitive feature
+ depdencies must also be set properly. For a given feature bit pair, either
+ optional or remote may be set, but not both. If this field is nil or empty,
+ the router will try to load destination features from the graph as a
+ fallback.
+ */
+ repeated lnrpc.FeatureBit dest_features = 16;
}
message TrackPaymentRequest {
@@ -109,6 +153,11 @@
invalid final cltv delta)
*/
FAILED_INCORRECT_PAYMENT_DETAILS = 5;
+
+ /**
+ Insufficient local balance.
+ */
+ FAILED_INSUFFICIENT_BALANCE = 6;
}
@@ -125,6 +174,11 @@
The taken route when state is SUCCEEDED.
*/
lnrpc.Route route = 3;
+
+ /**
+ The HTLCs made in attempt to settle the payment [EXPERIMENTAL].
+ */
+ repeated lnrpc.HTLCAttempt htlcs = 4;
}
@@ -201,6 +255,8 @@
TEMPORARY_NODE_FAILURE = 19;
PERMANENT_NODE_FAILURE = 20;
PERMANENT_CHANNEL_FAILURE = 21;
+ EXPIRY_TOO_FAR = 22;
+ MPP_TIMEOUT = 23;
/**
The error source is known, but the failure itself couldn't be decoded.
@@ -263,7 +319,7 @@
/**
The unique description of the funding transaction.
*/
- uint64 chan_id = 3;
+ uint64 chan_id = 3 [jstype = JS_STRING];
/**
A timestamp that allows ordering in the case of multiple announcements.
@@ -335,49 +391,70 @@
/// QueryMissionControlResponse contains mission control state.
message QueryMissionControlResponse {
- /// Node-level mission control state.
- repeated NodeHistory nodes = 1 [json_name = "nodes"];
+ reserved 1;
/// Node pair-level mission control state.
repeated PairHistory pairs = 2 [json_name = "pairs"];
}
-/// NodeHistory contains the mission control state for a particular node.
-message NodeHistory {
- /// Node pubkey
- bytes pubkey = 1 [json_name = "pubkey"];
+/// PairHistory contains the mission control state for a particular node pair.
+message PairHistory {
+ /// The source node pubkey of the pair.
+ bytes node_from = 1 [json_name ="node_from"];
- /// Time stamp of last failure. Set to zero if no failure happened yet.
- int64 last_fail_time = 2 [json_name = "last_fail_time"];
+ /// The destination node pubkey of the pair.
+ bytes node_to = 2 [json_name="node_to"];
+
+ reserved 3, 4, 5, 6;
+
+ PairData history = 7 [json_name="history"];
+}
+
+message PairData {
+ /// Time of last failure.
+ int64 fail_time = 1 [json_name = "fail_time"];
/**
- Estimation of success probability of forwarding towards peers of this node
- for which no specific history is available.
- **/
- float other_success_prob = 3 [json_name = "other_success_prob"];
+ Lowest amount that failed to forward rounded to whole sats. This may be
+ set to zero if the failure is independent of amount.
+ */
+ int64 fail_amt_sat = 2 [json_name = "fail_amt_sat"];
+
+ /**
+ Lowest amount that failed to forward in millisats. This may be
+ set to zero if the failure is independent of amount.
+ */
+ int64 fail_amt_msat = 4 [json_name = "fail_amt_msat"];
- reserved 4;
+ reserved 3;
+
+ /// Time of last success.
+ int64 success_time = 5 [json_name = "success_time"];
+
+ /// Highest amount that we could successfully forward rounded to whole sats.
+ int64 success_amt_sat = 6 [json_name = "success_amt_sat"];
+
+ /// Highest amount that we could successfully forward in millisats.
+ int64 success_amt_msat = 7 [json_name = "success_amt_msat"];
}
-/// PairHistory contains the mission control state for a particular node pair.
-message PairHistory {
+message QueryProbabilityRequest{
/// The source node pubkey of the pair.
- bytes node_from = 1 [json_name ="node_from"];
+ bytes from_node = 1 [json_name = "from_node"];
/// The destination node pubkey of the pair.
- bytes node_to = 2 [json_name="node_to"];
-
- /// Time stamp of last result.
- int64 timestamp = 3 [json_name = "timestamp"];
+ bytes to_node = 2 [json_name = "to_node"];
- /// Minimum penalization amount (only applies to failed attempts).
- int64 min_penalize_amt_sat = 4 [json_name = "min_penalize_amt_sat"];
+ /// The amount for which to calculate a probability.
+ int64 amt_msat = 3 [json_name = "amt_msat"];
+}
- /// Estimation of success probability for this pair.
- float success_prob = 5 [json_name = "success_prob"];
+message QueryProbabilityResponse{
+ /// The success probability for the requested pair.
+ double probability = 1 [json_name = "probability"];
- /// Whether the last payment attempt through this pair was successful.
- bool last_attempt_successful = 6 [json_name = "last_attempt_successful"];
+ /// The historical data for the requested pair.
+ PairData history = 2 [json_name = "history"];
}
message BuildRouteRequest {
@@ -397,7 +474,7 @@
The channel id of the channel that must be taken to the first hop. If zero,
any channel may be used.
*/
- uint64 outgoing_chan_id = 3;
+ uint64 outgoing_chan_id = 3 [jstype = JS_STRING];
/**
A list of hops that defines the route. This does not include the source hop
@@ -454,6 +531,12 @@
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.
diff -Naur proto/0.8.0-beta/signrpc/signer.proto proto/0.9.0-beta/signrpc/signer.proto
--- proto/0.8.0-beta/signrpc/signer.proto 2019-10-18 09:43:05.000000000 +0200
+++ proto/0.9.0-beta/signrpc/signer.proto 2020-02-04 11:35:07.000000000 +0100
@@ -13,17 +13,17 @@
}
message KeyDescriptor {
- /**
- The raw bytes of the key being identified. Either this or the KeyLocator
- must be specified.
- */
- bytes raw_key_bytes = 1;
-
- /**
- The key locator that identifies which key to use for signing. Either this
- or the raw bytes of the target key must be specified.
- */
- KeyLocator key_loc = 2;
+ /**
+ The raw bytes of the key being identified. Either this or the KeyLocator
+ must be specified.
+ */
+ bytes raw_key_bytes = 1;
+
+ /**
+ The key locator that identifies which key to use for signing. Either this
+ or the raw bytes of the target key must be specified.
+ */
+ KeyLocator key_loc = 2;
}
message TxOut {
@@ -119,6 +119,54 @@
repeated InputScript input_scripts = 1;
}
+message SignMessageReq {
+ /// The message to be signed.
+ bytes msg = 1;
+
+ /// The key locator that identifies which key to use for signing.
+ KeyLocator key_loc = 2;
+}
+message SignMessageResp {
+ /**
+ The signature for the given message in the fixed-size LN wire format.
+ */
+ bytes signature = 1;
+}
+
+message VerifyMessageReq {
+ /// The message over which the signature is to be verified.
+ bytes msg = 1;
+
+ /**
+ The fixed-size LN wire encoded signature to be verified over the given
+ message.
+ */
+ bytes signature = 2;
+
+ /// The public key the signature has to be valid for.
+ bytes pubkey = 3;
+}
+message VerifyMessageResp {
+ /// Whether the signature was valid over the given message.
+ bool valid = 1;
+}
+
+message SharedKeyRequest {
+ // The ephemeral public key to use for the DH key derivation.
+ bytes ephemeral_pubkey = 1;
+
+ /**
+ The optional key locator of the local key that should be used. If this
+ parameter is not set then the node's identity private key will be used.
+ */
+ KeyLocator key_loc = 2;
+}
+
+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
@@ -130,7 +178,7 @@
If we are unable to sign using the specified keys, then an error will be
returned.
*/
- rpc SignOutputRaw(SignReq) returns (SignResp);
+ rpc SignOutputRaw (SignReq) returns (SignResp);
/**
ComputeInputScript generates a complete InputIndex for the passed
@@ -144,5 +192,34 @@
in the TxOut field, the value in that same field, and finally the input
index.
*/
- rpc ComputeInputScript(SignReq) returns (InputScriptResp);
+ 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);
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment