lnd/lnrpc/routerrpc/router.proto

syntax = "proto3";

package routerrpc;

import "lightning.proto";

option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc";

/*
 * Comments in this file will be directly parsed into the API
 * Documentation as descriptions of the associated method, message, or field.
 * These descriptions should go right above the definition of the object, and
 * can be in either block or // comment format.
 *
 * An RPC method can be matched to an lncli command by placing a line in the
 * beginning of the description in exactly the following format:
 * lncli: `methodname`
 *
 * Failure to specify the exact name of the command will cause documentation
 * generation to fail.
 *
 * More information on how exactly the gRPC documentation is generated from
 * this proto file can be found here:
 * https://github.com/lightninglabs/lightning-api
 */

// Router is a service that offers advanced interaction with the router
// subsystem of the daemon.
service Router {
    /*
    SendPaymentV2 attempts to route a payment described by the passed
    PaymentRequest to the final destination. The call returns a stream of
    payment updates. When using this RPC, make sure to set a fee limit, as the
    default routing fee limit is 0 sats. Without a non-zero fee limit only
    routes without fees will be attempted which often fails with
    FAILURE_REASON_NO_ROUTE.
    */
    rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment);

    /* lncli: `trackpayment`
    TrackPaymentV2 returns an update stream for the payment identified by the
    payment hash.
    */
    rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment);

    /*
    TrackPayments returns an update stream for every payment that is not in a
    terminal state. Note that if payments are in-flight while starting a new
    subscription, the start of the payment stream could produce out-of-order
    and/or duplicate events. In order to get updates for every in-flight
    payment attempt make sure to subscribe to this method before initiating any
    payments.
    */
    rpc TrackPayments (TrackPaymentsRequest) returns (stream lnrpc.Payment);

    /*
    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);

    /*
    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.
    */
    rpc SendToRoute (SendToRouteRequest) returns (SendToRouteResponse) {
        option deprecated = true;
    }

    /*
    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 SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt);

    /* lncli: `resetmc`
    ResetMissionControl clears all mission control state and starts with a clean
    slate.
    */
    rpc ResetMissionControl (ResetMissionControlRequest)
        returns (ResetMissionControlResponse);

    /* lncli: `querymc`
    QueryMissionControl exposes the internal mission control state to callers.
    It is a development feature.
    */
    rpc QueryMissionControl (QueryMissionControlRequest)
        returns (QueryMissionControlResponse);

    /* lncli: `importmc`
    XImportMissionControl is an experimental API that imports the state provided
    to the internal mission control's state, using all results which are more
    recent than our existing values. These values will only be imported
    in-memory, and will not be persisted across restarts.
    */
    rpc XImportMissionControl (XImportMissionControlRequest)
        returns (XImportMissionControlResponse);

    /* lncli: `getmccfg`
    GetMissionControlConfig returns mission control's current config.
    */
    rpc GetMissionControlConfig (GetMissionControlConfigRequest)
        returns (GetMissionControlConfigResponse);

    /* lncli: `setmccfg`
    SetMissionControlConfig will set mission control's config, if the config
    provided is valid.
    */
    rpc SetMissionControlConfig (SetMissionControlConfigRequest)
        returns (SetMissionControlConfigResponse);

    /* lncli: `queryprob`
    Deprecated. QueryProbability returns the current success probability
    estimate for a given node pair and amount. The call returns a zero success
    probability if no channel is available or if the amount violates min/max
    HTLC constraints.
    */
    rpc QueryProbability (QueryProbabilityRequest)
        returns (QueryProbabilityResponse);

    /* lncli: `buildroute`
    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.
    Note that LND will use its default final_cltv_delta if no value is supplied.
    Make sure to add the correct final_cltv_delta depending on the invoice
    restriction. Moreover the caller has to make sure to provide the
    payment_addr if the route is paying an invoice which signaled it.
    */
    rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse);

    /*
    SubscribeHtlcEvents creates a uni-directional stream from the server to
    the client which delivers a stream of htlc events.
    */
    rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest)
        returns (stream HtlcEvent);

    /*
    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 SendPayment (SendPaymentRequest) returns (stream PaymentStatus) {
        option deprecated = true;
    }

    /*
    Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for
    the payment identified by the payment hash.
    */
    rpc TrackPayment (TrackPaymentRequest) returns (stream PaymentStatus) {
        option deprecated = true;
    }

    /**
    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.
    */
    rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse)
        returns (stream ForwardHtlcInterceptRequest);

    /* lncli: `updatechanstatus`
    UpdateChanStatus attempts to manually set the state of a channel
    (enabled, disabled, or auto). A manual "disable" request will cause the
    channel to stay disabled until a subsequent manual request of either
    "enable" or "auto".
    */
    rpc UpdateChanStatus (UpdateChanStatusRequest)
        returns (UpdateChanStatusResponse);
}

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;

    // 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;

    /*
    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).
    */
    uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true];

    /*
    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;

    /*
    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;

    /*
    Number of millisatoshis to send.

    The fields amt and amt_msat are mutually exclusive.
    */
    int64 amt_msat = 12;

    /*
    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 pubkey of the last hop of the route. If empty, any hop may be used.
    */
    bytes last_hop_pubkey = 14;

    // 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;

    /*
    The maximum number of partial payments that may be use to complete the full
    amount.
    */
    uint32 max_parts = 17;

    /*
    If set, only the final payment update is streamed back. Intermediate updates
    that show which htlcs are still in flight are suppressed.
    */
    bool no_inflight_updates = 18;

    /*
    The channel ids of the channels are allowed for the first hop. If empty,
    any channel may be used.
    */
    repeated uint64 outgoing_chan_ids = 19;

    /*
    An optional payment addr to be included within the last hop of the route.
    This is also called payment secret in specifications (e.g. BOLT 11).
    */
    bytes payment_addr = 20;

    /*
    The largest payment split that should be attempted when making a payment if
    splitting is necessary. Setting this value will effectively cause lnd to
    split more aggressively, vs only when it thinks it needs to. Note that this
    value is in milli-satoshis.
    */
    uint64 max_shard_size_msat = 21;

    /*
    If set, an AMP-payment will be attempted.
    */
    bool amp = 22;

    /*
    The time preference for this payment. Set to -1 to optimize for fees
    only, to 1 to optimize for reliability only or a value inbetween for a mix.
    */
    double time_pref = 23;
}

