lightning 4.10.5 → 4.11.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Versions
 
+## 4.11.1
+
+- `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`:

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/grpc/protos/lightning.proto

@@ -557,6 +557,44 @@ service Lightning {
     */
     rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse)
         returns (stream RPCMiddlewareRequest);
+
+    /* lncli: `sendcustom`
+    SendCustomMessage sends a custom peer message.
+    */
+    rpc SendCustomMessage (SendCustomMessageRequest)
+        returns (SendCustomMessageResponse);
+
+    /* lncli: `subscribecustom`
+    SubscribeCustomMessages subscribes to a stream of incoming custom peer
+    messages.
+    */
+    rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest)
+        returns (stream CustomMessage);
+}
+
+message SubscribeCustomMessagesRequest {
+}
+
+message CustomMessage {
+    // Peer from which the message originates
+    bytes peer = 1;
+
+    // Message type. This value will be in the custom range (>= 32768).
+    uint32 type = 2;
+
+    // Raw message data
+    bytes data = 3;
+}
+
+message SendCustomMessageRequest {
+    // Peer to send the message to
+    bytes peer = 1;
+    // Message type. This value needs to be in the custom range (>= 32768).
+    uint32 type = 2;
+    // Raw message data.
+    bytes data = 3;
+}
+message SendCustomMessageResponse {
 }
 
 message Utxo {

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

@@ -84,6 +84,7 @@ const {recoverFundsFromChannels} = require('./offchain');
 const {removePeer} = require('./peers');
 const {requestChainFeeIncrease} = require('./onchain');
 const {revokeAccess} = require('./macaroon');
+const {sendMessageToPeer} = require('./offchain');
 const {sendToChainAddress} = require('./onchain');
 const {sendToChainAddresses} = require('./onchain');
 const {sendToChainOutputScripts} = require('./onchain');
@@ -110,6 +111,7 @@ const {subscribeToPastPayments} = require('./offchain');
 const {subscribeToPayViaDetails} = require('./offchain');
 const {subscribeToPayViaRequest} = require('./offchain');
 const {subscribeToPayViaRoutes} = require('./offchain');
+const {subscribeToPeerMessages} = require('./offchain');
 const {subscribeToPeers} = require('./peers');
 const {subscribeToProbeForRoute} = require('./offchain');
 const {subscribeToRpcRequests} = require('./macaroon');
@@ -214,6 +216,7 @@ module.exports = {
   removePeer,
   requestChainFeeIncrease,
   revokeAccess,
+  sendMessageToPeer,
   sendToChainAddress,
   sendToChainAddresses,
   sendToChainOutputScripts,
@@ -240,6 +243,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPeerMessages,
   subscribeToPeers,
   subscribeToProbeForRoute,
   subscribeToRpcRequests,

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

@@ -334,6 +334,10 @@
     "method": "DeleteMacaroonId",
     "type": "default"
   },
+  "sendMessageToPeer": {
+    "method": "SendCustomMessage",
+    "type": "default"
+  },
   "sendToChainAddress": {
     "method": "SendCoins",
     "type": "default"
@@ -442,6 +446,10 @@
     "method": "SendToRouteV2",
     "type": "router"
   },
+  "subscribeToPeerMessages": {
+    "method": "SubscribeCustomMessages",
+    "type": "default"
+  },
   "subscribeToPeers": {
     "method": "SubscribePeerEvents",
     "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

@@ -8,7 +8,7 @@ const {sortBy} = require('./../../arrays');
 const defaultLimit = 250;
 const {isArray} = Array;
 const isFailed = payment => !!payment && payment.status === 'FAILED';
-const lastPageFirstIndexOffset = 1;
+const lastPageFirstIndexOffset = 0;
 const method = 'listPayments';
 const {parse} = JSON;
 const {stringify} = JSON;

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

@@ -32,6 +32,7 @@ const payViaRoutes = require('./pay_via_routes');
 const probeForRoute = require('./probe_for_route');
 const recoverFundsFromChannel = require('./recover_funds_from_channel');
 const recoverFundsFromChannels = require('./recover_funds_from_channels');
+const sendMessageToPeer = require('./send_message_to_peer');
 const subscribeToBackups = require('./subscribe_to_backups');
 const subscribeToChannels = require('./subscribe_to_channels');
 const subscribeToForwardRequests = require('./subscribe_to_forward_requests');
@@ -42,6 +43,7 @@ const subscribeToPastPayments = require('./subscribe_to_past_payments');
 const subscribeToPayViaDetails = require('./subscribe_to_pay_via_details');
 const subscribeToPayViaRequest = require('./subscribe_to_pay_via_request');
 const subscribeToPayViaRoutes = require('./subscribe_to_pay_via_routes');
+const subscribeToPeerMessages = require('./subscribe_to_peer_messages');
 const subscribeToProbeForRoute = require('./subscribe_to_probe_for_route');
 const updateConnectedWatchtower = require('./update_connected_watchtower');
 const updatePathfindingSettings = require('./update_pathfinding_settings');
@@ -84,6 +86,7 @@ module.exports = {
   probeForRoute,
   recoverFundsFromChannel,
   recoverFundsFromChannels,
+  sendMessageToPeer,
   subscribeToBackups,
   subscribeToChannels,
   subscribeToForwardRequests,
@@ -94,6 +97,7 @@ module.exports = {
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,
+  subscribeToPeerMessages,
   subscribeToProbeForRoute,
   updateConnectedWatchtower,
   updatePathfindingSettings,

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/offchain/send_message_to_peer.js

@@ -0,0 +1,76 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferFromHex = hex => Buffer.from(hex, 'hex');
+const defaultMessageType = 32768;
+const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const isPublicKey = n => !!n && /^[0-9A-F]{66}$/i.test(n);
+const method = 'sendCustomMessage';
+const notSupported = /unknown/;
+const type = 'default';
+
+/** Send a custom message to a connected peer
+
+  If specified, message type is expected to be between 32768 and 65535
+
+  Message data should not be larger than 65533 bytes
+
+  Note: this method is not supported in LND versions 0.13.3 and below
+
+  Requires `offchain:write` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+    message: <Message Hex String>
+    public_key: <To Peer Public Key Hex String>
+    [type]: <Message Type Number>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToSendMessageToPeer']);
+        }
+
+        if (!isHex(args.message)) {
+          return cbk([400, 'ExpectedCustomMessageDataToSendToPeer']);
+        }
+
+        if (!isPublicKey(args.public_key)) {
+          return cbk([400, 'ExpectedPeerPublicKeyToSendMessageTo']);
+        }
+
+        return cbk();
+      },
+
+      // Send the message to the peer
+      send: ['validate', ({}, cbk) => {
+        return args.lnd[type][method]({
+          data: bufferFromHex(args.message),
+          peer: bufferFromHex(args.public_key),
+          type: args.type || defaultMessageType,
+        },
+        err => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'SendMessageToPeerMethodNotSupported']);
+          }
+
+          if (!!err) {
+            console.log("ERR", err)
+            return cbk([503, 'UnexpectedErrorSendingMessageToPeer', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/offchain/subscribe_to_peer_messages.js

@@ -0,0 +1,63 @@
+const EventEmitter = require('events');
+
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {emitSubscriptionError} = require('./../../grpc');
+const {handleRemoveListener} = require('./../../grpc');
+const {isLnd} = require('./../../lnd_requests');
+const {rpcPeerMessageAsMessage} = require('./../../lnd_responses');
+
+const events = ['message_received'];
+const method = 'SubscribeCustomMessages';
+const type = 'default';
+
+/** Subscribe to incoming peer messages
+
+  Requires `offchain:read` permission
+
+  This method is not supported in LND 0.13.3 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns
+  <EventEmitter Object>
+
+  // A message was received from a peer
+  @event 'message_received'
+  {
+    message: <Message Hex String>
+    public_key: <From Peer Public Key Hex String>
+    type: <Message Type Number>
+  }
+*/
+module.exports = ({lnd}) => {
+  if (!isLnd({lnd, method, type})) {
+    throw new Error('ExpectedLndToSubscribeToPeerMessages');
+  }
+
+  const emitter = new EventEmitter();
+  const subscription = lnd[type][method]({});
+
+  const errored = emitSubscriptionError({emitter, subscription});
+
+  // Terminate subscription when all listeners are removed
+  handleRemoveListener({subscription, emitter, events});
+
+  subscription.on('end', () => emitter.emit('end'));
+  subscription.on('error', err => errored(err));
+  subscription.on('status', n => emitter.emit('status', n));
+
+  subscription.on('data', message => {
+    try {
+      // Notify listeners of the message
+      emitter.emit('message_received', rpcPeerMessageAsMessage(message));
+    } catch (err) {
+      return errored([503, err.message]);
+    }
+  });
+
+  return emitter;
+};

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/index.js

@@ -31,6 +31,7 @@ const rpcNodeAsNode = require('./rpc_node_as_node');
 const rpcOutpointAsUpdate = require('./rpc_outpoint_as_update');
 const rpcPaymentAsPayment = require('./rpc_payment_as_payment');
 const rpcPeerAsPeer = require('./rpc_peer_as_peer');
+const rpcPeerMessageAsMessage = require('./rpc_peer_message_as_message');
 const rpcRequestUpdateAsEvent = require('./rpc_request_update_as_event');
 const rpcResolutionAsResolution = require('./rpc_resolution_as_resolution');
 const rpcRouteAsRoute = require('./rpc_route_as_route');
@@ -72,6 +73,7 @@ module.exports = {
   rpcOutpointAsUpdate,
   rpcPaymentAsPayment,
   rpcPeerAsPeer,
+  rpcPeerMessageAsMessage,
   rpcRequestUpdateAsEvent,
   rpcResolutionAsResolution,
   rpcRouteAsRoute,

package/lnd_responses/rpc_peer_message_as_message.js

@@ -0,0 +1,44 @@
+const bufferAsHex = buffer => buffer.toString('hex');
+const {isBuffer} = Buffer;
+
+/** Map an RPC peer message to message details
+
+  {
+    data: <Message Data Buffer Object>
+    peer: <Peer Public Key Buffer Object>
+    type: <Message Type Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    message: <Message Data Hex String>
+    public_key: <Peer Public Key Hex String>
+    type: <Message Type Number>
+  }
+*/
+module.exports = args => {
+  if (!args) {
+    throw new Error('ExpectedRpcMessageToDerivePeerMessage');
+  }
+
+  if (!isBuffer(args.data)) {
+    throw new Error('ExpectedPeerMessageDataToDerivePeerMessage');
+  }
+
+  if (!isBuffer(args.peer)) {
+    throw new Error('ExpectedPeerPublicKeyBytesToDerivePeerMessage');
+  }
+
+  if (!args.type) {
+    throw new Error('ExpectedCustomMessageTypeNumberToDeriveMessage');
+  }
+
+  return {
+    message: bufferAsHex(args.data),
+    public_key: bufferAsHex(args.peer),
+    type: args.type,
+  };
+};

package/package.json

@@ -7,10 +7,10 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.3.7",
-    "@grpc/proto-loader": "0.6.5",
+    "@grpc/grpc-js": "1.4.1",
+    "@grpc/proto-loader": "0.6.6",
     "@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.5"
+  "version": "4.11.1"
 }

package/test/lnd_methods/offchain/test_send_message_to_peer.js

@@ -0,0 +1,68 @@
+const {test} = require('@alexbosworth/tap');
+
+const {sendMessageToPeer} = require('./../../../lnd_methods');
+
+const makeLnd = ({err}) => {
+  return {default: {sendCustomMessage: ({}, cbk) => cbk(err)}};
+};
+
+const makeArgs = override => {
+  const args = {
+    lnd: makeLnd({}),
+    message: Buffer.from('message').toString('hex'),
+    public_key: Buffer.alloc(33, 3).toString('hex'),
+    type: 40000,
+  };
+
+  Object.keys(override || {}).forEach(key => args[key] = override[key]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required',
+    error: [400, 'ExpectedAuthenticatedLndToSendMessageToPeer'],
+  },
+  {
+    args: makeArgs({message: undefined}),
+    description: 'A message is required',
+    error: [400, 'ExpectedCustomMessageDataToSendToPeer'],
+  },
+  {
+    args: makeArgs({public_key: undefined}),
+    description: 'A public key is required',
+    error: [400, 'ExpectedPeerPublicKeyToSendMessageTo'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: {details: 'unknown service'}})}),
+    description: 'Unimplemented error is returned',
+    error: [501, 'SendMessageToPeerMethodNotSupported'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: 'err'})}),
+    description: 'Server error is returned',
+    error: [503, 'UnexpectedErrorSendingMessageToPeer', {err: 'err'}],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Message is sent to peer',
+  },
+  {
+    args: makeArgs({type: undefined}),
+    description: 'Message with default type is sent to peer',
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, equal, rejects}) => {
+    if (!!error) {
+      await rejects(sendMessageToPeer(args), error, 'Got expected error');
+    } else {
+      await sendMessageToPeer(args);
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/offchain/test_subscribe_to_peer_messages.js

@@ -0,0 +1,132 @@
+const EventEmitter = require('events');
+
+const {test} = require('@alexbosworth/tap');
+
+const {subscribeToPeerMessages} = require('./../../../lnd_methods');
+
+const makeLnd = overrides => {
+  const data = {
+    data: Buffer.alloc(1),
+    peer: Buffer.alloc(33, 3),
+    type: 44444,
+  };
+
+  Object.keys(overrides).forEach(k => data[k] = overrides[k]);
+
+  return {
+    default: {
+      SubscribeCustomMessages: ({}) => {
+        const emitter = new EventEmitter();
+
+        emitter.cancel = () => {};
+
+        if (overrides.data === undefined) {
+          process.nextTick(() => emitter.emit('data', data));
+        } else {
+          process.nextTick(() => emitter.emit('data', overrides.data));
+        }
+
+        return emitter;
+      },
+    },
+  };
+};
+
+const tests = [
+  {
+    args: {
+      lnd: {
+        default: {
+          SubscribeCustomMessages: ({}) => {
+            const emitter = new EventEmitter();
+
+            emitter.cancel = () => {};
+
+            process.nextTick(() => emitter.emit('end'));
+            process.nextTick(() => emitter.emit('status'));
+            process.nextTick(() => emitter.emit('error', 'err'));
+
+            return emitter;
+          },
+        },
+      },
+    },
+    description: 'Errors are returned',
+    error: 'err',
+  },
+  {
+    args: {
+      lnd: {
+        default: {
+          SubscribeCustomMessages: ({}) => {
+            const emitter = new EventEmitter();
+
+            emitter.cancel = () => {};
+
+            process.nextTick(() => emitter.emit('error', {
+              details: 'Cancelled on client',
+            }));
+
+            return emitter;
+          },
+        },
+      },
+    },
+    description: 'Errors are returned',
+    error: {details: 'Cancelled on client'},
+  },
+  {
+    args: {lnd: makeLnd({peer: null})},
+    description: 'A peer is expected',
+    error: [503, 'ExpectedPeerPublicKeyBytesToDerivePeerMessage'],
+  },
+  {
+    args: {lnd: makeLnd({})},
+    description: 'Peer message event emitted',
+    expected: {
+      message: '00',
+      public_key: Buffer.alloc(33, 3).toString('hex'),
+      type: 44444,
+    },
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, equal, strictSame, throws}) => {
+    try {
+      subscribeToPeerMessages({});
+    } catch (err) {
+      strictSame(
+        err,
+        new Error('ExpectedLndToSubscribeToPeerMessages'), 'Needs lnd');
+    }
+
+    const sub = subscribeToPeerMessages(args);
+
+    if (!!error) {
+      sub.once('error', err => {
+        strictSame(err, error, 'Got expected error');
+
+        subscribeToPeerMessages(args);
+
+        process.nextTick(() => {
+          sub.removeAllListeners();
+
+          return end();
+        });
+      });
+    } else {
+      if (!expected) {
+        return end();
+      }
+
+      sub.once('message_received', message => {
+        strictSame(message, expected, 'Got message received');
+
+        return end();
+      });
+    }
+
+    return;
+  });
+});

