lightning 4.10.4 → 4.11.0

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Versions
 
-## 4.10.4
+## 4.11.0
+
+- `getFailedPayments`: Add method to get past failed payments
+- `subscribeToRpcRequests`: Add method to listen to and interact with RPC requests
+
+## 4.10.7
+
+- `getPayment`: Expand type definitions to match result data
+
+## 4.10.5
 
 - `getInvoice`, `getInvoices`, `subscribeToInvoice`, `subscribeToInvoices`:
     Fix `payment` being set when undefined, correct `is_push` for AMP pushes

package/README.md

@@ -131,6 +131,8 @@ Methods exported by this library support typescript, but ln-service includes add
     channels on the node.
 - [getConnectedWatchtowers](https://github.com/alexbosworth/ln-service#getconnectedwatchtowers):
     List watchtowers that were added
+- [getFailedPayments](https://github.com/alexbosworth/ln-service#getfailedpayments): List out
+    past payments that failed.
 - [getFeeRates](https://github.com/alexbosworth/ln-service#getfeerates): List routing fee rates
     and routing policies of channels on the node.
 - [getForwardingConfidence](https://github.com/alexbosworth/ln-service#getforwardingconfidence):

package/index.js

@@ -37,6 +37,7 @@ const {getChannelBalance} = require('./lnd_methods');
 const {getChannels} = require('./lnd_methods');
 const {getClosedChannels} = require('./lnd_methods');
 const {getConnectedWatchtowers} = require('./lnd_methods');
+const {getFailedPayments} = require('./lnd_methods');
 const {getFeeRates} = require('./lnd_methods');
 const {getForwardingConfidence} = require('./lnd_methods');
 const {getForwardingReputations} = require('./lnd_methods');
@@ -114,6 +115,7 @@ const {subscribeToPayViaRequest} = require('./lnd_methods');
 const {subscribeToPayViaRoutes} = require('./lnd_methods');
 const {subscribeToPeers} = require('./lnd_methods');
 const {subscribeToProbeForRoute} = require('./lnd_methods');
+const {subscribeToRpcRequests} = require('./lnd_methods');
 const {subscribeToTransactions} = require('./lnd_methods');
 const {subscribeToWalletStatus} = require('./lnd_methods');
 const {unauthenticatedLndGrpc} = require('./lnd_grpc');
@@ -169,6 +171,7 @@ module.exports = {
   getChannels,
   getClosedChannels,
   getConnectedWatchtowers,
+  getFailedPayments,
   getFeeRates,
   getForwardingConfidence,
   getForwardingReputations,
@@ -246,6 +249,7 @@ module.exports = {
   subscribeToPayViaRoutes,
   subscribeToPeers,
   subscribeToProbeForRoute,
+  subscribeToRpcRequests,
   subscribeToTransactions,
   subscribeToWalletStatus,
   unauthenticatedLndGrpc,

package/lnd_methods/index.js

@@ -35,6 +35,7 @@ const {getChannelBalance} = require('./offchain');
 const {getChannels} = require('./offchain');
 const {getClosedChannels} = require('./offchain');
 const {getConnectedWatchtowers} = require('./offchain');
+const {getFailedPayments} = require('./offchain');
 const {getFeeRates} = require('./offchain');
 const {getForwardingConfidence} = require('./offchain');
 const {getForwardingReputations} = require('./offchain');
@@ -164,6 +165,7 @@ module.exports = {
   getChannels,
   getClosedChannels,
   getConnectedWatchtowers,
+  getFailedPayments,
   getFeeRates,
   getForwardingConfidence,
   getForwardingReputations,

package/lnd_methods/macaroon/index.d.ts

@@ -1,4 +1,5 @@
 export * from './get_access_ids';
 export * from './grant_access';
 export * from './revoke_access';
+export * from './subscribe_to_rpc_requests';
 export * from './verify_access';

package/lnd_methods/macaroon/methods.json

@@ -139,6 +139,10 @@
     "methods": ["ListTowers", "Policy", "Stats"],
     "type": "tower_client"
   },
+  "getFailedPayments": {
+    "method": "ListPayments",
+    "type": "default"
+  },
   "getFeeRates": {
     "method": "FeeReport",
     "type": "default"

package/lnd_methods/macaroon/subscribe_to_rpc_requests.d.ts

@@ -0,0 +1,143 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+  LightningMethod,
+} from '../../typescript';
+
+export type SubscribeToRpcRequestsArgs = AuthenticatedLightningArgs<{
+  /** RPC Middleware Interception Name String */
+  id?: string;
+  /** Intercept Channel Closes Bool */
+  is_intercepting_close_channel_requests?: boolean;
+  /** Intercept Channel Opens Bool */
+  is_intercepting_open_channel_requests?: boolean;
+  /** Intercept Pay Via Route Bool */
+  is_intercepting_pay_via_routes_requests?: boolean;
+}>;
+
+export type SubscribeToRpcRequestsResult = {
+  /** RPC Request Subscription EventEmitter Object */
+  subscription: NodeJS.EventEmitter;
+};
+
+export type SubscribeToRpcRequestsCommonEvent = {
+  /** Request Id Number */
+  id: number;
+  /** Base64 Encoded Macaroon String */
+  macaroon?: string;
+  /** RPC URI String */
+  uri?: string;
+};
+
+export type SubscribeToRpcRequestsEvent<TRequest> =
+  Required<SubscribeToRpcRequestsCommonEvent> & {
+    accept: LightningMethod;
+    reject: LightningMethod<{
+      /** Rejection String */
+      message: string;
+    }>;
+    request: TRequest;
+  };
+
+/** A channel close request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsCloseChannelRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Request Sending Local Channel Funds To Address String */
+    address?: string;
+    /** Is Force Close Bool */
+    is_force_close?: boolean;
+    /** Confirmation Target Number */
+    target_confirmations?: number;
+    /** Tokens Per Virtual Byte Number */
+    tokens_per_vbyte?: number;
+    /** Transaction Id Hex String */
+    transaction_id: string;
+    /** Transaction Output Index Number */
+    transaction_vout: number;
+  }>;
+
+/** A channel open request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsOpenChannelRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Chain Fee Tokens Per VByte Number */
+    chain_fee_tokens_per_vbyte?: number;
+    /** Prefer Cooperative Close To Address String */
+    cooperative_close_address?: string;
+    /** Tokens to Gift To Partner Number */
+    give_tokens?: number;
+    /** Channel is Private Bool */
+    is_private?: boolean;
+    /** Local Tokens Number */
+    local_tokens: number;
+    /** Spend UTXOs With Minimum Confirmations Number */
+    min_confirmations?: number;
+    /** Minimum HTLC Millitokens String */
+    min_htlc_mtokens?: string;
+    /** Public Key Hex String */
+    partner_public_key: string;
+    /** Peer Output CSV Delay Number */
+    partner_csv_delay?: number;
+  }>;
+
+/** A pay to route request was intercepted: by default it will be rejected */
+export type SubscribeToRpcRequestsPayViaRouteRequestEvent =
+  SubscribeToRpcRequestsEvent<{
+    /** Payment Hash Hex String */
+    id: string;
+    route: {
+      /** Route Fee Tokens Number */
+      fee: number;
+      /** Route Fee Millitokens String */
+      fee_mtokens: string;
+      hops: {
+        /** Standard Format Channel Id String */
+        channel: string;
+        /** Channel Capacity Tokens Number */
+        channel_capacity: number;
+        /** Fee Tokens Number */
+        fee: number;
+        /** Fee Millitokens String */
+        fee_mtokens: string;
+        /** Forward Tokens Number */
+        forward: number;
+        /** Forward Millitokens String */
+        forward_mtokens: string;
+        /** Forward Edge Public Key Hex String */
+        public_key: string;
+        /** Timeout Block Height Number */
+        timeout?: number;
+      }[];
+      /** Total Fee-Inclusive Millitokens String */
+      mtokens: string;
+      /** Payment Identifier Hex String */
+      payment?: string;
+      /** Timeout Block Height Number */
+      timeout?: number;
+      /** Total Fee-Inclusive Tokens Number */
+      tokens: number;
+      /** Total Payment Millitokens String */
+      total_mtokens?: string;
+    };
+  }>;
+
+export type SubscribeToRpcRequestsRequestEvent =
+  SubscribeToRpcRequestsCommonEvent;
+
+export type SubscribeToRpcRequestsResponseEvent =
+  SubscribeToRpcRequestsCommonEvent;
+
+/**
+ * Subscribe to RPC requests and their responses
+ *
+ * `accept` and `reject` methods can be used with cbk or Promise syntax
+ *
+ * Requires `macaroon:write` permission
+ *
+ * LND must be running with "RPC middleware" enabled: `rpcmiddleware.enable=1`
+ *
+ * This method is not supported in LND 0.13.3 and below
+ */
+export const subscribeToRpcRequests: AuthenticatedLightningMethod<
+  SubscribeToRpcRequestsArgs,
+  SubscribeToRpcRequestsResult
+>;

package/lnd_methods/offchain/get_failed_payments.d.ts

@@ -0,0 +1,136 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+  PaginationArgs,
+} from '../../typescript';
+
+export type GetFailedPaymentsArgs = AuthenticatedLightningArgs<PaginationArgs>;
+
+export type GetFailedPaymentsResult = {
+  payments: {
+    attempts: {
+      failure?: {
+        /** Error Type Code Number */
+        code: number;
+        details?: {
+          /** Standard Format Channel Id String */
+          channel?: string;
+          /** Error Associated Block Height Number */
+          height?: number;
+          /** Failed Hop Index Number */
+          index?: number;
+          /** Error Millitokens String */
+          mtokens?: string;
+          policy?: {
+            /** Base Fee Millitokens String */
+            base_fee_mtokens: string;
+            /** Locktime Delta Number */
+            cltv_delta: number;
+            /** Fees Charged in Millitokens Per Million Number */
+            fee_rate: number;
+            /** Channel is Disabled Bool */
+            is_disabled?: boolean;
+            /** Maximum HLTC Millitokens Value String */
+            max_htlc_mtokens: string;
+            /** Minimum HTLC Millitokens Value String */
+            min_htlc_mtokens: string;
+            /** Updated At ISO 8601 Date String */
+            updated_at: string;
+          };
+          /** Error CLTV Timeout Height Number */
+          timeout_height?: number;
+          update?: {
+            /** Chain Id Hex String */
+            chain: string;
+            /** Channel Flags Number */
+            channel_flags: number;
+            /** Extra Opaque Data Hex String */
+            extra_opaque_data: string;
+            /** Message Flags Number */
+            message_flags: number;
+            /** Channel Update Signature Hex String */
+            signature: string;
+          };
+        };
+        /** Error Message String */
+        message: string;
+      };
+      /** Payment Add Index Number */
+      index?: number;
+      /** Payment Confirmed At ISO 8601 Date String */
+      confirmed_at?: string;
+      /** Payment Attempt Succeeded Bool */
+      is_confirmed: boolean;
+      /** Payment Attempt Failed Bool */
+      is_failed: boolean;
+      /** Payment Attempt is Waiting For Resolution Bool */
+      is_pending: boolean;
+      route: {
+        /** Route Fee Tokens Number */
+        fee: number;
+        /** Route Fee Millitokens String */
+        fee_mtokens: string;
+        hops: {
+          /** Standard Format Channel Id String */
+          channel: string;
+          /** Channel Capacity Tokens Number */
+          channel_capacity: number;
+          /** Fee Number */
+          fee: number;
+          /** Fee Millitokens String */
+          fee_mtokens: string;
+          /** Forward Tokens Number */
+          forward: number;
+          /** Forward Millitokens String */
+          forward_mtokens: string;
+          /** Forward Edge Public Key Hex String */
+          public_key?: string;
+          /** Timeout Block Height Number */
+          timeout?: number;
+        }[];
+        /** Total Fee-Inclusive Millitokens String */
+        mtokens: string;
+        /** Payment Identifier Hex String */
+        payment?: string;
+        /** Timeout Block Height Number */
+        timeout: number;
+        /** Total Fee-Inclusive Tokens Number */
+        tokens: number;
+        /** Total Millitokens String */
+        total_mtokens?: string;
+      };
+    }[];
+    /** Payment at ISO-8601 Date String */
+    created_at: string;
+    /** Destination Node Public Key Hex String */
+    destination?: string;
+    /** Payment Preimage Hash String */
+    id: string;
+    /** Payment Add Index Number */
+    index?: number;
+    /** Payment is Confirmed Bool */
+    is_confirmed: boolean;
+    /** Transaction Is Outgoing Bool */
+    is_outgoing: boolean;
+    /** Millitokens Attempted to Pay to Destination String */
+    mtokens: string;
+    /** BOLT 11 Payment Request String */
+    request?: string;
+    /** Payment Tokens Attempted to Pay Rounded Up Number */
+    safe_tokens: number;
+    /** Rounded Down Tokens Attempted to Pay to Destination Number */
+    tokens: number;
+  }[];
+  /** Next Opaque Paging Token String */
+  next?: string;
+};
+
+/**
+ * Get failed payments made through channels.
+ *
+ * Requires `offchain:read` permission
+ */
+export const getFailedPayments: AuthenticatedLightningMethod<
+  GetFailedPaymentsArgs,
+  GetFailedPaymentsResult
+>;

package/lnd_methods/offchain/get_failed_payments.js

@@ -0,0 +1,190 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+const {rpcPaymentAsPayment} = require('./../../lnd_responses');
+const {sortBy} = require('./../../arrays');
+
+const defaultLimit = 250;
+const {isArray} = Array;
+const isFailed = payment => !!payment && payment.status === 'FAILED';
+const lastPageFirstIndexOffset = 0;
+const method = 'listPayments';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'default';
+
+/** Get failed payments made through channels.
+
+  Requires `offchain:read` permission
+
+  {
+    [limit]: <Page Result Limit Number>
+    lnd: <Authenticated LND API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    payments: [{
+      attempts: [{
+        [failure]: {
+          code: <Error Type Code Number>
+          [details]: {
+            [channel]: <Standard Format Channel Id String>
+            [height]: <Error Associated Block Height Number>
+            [index]: <Failed Hop Index Number>
+            [mtokens]: <Error Millitokens String>
+            [policy]: {
+              base_fee_mtokens: <Base Fee Millitokens String>
+              cltv_delta: <Locktime Delta Number>
+              fee_rate: <Fees Charged in Millitokens Per Million Number>
+              [is_disabled]: <Channel is Disabled Bool>
+              max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
+              min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
+              updated_at: <Updated At ISO 8601 Date String>
+            }
+            [timeout_height]: <Error CLTV Timeout Height Number>
+            [update]: {
+              chain: <Chain Id Hex String>
+              channel_flags: <Channel Flags Number>
+              extra_opaque_data: <Extra Opaque Data Hex String>
+              message_flags: <Message Flags Number>
+              signature: <Channel Update Signature Hex String>
+            }
+          }
+          message: <Error Message String>
+        }
+        [index]: <Payment Add Index Number>
+        [confirmed_at]: <Payment Confirmed At ISO 8601 Date String>
+        is_confirmed: <Payment Attempt Succeeded Bool>
+        is_failed: <Payment Attempt Failed Bool>
+        is_pending: <Payment Attempt is Waiting For Resolution Bool>
+        route: {
+          fee: <Route Fee Tokens Number>
+          fee_mtokens: <Route Fee Millitokens String>
+          hops: [{
+            channel: <Standard Format Channel Id String>
+            channel_capacity: <Channel Capacity Tokens Number>
+            fee: <Fee Number>
+            fee_mtokens: <Fee Millitokens String>
+            forward: <Forward Tokens Number>
+            forward_mtokens: <Forward Millitokens String>
+            [public_key]: <Forward Edge Public Key Hex String>
+            [timeout]: <Timeout Block Height Number>
+          }]
+          mtokens: <Total Fee-Inclusive Millitokens String>
+          [payment]: <Payment Identifier Hex String>
+          timeout: <Timeout Block Height Number>
+          tokens: <Total Fee-Inclusive Tokens Number>
+          [total_mtokens]: <Total Millitokens String>
+        }
+      }]
+      created_at: <Payment at ISO-8601 Date String>
+      [destination]: <Destination Node Public Key Hex String>
+      id: <Payment Preimage Hash String>
+      [index]: <Payment Add Index Number>
+      is_confirmed: <Payment is Confirmed Bool>
+      is_outgoing: <Transaction Is Outgoing Bool>
+      mtokens: <Millitokens Attempted to Pay to Destination String>
+      [request]: <BOLT 11 Payment Request String>
+      safe_tokens: <Payment Tokens Attempted to Pay Rounded Up Number>
+      tokens: <Rounded Down Tokens Attempted to Pay to Destination Number>
+    }]
+    [next]: <Next Opaque Paging Token String>
+  }
+*/
+module.exports = ({limit, lnd, token}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!!limit && !!token) {
+          return cbk([400, 'ExpectedNoLimitWhenPagingPayFailuresWithToken']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndForGetFailedPaymentsRequest']);
+        }
+
+        return cbk();
+      },
+
+      // Get all payments
+      listPayments: ['validate', ({}, cbk) => {
+        let offset;
+        let resultsLimit = limit || defaultLimit;
+
+        if (!!token) {
+          try {
+            const pagingToken = parse(token);
+
+            offset = pagingToken.offset;
+            resultsLimit = pagingToken.limit;
+          } catch (err) {
+            return cbk([400, 'ExpectedValidPagingTokenForGetFailed', {err}]);
+          }
+        }
+
+        return lnd[type][method]({
+          include_incomplete: true,
+          index_offset: offset || Number(),
+          max_payments: resultsLimit,
+          reversed: true,
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedGetFailedPaymentsError', {err}]);
+          }
+
+          if (!res || !isArray(res.payments)) {
+            return cbk([503, 'ExpectedFailedPaymentsInListPaymentsResponse']);
+          }
+
+          if (typeof res.last_index_offset !== 'string') {
+            return cbk([503, 'ExpectedLastIndexOffsetWhenRequestingFailed']);
+          }
+
+          const lastOffset = Number(res.last_index_offset);
+          const offset = Number(res.first_index_offset);
+
+          const token = stringify({offset, limit: resultsLimit});
+
+          return cbk(null, {
+            payments: res.payments.filter(isFailed),
+            token: offset === lastPageFirstIndexOffset ? undefined : token,
+          });
+        });
+      }],
+
+      // Check and map payments
+      foundPayments: ['listPayments', ({listPayments}, cbk) => {
+        try {
+          const payments = listPayments.payments.map(rpcPaymentAsPayment);
+
+          return cbk(null, payments);
+        } catch (err) {
+          return cbk([503, err.message]);
+        }
+      }],
+
+      // Final found failed payments
+      payments: [
+        'foundPayments',
+        'listPayments',
+        ({foundPayments, listPayments}, cbk) =>
+      {
+        const payments = sortBy({
+          array: foundPayments,
+          attribute: 'created_at',
+        });
+
+        return cbk(null, {
+          next: listPayments.token || undefined,
+          payments: payments.sorted.reverse(),
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'payments'}, cbk));
+  });
+};

