lightning 4.13.0 → 4.14.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Versions
 
-## 4.13.0
+## 4.14.0
+
+- `getPayment`, `subscribeToPastPayment`: Add `pending` for pending payment details
+
+## 4.13.3
 
 - Add `sendMessageToPeer` to send a peer to peer message to a connected peer
 - Add `subscribeToPeerMessages` to listen to messages from connected peers

package/grpc/protos/invoices.proto

@@ -35,6 +35,12 @@ 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 {
@@ -134,4 +140,33 @@ message SubscribeSingleInvoiceRequest {
 
     // Hash corresponding to the (hold) invoice to subscribe to.
     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 {
+        bytes payment_hash = 1;
+        bytes payment_addr = 2;
+        bytes set_id = 3;
+    }
+
+    LookupModifier lookup_modifier = 4;
 }

package/grpc/protos/lightning.proto

@@ -3056,6 +3056,10 @@ message HopHint {
     uint32 cltv_expiry_delta = 5;
 }
 
+message SetID {
+    bytes set_id = 1;
+}
+
 message RouteHint {
     /*
     A list of hop hints that when chained together can assist in reaching a
@@ -3064,6 +3068,20 @@ message RouteHint {
     repeated HopHint hop_hints = 1;
 }
 
+message AMPInvoiceState {
+    // The state the HTLCs associated with this setID are in.
+    InvoiceHTLCState state = 1;
+
+    // The settle index of this HTLC set, if the invoice state is settled.
+    uint64 settle_index = 2;
+
+    // The time this HTLC set was settled expressed in unix epoch.
+    int64 settle_time = 3;
+
+    // The total amount paid for the sub-invoice expressed in milli satoshis.
+    int64 amt_paid_msat = 5;
+}
+
 message Invoice {
     /*
     An optional memo to attach along with the invoice. Used for record keeping
@@ -3209,7 +3227,7 @@ message Invoice {
 
     /*
     The payment address of this invoice. This value will be used in MPP
-    payments, and also for newer invoies that always require the MPP paylaod
+    payments, and also for newer invoices that always require the MPP payload
     for added end-to-end security.
     */
     bytes payment_addr = 26;
@@ -3218,6 +3236,16 @@ message Invoice {
     Signals whether or not this is an AMP invoice.
     */
     bool is_amp = 27;
+
+    /*
+    [EXPERIMENTAL]:
+
+    Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the
+    given set ID. This field is always populated for AMP invoices, and can be
+    used along side LookupInvoice to obtain the HTLC information related to a
+    given sub-invoice.
+    */
+    map<string, AMPInvoiceState> amp_invoice_state = 28;
 }
 
 enum InvoiceHTLCState {
@@ -4147,8 +4175,10 @@ message CheckMacPermResponse {
 
 message RPCMiddlewareRequest {
     /*
-    The unique ID of the intercepted request. Useful for mapping request to
-    response when implementing full duplex message interception.
+    The unique ID of the intercepted original gRPC request. Useful for mapping
+    request to response when implementing full duplex message interception. For
+    streaming requests, this will be the same ID for all incoming and outgoing
+    middleware intercept messages of the _same_ stream.
     */
     uint64 request_id = 1;
 
@@ -4203,6 +4233,16 @@ message RPCMiddlewareRequest {
         */
         RPCMessage response = 6;
     }
+
+    /*
+    The unique message ID of this middleware intercept message. There can be
+    multiple middleware intercept messages per single gRPC request (one for the
+    incoming request and one for the outgoing response) or gRPC stream (one for
+    each incoming message and one for each outgoing response). This message ID
+    must be referenced when responding (accepting/rejecting/modifying) to an
+    intercept message.
+    */
+    uint64 msg_id = 7;
 }
 
 message StreamAuth {
@@ -4242,11 +4282,11 @@ message RPCMessage {
 
 message RPCMiddlewareResponse {
     /*
-    The unique ID of the intercepted request that this response refers to. Must
-    always be set when giving feedback to an intercept but is ignored for the
-    initial registration message.
+    The request message ID this response refers to. Must always be set when
+    giving feedback to an intercept but is ignored for the initial registration
+    message.
     */
-    uint64 request_id = 1;
+    uint64 ref_msg_id = 1;
 
     /*
     The middleware can only send two types of messages to lnd: The initial

package/grpc/protos/signer.proto

@@ -74,14 +74,14 @@ message KeyLocator {
 
 message KeyDescriptor {
     /*
-    The raw bytes of the key being identified. Either this or the KeyLocator
-    must be specified.
+    The raw bytes of the public key in the key pair being identified. Either
+    this or the KeyLocator must be specified.
     */
     bytes raw_key_bytes = 1;
 
     /*
-    The key locator that identifies which key to use for signing. Either this
-    or the raw bytes of the target key must be specified.
+    The key locator that identifies which private key to use for signing.
+    Either this or the raw bytes of the target public key must be specified.
     */
     KeyLocator key_loc = 2;
 }

package/lnd_methods/info/constants.json

@@ -24,6 +24,7 @@
     "4f567577db9d85b6f392f960b3aabddcad3cd02c": "0.13.3-beta",
     "52bb3f33707b81972c67937c7a89addcdf00991c": "0.10.1-beta",
     "596fd90ef310cd7abbf2251edaae9ba4d5f8a689": "0.13.1-beta",
+    "61c34683058f2cc8dc10f49392a0057440d831c4": "0.13.4-beta",
     "725ff104808f49f0a5247bfdb4b6b5da7f488d38": "0.13.0-beta",
     "7f34774529fa0964d47fc418d4d2965435cbfdc0": "0.11.1-beta",
     "86d3dec7b939b21bb10f2cd1ff56970c392a1c69": "0.13.2-beta",

package/lnd_methods/macaroon/accept_rpc_request.js

@@ -30,7 +30,7 @@ module.exports = ({id, subscription}, cbk) => {
 
       // Send accept feedback to the stream
       accept: ['validate', ({}, cbk) => {
-        return subscription.write({feedback, request_id: id}, err => {
+        return subscription.write({feedback, ref_msg_id: id}, err => {
           if (!!err) {
             return cbk([503, 'UnexpectedErrorAcceptingRpcRequest', {err}]);
           }

package/lnd_methods/macaroon/handle_rpc_request_update.js

@@ -17,6 +17,7 @@ const isPayViaRoute = n => !!n && n === '/routerrpc.Router/SendToRouteV2';
     [is_intercepting_pay_via_routes_requests]: <Is Handling Route Reqs Bool>
     subscription: <Stream Subscription Object>
     update: {
+      msg_id: <Message Id Number String>
       request_id: <Request Id Number String>
       raw_macaroon: <Raw Macaroon Buffer Object>
       custom_caveat_condition: <Custom Caveat Condition String>
@@ -47,12 +48,13 @@ const isPayViaRoute = n => !!n && n === '/routerrpc.Router/SendToRouteV2';
     [accept]: ({}, cbk) => {}
     data: {
       [accept]: ({}, cbk) => {}
-      id: <Request Id Number>
+      call: <Call Id Number>
+      id: <Message Id Number>
       [macaroon]: <Base64 Encoded Macaroon String>
       [reject]: ({}, cbk) => {}
       [request]: {
         [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
-        [cooperative_close_address]: <Prefer Cooperative Close To Address String>
+        [cooperative_close_address]: <Prefer Cooperative Close Address String>
         [give_tokens]: <Tokens to Gift To Partner Number>
         [is_private]: <Channel is Private Bool>
         local_tokens: <Local Tokens Number>
@@ -72,6 +74,7 @@ module.exports = args => {
   const isInterceptOpenChans = !!args.is_intercepting_open_channel_requests;
   const isInterceptPayOnRoute = !!args.is_intercepting_pay_via_routes_requests;
 
+  const {call} = details;
   const {event} = details;
   const {id} = details;
   const {macaroon} = details;
@@ -144,5 +147,5 @@ module.exports = args => {
     };
   }
 
-  return {accept, event, data: {id, macaroon, uri}};
+  return {accept, event, data: {call, id, macaroon, uri}};
 };

package/lnd_methods/macaroon/reject_rpc_request.js

@@ -36,7 +36,7 @@ module.exports = ({id, message, subscription}, cbk) => {
             error: message || defaultRejectMessage,
             replace_response: false,
           },
-          request_id: id,
+          ref_msg_id: id,
         },
         err => {
           if (!!err) {

package/lnd_methods/macaroon/subscribe_to_rpc_requests.d.ts

@@ -21,7 +21,9 @@ export type SubscribeToRpcRequestsResult = {
 };
 
 export type SubscribeToRpcRequestsCommonEvent = {
-  /** Request Id Number */
+  /** Call Id Number */
+  call: number;
+  /** Message Id Number */
   id: number;
   /** Base64 Encoded Macaroon String */
   macaroon?: string;
@@ -135,7 +137,7 @@ export type SubscribeToRpcRequestsResponseEvent =
  *
  * LND must be running with "RPC middleware" enabled: `rpcmiddleware.enable=1`
  *
- * This method is not supported in LND 0.13.3 and below
+ * This method is not supported in LND 0.13.4 and below
  */
 export const subscribeToRpcRequests: AuthenticatedLightningMethod<
   SubscribeToRpcRequestsArgs,

package/lnd_methods/macaroon/subscribe_to_rpc_requests.js

@@ -22,7 +22,7 @@ const type = 'default';
 
   LND must be running with "RPC middleware" enabled: `rpcmiddleware.enable=1`
 
-  This method is not supported in LND 0.13.3 and below
+  This method is not supported in LND 0.13.4 and below
 
   {
     [id]: <RPC Middleware Interception Name String>
@@ -41,7 +41,7 @@ const type = 'default';
   @event 'close_channel_request'
   {
     accept: ({}, [cbk]) => {}
-    id: <Request Id Number>
+    id: <Message Id Number>
     macaroon: <Base64 Encoded Macaroon String>
     reject: ({message: <Rejection String>}, [cbk]) => {}
     request: {
@@ -59,7 +59,7 @@ const type = 'default';
   @event 'open_channel_request'
   {
     accept: ({}, [cbk]) => {}
-    id: <Request Id Number>
+    id: <Message Id Number>
     macaroon: <Base64 Encoded Macaroon String>
     reject: ({message: <Rejection String>}, [cbk]) => {}
     request: {
@@ -80,7 +80,7 @@ const type = 'default';
   @event 'pay_via_route_request'
   {
     accept: ({}, [cbk]) => {}
-    id: <Request Id Number>
+    id: <Message Id Number>
     macaroon: <Base64 Encoded Macaroon String>
     reject: ({message: <Rejection String>}, [cbk]) => {}
     request: {
@@ -110,14 +110,16 @@ const type = 'default';
 
   @event 'request'
   {
-    id: <Request Id Number>
+    call: <Call Identifier Number>
+    id: <Message Id Number>
     [macaroon]: <Base64 Encoded Macaroon String>
     [uri]: <RPC URI String>
   }
 
   @event 'response'
   {
-    id: <Request Id Number>
+    call: <Call Identifier Number>
+    id: <Message Id Number>
     [macaroon]: <Base64 Encoded Macaroon String>
     [uri]: <RPC URI String>
   }

package/lnd_methods/offchain/delete_failed_pay_attempts.js

@@ -16,7 +16,7 @@ const type = 'default';
 
   Method not supported on LND 0.12.1 or below
 
-  `id` is not supported on LND 0.13.3 or below
+  `id` is not supported on LND 0.13.4 or below
 
   {
     [id]: <Delete Only Failed Attempt Records For Payment With Hash Hex String>

package/lnd_methods/offchain/delete_payment.d.ts

@@ -13,6 +13,6 @@ export type DeletePaymentArgs = AuthenticatedLightningArgs<{
  *
  * Requires `offchain:write` permission
  *
- * Note: this method is not supported on LND 0.13.3 and below
+ * Note: this method is not supported on LND 0.13.4 and below
  */
 export const deletePayment: AuthenticatedLightningMethod<DeletePaymentArgs>;

package/lnd_methods/offchain/delete_payment.js

@@ -13,7 +13,7 @@ const type = 'default';
 
   Requires `offchain:write` permission
 
-  Note: this method is not supported on LND 0.13.3 and below
+  Note: this method is not supported on LND 0.13.4 and below
 
   {
     id: <Payment Preimage Hash Hex String>

package/lnd_methods/offchain/emit_payment.js

@@ -1,5 +1,6 @@
 const {confirmedFromPayment} = require('./../../lnd_responses');
 const {failureFromPayment} = require('./../../lnd_responses');
+const {pendingFromPayment} = require('./../../lnd_responses');
 const {states} = require('./payment_states');
 
 /** Emit payment from payment event
@@ -21,7 +22,7 @@ module.exports = ({data, emitter}) => {
       return emitter.emit('failed', failureFromPayment(data));
 
     case states.paying:
-      return emitter.emit('paying', {});
+      return emitter.emit('paying', pendingFromPayment(data));
 
     default:
       return;

package/lnd_methods/offchain/get_payment.d.ts

@@ -105,6 +105,60 @@ export type GetPaymentResult = {
     /** Total Tokens Paid */
     tokens: number;
   };
+  pending?: {
+    /** Created at ISO-8601 Date */
+    created_at: string;
+    /** Payment Destination Public Key Hex */
+    destination: string;
+    /** Payment Hash Hex */
+    id: string;
+    /** Total Millitokens Pending */
+    mtokens: string;
+    paths: {
+      /** Total Path Fee Tokens */
+      fee: number;
+      /** Total Path Fee Millitokens */
+      fee_mtokens: string;
+      hops: {
+        /** Standard Format Channel Id */
+        channel: string;
+        /** Channel Capacity Tokens */
+        channel_capacity: number;
+        /** Routing Fee Tokens */
+        fee: number;
+        /** Fee Millitokens */
+        fee_mtokens: string;
+        /** Forwarded Tokens */
+        forward: number;
+        /** Forward Millitokens */
+        forward_mtokens: string;
+        /** Public Key Hex */
+        public_key: string;
+        /** Timeout Block Height */
+        timeout: number;
+      }[];
+      /** Total Path Millitokens Paid */
+      mtokens: string;
+      /** MPP Payment Identifying Nonce */
+      payment: string;
+      /** Expiration Block Height */
+      timeout: number;
+      /** Path Tokens Paid */
+      tokens: number;
+      /** Total Millitokens Pending */
+      total_mtokens: string;
+    }[]
+    /** BOLT 11 Payment Request */
+    request?: string;
+    /** Payment Tokens Rounded Up */
+    safe_tokens: number;
+    /** Payment Preimage Hex */
+    secret: string;
+    /** Expiration Block Height */
+    timeout?: number;
+    /** Total Tokens Pending */
+    tokens: number;
+  };
 };
 
 /**

package/lnd_methods/offchain/get_payment.js

@@ -67,6 +67,30 @@ const type = 'router';
       timeout: <Expiration Block Height Number>
       tokens: <Total Tokens Paid Number>
     }
+    [pending]: {
+      created_at: <Payment Created At ISO 8601 Date String>
+      destination: <Payment Destination Hex String>
+      id: <Payment Hash Hex String>
+      mtokens: <Total Millitokens Pending String>
+      paths: [{
+        fee_mtokens: <Total Fee Millitokens Paid String>
+        hops: [{
+          channel: <Standard Format Channel Id String>
+          channel_capacity: <Channel Capacity Tokens Number>
+          fee: <Fee Tokens Rounded Down Number>
+          fee_mtokens: <Fee Millitokens String>
+          forward: <Forwarded Tokens Number>
+          forward_mtokens: <Forward Millitokens String>
+          public_key: <Public Key Hex String>
+          timeout: <Timeout Block Height Number>
+        }]
+        mtokens: <Total Millitokens Pending String>
+      }]
+      [request]: <BOLT 11 Encoded Payment Request String>
+      safe_tokens: <Payment Tokens Rounded Up Number>
+      [timeout]: <Expiration Block Height Number>
+      tokens: <Total Tokens Pending Number>
+    }
   }
 */
 module.exports = ({id, lnd}, cbk) => {
@@ -102,6 +126,7 @@ module.exports = ({id, lnd}, cbk) => {
             is_failed: !!res.failed,
             is_pending: !res.payment && !res.failed,
             payment: res.payment || undefined,
+            pending: res.pending || undefined,
           });
         };
 
@@ -109,7 +134,7 @@ module.exports = ({id, lnd}, cbk) => {
         sub.once('end', () => cbk([503, 'UnknownStatusOfPayment']));
         sub.once('error', err => finished(err));
         sub.once('failed', failed => finished(null, {failed}));
-        sub.once('paying', () => finished(null, {}));
+        sub.once('paying', pending => finished(null, {pending}));
 
         return;
       }],

package/lnd_methods/offchain/subscribe_to_forwards.js

@@ -16,7 +16,7 @@ const unknownFailureMessage = '2 UNKNOWN: unknown failure detail type: <nil>';
 
   Requires `offchain:read` permission
 
-  Note: LND 0.13.3 and below do not return `secret` for forwards
+  Note: LND 0.13.4 and below do not return `secret` for forwards
 
   {
     lnd: <Authenticated LND API Object>

package/lnd_methods/offchain/subscribe_to_past_payment.js

@@ -82,7 +82,34 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
   }
 
   @event 'paying'
-  {}
+  {
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Pending String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      fee_mtokens: <Total Fee Millitokens Pending String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Tokens Rounded Down Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Pending String>
+      safe_fee: <Total Fee Tokens Pending Rounded Up Number>
+      safe_tokens: <Total Tokens Pending, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_tokens: <Total Tokens Pending, Rounded Up Number>
+    [timeout]: <Expiration Block Height Number>
+    tokens: <Total Tokens Pending Rounded Down Number>
+  }
 */
 module.exports = args => {
   if (!isHash(args.id)) {

package/lnd_methods/offchain/subscribe_to_past_payments.d.ts

@@ -69,6 +69,6 @@ export type SubscribeToPastPaymentsPaymentEvent = {
  *
  * Requires `offchain:read` permission
  *
- * Note: Method not supported on LND 0.13.3 and below
+ * Note: Method not supported on LND 0.13.4 and below
  */
 export const subscribeToPastPayments: AuthenticatedLightningSubscription<SubscribeToPastPaymentsArgs>;

package/lnd_methods/offchain/subscribe_to_past_payments.js

@@ -23,7 +23,7 @@ const unknownFailureMessage = '2 UNKNOWN: unknown failure detail type: <nil>';
 
   Requires `offchain:read` permission
 
-  Note: Method not supported on LND 0.13.3 and below
+  Note: Method not supported on LND 0.13.4 and below
 
   {
     lnd: <Authenticated LND API Object>

package/lnd_methods/offchain/subscribe_to_peer_messages.d.ts

@@ -13,6 +13,6 @@ export type SubscribeToPeerMessagesMessageReceivedEvent =
  *
  * Requires `offchain:read` permission
  *
- * This method is not supported in LND 0.13.3 and below
+ * This method is not supported in LND 0.13.4 and below
  */
 export const subscribeToPeerMessages: AuthenticatedLightningSubscription;

package/lnd_methods/offchain/subscribe_to_peer_messages.js

@@ -16,7 +16,7 @@ const type = 'default';
 
   Requires `offchain:read` permission
 
-  This method is not supported in LND 0.13.3 and below
+  This method is not supported in LND 0.13.4 and below
 
   {
     lnd: <Authenticated LND API Object>

package/lnd_methods/offchain/update_routing_fees.d.ts

@@ -67,7 +67,7 @@ export type UpdateRoutingFeesResult = {
  *
  * Setting both `base_fee_tokens` and `base_fee_mtokens` is not supported
  *
- * `failures` are not returned on LND 0.13.3 and below
+ * `failures` are not returned on LND 0.13.4 and below
  *
  * Requires `offchain:write` permission
  */

package/lnd_methods/offchain/update_routing_fees.js

@@ -20,7 +20,7 @@ const type = 'default';
 
   Setting both `base_fee_tokens` and `base_fee_mtokens` is not supported
 
-  `failures` are not returned on LND 0.13.3 and below
+  `failures` are not returned on LND 0.13.4 and below
 
   Requires `offchain:write` permission
 

package/lnd_methods/unauthenticated/get_wallet_status.d.ts

@@ -26,7 +26,7 @@ export type GetWalletStatusResult = {
  *
  * This method is not supported on LND 0.12.1 and below
  *
- * `is_ready` is not supported on LND 0.13.3 and below
+ * `is_ready` is not supported on LND 0.13.4 and below
  */
 export const getWalletStatus: UnauthenticatedLightningMethod<
   {lnd: UnauthenticatedLnd},

package/lnd_methods/unauthenticated/get_wallet_status.js

@@ -14,7 +14,7 @@ const unsupportedMessage = 'unknown service lnrpc.State';
 
   This method is not supported on LND 0.12.1 and below
 
-  `is_ready` is not supported on LND 0.13.3 and below
+  `is_ready` is not supported on LND 0.13.4 and below
 
   {
     lnd: <Unauthenticated LND API Object>

package/lnd_methods/unauthenticated/subscribe_to_wallet_status.d.ts

@@ -25,6 +25,6 @@ export type SubscribeToWalletStatusStartingEvent = EmptyObject;
  *
  * This method is not supported on LND 0.12.1 and below
  *
- * `ready` is not supported on LND 0.13.3 and below
+ * `ready` is not supported on LND 0.13.4 and below
  */
 export const subscribeToWalletStatus: UnauthenticatedLightningSubscription;

package/lnd_methods/unauthenticated/subscribe_to_wallet_status.js

@@ -18,7 +18,7 @@ const type = 'status';
 
   This method is not supported on LND 0.12.1 and below
 
-  `ready` is not supported on LND 0.13.3 and below
+  `ready` is not supported on LND 0.13.4 and below
 
   {
     lnd: <Unauthenticated LND API Object>

package/lnd_responses/index.js

@@ -11,6 +11,7 @@ const nodeInfoAsNode = require('./node_info_as_node');
 const paymentFailure = require('./payment_failure');
 const paymentRequestDetails = require('./payment_request_details');
 const pendingAsPendingChannels = require('./pending_as_pending_channels');
+const pendingFromPayment = require('./pending_from_payment');
 const policyFromChannelUpdate = require('./policy_from_channel_update');
 const routesFromQueryRoutes = require('./routes_from_query_routes');
 const rpcAttemptHtlcAsAttempt = require('./rpc_attempt_htlc_as_attempt');
@@ -53,6 +54,7 @@ module.exports = {
   paymentFailure,
   paymentRequestDetails,
   pendingAsPendingChannels,
+  pendingFromPayment,
   policyFromChannelUpdate,
   routesFromQueryRoutes,
   rpcAttemptHtlcAsAttempt,

package/lnd_responses/pending_from_payment.js

@@ -0,0 +1,145 @@
+const {attemptStates} = require('./constants');
+const rpcAttemptHtlcAsAttempt = require('./rpc_attempt_htlc_as_attempt');
+const {safeTokens} = require('./../bolt00');
+
+const {isArray} = Array;
+const is256Hex = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const {max} = Math;
+const mtokensAsTokens = mtokens => safeTokens({mtokens}).tokens;
+const nsAsDate = ns => new Date(Number(BigInt(ns) / BigInt(1e6)));
+
+/** Calculate total payment details from RPC payment HTLC elements
+
+  The `route` attribute only returns the first route, there may be more due to
+  payment splitting
+
+  {
+    creation_date: <Creation Date Epoch Time Seconds String>
+    creation_time_ns: <Creation Date Epoch Time Nanoseconds String>
+    failure_reason: <Payment Failure Reason String>
+    fee_msat: <Fee Paid in Millitokens String>
+    fee_sat: <Fee Paid in Tokens String>
+    htlcs: [{
+      attempt_time_ns: <HTLC Sent At Epoch Time Nanoseconds String>
+      resolve_time_ns: <HTLC Resolved At Epoch Time Nanoseconds String>
+      route: {
+        hops: [{
+          amt_to_forward: <Tokens to Forward String>
+          amt_to_forward_msat: <Millitokens to Forward String>
+          chan_id: <Numeric Format Channel Id String>
+          chan_capacity: <Channel Capacity Tokens String>
+          custom_records: {
+            <UInt64 String>: <Record Data Buffer>
+          }
+          expiry: <Timeout Chain Height Number>
+          fee: <Fee in Tokens String>
+          fee_msat: <Fee in Millitokens String>
+          [mpp_record]: {
+            payment_addr: <Payment Identifier Buffer>
+            total_amt_msat: <Total Payment Millitokens Amount String>
+          }
+          [pub_key]: <Next Hop Public Key Hex String>
+          tlv_payload: <Has Extra TLV Data Bool>
+        }]
+        total_amt: <Total Tokens String>
+        total_amt_msat: <Route Total Millitokens String>
+        total_fees: <Route Fee Tokens String>
+        total_fees_msat: <Route Total Fees Millitokens String>
+        total_time_lock: <Route Total Timelock Number>
+      }
+      status: <HTLC Status String>
+    }]
+    path: [<Hop Public Key Hex String>]
+    payment_hash: <Preimage SHA256 Hash Hex String>
+    payment_index: <Payment Index String>
+    payment_preimage: <Payment Secret Preimage Hex String>
+    payment_request: <BOLT 11 Payment Request String>
+    status: <Payment State String>
+    value: <Tokens String>
+    value_msat: <Paid Tokens Without Routing Fees Millitokens String>
+    value_sat: <Paid Tokens Without Routing Fees String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Public Key Hex String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Pending String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      fee_mtokens: <Total Fee Millitokens Pending String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Tokens Rounded Down Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Paid String>
+      safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+      safe_tokens: <Total Tokens Paid, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_tokens: <Total Tokens Pending, Rounded Up Number>
+    [timeout]: <Expiration Block Height Number>
+    tokens: <Total Tokens Pending Rounded Down Number>
+  }
+*/
+module.exports = payment => {
+  if (!payment) {
+    throw new Error('ExpectedPendingPaymentToDerivePendingDetails');
+  }
+
+  if (!payment.creation_time_ns) {
+    throw new Error('ExpectedPaymentCreationDateToDerivePendingDetails');
+  }
+
+  if (!payment.fee_msat) {
+    throw new Error('ExpectedPaymentFeeMillitokensAmountForPendingPayment');
+  }
+
+  if (!isArray(payment.htlcs)) {
+    throw new Error('ExpectedArrayOfPaymentHtlcsInPendingPayment');
+  }
+
+  if (!payment.htlcs.find(n => n.status === attemptStates.pending)) {
+    throw new Error('ExpectedPendingHtlcInPendingPayment');
+  }
+
+  if (!is256Hex(payment.payment_hash)) {
+    throw new Error('ExpectedPaymentHashForPaymentAsPendingPayment');
+  }
+
+  if (mtokensAsTokens(payment.value_msat) !== Number(payment.value_sat)) {
+    throw new Error('ExpectedValueOfTokensAndMillitokensToBeConsistent');
+  }
+
+  const attempts = payment.htlcs.map(htlc => rpcAttemptHtlcAsAttempt(htlc));
+  const mtokens = BigInt(payment.value_msat) + BigInt(payment.fee_msat);
+
+  const pending = attempts.filter(n => n.is_pending);
+
+  const [first] = pending;
+
+  const [destination] = first.route.hops.map(n => n.public_key).reverse();
+
+  return {
+    destination,
+    created_at: nsAsDate(payment.creation_time_ns).toISOString(),
+    id: payment.payment_hash,
+    mtokens: mtokens.toString(),
+    paths: pending.map(n => n.route),
+    request: payment.payment_request || undefined,
+    safe_tokens: safeTokens({mtokens: mtokens.toString()}).safe,
+    timeout: max(...pending.map(n => n.route.timeout).filter(n => !!n)),
+    tokens: safeTokens({mtokens: mtokens.toString()}).tokens,
+  };
+};

package/lnd_responses/rpc_channel_as_old_rpc_channel.js

@@ -23,6 +23,6 @@ module.exports = ({channel, version}) => {
 
   const type = adjustedChannelTypes[channel.commitment_type];
 
-  // Versions of LND 0.13.3 and before use a different channel type value
+  // Versions of LND 0.13.4 and before use a different channel type value
   return assign(channel, {commitment_type: type || defaultChannelType});
 };

package/lnd_responses/rpc_request_update_as_event.js

@@ -7,6 +7,7 @@ const streamAuth = 'stream_auth';
 /** Derive request details from an RPC request update
 
   {
+    msg_id: <Message Id Number String>
     request_id: <Request Id Number String>
     raw_macaroon: <Raw Macaroon Buffer Object>
     custom_caveat_condition: <Custom Caveat Condition String>
@@ -33,6 +34,7 @@ const streamAuth = 'stream_auth';
 
   @returns
   {
+    call: <Call Id Number>
     [event]: <Event Type String>
     id: <Request Id Number>
     [macaroon]: <Base64 Encoded Macaroon String>
@@ -52,6 +54,10 @@ module.exports = args => {
     throw new Error('ExpectedInterceptTypeInRpcRequestUpdate');
   }
 
+  if (args.msg_id === undefined) {
+    throw new Error('ExpectedMessageIdInRpcRequestUpdate');
+  }
+
   if (!isBuffer(args.raw_macaroon)) {
     throw new Error('ExpectedCompleteMacaroonCredentialsInRequestUpdate');
   }
@@ -60,7 +66,8 @@ module.exports = args => {
     throw new Error('ExpectedRequestIdInRpcRequestUpdate');
   }
 
-  const id = Number(args.request_id);
+  const call = Number(args.request_id);
+  const id = Number(args.msg_id);
 
   switch (args.intercept_type) {
   // New subscription
@@ -74,6 +81,7 @@ module.exports = args => {
     }
 
     return {
+      call,
       id,
       event: request,
       macaroon: bufferAsBase64(args.raw_macaroon),
@@ -91,6 +99,7 @@ module.exports = args => {
     }
 
     return {
+      call,
       id,
       event: request,
       macaroon: bufferAsBase64(args.raw_macaroon),
@@ -108,6 +117,7 @@ module.exports = args => {
     }
 
     return {
+      call,
       id,
       event: response,
       macaroon: bufferAsBase64(args.raw_macaroon),
@@ -116,6 +126,6 @@ module.exports = args => {
 
   // Unknown update
   default:
-    return {id, macaroon: bufferAsBase64(args.raw_macaroon)};
+    return {call, id, macaroon: bufferAsBase64(args.raw_macaroon)};
   }
 };

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.4.2",
+    "@grpc/grpc-js": "1.4.4",
     "@grpc/proto-loader": "0.6.6",
     "@types/express": "4.17.13",
-    "@types/node": "16.11.6",
+    "@types/node": "16.11.7",
     "@types/request": "2.48.7",
     "@types/ws": "8.2.0",
     "async": "3.2.2",
@@ -20,7 +20,7 @@
     "body-parser": "1.19.0",
     "bolt07": "1.7.4",
     "bolt09": "0.2.0",
-    "cbor": "8.0.2",
+    "cbor": "8.1.0",
     "express": "4.17.1",
     "invoices": "2.0.1",
     "psbt": "1.1.10"
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.13.0"
+  "version": "4.14.0"
 }

package/test/lnd_methods/macaroon/test_handle_rpc_request_update.js

@@ -24,6 +24,7 @@ const tests = [
       },
       subscription: {},
       update: {
+        msg_id: '1',
         request_id: '1',
         raw_macaroon: Buffer.alloc(0),
         custom_caveat_condition: '',
@@ -79,6 +80,7 @@ const tests = [
       },
       subscription: {},
       update: {
+        msg_id: '1',
         request_id: '1',
         raw_macaroon: Buffer.alloc(0),
         custom_caveat_condition: '',
@@ -141,6 +143,7 @@ const tests = [
       },
       subscription: {},
       update: {
+        msg_id: '1',
         request_id: '1',
         raw_macaroon: Buffer.alloc(0),
         custom_caveat_condition: '',
@@ -189,6 +192,7 @@ const tests = [
     args: {
       subscription: {},
       update: {
+        msg_id: '1',
         request_id: '1',
         raw_macaroon: Buffer.alloc(0),
         custom_caveat_condition: '',

package/test/lnd_methods/macaroon/test_subscribe_to_rpc_requests.js

@@ -18,6 +18,7 @@ const makeArgs = overrides => {
 
           process.nextTick(() => {
             emitter.emit('data', {
+              msg_id: '1',
               request_id: '1',
               raw_macaroon: Buffer.alloc(0),
               custom_caveat_condition: '',
@@ -86,6 +87,7 @@ const tests = [
 
             process.nextTick(() => {
               emitter.emit('data', {
+                msg_id: '1',
                 request_id: '1',
                 raw_macaroon: Buffer.alloc(0),
                 custom_caveat_condition: '',
@@ -102,7 +104,7 @@ const tests = [
     description: 'RPC write errors are passed back',
     expected: {
       events: [
-        {id: 1, macaroon: undefined, uri: 'method_full_uri'},
+        {call: 1, id: 1, macaroon: undefined, uri: 'method_full_uri'},
         [503, 'UnexpectedErrorAcceptingRpcRequest', {err: 'err'}],
       ],
     },
@@ -112,7 +114,7 @@ const tests = [
     description: 'RPC request subscription is returned',
     expected: {
       events: [
-        {id: 1, macaroon: undefined, uri: 'method_full_uri'},
+        {call: 1, id: 1, macaroon: undefined, uri: 'method_full_uri'},
         [503, 'ExpectedCustomCaveatConditionInRpcRequestUpdate'],
         {details: 'Cancelled on client'},
       ],
@@ -161,6 +163,7 @@ const tests = [
 
             process.nextTick(() => {
               emitter.emit('data', {
+                msg_id: '1',
                 request_id: '1',
                 raw_macaroon: Buffer.alloc(0),
                 custom_caveat_condition: '',

package/test/lnd_methods/offchain/test_get_payment.js

@@ -8,7 +8,48 @@ const makeLnd = args => {
   return {
     router: {
       trackPaymentV2: ({}) => {
-        const data = args.data || {status: 'IN_FLIGHT'};
+        const data = args.data || {
+          creation_date: '1',
+          creation_time_ns: '1',
+          failure_reason: 'FAILURE_REASON_NONE',
+          fee: '1',
+          fee_msat: '1000',
+          fee_sat: '1',
+          htlcs: [{
+            attempt_time_ns: '1',
+            status: 'IN_FLIGHT',
+            resolve_time_ns: '1',
+            route: {
+              hops: [{
+                amt_to_forward: '1',
+                amt_to_forward_msat: '1000',
+                chan_capacity: '1',
+                chan_id: '1',
+                custom_records: {'1': Buffer.alloc(1)},
+                expiry: 1,
+                fee: '1',
+                fee_msat: '1000',
+                mpp_record: {payment_addr: Buffer.alloc(32), total_amt_msat: '1000'},
+                pub_key: Buffer.alloc(33).toString('hex'),
+                tlv_payload: true,
+              }],
+              total_amt: '1',
+              total_amt_msat: '1000',
+              total_time_lock: 1,
+              total_fees: '1',
+              total_fees_msat: '1000',
+            },
+          }],
+          path: [Buffer.alloc(33).toString('hex')],
+          payment_hash: Buffer.alloc(32).toString('hex'),
+          payment_index: '1',
+          payment_preimage: Buffer.alloc(32).toString('hex'),
+          payment_request: '',
+          status: 'IN_FLIGHT',
+          value: '1',
+          value_msat: '1000',
+          value_sat: '1',
+        };
         const emitter = new EventEmitter();
 
         if (!!args.is_end) {
@@ -146,6 +187,35 @@ const tests = [
         is_failed: false,
         is_pending: true,
         payment: undefined,
+        pending: {
+          created_at: '1970-01-01T00:00:00.000Z',
+          destination: Buffer.alloc(33).toString('hex'),
+          id: Buffer.alloc(32).toString('hex'),
+          mtokens: '2000',
+          paths: [{
+            fee: 1,
+            fee_mtokens: '1000',
+            hops: [{
+              channel: '0x0x1',
+              channel_capacity: 1,
+              fee: 1,
+              fee_mtokens: '1000',
+              forward: 1,
+              forward_mtokens: '1000',
+              public_key: Buffer.alloc(33).toString('hex'),
+              timeout: 1,
+            }],
+            mtokens: '1000',
+            payment: '0000000000000000000000000000000000000000000000000000000000000000',
+            timeout: 1,
+            tokens: 1,
+            total_mtokens: '1000',
+          }],
+          request: undefined,
+          safe_tokens: 2,
+          timeout: 1,
+          tokens: 2,
+        },
       },
     },
   },

package/test/lnd_responses/test_pending_from_payment.js

@@ -0,0 +1,143 @@
+const {test} = require('@alexbosworth/tap');
+
+const {pendingFromPayment} = require('./../../lnd_responses');
+
+const makeArgs = overrides => {
+  const args = {
+    creation_date: '1',
+    creation_time_ns: '1',
+    failure_reason: 'FAILURE_REASON_NONE',
+    fee: '1',
+    fee_msat: '1000',
+    fee_sat: '1',
+    htlcs: [{
+      attempt_time_ns: '1',
+      status: 'IN_FLIGHT',
+      resolve_time_ns: '1',
+      route: {
+        hops: [{
+          amt_to_forward: '1',
+          amt_to_forward_msat: '1000',
+          chan_capacity: '1',
+          chan_id: '1',
+          custom_records: {'1': Buffer.alloc(1)},
+          expiry: 1,
+          fee: '1',
+          fee_msat: '1000',
+          mpp_record: {payment_addr: Buffer.alloc(32), total_amt_msat: '1000'},
+          pub_key: Buffer.alloc(33).toString('hex'),
+          tlv_payload: true,
+        }],
+        total_amt: '1',
+        total_amt_msat: '1000',
+        total_time_lock: 1,
+        total_fees: '1',
+        total_fees_msat: '1000',
+      },
+    }],
+    path: [Buffer.alloc(33).toString('hex')],
+    payment_hash: Buffer.alloc(32).toString('hex'),
+    payment_index: '1',
+    payment_preimage: Buffer.alloc(32).toString('hex'),
+    payment_request: '',
+    status: 'IN_FLIGHT',
+    value: '1',
+    value_msat: '1000',
+    value_sat: '1',
+  };
+
+  Object.keys(overrides).forEach(k => args[k] = overrides[k]);
+
+  return args;
+};
+
+const makeExpected = overrides => {
+  const expected = {
+    created_at: '1970-01-01T00:00:00.000Z',
+    destination: Buffer.alloc(33).toString('hex'),
+    id: Buffer.alloc(32).toString('hex'),
+    mtokens: '2000',
+    paths: [{
+      fee: 1,
+      fee_mtokens: '1000',
+      hops: [{
+        channel: '0x0x1',
+        channel_capacity: 1,
+        fee: 1,
+        fee_mtokens: '1000',
+        forward: 1,
+        forward_mtokens: '1000',
+        public_key: Buffer.alloc(33).toString('hex'),
+        timeout: 1,
+      }],
+      mtokens: '1000',
+      payment: '0000000000000000000000000000000000000000000000000000000000000000',
+      timeout: 1,
+      tokens: 1,
+      total_mtokens: '1000',
+    }],
+    request: undefined,
+    safe_tokens: 2,
+    timeout: 1,
+    tokens: 2,
+  };
+
+  Object.keys(overrides).forEach(k => expected[k] = overrides[k]);
+
+  return expected;
+};
+
+const tests = [
+  {
+    args: undefined,
+    description: 'A payment is expected',
+    error: 'ExpectedPendingPaymentToDerivePendingDetails',
+  },
+  {
+    args: makeArgs({creation_time_ns: undefined}),
+    description: 'Creation time is expected',
+    error: 'ExpectedPaymentCreationDateToDerivePendingDetails',
+  },
+  {
+    args: makeArgs({fee_msat: undefined}),
+    description: 'Fee millitokens are expected',
+    error: 'ExpectedPaymentFeeMillitokensAmountForPendingPayment',
+  },
+  {
+    args: makeArgs({htlcs: undefined}),
+    description: 'HTLCs are expected',
+    error: 'ExpectedArrayOfPaymentHtlcsInPendingPayment',
+  },
+  {
+    args: makeArgs({htlcs: [{}]}),
+    description: 'A successful HTLC is expected',
+    error: 'ExpectedPendingHtlcInPendingPayment',
+  },
+  {
+    args: makeArgs({payment_hash: undefined}),
+    description: 'A payment hash is expected',
+    error: 'ExpectedPaymentHashForPaymentAsPendingPayment',
+  },
+  {
+    args: makeArgs({value_sat: '1', value_msat: '0'}),
+    description: 'Values are expected to agree',
+    error: 'ExpectedValueOfTokensAndMillitokensToBeConsistent',
+  },
+  {
+    args: makeArgs({}),
+    description: 'Payment is mapped to confirmed payment details',
+    expected: makeExpected({}),
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    if (!!error) {
+      throws(() => pendingFromPayment(args), new Error(error), 'Err');
+    } else {
+      strictSame(pendingFromPayment(args), expected, 'Mapped');
+    }
+
+    return end();
+  });
+});

package/test/lnd_responses/test_rpc_request_update_as_event.js

@@ -4,6 +4,7 @@ const method = require('./../../lnd_responses/rpc_request_update_as_event');
 
 const makeArgs = overrides => {
   const args = {
+    msg_id: '1',
     request_id: '1',
     raw_macaroon: Buffer.alloc(0),
     custom_caveat_condition: '',
@@ -16,7 +17,7 @@ const makeArgs = overrides => {
 };
 
 const makeExpected = overrides => {
-  const expected = {id: 1, macaroon: undefined};
+  const expected = {call: 1, id: 1, macaroon: undefined};
 
   Object.keys(overrides).forEach(k => expected[k] = overrides[k]);
 
@@ -39,6 +40,11 @@ const tests = [
     description: 'An intercept type is expected',
     error: 'ExpectedInterceptTypeInRpcRequestUpdate',
   },
+  {
+    args: makeArgs({msg_id: undefined}),
+    description: 'A message id is expected',
+    error: 'ExpectedMessageIdInRpcRequestUpdate',
+  },
   {
     args: makeArgs({raw_macaroon: undefined}),
     description: 'A raw macaroon is expected',

package/test/protos/protos.json

@@ -4,7 +4,7 @@
     ["lightning", 1218],
     ["lightning", 1226],
     ["lightning", 1233],
-    ["lightning", 3431],
+    ["lightning", 3459],
     ["router", 100],
     ["walletkit", 3],
     ["walletunlocker", 2]