package routerrpc

Get desktop application:
View/edit binary Protocol Buffers messages

Router is a service that offers advanced interaction with the router subsystem of the daemon.

• rpc SendPaymentV2 (SendPaymentRequest, stream lnrpc.Payment)

  lndrouter.proto:17

  SendPaymentV2 attempts to route a payment described by the passed PaymentRequest to the final destination. The call returns a stream of payment updates.

• rpc TrackPaymentV2 (TrackPaymentRequest, stream lnrpc.Payment)

  lndrouter.proto:23

  TrackPaymentV2 returns an update stream for the payment identified by the payment hash.

• rpc EstimateRouteFee (RouteFeeRequest, RouteFeeResponse)

  lndrouter.proto:29

  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.

  message RouteFeeRequest

  lndrouter.proto:253

  • bytes dest = 1

    The destination once wishes to obtain a routing fee quote to.

  • int64 amt_sat = 2

    The amount one wishes to send to the target destination.

  message RouteFeeResponse

  lndrouter.proto:265

  • int64 routing_fee_msat = 1

    A lower bound of the estimated fee to the target destination within the network, expressed in milli-satoshis.

  • int64 time_lock_delay = 2

    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.

• rpc SendToRoute (SendToRouteRequest, SendToRouteResponse)

  lndrouter.proto:38

  Deprecated, use SendToRouteV2. 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. It differs from the newer SendToRouteV2 in that it doesn't return the full HTLC information.

  message SendToRouteResponse

  lndrouter.proto:288

  • bytes preimage = 1

    The preimage obtained by making the payment.

  • optional lnrpc.Failure failure = 2

    The failure message in case the payment failed.

• rpc SendToRouteV2 (SendToRouteRequest, lnrpc.HTLCAttempt)

  lndrouter.proto:48

  SendToRouteV2 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 ResetMissionControl (ResetMissionControlRequest, ResetMissionControlResponse)

  lndrouter.proto:54

  ResetMissionControl clears all mission control state and starts with a clean slate.

  message ResetMissionControlRequest

  lndrouter.proto:296

  (message has no fields)

  message ResetMissionControlResponse

  lndrouter.proto:299

  (message has no fields)

• rpc QueryMissionControl (QueryMissionControlRequest, QueryMissionControlResponse)

  lndrouter.proto:61

  QueryMissionControl exposes the internal mission control state to callers. It is a development feature.

  message QueryMissionControlRequest

  lndrouter.proto:302

  (message has no fields)

  message QueryMissionControlResponse

  lndrouter.proto:306

  QueryMissionControlResponse contains mission control state.

  • repeated PairHistory pairs = 2

    Node pair-level mission control state.

• rpc QueryProbability (QueryProbabilityRequest, QueryProbabilityResponse)

  lndrouter.proto:68

  QueryProbability returns the current success probability estimate for a given node pair and amount.

  message QueryProbabilityRequest

  lndrouter.proto:354

  • bytes from_node = 1

    The source node pubkey of the pair.

  • bytes to_node = 2

    The destination node pubkey of the pair.

  • int64 amt_msat = 3

    The amount for which to calculate a probability.

  message QueryProbabilityResponse

  lndrouter.proto:365

  • double probability = 1

    The success probability for the requested pair.

  • optional PairData history = 2

    The historical data for the requested pair.

• rpc BuildRoute (BuildRouteRequest, BuildRouteResponse)

  lndrouter.proto:76

  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.

  message BuildRouteRequest

  lndrouter.proto:373

  • int64 amt_msat = 1

    The amount to send expressed in msat. If set to zero, the minimum routable amount is used.

  • int32 final_cltv_delta = 2

    CLTV delta from the current height that should be used for the timelock of the final hop

  • uint64 outgoing_chan_id = 3

    The channel id of the channel that must be taken to the first hop. If zero, any channel may be used.

  • repeated bytes hop_pubkeys = 4

    A list of hops that defines the route. This does not include the source hop pubkey.

  message BuildRouteResponse

  lndrouter.proto:399

  • optional lnrpc.Route route = 1

    Fully specified route that can be used to execute the payment.

• rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest, stream HtlcEvent)

  lndrouter.proto:82

  SubscribeHtlcEvents creates a uni-directional stream from the server to the client which delivers a stream of htlc events.

  message SubscribeHtlcEventsRequest

  lndrouter.proto:406

  (message has no fields)

  message HtlcEvent

  lndrouter.proto:417

  HtlcEvent contains the htlc event that was processed. These are served on a best-effort basis; events are not persisted, delivery is not guaranteed (in the event of a crash in the switch, forward events may be lost) and some events may be replayed upon restart. Events consumed from this package should be de-duplicated by the htlc's unique combination of incoming and outgoing channel id and htlc id. [EXPERIMENTAL]

  • uint64 incoming_channel_id = 1

    The short channel id that the incoming htlc arrived at our node on. This value is zero for sends.

  • uint64 outgoing_channel_id = 2

    The short channel id that the outgoing htlc left our node on. This value is zero for receives.

  • uint64 incoming_htlc_id = 3

    Incoming id is the index of the incoming htlc in the incoming channel. This value is zero for sends.

  • uint64 outgoing_htlc_id = 4

    Outgoing id is the index of the outgoing htlc in the outgoing channel. This value is zero for receives.

  • uint64 timestamp_ns = 5

    The time in unix nanoseconds that the event occurred.

  • HtlcEvent.EventType event_type = 6

    The event type indicates whether the htlc was part of a send, receive or forward.

  • oneof event

    • ForwardEvent forward_event = 7

    • ForwardFailEvent forward_fail_event = 8

    • SettleEvent settle_event = 9

    • LinkFailEvent link_fail_event = 10