package/lnd_methods/offchain/get_payment.d.ts

@@ -32,6 +32,8 @@ export type GetPaymentResult = {
     created_at: string;
     /** Payment Destination Public Key Hex */
     destination: string;
+    /** Total Fee Tokens To Pay */
+    fee: number;
     /** Total Fee Millitokens To Pay */
     fee_mtokens: string;
     hops: {
@@ -56,6 +58,40 @@ export type GetPaymentResult = {
     id: string;
     /** Total Millitokens Paid */
     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 Paid On All Paths */
+      total_mtokens: string;
+    }[]
     /** BOLT 11 Payment Request */
     request?: string;
     /** Payment Forwarding Fee Rounded Up Tokens */

package/lnd_methods/offchain/get_payment.js

@@ -53,6 +53,7 @@ const type = 'router';
           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>

package/lnd_methods/offchain/get_payments.js

@@ -131,8 +131,6 @@ module.exports = ({limit, lnd, token}, cbk) => {
           }
         }
 
-        const start = Date.now();
-
         return lnd[type][method]({
           include_incomplete: false,
           index_offset: offset || Number(),
@@ -187,8 +185,8 @@ module.exports = ({limit, lnd, token}, cbk) => {
         });
 
         return cbk(null, {
-          payments: payments.sorted.reverse(),
           next: !!foundPayments.length ? listPayments.token : undefined,
+          payments: payments.sorted.reverse(),
         });
       }],
     },

