340 lines
10 KiB
Protocol Buffer
340 lines
10 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
import "rpc.proto";
|
|
|
|
package routerrpc;
|
|
|
|
option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
|
|
|
|
message PaymentRequest {
|
|
/// The identity pubkey of the payment recipient
|
|
bytes dest = 1;
|
|
|
|
/// Number of satoshis to send.
|
|
int64 amt = 2;
|
|
|
|
/// The hash to use within the payment's HTLC
|
|
bytes payment_hash = 3;
|
|
|
|
/**
|
|
The CLTV delta from the current height that should be used to set the
|
|
timelock for the final hop.
|
|
*/
|
|
int32 final_cltv_delta = 4;
|
|
|
|
/**
|
|
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. The amount in the payment request may be zero. In
|
|
that case it is required to set the amt field as well. If no payment request
|
|
is specified, the following fields are required: dest, amt and payment_hash.
|
|
*/
|
|
string payment_request = 5;
|
|
|
|
/**
|
|
An upper limit on the amount of time we should spend when attempting to
|
|
fulfill the payment. This is expressed in seconds. If we cannot make a
|
|
successful payment within this time frame, an error will be returned.
|
|
This field must be non-zero.
|
|
*/
|
|
int32 timeout_seconds = 6;
|
|
|
|
/**
|
|
The maximum number of satoshis 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.
|
|
*/
|
|
int64 fee_limit_sat = 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 = 8;
|
|
|
|
/**
|
|
An optional maximum total time lock for the route. If zero, there is no
|
|
maximum enforced.
|
|
*/
|
|
int32 cltv_limit = 9;
|
|
}
|
|
|
|
message PaymentResponse {
|
|
/**
|
|
The payment hash that we paid to. Provided so callers are able to map
|
|
responses (which may be streaming) back to their original requests.
|
|
*/
|
|
bytes pay_hash = 1;
|
|
|
|
/**
|
|
The pre-image of the payment successfully completed.
|
|
*/
|
|
bytes pre_image = 2;
|
|
|
|
/**
|
|
If not an empty string, then a string representation of the payment error.
|
|
*/
|
|
string payment_err = 3;
|
|
}
|
|
|
|
message RouteFeeRequest {
|
|
/**
|
|
The destination once wishes to obtain a routing fee quote to.
|
|
*/
|
|
bytes dest = 1;
|
|
|
|
/**
|
|
The amount one wishes to send to the target destination.
|
|
*/
|
|
int64 amt_sat = 2;
|
|
}
|
|
|
|
message RouteFeeResponse {
|
|
/**
|
|
A lower bound of the estimated fee to the target destination within the
|
|
network, expressed in milli-satoshis.
|
|
*/
|
|
int64 routing_fee_msat = 1;
|
|
|
|
/**
|
|
An estimate of the worst case time delay that can occur. Note that callers
|
|
will still need to factor in the final CLTV delta of the last hop into this
|
|
value.
|
|
*/
|
|
int64 time_lock_delay = 2;
|
|
}
|
|
|
|
message SendToRouteRequest {
|
|
/// The payment hash to use for the HTLC.
|
|
bytes payment_hash = 1;
|
|
|
|
/// Route that should be used to attempt to complete the payment.
|
|
lnrpc.Route route = 2;
|
|
}
|
|
|
|
message SendToRouteResponse {
|
|
/// The preimage obtained by making the payment.
|
|
bytes preimage = 1;
|
|
|
|
/// The failure message in case the payment failed.
|
|
Failure failure = 2;
|
|
}
|
|
|
|
message Failure {
|
|
enum FailureCode {
|
|
/**
|
|
The numbers assigned in this enumeration match the failure codes as
|
|
defined in BOLT #4. Because protobuf 3 requires enums to start with 0,
|
|
a RESERVED value is added.
|
|
*/
|
|
RESERVED = 0;
|
|
|
|
UNKNOWN_PAYMENT_HASH = 1;
|
|
INCORRECT_PAYMENT_AMOUNT = 2;
|
|
FINAL_INCORRECT_CLTV_EXPIRY = 3;
|
|
FINAL_INCORRECT_HTLC_AMOUNT = 4;
|
|
FINAL_EXPIRY_TOO_SOON = 5;
|
|
INVALID_REALM = 6;
|
|
EXPIRY_TOO_SOON = 7;
|
|
INVALID_ONION_VERSION = 8;
|
|
INVALID_ONION_HMAC = 9;
|
|
INVALID_ONION_KEY = 10;
|
|
AMOUNT_BELOW_MINIMUM = 11;
|
|
FEE_INSUFFICIENT = 12;
|
|
INCORRECT_CLTV_EXPIRY = 13;
|
|
CHANNEL_DISABLED = 14;
|
|
TEMPORARY_CHANNEL_FAILURE = 15;
|
|
REQUIRED_NODE_FEATURE_MISSING = 16;
|
|
REQUIRED_CHANNEL_FEATURE_MISSING = 17;
|
|
UNKNOWN_NEXT_PEER = 18;
|
|
TEMPORARY_NODE_FAILURE = 19;
|
|
PERMANENT_NODE_FAILURE = 20;
|
|
PERMANENT_CHANNEL_FAILURE = 21;
|
|
}
|
|
|
|
/// Failure code as defined in the Lightning spec
|
|
FailureCode code = 1;
|
|
|
|
/**
|
|
The node pubkey of the intermediate or final node that generated the failure
|
|
message.
|
|
**/
|
|
bytes failure_source_pubkey = 2;
|
|
|
|
/// An optional channel update message.
|
|
ChannelUpdate channel_update = 3;
|
|
|
|
/// A failure type-dependent htlc value.
|
|
uint64 htlc_msat = 4;
|
|
|
|
/// The sha256 sum of the onion payload.
|
|
bytes onion_sha_256 = 5;
|
|
|
|
/// A failure type-dependent cltv expiry value.
|
|
uint32 cltv_expiry = 6;
|
|
|
|
/// A failure type-dependent flags value.
|
|
uint32 flags = 7;
|
|
}
|
|
|
|
|
|
message ChannelUpdate {
|
|
/**
|
|
The signature that validates the announced data and proves the ownership
|
|
of node id.
|
|
*/
|
|
bytes signature = 1;
|
|
|
|
/**
|
|
The target chain that this channel was opened within. This value
|
|
should be the genesis hash of the target chain. Along with the short
|
|
channel ID, this uniquely identifies the channel globally in a
|
|
blockchain.
|
|
*/
|
|
bytes chain_hash = 2;
|
|
|
|
/**
|
|
The unique description of the funding transaction.
|
|
*/
|
|
uint64 chan_id = 3;
|
|
|
|
/**
|
|
A timestamp that allows ordering in the case of multiple announcements.
|
|
We should ignore the message if timestamp is not greater than the
|
|
last-received.
|
|
*/
|
|
uint32 timestamp = 4;
|
|
|
|
/**
|
|
The bitfield that describes whether optional fields are present in this
|
|
update. Currently, the least-significant bit must be set to 1 if the
|
|
optional field MaxHtlc is present.
|
|
*/
|
|
uint32 message_flags = 10;
|
|
|
|
/**
|
|
The bitfield that describes additional meta-data concerning how the
|
|
update is to be interpreted. Currently, the least-significant bit must be
|
|
set to 0 if the creating node corresponds to the first node in the
|
|
previously sent channel announcement and 1 otherwise. If the second bit
|
|
is set, then the channel is set to be disabled.
|
|
*/
|
|
uint32 channel_flags = 5;
|
|
|
|
/**
|
|
The minimum number of blocks this node requires to be added to the expiry
|
|
of HTLCs. This is a security parameter determined by the node operator.
|
|
This value represents the required gap between the time locks of the
|
|
incoming and outgoing HTLC's set to this node.
|
|
*/
|
|
uint32 time_lock_delta = 6;
|
|
|
|
/**
|
|
The minimum HTLC value which will be accepted.
|
|
*/
|
|
uint64 htlc_minimum_msat = 7;
|
|
|
|
/**
|
|
The base fee that must be used for incoming HTLC's to this particular
|
|
channel. This value will be tacked onto the required for a payment
|
|
independent of the size of the payment.
|
|
*/
|
|
uint32 base_fee = 8;
|
|
|
|
/**
|
|
The fee rate that will be charged per millionth of a satoshi.
|
|
*/
|
|
uint32 fee_rate = 9;
|
|
|
|
/**
|
|
The maximum HTLC value which will be accepted.
|
|
*/
|
|
uint64 htlc_maximum_msat = 11;
|
|
|
|
/**
|
|
The set of data that was appended to this message, some of which we may
|
|
not actually know how to iterate or parse. By holding onto this data, we
|
|
ensure that we're able to properly validate the set of signatures that
|
|
cover these new fields, and ensure we're able to make upgrades to the
|
|
network in a forwards compatible manner.
|
|
*/
|
|
bytes extra_opaque_data = 12;
|
|
}
|
|
message ResetMissionControlRequest{}
|
|
|
|
message ResetMissionControlResponse{}
|
|
|
|
message QueryMissionControlRequest {}
|
|
|
|
/// QueryMissionControlResponse contains mission control state per node.
|
|
message QueryMissionControlResponse {
|
|
repeated NodeHistory nodes = 1;
|
|
}
|
|
|
|
/// NodeHistory contains the mission control state for a particular node.
|
|
message NodeHistory {
|
|
/// Node pubkey
|
|
bytes pubkey = 1 [json_name = "pubkey"];
|
|
|
|
/// Time stamp of last failure. Set to zero if no failure happened yet.
|
|
int64 last_fail_time = 2 [json_name = "last_fail_time"];
|
|
|
|
/// Estimation of success probability for channels not in the channel array.
|
|
float other_chan_success_prob = 3 [json_name = "other_chan_success_prob"];
|
|
|
|
/// Historical information of particular channels.
|
|
repeated ChannelHistory channels = 4 [json_name = "channels"];
|
|
}
|
|
|
|
/// NodeHistory contains the mission control state for a particular channel.
|
|
message ChannelHistory {
|
|
/// Short channel id
|
|
uint64 channel_id = 1 [json_name = "channel_id"];
|
|
|
|
/// Time stamp of last failure.
|
|
int64 last_fail_time = 2 [json_name = "last_fail_time"];
|
|
|
|
/// Minimum penalization amount.
|
|
int64 min_penalize_amt_sat = 3 [json_name = "min_penalize_amt_sat"];
|
|
|
|
/// Estimation of success probability for this channel.
|
|
float success_prob = 4 [json_name = "success_prob"];
|
|
}
|
|
|
|
service Router {
|
|
/**
|
|
SendPayment attempts to route a payment described by the passed
|
|
PaymentRequest to the final destination. If we are unable to route the
|
|
payment, or cannot find a route that satisfies the constraints in the
|
|
PaymentRequest, then an error will be returned. Otherwise, the payment
|
|
pre-image, along with the final route will be returned.
|
|
*/
|
|
rpc SendPayment(PaymentRequest) returns (PaymentResponse);
|
|
|
|
/**
|
|
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);
|
|
}
|