github.com/decred/dcrlnd@v0.7.6/lnrpc/invoicesrpc/invoices.proto (about)

     1  syntax = "proto3";
     2  
     3  import "lightning.proto";
     4  
     5  package invoicesrpc;
     6  
     7  option go_package = "github.com/decred/dcrlnd/lnrpc/invoicesrpc";
     8  
     9  // Invoices is a service that can be used to create, accept, settle and cancel
    10  // invoices.
    11  service Invoices {
    12      /*
    13      SubscribeSingleInvoice returns a uni-directional stream (server -> client)
    14      to notify the client of state transitions of the specified invoice.
    15      Initially the current invoice state is always sent out.
    16      */
    17      rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest)
    18          returns (stream lnrpc.Invoice);
    19  
    20      /*
    21      CancelInvoice cancels a currently open invoice. If the invoice is already
    22      canceled, this call will succeed. If the invoice is already settled, it will
    23      fail.
    24      */
    25      rpc CancelInvoice (CancelInvoiceMsg) returns (CancelInvoiceResp);
    26  
    27      /*
    28      AddHoldInvoice creates a hold invoice. It ties the invoice to the hash
    29      supplied in the request.
    30      */
    31      rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp);
    32  
    33      /*
    34      SettleInvoice settles an accepted invoice. If the invoice is already
    35      settled, this call will succeed.
    36      */
    37      rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp);
    38  
    39      /*
    40      LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced
    41      using either its payment hash, payment address, or set ID.
    42      */
    43      rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice);
    44  }
    45  
    46  message CancelInvoiceMsg {
    47      // Hash corresponding to the (hold) invoice to cancel.
    48      bytes payment_hash = 1;
    49  }
    50  message CancelInvoiceResp {
    51  }
    52  
    53  message AddHoldInvoiceRequest {
    54      /*
    55      An optional memo to attach along with the invoice. Used for record keeping
    56      purposes for the invoice's creator, and will also be set in the description
    57      field of the encoded payment request if the description_hash field is not
    58      being used.
    59      */
    60      string memo = 1;
    61  
    62      // The hash of the preimage
    63      bytes hash = 2;
    64  
    65      /*
    66      The value of this invoice in atoms.
    67  
    68      The fields value and value_m_atoms are mutually exclusive.
    69      */
    70      int64 value = 3;
    71  
    72      /*
    73      The value of this invoice in milliatoms.
    74  
    75      The fields value and value_m_atoms are mutually exclusive.
    76      */
    77      int64 value_m_atoms = 10;
    78  
    79      /*
    80      Hash (SHA-256) of a description of the payment. Used if the description of
    81      payment (memo) is too long to naturally fit within the description field
    82      of an encoded payment request.
    83      */
    84      bytes description_hash = 4;
    85  
    86      // Payment request expiry time in seconds. Default is 3600 (1 hour).
    87      int64 expiry = 5;
    88  
    89      // Fallback on-chain address.
    90      string fallback_addr = 6;
    91  
    92      // Delta to use for the time-lock of the CLTV extended to the final hop.
    93      uint64 cltv_expiry = 7;
    94  
    95      /*
    96      Route hints that can each be individually used to assist in reaching the
    97      invoice's destination.
    98      */
    99      repeated lnrpc.RouteHint route_hints = 8;
   100  
   101      // Whether this invoice should include routing hints for private channels.
   102      bool private = 9;
   103  }
   104  
   105  message AddHoldInvoiceResp {
   106      /*
   107      A bare-bones invoice for a payment within the Lightning Network. With the
   108      details of the invoice, the sender has all the data necessary to send a
   109      payment to the recipient.
   110      */
   111      string payment_request = 1;
   112  
   113      /*
   114      The "add" index of this invoice. Each newly created invoice will increment
   115      this index making it monotonically increasing. Callers to the
   116      SubscribeInvoices call can use this to instantly get notified of all added
   117      invoices with an add_index greater than this one.
   118      */
   119      uint64 add_index = 2;
   120  
   121      /*
   122      The payment address of the generated invoice. This value should be used
   123      in all payments for this invoice as we require it for end to end
   124      security.
   125      */
   126      bytes payment_addr = 3;
   127  }
   128  
   129  message SettleInvoiceMsg {
   130      // Externally discovered pre-image that should be used to settle the hold
   131      // invoice.
   132      bytes preimage = 1;
   133  }
   134  
   135  message SettleInvoiceResp {
   136  }
   137  
   138  message SubscribeSingleInvoiceRequest {
   139      reserved 1;
   140  
   141      // Hash corresponding to the (hold) invoice to subscribe to.
   142      bytes r_hash = 2;
   143  }
   144  
   145  enum LookupModifier {
   146      // The default look up modifier, no look up behavior is changed.
   147      DEFAULT = 0;
   148  
   149      /*
   150      Indicates that when a look up is done based on a set_id, then only that set
   151      of HTLCs related to that set ID should be returned.
   152      */
   153      HTLC_SET_ONLY = 1;
   154  
   155      /*
   156      Indicates that when a look up is done using a payment_addr, then no HTLCs
   157      related to the payment_addr should be returned. This is useful when one
   158      wants to be able to obtain the set of associated setIDs with a given
   159      invoice, then look up the sub-invoices "projected" by that set ID.
   160      */
   161      HTLC_SET_BLANK = 2;
   162  }
   163  
   164  message LookupInvoiceMsg {
   165      oneof invoice_ref {
   166          bytes payment_hash = 1;
   167          bytes payment_addr = 2;
   168          bytes set_id = 3;
   169      }
   170  
   171      LookupModifier lookup_modifier = 4;
   172  }