package/lnd_methods/offchain/index.d.ts

@@ -14,6 +14,7 @@ export * from './get_channel_balance';
 export * from './get_channels';
 export * from './get_closed_channels';
 export * from './get_connected_watchtowers';
+export * from './get_failed_payments';
 export * from './get_fee_rates';
 export * from './get_forwarding_confidence';
 export * from './get_forwarding_reputations';

package/lnd_methods/offchain/index.js

@@ -14,6 +14,7 @@ const getChannelBalance = require('./get_channel_balance');
 const getChannels = require('./get_channels');
 const getClosedChannels = require('./get_closed_channels');
 const getConnectedWatchtowers = require('./get_connected_watchtowers');
+const getFailedPayments = require('./get_failed_payments');
 const getFeeRates = require('./get_fee_rates');
 const getForwardingConfidence = require('./get_forwarding_confidence');
 const getForwardingReputations = require('./get_forwarding_reputations');
@@ -65,6 +66,7 @@ module.exports = {
   getChannels,
   getClosedChannels,
   getConnectedWatchtowers,
+  getFailedPayments,
   getFeeRates,
   getForwardingConfidence,
   getForwardingReputations,

package/lnd_methods/offchain/probe_for_route.d.ts

@@ -118,6 +118,10 @@ export type ProbeForRouteResult = {
 /**
  * Probe to find a successful route
  *
+ * When probing to a payment request, make sure to specify the fields encoded in the payment request such as `cltv_delta`.
+ *
+ * If `total_mtokens` are specified, a `payment` nonce is required.
+ *
  * Requires `offchain:write` permission
  */
 export const probeForRoute: AuthenticatedLightningMethod<

package/lnd_methods/onchain/propose_channel.d.ts

@@ -34,7 +34,7 @@ export type ProposeChannelArgs = AuthenticatedLightningArgs<{
  * Channel proposals can allow for cooperative close delays or external funding
 flows.
  *
- * Requires `offchain:write`, `onchain:write` permissions
+ * Requires `address:read`, `offchain:write`, `onchain:write` permissions
  *
  * Requires LND compiled with `walletrpc` build tag
  */

package/lnd_methods/unauthenticated/get_wallet_status.d.ts

@@ -24,7 +24,9 @@ export type GetWalletStatusResult = {
 /**
  * Get wallet status.
  *
- * Requires `info:read` permission
+ * This method is not supported on LND 0.12.1 and below
+ *
+ * `is_ready` is not supported on LND 0.13.3 and below
  */
 export const getWalletStatus: UnauthenticatedLightningMethod<
   {lnd: UnauthenticatedLnd},

package/lnd_methods/unauthenticated/subscribe_to_wallet_status.d.ts

@@ -24,5 +24,7 @@ export type SubscribeToWalletStatusStartingEvent = EmptyObject;
  * Subscribe to wallet status events
  *
  * This method is not supported on LND 0.12.1 and below
+ *
+ * `ready` is not supported on LND 0.13.3 and below
  */
 export const subscribeToWalletStatus: UnauthenticatedLightningSubscription;

package/lnd_responses/rpc_payment_as_payment.js

@@ -1,6 +1,9 @@
+const {parsePaymentRequest} = require('invoices');
+
 const rpcAttemptHtlcAsAttempt = require('./rpc_attempt_htlc_as_attempt');
 const {safeTokens} = require('./../bolt00');
 
+const emptyHash = Buffer.alloc(32).toString('hex');
 const {isArray} = Array;
 const msPerSecond = 1e3;
 const nanoSecsPerMillisecond = BigInt(1e6);
@@ -129,9 +132,9 @@ const routePublicKeys = route => route.hops.map(n => n.public_key);
       }
     }]
     created_at: <Payment at ISO-8601 Date String>
-    destination: <Destination Node Public Key Hex String>
-    fee: <Paid Routing Fee Rounded Down Tokens Number>
-    fee_mtokens: <Paid Routing Fee in Millitokens String>
+    [destination]: <Destination Node Public Key Hex String>
+    [fee]: <Paid Routing Fee Rounded Down Tokens Number>
+    [fee_mtokens]: <Paid Routing Fee in Millitokens String>
     hops: [<First Route Hop Public Key Hex String>]
     id: <Payment Preimage Hash String>
     [index]: <Payment Add Index Number>
@@ -139,9 +142,9 @@ const routePublicKeys = route => route.hops.map(n => n.public_key);
     is_outgoing: <Transaction Is Outgoing Bool>
     mtokens: <Millitokens Sent to Destination String>
     [request]: <BOLT 11 Payment Request String>
-    safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
-    safe_tokens: <Payment Tokens Rounded Up Number>
-    secret: <Payment Preimage Hex String>
+    [safe_fee]: <Payment Forwarding Fee Rounded Up Tokens Number>
+    safe_tokens: <Payment Tokens Sent to Destination Rounded Up Number>
+    [secret]: <Payment Preimage Hex String>
     tokens: <Rounded Down Tokens Sent to Destination Number>
   }
 */