message TrackPaymentRequest {
    // The hash of the payment to look up.
    bytes payment_hash = 1;

    /*
    If set, only the final payment update is streamed back. Intermediate updates
    that show which htlcs are still in flight are suppressed.
    */
    bool no_inflight_updates = 2;
}

message TrackPaymentsRequest {
    /*
    If set, only the final payment updates are streamed back. Intermediate
    updates that show which htlcs are still in flight are suppressed.
    */
    bool no_inflight_updates = 1;
}

message RouteFeeRequest {
    /*
    The destination one wishes to obtain a routing fee quote to. If set, this
    parameter requires the amt_sat parameter also to be set. This parameter
    combination triggers a graph based routing fee estimation as opposed to a
    payment probe based estimate in case a payment request is provided. The
    graph based estimation is an algorithm that is executed on the in memory
    graph. Hence its runtime is significantly shorter than a payment probe
    estimation that sends out actual payments to the network.
    */
    bytes dest = 1;

    /*
    The amount one wishes to send to the target destination. It is only to be
    used in combination with the dest parameter.
    */
    int64 amt_sat = 2;

    /*
    A payment request of the target node that the route fee request is intended
    for. Its parameters are input to probe payments that estimate routing fees.
    The timeout parameter can be specified to set a maximum time on the probing
    attempt. Cannot be used in combination with dest and amt_sat.
    */
    string payment_request = 3;

    /*
    A user preference of how long a probe payment should maximally be allowed to
    take, denoted in seconds. The probing payment loop is aborted if this
    timeout is reached. Note that the probing process itself can take longer
    than the timeout if the HTLC becomes delayed or stuck. Canceling the context
    of this call will not cancel the payment loop, the duration is only
    controlled by the timeout parameter.
    */
    uint32 timeout = 4;
}

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;

    /*
    An indication whether a probing payment succeeded or whether and why it
    failed. FAILURE_REASON_NONE indicates success.
    */
    lnrpc.PaymentFailureReason failure_reason = 5;
}

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;

    /*
    Whether the payment should be marked as failed when a temporary error is
    returned from the given route. Set it to true so the payment won't be
    failed unless a terminal error is occurred, such as payment timeout, no
    routes, incorrect payment details, or insufficient funds.
    */
    bool skip_temp_err = 3;
}

