lnd.xprv/lnrpc/routerrpc/router.proto
2019-05-29 14:07:03 +02:00

272 lines
7.9 KiB
Protocol Buffer

syntax = "proto3";
import "rpc.proto";
package routerrpc;
option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";
message PaymentRequest {
/**
A serialized BOLT-11 payment request that contains all information
required to dispatch the payment. If the pay req is invalid, or expired,
an error will be returned.
*/
string pay_req = 1;
/**
An absolute limit on the highest fee we should pay when looking for a route
to the destination. Routes with fees higher than this will be ignored, if
there are no routes with a fee below this amount, an error will be
returned.
*/
int64 fee_limit_sat = 2;
/**
An absolute limit on the cumulative CLTV value along the route for this
payment. Routes with total CLTV values higher than this will be ignored,
if there are no routes with a CLTV value below this amount, an error will
be returned.
*/
int32 cltv_limit = 3;
/**
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.
*/
int32 timeout_seconds = 4;
/**
The channel id of the channel that must be taken to the first hop. If zero,
any channel may be used.
*/
int64 outgoing_channel_id = 5;
}
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;
}
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);
}