@@ -186,13 +189,46 @@ module.exports = payment => {
     throw new Error('ExpectedPaymentValueInRpcPaymentDetails');
   }
 
+  const creationDateEpochMs = (() => {
+    // Exit early when creation time nanoseconds is not defined
+    if (payment.creation_time_ns === Number().toString()) {
+      return Number(payment.creation_date) * msPerSecond;
+    }
+
+    return Number(BigInt(payment.creation_time_ns) / nanoSecsPerMillisecond);
+  })();
+
   const attempts = payment.htlcs.map(htlc => rpcAttemptHtlcAsAttempt(htlc));
+  const index = Number(payment.payment_index) || undefined;
+  const request = payment.payment_request || undefined;
+
+  // Exit early when there were no attempts
+  if (!attempts.length) {
+    const {destination} = !!request ? parsePaymentRequest({request}) : {};
 
-  if (!payment.path.length && !attempts.length) {
-    throw new Error('ExpectedAttemptInPaymentDetails');
+    return {
+      attempts,
+      destination,
+      index,
+      request,
+      confirmed_at: undefined,
+      created_at: new Date(creationDateEpochMs).toISOString(),
+      fee: undefined,
+      fee_mtokens: undefined,
+      hops: [],
+      id: payment.payment_hash,
+      is_confirmed: false,
+      is_outgoing: true,
+      mtokens: payment.value_msat,
+      safe_fee: undefined,
+      safe_tokens: safeTokens({mtokens: payment.value_msat}).safe,
+      secret: undefined,
+      tokens: safeTokens({mtokens: payment.value_msat}).tokens,
+    };
   }
 
   const hasPath = !!payment.path.length;
+  const hasPreimage = payment.payment_preimage !== emptyHash;
   const [attempt] = attempts;
   const successes = attempts.filter(n => n.is_confirmed);
 
@@ -201,32 +237,46 @@ module.exports = payment => {
 
   const [destination, ...hops] = path.reverse();
 
-  const creationDateEpochMs = (() => {
-    // Exit early when creation time nanoseconds is not defined
-    if (payment.creation_time_ns === Number().toString()) {
-      return Number(payment.creation_date) * msPerSecond;
-    }
-
-    return Number(BigInt(payment.creation_time_ns) / nanoSecsPerMillisecond);
-  })();
+  // Exit early when the payment was never settled
+  if (!hasPreimage) {
+    return {
+      attempts,
+      destination,
+      index,
+      request,
+      confirmed_at: undefined,
+      created_at: new Date(creationDateEpochMs).toISOString(),
+      fee: undefined,
+      fee_mtokens: undefined,
+      hops: hops.reverse(),
+      id: payment.payment_hash,
+      is_confirmed: false,
+      is_outgoing: true,
+      mtokens: payment.value_msat,
+      safe_fee: undefined,
+      safe_tokens: safeTokens({mtokens: payment.value_msat}).safe,
+      secret: undefined,
+      tokens: safeTokens({mtokens: payment.value_msat}).tokens,
+    };
+  }
 
   return {
+    attempts,
     destination,
-    attempts: payment.htlcs.map(htlc => rpcAttemptHtlcAsAttempt(htlc)),
+    index,
+    request,
     confirmed_at: confirmedAt || undefined,
     created_at: new Date(creationDateEpochMs).toISOString(),
     fee: safeTokens({mtokens: payment.fee_msat}).tokens,
     fee_mtokens: payment.fee_msat,
     hops: hops.reverse(),
     id: payment.payment_hash,
-    index: Number(payment.payment_index) || undefined,
-    is_confirmed: payment.value_msat !== Number().toString(),
+    is_confirmed: true,
     is_outgoing: true,
     mtokens: payment.value_msat,
-    request: payment.payment_request || undefined,
-    secret: payment.payment_preimage,
     safe_fee: safeTokens({mtokens: payment.fee_msat}).safe,
     safe_tokens: safeTokens({mtokens: payment.value_msat}).safe,
+    secret: payment.payment_preimage,
     tokens: safeTokens({mtokens: payment.value_msat}).tokens,
   };
 };

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.3.7",
+    "@grpc/grpc-js": "1.4.1",
     "@grpc/proto-loader": "0.6.5",
     "@types/express": "4.17.13",
-    "@types/node": "16.10.3",
+    "@types/node": "16.11.1",
     "@types/request": "2.48.7",
     "@types/ws": "8.2.0",
     "async": "3.2.1",
@@ -29,8 +29,8 @@
   "devDependencies": {
     "@alexbosworth/node-fetch": "2.6.2",
     "@alexbosworth/tap": "15.0.10",
-    "tsd": "0.17.0",
-    "typescript": "4.4.3",
+    "tsd": "0.18.0",
+    "typescript": "4.4.4",
     "ws": "8.2.3"
   },
   "engines": {
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.10.4"
+  "version": "4.11.0"
 }

package/test/lnd_methods/offchain/test_get_failed_payments.js

@@ -0,0 +1,160 @@
+const {test} = require('@alexbosworth/tap');
+
+const {getPayments} = require('./../../../');
+
+const makeLnd = args => {
+  return {
+    default: {
+      listPayments: ({}, cbk) => cbk(null, {
+        first_index_offset: args.first_index_offset || '1',
+        payments: [{
+          creation_date: '1',
+          creation_time_ns: '1',
+          failure_reason: '',
+          fee_msat: '1000',
+          fee_sat: '1',
+          htlcs: [],
+          path: [Buffer.alloc(33, 2).toString('hex')],
+          payment_hash: Buffer.alloc(32).toString('hex'),
+          payment_index: '1',
+          payment_preimage: Buffer.alloc(32).toString('hex'),
+          payment_request: '',
+          status: 'FAILED',
+          value: '1',
+          value_msat: '1000',
+          value_sat: '1',
+        }],
+        last_index_offset: args.last_index_offset || '1',
+      }),
+    },
+  };
+};
+
+const makeArgs = overrides => {
+  const args = {lnd: makeLnd({})};
+
+  Object.keys(overrides).forEach(k => args[k] = overrides[k]);
+
+  return args;
+};
+
+const makeExpectedPayment = ({}) => {
+  return {
+    destination: undefined,
+    attempts: [],
+    confirmed_at: undefined,
+    created_at: '1970-01-01T00:00:00.000Z',
+    fee: undefined,
+    fee_mtokens: undefined,
+    hops: [],
+    id: '0000000000000000000000000000000000000000000000000000000000000000',
+    index: 1,
+    is_confirmed: false,
+    is_outgoing: true,
+    mtokens: '1000',
+    request: undefined,
+    secret: undefined,
+    safe_fee: undefined,
+    safe_tokens: 1,
+    tokens: 1,
+  };
+};
+
+const tests = [
+  {
+    args: makeArgs({limit: 1, token: 'token'}),
+    description: 'A limit cannot be passed with a token',
+    error: [400, 'UnexpectedLimitWhenPagingPaymentsWithToken'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required',
+    error: [400, 'ExpectedLndForGetPaymentsRequest'],
+  },
+  {
+    args: makeArgs({token: 'token'}),
+    description: 'A valid token is required',
+    error: [400, 'ExpectedValidPagingTokenForPaymentReq'],
+  },
+  {
+    args: makeArgs({lnd: {default: {listPayments: ({}, cbk) => cbk('err')}}}),
+    description: 'Errors from LND are passed back',
+    error: [503, 'UnexpectedGetPaymentsError', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: {default: {listPayments: ({}, cbk) => cbk()}}}),
+    description: 'A response is expected from LND',
+    error: [503, 'ExpectedPaymentsInListPaymentsResponse'],
+  },
+  {
+    args: makeArgs({
+      lnd: {default: {listPayments: ({}, cbk) => cbk(null, {})}},
+    }),
+    description: 'A response with payments is expected from LND',
+    error: [503, 'ExpectedPaymentsInListPaymentsResponse'],
+  },
+  {
+    args: makeArgs({
+      lnd: {default: {listPayments: ({}, cbk) => cbk(null, {payments: []})}},
+    }),
+    description: 'A response with payments and last index is expected',
+    error: [503, 'ExpectedLastIndexOffsetWhenRequestingPayments'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        default: {
+          listPayments: ({}, cbk) => cbk(null, {
+            last_index_offset: '1',
+            payments: [{}],
+          }),
+        },
+      },
+    }),
+    description: 'A response with valid payments is expected',
+    error: [503, 'ExpectedCreationDateInRpcPaymentDetails'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'A payment is returned',
+    expected: {payment: makeExpectedPayment({})},
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        default: {
+          listPayments: ({}, cbk) => cbk(null, {
+            last_index_offset: '1',
+            payments: [],
+          }),
+        },
+      },
+    }),
+    description: 'No payments are returned',
+    expected: {},
+  },
+  {
+    args: makeArgs({
+      lnd: makeLnd({first_index_offset: '2'}),
+      token: JSON.stringify({limit: 1, offset: 1})
+    }),
+    description: 'A payment is returned when a token is specified',
+    expected: {payment: makeExpectedPayment({})},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects,  strictSame}) => {
+    if (!!error) {
+      await rejects(() => getPayments(args), error, 'Got expected error');
+    } else {
+      const {payments} = await getPayments(args);
+
+      const [payment] = payments;
+
+      strictSame(payment, expected.payment, 'Got expected payment');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/offchain/test_get_payments.js

@@ -39,7 +39,7 @@ const makeLnd = args => {
           path: [Buffer.alloc(33, 2).toString('hex')],
           payment_hash: Buffer.alloc(32).toString('hex'),
           payment_index: '1',
-          payment_preimage: Buffer.alloc(32).toString('hex'),
+          payment_preimage: Buffer.alloc(32, 1).toString('hex'),
           payment_request: '',
           status: 'SETTLED',
           value: '1',
@@ -99,7 +99,7 @@ const makeExpectedPayment = ({}) => {
     is_outgoing: true,
     mtokens: '1000',
     request: undefined,
-    secret: '0000000000000000000000000000000000000000000000000000000000000000',
+    secret: Buffer.alloc(32, 1).toString('hex'),
     safe_fee: 1,
     safe_tokens: 1,
     tokens: 1,

package/test/lnd_responses/test_rpc_payment_as_payment.js

@@ -57,9 +57,9 @@ const makeArgs = overrides => {
     path: [Buffer.alloc(33).toString('hex'), Buffer.alloc(33).toString('hex')],
     payment_hash: Buffer.alloc(32).toString('hex'),
     payment_index: '1',
-    payment_preimage: Buffer.alloc(32).toString('hex'),
+    payment_preimage: Buffer.alloc(32, 1).toString('hex'),
     payment_request: 'lntb1500n1pdn4czkpp5ugdqer05qrrxuchrzkcue94th9w2xzasp9qm7d0yxcgp4uh4kn4qdpa2fjkzep6yprkcmmzv9kzqsmj09c8gmmrw4e8yetwvdujq5n9va6kcct5d9hkucqzysdlghdpua7uvjjkcfj49psxtlqzkp5pdncffdfk2cp3mp76thrl29qhqgzufm503pjj96586n5w6edgw3n66j4rxxs707y4zdjuhyt6qqe5weu4',
-    status: 'FAILED',
+    status: 'SETTLED',
     value: '1',
     value_msat: '1000',
     value_sat: '1',
@@ -111,7 +111,7 @@ const makeExpected = overrides => {
     request: 'lntb1500n1pdn4czkpp5ugdqer05qrrxuchrzkcue94th9w2xzasp9qm7d0yxcgp4uh4kn4qdpa2fjkzep6yprkcmmzv9kzqsmj09c8gmmrw4e8yetwvdujq5n9va6kcct5d9hkucqzysdlghdpua7uvjjkcfj49psxtlqzkp5pdncffdfk2cp3mp76thrl29qhqgzufm503pjj96586n5w6edgw3n66j4rxxs707y4zdjuhyt6qqe5weu4',
     safe_fee: 1,
     safe_tokens: 1,
-    secret: Buffer.alloc(32).toString('hex'),
+    secret: Buffer.alloc(32, 1).toString('hex'),
     tokens: 1,
   };
 
@@ -141,11 +141,6 @@ const tests = [
     description: 'HTLC array is expected to be present',
     error: 'ExpectedHtlcsArrayInRpcPaymentDetails',
   },
-  {
-    args: makeArgs({htlcs: [], path: []}),
-    description: 'HTLC or path array is expected to be filled',
-    error: 'ExpectedAttemptInPaymentDetails',
-  },
   {
     args: makeArgs({path: undefined}),
     description: 'A path is expected to be present',
@@ -186,6 +181,46 @@ const tests = [
     description: 'A payment request is optional',
     expected: makeExpected({request: undefined}),
   },
+  {
+    args: makeArgs({htlcs: []}),
+    description: 'Attempts are optional',
+    expected: makeExpected({
+      attempts: [],
+      destination: '02212d3ec887188b284dbb7b2e6eb40629a6e14fb049673f22d2a0aa05f902090e',
+      fee: undefined,
+      fee_mtokens: undefined,
+      hops: [],
+      is_confirmed: false,
+      safe_fee: undefined,
+      secret: undefined,
+    }),
+  },
+  {
+    args: makeArgs({htlcs: [], payment_request: ''}),
+    description: 'Payment requests are optional when there are no attempts',
+    expected: makeExpected({
+      attempts: [],
+      destination: undefined,
+      fee: undefined,
+      fee_mtokens: undefined,
+      hops: [],
+      is_confirmed: false,
+      request: undefined,
+      safe_fee: undefined,
+      secret: undefined,
+    }),
+  },
+  {
+    args: makeArgs({payment_preimage: Buffer.alloc(32).toString('hex')}),
+    description: 'Empty preimage means not settled',
+    expected: makeExpected({
+      fee: undefined,
+      fee_mtokens: undefined,
+      is_confirmed: false,
+      safe_fee: undefined,
+      secret: undefined,
+    }),
+  },
   {
     args: makeArgs({
       creation_date: '1587410235',

package/test/typescript/get_failed_payments.test-d.ts

@@ -0,0 +1,31 @@
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {getFailedPayments, GetFailedPaymentsResult} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+const limit = 1;
+const token = 'token';
+
+expectError(getFailedPayments());
+expectError(getFailedPayments({}));
+expectError(getFailedPayments({lnd, limit, token})); // ExpectedNoLimitWhenPagingPayFailuresWithToken
+
+expectType<GetFailedPaymentsResult>(await getFailedPayments({lnd}));
+expectType<GetFailedPaymentsResult>(await getFailedPayments({lnd, limit}));
+expectType<GetFailedPaymentsResult>(await getFailedPayments({lnd, token}));
+
+expectType<void>(
+  getFailedPayments({lnd}, (error, result) => {
+    expectType<GetFailedPaymentsResult>(result);
+  })
+);
+expectType<void>(
+  getFailedPayments({lnd, limit}, (error, result) => {
+    expectType<GetFailedPaymentsResult>(result);
+  })
+);
+expectType<void>(
+  getFailedPayments({lnd, token}, (error, result) => {
+    expectType<GetFailedPaymentsResult>(result);
+  })
+);

package/test/typescript/subscribe_to_rpc_requests.test-d.ts

@@ -0,0 +1,46 @@
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {
+  subscribeToRpcRequests,
+  SubscribeToRpcRequestsResult,
+} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+const id = 'id';
+const is_intercepting_close_channel_requests = true;
+const is_intercepting_open_channel_requests = true;
+const is_intercepting_pay_via_routes_requests = true;
+
+expectError(subscribeToRpcRequests());
+expectError(subscribeToRpcRequests({}));
+
+expectType<SubscribeToRpcRequestsResult>(await subscribeToRpcRequests({lnd}));
+expectType<SubscribeToRpcRequestsResult>(
+  await subscribeToRpcRequests({
+    lnd,
+    id,
+    is_intercepting_close_channel_requests,
+    is_intercepting_open_channel_requests,
+    is_intercepting_pay_via_routes_requests,
+  })
+);
+
+expectType<void>(
+  subscribeToRpcRequests({lnd}, (err, res) => {
+    expectType<SubscribeToRpcRequestsResult>(res);
+  })
+);
+expectType<void>(
+  subscribeToRpcRequests(
+    {
+      lnd,
+      id,
+      is_intercepting_close_channel_requests,
+      is_intercepting_open_channel_requests,
+      is_intercepting_pay_via_routes_requests,
+    },
+    (err, res) => {
+      expectType<SubscribeToRpcRequestsResult>(res);
+    }
+  )
+);