message SendToRouteResponse {
    // The preimage obtained by making the payment.
    bytes preimage = 1;

    // The failure message in case the payment failed.
    lnrpc.Failure failure = 2;
}

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;
}

message XImportMissionControlRequest {
    // Node pair-level mission control state to be imported.
    repeated PairHistory pairs = 1;

    // Whether to force override MC pair history. Note that even with force
    // override the failure pair is imported before the success pair and both
    // still clamp existing failure/success amounts.
    bool force = 2;
}

message XImportMissionControlResponse {
}

// PairHistory contains the mission control state for a particular node pair.
message PairHistory {
    // The source node pubkey of the pair.
    bytes node_from = 1;

    // The destination node pubkey of the pair.
    bytes node_to = 2;

    reserved 3, 4, 5, 6;

    PairData history = 7;
}

message PairData {
    // Time of last failure.
    int64 fail_time = 1;

    /*
    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;

    /*
    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;

    reserved 3;

    // Time of last success.
    int64 success_time = 5;

    // Highest amount that we could successfully forward rounded to whole sats.
    int64 success_amt_sat = 6;

    // Highest amount that we could successfully forward in millisats.
    int64 success_amt_msat = 7;
}

message GetMissionControlConfigRequest {
}

message GetMissionControlConfigResponse {
    /*
    Mission control's currently active config.
    */
    MissionControlConfig config = 1;
}

message SetMissionControlConfigRequest {
    /*
    The config to set for mission control. Note that all values *must* be set,
    because the full config will be applied.
    */
    MissionControlConfig config = 1;
}

message SetMissionControlConfigResponse {
}

message MissionControlConfig {
    /*
    Deprecated, use AprioriParameters. The amount of time mission control will
    take to restore a penalized node or channel back to 50% success probability,
    expressed in seconds. Setting this value to a higher value will penalize
    failures for longer, making mission control less likely to route through
    nodes and channels that we have previously recorded failures for.
    */
    uint64 half_life_seconds = 1 [deprecated = true];

    /*
    Deprecated, use AprioriParameters. The probability of success mission
    control should assign to hop in a route where it has no other information
    available. Higher values will make mission control more willing to try hops
    that we have no information about, lower values will discourage trying these
    hops.
    */
    float hop_probability = 2 [deprecated = true];

    /*
    Deprecated, use AprioriParameters. The importance that mission control
    should place on historical results, expressed as a value in [0;1]. Setting
    this value to 1 will ignore all historical payments and just use the hop
    probability to assess the probability of success for each hop. A zero value
    ignores hop probability completely and relies entirely on historical
    results, unless none are available.
    */
    float weight = 3 [deprecated = true];

    /*
    The maximum number of payment results that mission control will store.
    */
    uint32 maximum_payment_results = 4;

    /*
    The minimum time that must have passed since the previously recorded failure
    before we raise the failure amount.
    */
    uint64 minimum_failure_relax_interval = 5;

    enum ProbabilityModel {
        APRIORI = 0;
        BIMODAL = 1;
    }

    /*
    ProbabilityModel defines which probability estimator should be used in
    pathfinding. Note that the bimodal estimator is experimental.
    */
    ProbabilityModel model = 6;

    /*
    EstimatorConfig is populated dependent on the estimator type.
    */
    oneof EstimatorConfig {
        AprioriParameters apriori = 7;
        BimodalParameters bimodal = 8;
    }
}

