0fc401de19
With the introduction of the max CLTV limit parameter, nodes are able to reject HTLCs that exceed it. This should also be applied to path finding, otherwise HTLCs crafted by the same node that exceed it never left the switch. This wasn't a big deal since the previous max CLTV limit was ~5000 blocks. Once it was lowered to 1008, the issue became more apparent. Therefore, all of our path finding attempts now have a restriction of said limit in in order to properly carry out HTLCs to the network.
465 lines
13 KiB
Protocol Buffer
465 lines
13 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.
|
|
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. 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.
|
|
*/
|
|
map<uint64, bytes> dest_tlv = 11;
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
|
|
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;
|
|
}
|
|
|
|
|
|
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;
|
|
|
|
/**
|
|
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;
|
|
|
|
/**
|
|
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 {
|
|
/// Node-level mission control state.
|
|
repeated NodeHistory nodes = 1 [json_name = "nodes"];
|
|
|
|
/// 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"];
|
|
|
|
/// 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 of forwarding towards peers of this node
|
|
for which no specific history is available.
|
|
**/
|
|
float other_success_prob = 3 [json_name = "other_success_prob"];
|
|
|
|
reserved 4;
|
|
}
|
|
|
|
/// 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"];
|
|
|
|
/// Time stamp of last result.
|
|
int64 timestamp = 3 [json_name = "timestamp"];
|
|
|
|
/// Minimum penalization amount (only applies to failed attempts).
|
|
int64 min_penalize_amt_sat = 4 [json_name = "min_penalize_amt_sat"];
|
|
|
|
/// Estimation of success probability for this pair.
|
|
float success_prob = 5 [json_name = "success_prob"];
|
|
|
|
/// Whether the last payment attempt through this pair was successful.
|
|
bool last_attempt_successful = 6 [json_name = "last_attempt_successful"];
|
|
}
|
|
|
|
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;
|
|
|
|
/**
|
|
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);
|
|
|
|
/**
|
|
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);
|
|
}
|