wip

proto/others/invoices.proto

@@ -1,6 +1,6 @@
 syntax = "proto3";
 
-import "rpc.proto";
+import "lightning.proto";
 
 package invoicesrpc;
 
@@ -35,10 +35,17 @@ service Invoices {
     settled, this call will succeed.
     */
     rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp);
+
+    /*
+    LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced
+    using either its payment hash, payment address, or set ID.
+    */
+    rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice);
 }
 
 message CancelInvoiceMsg {
-    // Hash corresponding to the (hold) invoice to cancel.
+    // Hash corresponding to the (hold) invoice to cancel. When using
+    // REST, this field must be encoded as base64.
     bytes payment_hash = 1;
 }
 message CancelInvoiceResp {
@@ -98,11 +105,26 @@ message AddHoldInvoiceRequest {
 
 message AddHoldInvoiceResp {
     /*
-    A bare-bones invoice for a payment within the Lightning Network.  With the
+    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.
     */
     string payment_request = 1;
+
+    /*
+    The "add" index of this invoice. Each newly created invoice will increment
+    this index making it monotonically increasing. Callers to the
+    SubscribeInvoices call can use this to instantly get notified of all added
+    invoices with an add_index greater than this one.
+    */
+    uint64 add_index = 2;
+
+    /*
+    The payment address of the generated invoice. This value should be used
+    in all payments for this invoice as we require it for end to end
+    security.
+    */
+    bytes payment_addr = 3;
 }
 
 message SettleInvoiceMsg {
@@ -117,6 +139,37 @@ message SettleInvoiceResp {
 message SubscribeSingleInvoiceRequest {
     reserved 1;
 
-    // Hash corresponding to the (hold) invoice to subscribe to.
+    // Hash corresponding to the (hold) invoice to subscribe to. When using
+    // REST, this field must be encoded as base64url.
     bytes r_hash = 2;
 }
+
+enum LookupModifier {
+    // The default look up modifier, no look up behavior is changed.
+    DEFAULT = 0;
+
+    /*
+    Indicates that when a look up is done based on a set_id, then only that set
+    of HTLCs related to that set ID should be returned.
+    */
+    HTLC_SET_ONLY = 1;
+
+    /*
+    Indicates that when a look up is done using a payment_addr, then no HTLCs
+    related to the payment_addr should be returned. This is useful when one
+    wants to be able to obtain the set of associated setIDs with a given
+    invoice, then look up the sub-invoices "projected" by that set ID.
+    */
+    HTLC_SET_BLANK = 2;
+}
+
+message LookupInvoiceMsg {
+    oneof invoice_ref {
+        // When using REST, this field must be encoded as base64.
+        bytes payment_hash = 1;
+        bytes payment_addr = 2;
+        bytes set_id = 3;
+    }
+
+    LookupModifier lookup_modifier = 4;
+}

proto/others/router.proto

@@ -1,6 +1,6 @@
 syntax = "proto3";
 
-import "rpc.proto";
+import "lightning.proto";
 
 package routerrpc;
 
@@ -22,6 +22,16 @@ service Router {
     */
     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.
@@ -284,6 +294,12 @@ message SendPaymentRequest {
     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 {
@@ -297,6 +313,14 @@ message TrackPaymentRequest {
     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 once wishes to obtain a routing fee quote to.
@@ -330,6 +354,14 @@ message SendToRouteRequest {
 
     // 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 {
@@ -360,6 +392,11 @@ message QueryMissionControlResponse {
 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 {
@@ -581,6 +618,8 @@ message HtlcEvent {
         ForwardFailEvent forward_fail_event = 8;
         SettleEvent settle_event = 9;
         LinkFailEvent link_fail_event = 10;
+        SubscribedEvent subscribed_event = 11;
+        FinalHtlcEvent final_htlc_event = 12;
     }
 }
 
@@ -607,6 +646,16 @@ message ForwardFailEvent {
 }
 
 message SettleEvent {
+    // The revealed preimage.
+    bytes preimage = 1;
+}
+
+message FinalHtlcEvent {
+    bool settled = 1;
+    bool offchain = 2;
+}
+
+message SubscribedEvent {
 }
 
 message LinkFailEvent {
@@ -676,7 +725,7 @@ enum PaymentState {
     FAILED_NO_ROUTE = 3;
 
     /*
-    A non-recoverable error has occured.
+    A non-recoverable error has occurred.
     */
     FAILED_ERROR = 4;
 
@@ -753,6 +802,10 @@ message ForwardHtlcInterceptRequest {
 
     // 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;
 }
 
 /**
@@ -774,6 +827,21 @@ message ForwardHtlcInterceptResponse {
 
     // 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 {
@@ -795,4 +863,4 @@ enum ChanStatusAction {
 }
 
 message UpdateChanStatusResponse {
-}
+}