546 lines
16 KiB
Protocol Buffer
546 lines
16 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
import "rpc.proto";
|
|
|
|
package routerrpc;
|
|
|
|
option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
|
|
|
|
message SendPaymentRequest {
|
|
/// The identity pubkey of the payment recipient
|
|
bytes dest = 1;
|
|
|
|
/**
|
|
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;
|
|
|
|
/**
|
|
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.
|
|
|
|
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 [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. 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;
|
|
|
|
/**
|
|
Optional route hints to reach the destination through private channels.
|
|
*/
|
|
repeated lnrpc.RouteHint route_hints = 10 [json_name = "route_hints"];
|
|
|
|
/**
|
|
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. 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 = 15;
|
|
|
|
/**
|
|
Features assumed to be supported by the final node. All transitive feature
|
|
dependencies 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 {
|
|
/// The hash of the payment to look up.
|
|
bytes payment_hash = 1;
|
|
}
|
|
|
|
enum PaymentState {
|
|
/**
|
|
Payment is still in flight.
|
|
*/
|
|
IN_FLIGHT = 0;
|
|
|
|
/**
|
|
Payment completed successfully.
|
|
*/
|
|
SUCCEEDED = 1;
|
|
|
|
/**
|
|
There are more routes to try, but the payment timeout was exceeded.
|
|
*/
|
|
FAILED_TIMEOUT = 2;
|
|
|
|
/**
|
|
All possible routes were tried and failed permanently. Or were no
|
|
routes to the destination at all.
|
|
*/
|
|
FAILED_NO_ROUTE = 3;
|
|
|
|
/**
|
|
A non-recoverable error has occured.
|
|
*/
|
|
FAILED_ERROR = 4;
|
|
|
|
/**
|
|
Payment details incorrect (unknown hash, invalid amt or
|
|
invalid final cltv delta)
|
|
*/
|
|
FAILED_INCORRECT_PAYMENT_DETAILS = 5;
|
|
|
|
/**
|
|
Insufficient local balance.
|
|
*/
|
|
FAILED_INSUFFICIENT_BALANCE = 6;
|
|
}
|
|
|
|
|
|
message PaymentStatus {
|
|
/// Current state the payment is in.
|
|
PaymentState state = 1;
|
|
|
|
/**
|
|
The pre-image of the payment when state is SUCCEEDED.
|
|
*/
|
|
bytes preimage = 2;
|
|
|
|
/**
|
|
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;
|
|
}
|
|
|
|
|
|
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;
|
|
|
|
INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS = 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;
|
|
EXPIRY_TOO_FAR = 22;
|
|
MPP_TIMEOUT = 23;
|
|
|
|
/**
|
|
The error source is known, but the failure itself couldn't be decoded.
|
|
*/
|
|
UNKNOWN_FAILURE = 998;
|
|
|
|
/**
|
|
An unreadable failure result is returned if the received failure message
|
|
cannot be decrypted. In that case the error source is unknown.
|
|
*/
|
|
UNREADABLE_FAILURE = 999;
|
|
}
|
|
|
|
/// Failure code as defined in the Lightning spec
|
|
FailureCode code = 1;
|
|
|
|
reserved 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;
|
|
|
|
/**
|
|
The position in the path of the intermediate or final node that generated
|
|
the failure message. Position zero is the sender node.
|
|
**/
|
|
uint32 failure_source_index = 8;
|
|
|
|
/// A failure type-dependent block height.
|
|
uint32 height = 9;
|
|
}
|
|
|
|
|
|
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 [jstype = JS_STRING];
|
|
|
|
/**
|
|
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.
|
|
message QueryMissionControlResponse {
|
|
reserved 1;
|
|
|
|
/// Node pair-level mission control state.
|
|
repeated PairHistory pairs = 2 [json_name = "pairs"];
|
|
}
|
|
|
|
/// 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"];
|
|
|
|
/// 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"];
|
|
|
|
/**
|
|
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 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"];
|
|
}
|
|
|
|
message QueryProbabilityRequest{
|
|
/// The source node pubkey of the pair.
|
|
bytes from_node = 1 [json_name = "from_node"];
|
|
|
|
/// The destination node pubkey of the pair.
|
|
bytes to_node = 2 [json_name = "to_node"];
|
|
|
|
/// The amount for which to calculate a probability.
|
|
int64 amt_msat = 3 [json_name = "amt_msat"];
|
|
}
|
|
|
|
message QueryProbabilityResponse{
|
|
/// The success probability for the requested pair.
|
|
double probability = 1 [json_name = "probability"];
|
|
|
|
/// The historical data for the requested pair.
|
|
PairData history = 2 [json_name = "history"];
|
|
}
|
|
|
|
message BuildRouteRequest {
|
|
/**
|
|
The amount to send expressed in msat. If set to zero, the minimum routable
|
|
amount is used.
|
|
*/
|
|
int64 amt_msat = 1;
|
|
|
|
/**
|
|
CLTV delta from the current height that should be used for the timelock
|
|
of the final hop
|
|
*/
|
|
int32 final_cltv_delta = 2;
|
|
|
|
/**
|
|
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 [jstype = JS_STRING];
|
|
|
|
/**
|
|
A list of hops that defines the route. This does not include the source hop
|
|
pubkey.
|
|
*/
|
|
repeated bytes hop_pubkeys = 4;
|
|
}
|
|
|
|
message BuildRouteResponse {
|
|
/**
|
|
Fully specified route that can be used to execute the payment.
|
|
*/
|
|
lnrpc.Route route = 1;
|
|
}
|
|
|
|
service Router {
|
|
/**
|
|
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);
|
|
|
|
/**
|
|
TrackPayment returns an update stream for the payment identified by the
|
|
payment hash.
|
|
*/
|
|
rpc TrackPayment(TrackPaymentRequest) returns (stream PaymentStatus);
|
|
|
|
|
|
/**
|
|
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);
|
|
}
|