• rpc SendPayment (SendPaymentRequest, stream PaymentStatus)

  lndrouter.proto:90

  Deprecated, use SendPaymentV2. 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 TrackPayment (TrackPaymentRequest, stream PaymentStatus)

  lndrouter.proto:98

  Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for the payment identified by the payment hash.

• rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse, stream ForwardHtlcInterceptRequest)

  lndrouter.proto:109

  * HtlcInterceptor dispatches a bi-directional streaming RPC in which Forwarded HTLC requests are sent to the client and the client responds with a boolean that tells LND if this htlc should be intercepted. In case of interception, the htlc can be either settled, cancelled or resumed later by using the ResolveHoldForward endpoint.

  message ForwardHtlcInterceptResponse

  lndrouter.proto:643

  * ForwardHtlcInterceptResponse enables the caller to resolve a previously hold forward. The caller can choose either to: - `Resume`: Execute the default behavior (usually forward). - `Reject`: Fail the htlc backwards. - `Settle`: Settle this htlc with a given preimage.

  • optional CircuitKey incoming_circuit_key = 1

    * The key of this forwarded htlc. It defines the incoming channel id and the index in this channel.

  • ResolveHoldForwardAction action = 2

    The resolve action for this intercepted htlc.

  • bytes preimage = 3

    The preimage in case the resolve action is Settle.

  message ForwardHtlcInterceptRequest

  lndrouter.proto:601

  • optional CircuitKey incoming_circuit_key = 1

    The key of this forwarded htlc. It defines the incoming channel id and the index in this channel.

  • uint64 incoming_amount_msat = 5

    The incoming htlc amount.

  • uint32 incoming_expiry = 6

    The incoming htlc expiry.

  • bytes payment_hash = 2

    The htlc payment hash. This value is not guaranteed to be unique per request.

  • uint64 outgoing_requested_chan_id = 7

    The requested outgoing channel id for this forwarded htlc. Because of non-strict forwarding, this isn't necessarily the channel over which the packet will be forwarded eventually. A different channel to the same peer may be selected as well.

  • uint64 outgoing_amount_msat = 3

    The outgoing htlc amount.

  • uint32 outgoing_expiry = 4

    The outgoing htlc expiry.

  • map<uint64, bytes> custom_records = 8

    Any custom records that were present in the payload.

Used in: ForwardHtlcInterceptRequest, ForwardHtlcInterceptResponse

• uint64 chan_id = 1

  / The id of the channel that the is part of this circuit.

• uint64 htlc_id = 2

  / The index of the incoming htlc in the incoming channel.

Used in: LinkFailEvent

• UNKNOWN = 0

• NO_DETAIL = 1

• ONION_DECODE = 2

• LINK_NOT_ELIGIBLE = 3

• ON_CHAIN_TIMEOUT = 4

• HTLC_EXCEEDS_MAX = 5

• INSUFFICIENT_BALANCE = 6

• INCOMPLETE_FORWARD = 7

• HTLC_ADD_FAILED = 8

• FORWARDS_DISABLED = 9

• INVOICE_CANCELED = 10

• INVOICE_UNDERPAID = 11

• INVOICE_EXPIRY_TOO_SOON = 12

• INVOICE_NOT_OPEN = 13

• MPP_INVOICE_TIMEOUT = 14

• ADDRESS_MISMATCH = 15

• SET_TOTAL_MISMATCH = 16

• SET_TOTAL_TOO_LOW = 17

• SET_OVERPAID = 18

• UNKNOWN_INVOICE = 19

• INVALID_KEYSEND = 20

• MPP_IN_PROGRESS = 21

• CIRCULAR_ROUTE = 22

Used in: HtlcEvent

• optional HtlcInfo info = 1

  Info contains details about the htlc that was forwarded.

Used in: HtlcEvent

(message has no fields)

Used in: HtlcEvent

• UNKNOWN = 0

• SEND = 1

• RECEIVE = 2

• FORWARD = 3

Used in: ForwardEvent, LinkFailEvent

• uint32 incoming_timelock = 1

  The timelock on the incoming htlc.

• uint32 outgoing_timelock = 2

  The timelock on the outgoing htlc.