package/test/lnd_responses/test_rpc_peer_message_as_message.js

@@ -0,0 +1,67 @@
+const {test} = require('@alexbosworth/tap');
+
+const {rpcPeerMessageAsMessage} = require('./../../lnd_responses');
+
+const makeArgs = overrides => {
+  const response = {
+    data: Buffer.alloc(1),
+    peer: Buffer.alloc(33, 3),
+    type: 44444,
+  };
+
+  Object.keys(overrides || {}).forEach(key => response[key] = overrides[key]);
+
+  return response;
+};
+
+
+const makeExpected = overrides => {
+  const expected = {
+    message: '00',
+    public_key: '030303030303030303030303030303030303030303030303030303030303030303',
+    type: 44444,
+  };
+
+  Object.keys(overrides || {}).forEach(key => expected[key] = overrides[key]);
+
+  return expected;
+};
+
+const tests = [
+  {
+    description: 'RPC peer message is expected',
+    error: 'ExpectedRpcMessageToDerivePeerMessage',
+  },
+  {
+    args: makeArgs({data: undefined}),
+    description: 'data is expected',
+    error: 'ExpectedPeerMessageDataToDerivePeerMessage',
+  },
+  {
+    args: makeArgs({peer: undefined}),
+    description: 'peer public key is expected',
+    error: 'ExpectedPeerPublicKeyBytesToDerivePeerMessage',
+  },
+  {
+    args: makeArgs({type: undefined}),
+    description: 'type is expected',
+    error: 'ExpectedCustomMessageTypeNumberToDeriveMessage',
+  },
+  {
+    args: makeArgs({}),
+    description: 'RPC peer message is mapped to message',
+    expected: makeExpected({}),
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    if (!!error) {
+      throws(() => rpcPeerMessageAsMessage(args), new Error(error), 'Got err');
+    } else {
+      strictSame(rpcPeerMessageAsMessage(args), expected, 'Mapped to message');
+    }
+
+    return end();
+  });
+});

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