message BimodalParameters {
    /*
    NodeWeight defines how strongly other previous forwardings on channels of a
    router should be taken into account when computing a channel's probability
    to route. The allowed values are in the range [0, 1], where a value of 0
    means that only direct information about a channel is taken into account.
    */
    double node_weight = 1;

    /*
    ScaleMsat describes the scale over which channels statistically have some
    liquidity left. The value determines how quickly the bimodal distribution
    drops off from the edges of a channel. A larger value (compared to typical
    channel capacities) means that the drop off is slow and that channel
    balances are distributed more uniformly. A small value leads to the
    assumption of very unbalanced channels.
    */
    uint64 scale_msat = 2;

    /*
    DecayTime describes the information decay of knowledge about previous
    successes and failures in channels. The smaller the decay time, the quicker
    we forget about past forwardings.
    */
    uint64 decay_time = 3;
}

message AprioriParameters {
    /*
    The amount of time mission control will take to restore a penalized node
    or channel back to 50% success probability, expressed in seconds. Setting
    this value to a higher value will penalize failures for longer, making
    mission control less likely to route through nodes and channels that we
    have previously recorded failures for.
    */
    uint64 half_life_seconds = 1;

    /*
    The probability of success mission control should assign to hop in a route
    where it has no other information available. Higher values will make mission
    control more willing to try hops that we have no information about, lower
    values will discourage trying these hops.
    */
    double hop_probability = 2;

    /*
    The importance that mission control should place on historical results,
    expressed as a value in [0;1]. Setting this value to 1 will ignore all
    historical payments and just use the hop probability to assess the
    probability of success for each hop. A zero value ignores hop probability
    completely and relies entirely on historical results, unless none are
    available.
    */
    double weight = 3;

    /*
    The fraction of a channel's capacity that we consider to have liquidity. For
    amounts that come close to or exceed the fraction, an additional penalty is
    applied. A value of 1.0 disables the capacity factor. Allowed values are in
    [0.75, 1.0].
    */
    double capacity_fraction = 4;
}

message QueryProbabilityRequest {
    // The source node pubkey of the pair.
    bytes from_node = 1;

    // The destination node pubkey of the pair.
    bytes to_node = 2;

    // The amount for which to calculate a probability.
    int64 amt_msat = 3;
}

message QueryProbabilityResponse {
    // The success probability for the requested pair.
    double probability = 1;

    // The historical data for the requested pair.
    PairData history = 2;
}

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;

    /*
    An optional payment addr to be included within the last hop of the route.
    This is also called payment secret in specifications (e.g. BOLT 11).
    */
    bytes payment_addr = 5;
}

message BuildRouteResponse {
    /*
    Fully specified route that can be used to execute the payment.
    */
    lnrpc.Route route = 1;
}

message SubscribeHtlcEventsRequest {
}

/*
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]
*/
message HtlcEvent {
    /*
    The short channel id that the incoming htlc arrived at our node on. This
    value is zero for sends.
    */
    uint64 incoming_channel_id = 1;

    /*
    The short channel id that the outgoing htlc left our node on. This value
    is zero for receives.
    */
    uint64 outgoing_channel_id = 2;

    /*
    Incoming id is the index of the incoming htlc in the incoming channel.
    This value is zero for sends.
    */
    uint64 incoming_htlc_id = 3;

    /*
    Outgoing id is the index of the outgoing htlc in the outgoing channel.
    This value is zero for receives.
    */
    uint64 outgoing_htlc_id = 4;

    /*
    The time in unix nanoseconds that the event occurred.
    */
    uint64 timestamp_ns = 5;

    enum EventType {
        UNKNOWN = 0;
        SEND = 1;
        RECEIVE = 2;
        FORWARD = 3;
    }

    /*
    The event type indicates whether the htlc was part of a send, receive or
    forward.
    */
    EventType event_type = 6;

    oneof event {
        ForwardEvent forward_event = 7;
        ForwardFailEvent forward_fail_event = 8;
        SettleEvent settle_event = 9;
        LinkFailEvent link_fail_event = 10;
        SubscribedEvent subscribed_event = 11;
        FinalHtlcEvent final_htlc_event = 12;
    }
}