• uint64 incoming_amt_msat = 3

  The amount of the incoming htlc.

• uint64 outgoing_amt_msat = 4

  The amount of the outgoing htlc.

Used in: HtlcEvent

• optional HtlcInfo info = 1

  Info contains details about the htlc that we failed.

• lnrpc.Failure.FailureCode wire_failure = 2

  FailureCode is the BOLT error code for the failure.

• FailureDetail failure_detail = 3

  FailureDetail provides additional information about the reason for the failure. This detail enriches the information provided by the wire message and may be 'no detail' if the wire message requires no additional metadata.

• string failure_string = 4

  A string representation of the link failure.

Used in: PairHistory, QueryProbabilityResponse

• int64 fail_time = 1

  Time of last failure.

• int64 fail_amt_sat = 2

  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_msat = 4

  Lowest amount that failed to forward in millisats. This may be set to zero if the failure is independent of amount.

• int64 success_time = 5

  Time of last success.

• int64 success_amt_sat = 6

  Highest amount that we could successfully forward rounded to whole sats.

• int64 success_amt_msat = 7

  Highest amount that we could successfully forward in millisats.

PairHistory contains the mission control state for a particular node pair.

Used in: QueryMissionControlResponse

• bytes node_from = 1

  The source node pubkey of the pair.

• bytes node_to = 2

  The destination node pubkey of the pair.

• optional PairData history = 7

Used in: PaymentStatus

• IN_FLIGHT = 0

  Payment is still in flight.

• SUCCEEDED = 1

  Payment completed successfully.

• FAILED_TIMEOUT = 2

  There are more routes to try, but the payment timeout was exceeded.

• FAILED_NO_ROUTE = 3

  All possible routes were tried and failed permanently. Or were no routes to the destination at all.

• FAILED_ERROR = 4

  A non-recoverable error has occured.

• FAILED_INCORRECT_PAYMENT_DETAILS = 5

  Payment details incorrect (unknown hash, invalid amt or invalid final cltv delta)

• FAILED_INSUFFICIENT_BALANCE = 6

  Insufficient local balance.

Used as response type in: Router.SendPayment, Router.TrackPayment

• PaymentState state = 1

  Current state the payment is in.

• bytes preimage = 2

  The pre-image of the payment when state is SUCCEEDED.

• repeated lnrpc.HTLCAttempt htlcs = 4

  The HTLCs made in attempt to settle the payment [EXPERIMENTAL].

Used in: ForwardHtlcInterceptResponse

• SETTLE = 0

• FAIL = 1

• RESUME = 2

Used as request type in: Router.SendPayment, Router.SendPaymentV2

• bytes dest = 1

  The identity pubkey of the payment recipient

• int64 amt = 2

  Number of satoshis to send. The fields amt and amt_msat are mutually exclusive.

• int64 amt_msat = 12

  Number of millisatoshis to send. The fields amt and amt_msat are mutually exclusive.

• bytes payment_hash = 3

  The hash to use within the payment's HTLC

• int32 final_cltv_delta = 4

  The CLTV delta from the current height that should be used to set the timelock for the final hop.

• string payment_request = 5

  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.

• int32 timeout_seconds = 6

  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.

• int64 fee_limit_sat = 7

  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_msat = 13

  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.

• uint64 outgoing_chan_id = 8

  Deprecated, use outgoing_chan_ids. The channel id of the channel that must be taken to the first hop. If zero, any channel may be used (unless outgoing_chan_ids are set).

• repeated uint64 outgoing_chan_ids = 19

  The channel ids of the channels are allowed for the first hop. If empty, any channel may be used.

• bytes last_hop_pubkey = 14

  The pubkey of the last hop of the route. If empty, any hop may be used.

• int32 cltv_limit = 9

  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.

• repeated lnrpc.RouteHint route_hints = 10

  Optional route hints to reach the destination through private channels.

• map<uint64, bytes> dest_custom_records = 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. Record types are required to be in the custom range >= 65536. When using REST, the values must be encoded as base64.

• bool allow_self_payment = 15

  If set, circular payments to self are permitted.

• repeated lnrpc.FeatureBit dest_features = 16

  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.

• uint32 max_parts = 17

  The maximum number of partial payments that may be use to complete the full amount.

• bool no_inflight_updates = 18

  If set, only the final payment update is streamed back. Intermediate updates that show which htlcs are still in flight are suppressed.

Used as request type in: Router.SendToRoute, Router.SendToRouteV2

• bytes payment_hash = 1

  The payment hash to use for the HTLC.

• optional lnrpc.Route route = 2

  Route that should be used to attempt to complete the payment.

Used in: HtlcEvent

(message has no fields)

Used as request type in: Router.TrackPayment, Router.TrackPaymentV2

• bytes payment_hash = 1

  The hash of the payment to look up.

• bool no_inflight_updates = 2

  If set, only the final payment update is streamed back. Intermediate updates that show which htlcs are still in flight are suppressed.