message HtlcInfo {
    // The timelock on the incoming htlc.
    uint32 incoming_timelock = 1;

    // The timelock on the outgoing htlc.
    uint32 outgoing_timelock = 2;

    // The amount of the incoming htlc.
    uint64 incoming_amt_msat = 3;

    // The amount of the outgoing htlc.
    uint64 outgoing_amt_msat = 4;
}

message ForwardEvent {
    // Info contains details about the htlc that was forwarded.
    HtlcInfo info = 1;
}

message ForwardFailEvent {
}

message SettleEvent {
    // The revealed preimage.
    bytes preimage = 1;
}

message FinalHtlcEvent {
    bool settled = 1;
    bool offchain = 2;
}

message SubscribedEvent {
}

message LinkFailEvent {
    // Info contains details about the htlc that we failed.
    HtlcInfo info = 1;

    // FailureCode is the BOLT error code for the failure.
    lnrpc.Failure.FailureCode wire_failure = 2;

    /*
    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.
    */
    FailureDetail failure_detail = 3;

    // A string representation of the link failure.
    string failure_string = 4;
}

enum FailureDetail {
    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;
}

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 occurred.
    */
    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;

    reserved 3;

    /*
    The HTLCs made in attempt to settle the payment [EXPERIMENTAL].
    */
    repeated lnrpc.HTLCAttempt htlcs = 4;
}

message CircuitKey {
    /// The id of the channel that the is part of this circuit.
    uint64 chan_id = 1;

    /// The index of the incoming htlc in the incoming channel.
    uint64 htlc_id = 2;
}

message ForwardHtlcInterceptRequest {
    /*
    The key of this forwarded htlc. It defines the incoming channel id and
    the index in this channel.
    */
    CircuitKey incoming_circuit_key = 1;

    // The incoming htlc amount.
    uint64 incoming_amount_msat = 5;

    // The incoming htlc expiry.
    uint32 incoming_expiry = 6;

    /*
    The htlc payment hash. This value is not guaranteed to be unique per
    request.
    */
    bytes payment_hash = 2;

    // 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_requested_chan_id = 7;

    // The outgoing htlc amount.
    uint64 outgoing_amount_msat = 3;

    // The outgoing htlc expiry.
    uint32 outgoing_expiry = 4;

    // Any custom records that were present in the payload.
    map<uint64, bytes> custom_records = 8;

    // The onion blob for the next hop
    bytes onion_blob = 9;

    // The block height at which this htlc will be auto-failed to prevent the
    // channel from force-closing.
    int32 auto_fail_height = 10;
}

/**
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.
*/
message ForwardHtlcInterceptResponse {
    /**
    The key of this forwarded htlc. It defines the incoming channel id and
    the index in this channel.
    */
    CircuitKey incoming_circuit_key = 1;

    // The resolve action for this intercepted htlc.
    ResolveHoldForwardAction action = 2;

    // The preimage in case the resolve action is Settle.
    bytes preimage = 3;

    // Encrypted failure message in case the resolve action is Fail.
    //
    // If failure_message is specified, the failure_code field must be set
    // to zero.
    bytes failure_message = 4;

    // Return the specified failure code in case the resolve action is Fail. The
    // message data fields are populated automatically.
    //
    // If a non-zero failure_code is specified, failure_message must not be set.
    //
    // For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the
    // default value for this field.
    lnrpc.Failure.FailureCode failure_code = 5;
}

enum ResolveHoldForwardAction {
    SETTLE = 0;
    FAIL = 1;
    RESUME = 2;
}

message UpdateChanStatusRequest {
    lnrpc.ChannelPoint chan_point = 1;

    ChanStatusAction action = 2;
}

enum ChanStatusAction {
    ENABLE = 0;
    DISABLE = 1;
    AUTO = 2;
}

message UpdateChanStatusResponse {
}