lightning 4.4.0 → 4.7.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Versions
 
+## 4.7.1
+
+- `getPayment`: Add `created_at` to indicate the creation date of the payment
+- `getPayment`: Add `request` to indicate serialized payment request
+- `subscribeToPastPayment`: Add `created_at` to indicate the creation date of the payment
+- `subscribeToPastPayment`: Add `request` to indicate serialized payment request
+- `subscribeToPastPayments`: Add `created_at` to indicate the creation date of the payment
+- `subscribeToPastPayments`: Add `request` to indicate serialized payment request
+
+## 4.6.0
+
+- `getPayment`: Add `destination` to indicate the destination of the payment
+- `subscribeToPastPayment`: Add `destination` to indicate the destination of the payment
+- `subscribeToPastPayments`: Add `destination` to indicate the destination of the payment
+
+## 4.5.0
+
+- `deletePayment`: Add method to delete a single payment
+- `deleteFailedPayAttempts`: Add `id` argument to delete failed attempts for a payment
+- `getWalletStatus`: `is_ready`: Add wallet server ready status
+- `subscribeToWalletStatus`: Add `ready` event to indicate server ready status
+
 ## 4.4.0
 
 - `getPayment`: Add `confirmed_at` to indicate when payment resolved successfully

package/grpc/protos/lightning.proto

@@ -200,6 +200,16 @@ service Lightning {
     */
     rpc OpenChannel (OpenChannelRequest) returns (stream OpenStatusUpdate);
 
+    /* lncli: `batchopenchannel`
+    BatchOpenChannel attempts to open multiple single-funded channels in a
+    single transaction in an atomic way. This means either all channel open
+    requests succeed at once or all attempts are aborted if any of them fail.
+    This is the safer variant of using PSBTs to manually fund a batch of
+    channels through the OpenChannel RPC.
+    */
+    rpc BatchOpenChannel (BatchOpenChannelRequest)
+        returns (BatchOpenChannelResponse);
+
     /*
     FundingStateStep is an advanced funding related call that allows the caller
     to either execute some preparatory steps for a funding workflow, or
@@ -330,7 +340,14 @@ service Lightning {
     rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse);
 
     /*
-    DeleteAllPayments deletes all outgoing payments from DB.
+    DeletePayment deletes an outgoing payment from DB. Note that it will not
+    attempt to delete an In-Flight payment, since that would be unsafe.
+    */
+    rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse);
+
+    /*
+    DeleteAllPayments deletes all outgoing payments from DB. Note that it will
+    not attempt to delete In-Flight payments, since that would be unsafe.
     */
     rpc DeleteAllPayments (DeleteAllPaymentsRequest)
         returns (DeleteAllPaymentsResponse);
@@ -515,6 +532,14 @@ service Lightning {
     */
     rpc ListPermissions (ListPermissionsRequest)
         returns (ListPermissionsResponse);
+
+    /*
+    CheckMacaroonPermissions checks whether a request follows the constraints
+    imposed on the macaroon and that the macaroon is authorized to follow the
+    provided permissions.
+    */
+    rpc CheckMacaroonPermissions (CheckMacPermRequest)
+        returns (CheckMacPermResponse);
 }
 
 message Utxo {
@@ -1776,6 +1801,84 @@ message ReadyForPsbtFunding {
     bytes psbt = 3;
 }
 
+message BatchOpenChannelRequest {
+    // The list of channels to open.
+    repeated BatchOpenChannel channels = 1;
+
+    // The target number of blocks that the funding transaction should be
+    // confirmed by.
+    int32 target_conf = 2;
+
+    // A manual fee rate set in sat/vByte that should be used when crafting the
+    // funding transaction.
+    int64 sat_per_vbyte = 3;
+
+    // The minimum number of confirmations each one of your outputs used for
+    // the funding transaction must satisfy.
+    int32 min_confs = 4;
+
+    // Whether unconfirmed outputs should be used as inputs for the funding
+    // transaction.
+    bool spend_unconfirmed = 5;
+
+    // An optional label for the batch transaction, limited to 500 characters.
+    string label = 6;
+}
+
+message BatchOpenChannel {
+    // The pubkey of the node to open a channel with. When using REST, this
+    // field must be encoded as base64.
+    bytes node_pubkey = 1;
+
+    // The number of satoshis the wallet should commit to the channel.
+    int64 local_funding_amount = 2;
+
+    // The number of satoshis to push to the remote side as part of the initial
+    // commitment state.
+    int64 push_sat = 3;
+
+    // Whether this channel should be private, not announced to the greater
+    // network.
+    bool private = 4;
+
+    // The minimum value in millisatoshi we will require for incoming HTLCs on
+    // the channel.
+    int64 min_htlc_msat = 5;
+
+    // The delay we require on the remote's commitment transaction. If this is
+    // not set, it will be scaled automatically with the channel size.
+    uint32 remote_csv_delay = 6;
+
+    /*
+    Close address is an optional address which specifies the address to which
+    funds should be paid out to upon cooperative close. This field may only be
+    set if the peer supports the option upfront feature bit (call listpeers
+    to check). The remote peer will only accept cooperative closes to this
+    address if it is set.
+
+    Note: If this value is set on channel creation, you will *not* be able to
+    cooperatively close out to a different address.
+    */
+    string close_address = 7;
+
+    /*
+    An optional, unique identifier of 32 random bytes that will be used as the
+    pending channel ID to identify the channel while it is in the pre-pending
+    state.
+    */
+    bytes pending_chan_id = 8;
+
+    /*
+    The explicit commitment type to use. Note this field will only be used if
+    the remote peer supports explicit channel negotiation.
+    */
+    CommitmentType commitment_type = 9;
+}
+
+message BatchOpenChannelResponse {
+    repeated PendingUpdate pending_channels = 1;
+}
+
 message OpenChannelRequest {
     // A manual fee rate set in sat/vbyte that should be used when crafting the
     // funding transaction.
@@ -1867,6 +1970,12 @@ message OpenChannelRequest {
     transaction.
     */
     uint32 max_local_csv = 17;
+
+    /*
+    The explicit commitment type to use. Note this field will only be used if
+    the remote peer supports explicit channel negotiation.
+    */
+    CommitmentType commitment_type = 18;
 }
 message OpenStatusUpdate {
     oneof update {
@@ -3354,6 +3463,16 @@ message ListPaymentsResponse {
     uint64 last_index_offset = 3;
 }
 
+message DeletePaymentRequest {
+    // Payment hash to delete.
+    bytes payment_hash = 1;
+
+    /*
+    Only delete failed HTLCs from the payment, not the payment itself.
+    */
+    bool failed_htlcs_only = 2;
+}
+
 message DeleteAllPaymentsRequest {
     // Only delete failed payments.
     bool failed_payments_only = 1;
@@ -3364,6 +3483,9 @@ message DeleteAllPaymentsRequest {
     bool failed_htlcs_only = 2;
 }
 
+message DeletePaymentResponse {
+}
+
 message DeleteAllPaymentsResponse {
 }
 
@@ -3891,4 +4013,14 @@ message MacaroonId {
 message Op {
     string entity = 1;
     repeated string actions = 2;
-}
+}
+
+message CheckMacPermRequest {
+    bytes macaroon = 1;
+    repeated MacaroonPermission permissions = 2;
+    string fullMethod = 3;
+}
+
+message CheckMacPermResponse {
+    bool valid = 1;
+}

package/grpc/protos/stateservice.proto

@@ -41,6 +41,9 @@ enum WalletState {
     UNLOCKED = 2;
     RPC_ACTIVE = 3;
 
+    // SERVER_ACTIVE means that the lnd server is ready to accept calls.
+    SERVER_ACTIVE = 4;
+
     WAITING_TO_START = 255;
 }
 

package/index.js

@@ -15,6 +15,7 @@ const {decodePaymentRequest} = require('./lnd_methods');
 const {deleteFailedPayAttempts} = require('./lnd_methods');
 const {deleteFailedPayments} = require('./lnd_methods');
 const {deleteForwardingReputations} = require('./lnd_methods');
+const {deletePayment} = require('./lnd_methods');
 const {deletePayments} = require('./lnd_methods');
 const {diffieHellmanComputeSecret} = require('./lnd_methods');
 const {disableChannel} = require('./lnd_methods');
@@ -107,6 +108,7 @@ const {subscribeToInvoice} = require('./lnd_methods');
 const {subscribeToInvoices} = require('./lnd_methods');
 const {subscribeToOpenRequests} = require('./lnd_methods');
 const {subscribeToPastPayment} = require('./lnd_methods');
+const {subscribeToPastPayments} = require('./lnd_methods');
 const {subscribeToPayViaDetails} = require('./lnd_methods');
 const {subscribeToPayViaRequest} = require('./lnd_methods');
 const {subscribeToPayViaRoutes} = require('./lnd_methods');
@@ -144,6 +146,7 @@ module.exports = {
   deleteFailedPayAttempts,
   deleteFailedPayments,
   deleteForwardingReputations,
+  deletePayment,
   deletePayments,
   disableChannel,
   disconnectWatchtower,
@@ -236,6 +239,7 @@ module.exports = {
   subscribeToInvoices,
   subscribeToOpenRequests,
   subscribeToPastPayment,
+  subscribeToPastPayments,
   subscribeToPayViaDetails,
   subscribeToPayViaRequest,
   subscribeToPayViaRoutes,

package/lnd_methods/index.js

@@ -14,6 +14,7 @@ const {decodePaymentRequest} = require('./offchain');
 const {deleteFailedPayAttempts} = require('./offchain');
 const {deleteFailedPayments} = require('./offchain');
 const {deleteForwardingReputations} = require('./offchain');
+const {deletePayment} = require('./offchain');
 const {deletePayments} = require('./offchain');
 const {diffieHellmanComputeSecret} = require('./signer');
 const {disableChannel} = require('./offchain');
@@ -118,6 +119,7 @@ const {updateChainTransaction} = require('./onchain');
 const {updateConnectedWatchtower} = require('./offchain');
 const {updatePathfindingSettings} = require('./offchain');
 const {updateRoutingFees} = require('./offchain');
+const {verifyAccess} = require('./macaroon');
 const {verifyBackup} = require('./offchain');
 const {verifyBackups} = require('./offchain');
 const {verifyBytesSignature} = require('./signer');
@@ -140,6 +142,7 @@ module.exports = {
   deleteFailedPayAttempts,
   deleteFailedPayments,
   deleteForwardingReputations,
+  deletePayment,
   deletePayments,
   diffieHellmanComputeSecret,
   disableChannel,
@@ -244,6 +247,7 @@ module.exports = {
   updateConnectedWatchtower,
   updatePathfindingSettings,
   updateRoutingFees,
+  verifyAccess,
   verifyBackup,
   verifyBackups,
   verifyBytesSignature,

package/lnd_methods/macaroon/index.js

@@ -1,5 +1,6 @@
 const getAccessIds = require('./get_access_ids');
 const grantAccess = require('./grant_access');
 const revokeAccess = require('./revoke_access');
+const verifyAccess = require('./verify_access');
 
-module.exports = {getAccessIds, grantAccess, revokeAccess};
+module.exports = {getAccessIds, grantAccess, revokeAccess, verifyAccess};

package/lnd_methods/macaroon/verify_access.js

@@ -0,0 +1,85 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const accessDeniedMessage = 'permission denied';
+const asPermission = n => ({action: n.split(':')[1], entity: n.split(':')[0]});
+const base64AsBuffer = base64 => Buffer.from(base64, 'base64');
+const {isArray} = Array;
+const isBoolean = n => n === false || n === true;
+const method = 'checkMacaroonPermissions';
+const notSupported = /unknown/;
+const type = 'default';
+
+/** Verify an access token has a given set of permissions
+
+  Note: this method is not supported in LND versions 0.13.1 and below
+
+  Requires `macaroon:read` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+    macaroon: <Base64 Encoded Macaroon String>
+    permissions: [<Entity:Action String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    is_valid: <Access Token is Valid For Described Permissions Bool>
+  }
+*/
+module.exports = ({lnd, macaroon, permissions}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndApiObjectToVerifyAccess']);
+        }
+
+        if (!macaroon) {
+          return cbk([400, 'ExpectedMacaroonToVerifyAccess']);
+        }
+
+        if (!isArray(permissions)) {
+          return cbk([400, 'ExpectedPermissionsArrayToVerifyAccess']);
+        }
+
+        return cbk();
+      },
+
+      // Check macaroon access
+      check: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          macaroon: base64AsBuffer(macaroon),
+          permissions: permissions.map(permission => asPermission(permission)),
+        },
+        (err, res) => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'VerifyAccessMethodNotSupported']);
+          }
+
+          if (!!err && err.details === accessDeniedMessage) {
+            return cbk(null, {is_valid: false});
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorFromCheckMacaroonMethod', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseFromCheckMacaroonRequest']);
+          }
+
+          if (!isBoolean(res.valid)) {
+            return cbk([503, 'ExpectedValidIndicatorInCheckMacaroonResponse']);
+          }
+
+          return cbk(null, {is_valid: res.valid});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'check'}, cbk));
+  });
+};

package/lnd_methods/offchain/delete_failed_pay_attempts.js

@@ -3,7 +3,11 @@ const {returnResult} = require('asyncjs-util');
 
 const {isLnd} = require('./../../lnd_requests');
 
-const method = 'deleteAllPayments';
+const deleteAllMethod = 'deleteAllPayments';
+const deleteOneMethod = 'deletePayment';
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const notSupported = /unknown/;
 const type = 'default';
 
 /** Delete failed payment attempt records
@@ -12,18 +16,25 @@ const type = 'default';
 
   Method not supported on LND 0.12.1 or below
 
+  `id` is not supported on LND 0.13.1 or below
+
   {
+    [id]: <Delete Only Failed Attempt Records For Payment With Hash Hex String>
     lnd: <Authenticated LND API Object>
   }
 
   @returns via cbk or Promise
 */
-module.exports = ({lnd}, cbk) => {
+module.exports = ({id, lnd}, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!isLnd({lnd, method, type})) {
+        if (!!id && !isHash(id)) {
+          return cbk([400, 'ExpectedPaymentHashToDeleteFailedPayAttempts']);
+        }
+
+        if (!isLnd({lnd, type, method: deleteAllMethod})) {
           return cbk([400, 'ExpectedAuthenticatedLndToDeleteFailedAttempts']);
         }
 
@@ -32,7 +43,17 @@ module.exports = ({lnd}, cbk) => {
 
       // Delete failed payments
       deletePayments: ['validate', ({}, cbk) => {
-        return lnd[type][method]({failed_htlcs_only: true}, err => {
+        const method = !id ? deleteAllMethod : deleteOneMethod;
+
+        return lnd[type][method]({
+          failed_htlcs_only: true,
+          id: !!id ? hexAsBuffer(id) : undefined,
+        },
+        err => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'DeleteFailedPaymentAttemptsMethodNotSupported']);
+          }
+
           if (!!err) {
             return cbk([503, 'UnexpectedErrorDeletingFailedAttempts', {err}]);
           }

package/lnd_methods/offchain/delete_payment.d.ts

@@ -0,0 +1,18 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type DeletePaymentArgs = AuthenticatedLightningArgs<{
+  /** Payment Preimage Hash Hex String */
+  id: string;
+}>;
+
+/**
+ * Delete a payment record
+ *
+ * Requires `offchain:write` permission
+ *
+ * Note: this method is not supported on LND 0.13.1 and below
+ */
+export const deletePayment: AuthenticatedLightningMethod<DeletePaymentArgs>;

package/lnd_methods/offchain/delete_payment.js

@@ -0,0 +1,58 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const hexAsBytes = hex => Buffer.from(hex, 'hex');
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const method = 'deletePayment';
+const notSupported = /unknown/;
+const type = 'default';
+
+/** Delete a payment record
+
+  Requires `offchain:write` permission
+
+  Note: this method is not supported on LND 0.13.1 and below
+
+  {
+    id: <Payment Preimage Hash Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = ({id, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isHash(id)) {
+          return cbk([400, 'ExpectedPaymentHashToDeletePaymentRecord']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToDeletePayment']);
+        }
+
+        return cbk();
+      },
+
+      // Delete all payments
+      deletePayments: ['validate', ({}, cbk) => {
+        return lnd[type][method]({payment_hash: hexAsBytes(id)}, err => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'DeletePaymentMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorDeletingPayment', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/offchain/emit_payment.d.ts

@@ -1,7 +1,7 @@
 import * as events from 'events';
 import {ConfirmedFromPaymentResult} from '../../lnd_responses/confirmed_from_payment';
 import {FailureFromPaymentResult} from '../../lnd_responses/failure_from_payment';
-import {LightningError, PaymentState} from '../../typescript';
+import {EmptyObject, LightningError, PaymentState} from '../../typescript';
 
 export type EmitPaymentArgs = {
   data: {
@@ -14,8 +14,8 @@ export type EmitPaymentConfirmedEvent = ConfirmedFromPaymentResult;
 
 export type EmitPaymentFailedEvent = FailureFromPaymentResult;
 
-export type EmitPaymentPayingEvent = {[key: string]: never};
+export type EmitPaymentPayingEvent = EmptyObject;
 
-export type EmitPaymentError = LightningError<never>;
+export type EmitPaymentError = LightningError<undefined>;
 
 export const emitPayment: (args: EmitPaymentArgs) => boolean | undefined;

package/lnd_methods/offchain/get_payment.d.ts

@@ -28,6 +28,10 @@ export type GetPaymentResult = {
   payment?: {
     /** Confirmed at ISO-8601 Date */
     confirmed_at: string;
+    /** Created at ISO-8601 Date */
+    created_at: string;
+    /** Payment Destination Public Key Hex */
+    destination: string;
     /** Total Fee Millitokens To Pay */
     fee_mtokens: string;
     hops: {
@@ -52,6 +56,8 @@ export type GetPaymentResult = {
     id: string;
     /** Total Millitokens Paid */
     mtokens: string;
+    /** BOLT 11 Payment Request */
+    request?: string;
     /** Payment Forwarding Fee Rounded Up Tokens */
     safe_fee: number;
     /** Payment Tokens Rounded Up */

package/lnd_methods/offchain/get_payment.js

@@ -30,6 +30,8 @@ const type = 'router';
     [is_pending]: <Payment Is Pending Bool>
     [payment]: {
       confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+      created_at: <Payment Created At ISO 8601 Date String>
+      destination: <Payment Destination Hex String>
       fee: <Total Fees Paid Rounded Down Number>
       fee_mtokens: <Total Fee Millitokens Paid String>
       hops: [{
@@ -57,6 +59,7 @@ const type = 'router';
         }]
         mtokens: <Total Millitokens Paid String>
       }]
+      [request]: <BOLT 11 Encoded Payment Request String>
       safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
       safe_tokens: <Payment Tokens Rounded Up Number>
       secret: <Payment Preimage Hex String>

package/lnd_methods/offchain/index.d.ts

@@ -3,6 +3,7 @@ export * from './decode_payment_request';
 export * from './delete_failed_pay_attempts';
 export * from './delete_failed_payments';
 export * from './delete_forwarding_reputations';
+export * from './delete_payment';
 export * from './delete_payments';
 export * from './disable_channel';
 export * from './disconnect_watchtower';
@@ -36,6 +37,7 @@ export * from './subscribe_to_forward_requests';
 export * from './subscribe_to_forwards';
 export * from './subscribe_to_open_requests';
 export * from './subscribe_to_past_payment';
+export * from './subscribe_to_past_payments';
 export * from './subscribe_to_pay_via_details';
 export * from './subscribe_to_pay_via_request';
 export * from './subscribe_to_pay_via_routes';

package/lnd_methods/offchain/index.js

@@ -3,6 +3,7 @@ const decodePaymentRequest = require('./decode_payment_request');
 const deleteFailedPayAttempts = require('./delete_failed_pay_attempts');
 const deleteFailedPayments = require('./delete_failed_payments');
 const deleteForwardingReputations = require('./delete_forwarding_reputations');
+const deletePayment = require('./delete_payment');
 const deletePayments = require('./delete_payments');
 const disableChannel = require('./disable_channel');
 const disconnectWatchtower = require('./disconnect_watchtower');
@@ -53,6 +54,7 @@ module.exports = {
   deleteFailedPayAttempts,
   deleteFailedPayments,
   deleteForwardingReputations,
+  deletePayment,
   deletePayments,
   disableChannel,
   disconnectWatchtower,

package/lnd_methods/offchain/subscribe_to_past_payment.d.ts

@@ -11,6 +11,10 @@ export type SubscribeToPastPaymentArgs = AuthenticatedLightningArgs<{
 export type SubscribeToPastPaymentConfirmedEvent = {
   /** Confirmed at ISO-8601 Date */
   confirmed: string;
+  /** Created at ISO-8601 Date */
+  created_at: string;
+  /** Payment Destination Public Key Hex */
+  destination: string;
   /** Payment Forwarding Fee Rounded Down Tokens */
   fee: number;
   /** Total Fee Millitokens To Pay */
@@ -37,6 +41,8 @@ export type SubscribeToPastPaymentConfirmedEvent = {
   id: string;
   /** Total Millitokens Paid */
   mtokens: string;
+  /** BOLT 11 Payment Request */
+  request?: string;
   /** Payment Forwarding Fee Rounded Up Tokens */
   safe_fee: number;
   /** Payment Tokens Rounded Up */

package/lnd_methods/offchain/subscribe_to_past_payment.js

@@ -41,6 +41,8 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
   @event 'confirmed'
   {
     confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
     fee: <Total Fee Tokens Paid Rounded Down Number>
     fee_mtokens: <Total Fee Millitokens Paid String>
     id: <Payment Hash Hex String>
@@ -63,6 +65,7 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
       safe_tokens: <Total Tokens Paid, Rounded Up Number>
       timeout: <Expiration Block Height Number>
     }]
+    [request]: <BOLT 11 Encoded Payment Request String>
     safe_fee: <Total Fee Tokens Paid Rounded Up Number>
     safe_tokens: <Total Tokens Paid, Rounded Up Number>
     secret: <Payment Preimage Hex String>

package/lnd_methods/offchain/subscribe_to_past_payments.d.ts

@@ -0,0 +1,74 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningSubscription,
+  EmptyObject,
+  LightningError,
+} from '../../typescript';
+
+export type SubscribeToPastPaymentsArgs = AuthenticatedLightningArgs;
+
+export type SubscribeToPastPaymentsErrorEvent = LightningError;
+
+export type SubscribeToPastPaymentsPaymentEvent = {
+  /** Payment Confirmed At ISO 8601 Date String */
+  confirmed_at: string;
+  /** Created at ISO-8601 Date */
+  created_at: string;
+  /** Payment Destination Public Key Hex */
+  destination: string;
+  /** Paid Routing Fee Rounded Down Tokens Number */
+  fee: number;
+  /** Paid Routing Fee in Millitokens String */
+  fee_mtokens: string;
+  /** Payment Preimage Hash String */
+  id: string;
+  /** Millitokens Sent to Destination String */
+  mtokens: string;
+  paths: [
+    {
+      /** Total Fee Millitokens Paid String */
+      fee_mtokens: string;
+      hops: [
+        {
+          /** Standard Format Channel Id String */
+          channel: string;
+          /** Channel Capacity Tokens Number */
+          channel_capacity: number;
+          /** Fee Tokens Rounded Down Number */
+          fee: number;
+          /** Fee Millitokens String */
+          fee_mtokens: string;
+          /** Forward Millitokens String */
+          forward_mtokens: string;
+          /** Public Key Hex String */
+          public_key: string;
+          /** Timeout Block Height Number */
+          timeout: number;
+        }
+      ];
+      /** Total Millitokens Paid String */
+      mtokens: string;
+    }
+  ];
+  /** BOLT 11 Payment Request */
+  request?: string;
+  /** Total Fee Tokens Paid Rounded Up Number */
+  safe_fee: number;
+  /** Total Tokens Paid, Rounded Up Number */
+  safe_tokens: number;
+  /** Payment Preimage Hex String */
+  secret: string;
+  /** Expiration Block Height Number */
+  timeout: number;
+  /** Total Tokens Paid Rounded Down Number */
+  tokens: number;
+};
+
+/**
+ * Subscribe to successful outgoing payments
+ *
+ * Requires `offchain:read` permission
+ *
+ * Note: Method not supported on LND 0.13.1 and below
+ */
+export const subscribeToPastPayments: AuthenticatedLightningSubscription<SubscribeToPastPaymentsArgs>;

package/lnd_methods/offchain/subscribe_to_past_payments.js

@@ -41,6 +41,8 @@ const unknownFailureMessage = '2 UNKNOWN: unknown failure detail type: <nil>';
   @event 'payment'
   {
     confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
     fee: <Paid Routing Fee Rounded Down Tokens Number>
     fee_mtokens: <Paid Routing Fee in Millitokens String>
     id: <Payment Preimage Hash String>
@@ -58,6 +60,7 @@ const unknownFailureMessage = '2 UNKNOWN: unknown failure detail type: <nil>';
       }]
       mtokens: <Total Millitokens Paid String>
     }]
+    [request]: <BOLT 11 Encoded Payment Request String>
     safe_fee: <Total Fee Tokens Paid Rounded Up Number>
     safe_tokens: <Total Tokens Paid, Rounded Up Number>
     secret: <Payment Preimage Hex String>

package/lnd_methods/offchain/subscribe_to_probe_for_route.d.ts

@@ -63,7 +63,7 @@ export type SubscribeToProbeForRouteArgs = AuthenticatedLightningArgs<{
   total_mtokens?: string;
 }>;
 
-export type SubscribeToProbeForRouteErrorEvent = LightningError<never>;
+export type SubscribeToProbeForRouteErrorEvent = LightningError<undefined>;
 
 export type SubscribeToProbeForRouteProbeSuccessEvent = {
   route: {

package/lnd_methods/unauthenticated/get_wallet_status.d.ts

@@ -11,6 +11,9 @@ export type GetWalletStatusResult = {
   /** Is Wallet File Encrypted */
   is_locked?: boolean;
 
+  /** Is Wallet Ready For All RPC Calls */
+  is_ready?: boolean;
+
   /** Is Wallet Starting Up */
   is_starting?: boolean;
 

package/lnd_methods/unauthenticated/get_wallet_status.js

@@ -14,6 +14,8 @@ 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.1 and below
+
   {
     lnd: <Unauthenticated LND API Object>
   }
@@ -23,6 +25,7 @@ const unsupportedMessage = 'unknown service lnrpc.State';
     [is_absent]: <Wallet Not Created Bool>
     [is_active]: <Wallet Is Active Bool>
     [is_locked]: <Wallet File Encrypted And Wallet Not Active Bool>
+    [is_ready]: <Wallet Is Ready For RPC Calls Bool>
     [is_starting]: <Wallet Is Starting Up Bool>
     [is_waiting]: <Wallet Is Waiting To Start Bool>
   }

package/lnd_methods/unauthenticated/subscribe_to_wallet_status.d.ts

@@ -6,7 +6,7 @@ import {
 /** The wallet has yet to be created */
 export type SubscribeToWalletStatusAbsentEvent = EmptyObject;
 
-/** The wallet is activated and ready for all requests */
+/** The wallet is activated and has started working */
 export type SubscribeToWalletStatusActiveEvent = EmptyObject;
 
 export type SubscribeToWalletStatusErrorEvent = Error;
@@ -14,6 +14,9 @@ export type SubscribeToWalletStatusErrorEvent = Error;
 /** The wallet is inactive because it is locked */
 export type SubscribeToWalletStatusLockedEvent = EmptyObject;
 
+/** The wallet is ready for all RPC requests */
+export type SubscribeToWalletStatusReadyEvent = EmptyObject;
+
 /** The wallet is in the process of starting */
 export type SubscribeToWalletStatusStartingEvent = EmptyObject;
 

package/lnd_methods/unauthenticated/subscribe_to_wallet_status.js

@@ -8,6 +8,7 @@ const method = 'subscribeState';
 const stateAbsent = 'NON_EXISTING';
 const stateActive = 'RPC_ACTIVE';
 const stateLocked = 'LOCKED';
+const stateReady = 'SERVER_ACTIVE';
 const stateStarting = 'UNLOCKED';
 const stateWaiting = 'WAITING_TO_START';
 const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
@@ -17,6 +18,8 @@ const type = 'status';
 
   This method is not supported on LND 0.12.1 and below
 
+  `ready` is not supported on LND 0.13.1 and below
+
   {
     lnd: <Unauthenticated LND API Object>
   }
@@ -40,6 +43,9 @@ const type = 'status';
   // The wallet is inactive because it is locked
   @event 'locked'
 
+  // The wallet is ready for all RPC server requests
+  @event 'ready'
+
   // The wallet is in the process of starting
   @event 'starting'
 
@@ -98,6 +104,9 @@ module.exports = ({lnd}) => {
     case stateLocked:
       return emitter.emit('locked', {});
 
+    case stateReady:
+      return emitter.emit('ready', {});
+
     case stateStarting:
       return emitter.emit('starting', {});
 

package/lnd_responses/confirmed_from_payment.js

@@ -6,6 +6,7 @@ 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
 
@@ -65,6 +66,8 @@ const mtokensAsTokens = mtokens => safeTokens({mtokens}).tokens;
   @returns
   {
     confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Public Key Hex String>
     fee: <Total Fee Tokens Paid Rounded Down Number>
     fee_mtokens: <Total Fee Millitokens Paid String>
     hops: [{
@@ -97,6 +100,7 @@ const mtokensAsTokens = mtokens => safeTokens({mtokens}).tokens;
       safe_tokens: <Total Tokens Paid, Rounded Up Number>
       timeout: <Expiration Block Height Number>
     }]
+    [request]: <BOLT 11 Encoded Payment Request String>
     safe_fee: <Total Fee Tokens Paid Rounded Up Number>
     safe_tokens: <Total Tokens Paid, Rounded Up Number>
     secret: <Payment Preimage Hex String>
@@ -109,6 +113,10 @@ module.exports = payment => {
     throw new Error('ExpectedConfirmedPaymentToDeriveConfirmationDetails');
   }
 
+  if (!payment.creation_time_ns) {
+    throw new Error('ExpectedPaymentCreationDateToDerivePaymentDetails');
+  }
+
   if (!payment.fee_msat) {
     throw new Error('ExpectedPaymentFeeMillitokensAmountForPayment');
   }
@@ -141,14 +149,19 @@ module.exports = payment => {
   const [confirmedAt] = successes.map(n => n.confirmed_at).sort().reverse();
   const [success] = successes;
 
+  const [destination] = success.route.hops.map(n => n.public_key).reverse();
+
   return {
+    destination,
     confirmed_at: confirmedAt,
+    created_at: nsAsDate(payment.creation_time_ns).toISOString(),
     fee: safeTokens({mtokens: payment.fee_msat}).tokens,
     fee_mtokens: payment.fee_msat,
     hops: success.route.hops,
     id: payment.payment_hash,
     mtokens: mtokens.toString(),
     paths: successes.map(n => n.route),
+    request: payment.payment_request || undefined,
     safe_fee: safeTokens({mtokens: payment.fee_msat}).safe,
     safe_tokens: safeTokens({mtokens: mtokens.toString()}).safe,
     secret: payment.payment_preimage,

package/lnd_responses/rpc_wallet_state_as_state.js

@@ -1,6 +1,7 @@
 const stateAbsent = 'NON_EXISTING';
 const stateActive = 'RPC_ACTIVE';
 const stateLocked = 'LOCKED';
+const stateReady = 'SERVER_ACTIVE';
 const stateStarting = 'UNLOCKED';
 const stateWaiting = 'WAITING_TO_START';
 
@@ -15,6 +16,7 @@ const stateWaiting = 'WAITING_TO_START';
     [is_absent]: <Wallet Not Created Bool>
     [is_active]: <Wallet Is Active Bool>
     [is_locked]: <Wallet File Encrypted And Wallet Not Active Bool>
+    [is_ready]: <Wallet Is Ready For All RPC Calls Bool>
     [is_starting]: <Wallet Is Starting Up Bool>
     [is_waiting]: <Wallet Is Waiting To Start Bool>
   }
@@ -38,6 +40,9 @@ module.exports = args => {
   case stateLocked:
     return {is_locked: true};
 
+  case stateReady:
+    return {is_active: true, is_ready: true};
+
   case stateStarting:
     return {is_starting: true};
 

package/package.json

@@ -8,9 +8,9 @@
   },
   "dependencies": {
     "@grpc/grpc-js": "1.3.7",
-    "@grpc/proto-loader": "0.6.4",
+    "@grpc/proto-loader": "0.6.5",
     "@types/express": "4.17.13",
-    "@types/node": "16.9.1",
+    "@types/node": "16.9.6",
     "@types/request": "2.48.7",
     "@types/ws": "7.4.7",
     "async": "3.2.1",
@@ -19,7 +19,7 @@
     "bn.js": "5.2.0",
     "body-parser": "1.19.0",
     "bolt07": "1.7.3",
-    "bolt09": "0.1.5",
+    "bolt09": "0.2.0",
     "cbor": "8.0.0",
     "express": "4.17.1",
     "invoices": "2.0.0",
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.4.0"
+  "version": "4.7.1"
 }

package/test/lnd_methods/macaroon/test_verify_access.js

@@ -0,0 +1,101 @@
+const {test} = require('@alexbosworth/tap');
+
+const {verifyAccess} = require('./../../../lnd_methods');
+
+const makeArgs = overrides => {
+  const args = {
+    lnd: {
+      default: {
+        checkMacaroonPermissions: ({}, cbk) => cbk(null, {valid: true}),
+      },
+    },
+    macaroon: Buffer.from('macaroon').toString('base64'),
+    permissions: ['entity:action'],
+  };
+
+  Object.keys(overrides).forEach(k => args[k] = overrides[k]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND is required to verify access',
+    error: [400, 'ExpectedAuthenticatedLndApiObjectToVerifyAccess'],
+  },
+  {
+    args: makeArgs({macaroon: undefined}),
+    description: 'A macaroon is required',
+    error: [400, 'ExpectedMacaroonToVerifyAccess'],
+  },
+  {
+    args: makeArgs({permissions: undefined}),
+    description: 'Permissions to check are required',
+    error: [400, 'ExpectedPermissionsArrayToVerifyAccess'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        default: {
+          checkMacaroonPermissions: ({}, cbk) => cbk({details: 'unknown ser'}),
+        },
+      },
+    }),
+    description: 'Method not supported error returned',
+    error: [501, 'VerifyAccessMethodNotSupported'],
+  },
+  {
+    args: makeArgs({
+      lnd: {
+        default: {
+          checkMacaroonPermissions: ({}, cbk) => cbk({
+            details: 'permission denied',
+          }),
+        },
+      },
+    }),
+    description: 'Method not supported error returned',
+    expected: {is_valid: false},
+  },
+  {
+    args: makeArgs({
+      lnd: {default: {checkMacaroonPermissions: ({}, cbk) => cbk('err')}},
+    }),
+    description: 'Errors are passed back',
+    error: [503, 'UnexpectedErrorFromCheckMacaroonMethod', {err: 'err'}],
+  },
+  {
+    args: makeArgs({
+      lnd: {default: {checkMacaroonPermissions: ({}, cbk) => cbk()}},
+    }),
+    description: 'A response is expected',
+    error: [503, 'ExpectedResponseFromCheckMacaroonRequest'],
+  },
+  {
+    args: makeArgs({
+      lnd: {default: {checkMacaroonPermissions: ({}, cbk) => cbk(null, {})}},
+    }),
+    description: 'A valid attribute is expected',
+    error: [503, 'ExpectedValidIndicatorInCheckMacaroonResponse'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Validity is returned',
+    expected: {is_valid: true},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(() => verifyAccess(args), error, 'Got expected error');
+    } else {
+      const res = await verifyAccess(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/offchain/test_delete_failed_pay_attempts.js

@@ -8,6 +8,24 @@ const tests = [
     description: 'LND object is required',
     error: [400, 'ExpectedAuthenticatedLndToDeleteFailedAttempts'],
   },
+  {
+    args: {id: 1},
+    description: 'A payment id is expected to be a hash',
+    error: [400, 'ExpectedPaymentHashToDeleteFailedPayAttempts'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        default: {
+          deleteAllPayments: ({}, cbk) => cbk(),
+          deletePayment: ({}, cbk) => cbk({details: 'unknown'}),
+        },
+      },
+    },
+    description: 'An unsupported error is returned',
+    error: [501, 'DeleteFailedPaymentAttemptsMethodNotSupported'],
+  },
   {
     args: {lnd: {default: {deleteAllPayments: ({}, cbk) => cbk('err')}}},
     description: 'An unexpected error is returned',

package/test/lnd_methods/offchain/test_delete_payment.js

@@ -0,0 +1,51 @@
+const {test} = require('@alexbosworth/tap');
+
+const {deletePayment} = require('./../../../lnd_methods');
+
+const tests = [
+  {
+    args: {},
+    description: 'An id is required',
+    error: [400, 'ExpectedPaymentHashToDeletePaymentRecord'],
+  },
+  {
+    args: {id: Buffer.alloc(32).toString('hex')},
+    description: 'LND object is required',
+    error: [400, 'ExpectedAuthenticatedLndToDeletePayment'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {default: {deletePayment: ({}, cbk) => cbk({details: 'unknown'})}},
+    },
+    description: 'An unexpected error is returned',
+    error: [501, 'DeletePaymentMethodNotSupported'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {default: {deletePayment: ({}, cbk) => cbk('err')}},
+    },
+    description: 'An unexpected error is returned',
+    error: [503, 'UnexpectedErrorDeletingPayment', {err: 'err'}],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {default: {deletePayment: ({}, cbk) => cbk()}},
+    },
+    description: 'Payments are deleted',
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({deepEqual, end, equal, rejects}) => {
+    if (!!error) {
+      await rejects(deletePayment(args), error, 'Got expected error');
+    } else {
+      await deletePayment(args);
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/offchain/test_delete_payments.js

@@ -15,7 +15,7 @@ const tests = [
   },
   {
     args: {lnd: {default: {deleteAllPayments: ({}, cbk) => cbk()}}},
-    description: 'Payments are deleted',
+    description: 'Payment is deleted',
   },
 ];
 

package/test/lnd_methods/offchain/test_pay_via_payment_details.js

@@ -306,7 +306,7 @@ const tests = [
   {
     args: makeArgs({lnd: makeLnd({data: {status: 'SUCCEEDED'}})}),
     description: 'A payment attempt is in flight',
-    error: [503, 'ExpectedPaymentFeeMillitokensAmountForPayment'],
+    error: [503, 'ExpectedPaymentCreationDateToDerivePaymentDetails'],
   },
 ];
 

package/test/lnd_methods/offchain/test_subscribe_to_past_payments.js

@@ -204,6 +204,8 @@ const tests = [
     description: 'A past payment is emitted',
     expected: {
       confirmed_at: '1970-01-01T00:00:00.000Z',
+      created_at: '1970-01-01T00:00:00.000Z',
+      destination: '000000000000000000000000000000000000000000000000000000000000000000',
       fee: 1,
       fee_mtokens: '1000',
       hops: [
@@ -243,6 +245,7 @@ const tests = [
           total_mtokens: '1000',
         }
       ],
+      request: undefined,
       safe_fee: 1,
       safe_tokens: 2,
       secret: '0000000000000000000000000000000000000000000000000000000000000000',

package/test/lnd_responses/test_confirmed_from_payment.js

@@ -54,6 +54,8 @@ const makeArgs = overrides => {
 const makeExpected = overrides => {
   const expected = {
     confirmed_at: '1970-01-01T00:00:00.000Z',
+    created_at: '1970-01-01T00:00:00.000Z',
+    destination: Buffer.alloc(33).toString('hex'),
     fee: 1,
     fee_mtokens: '1000',
     hops: [{
@@ -87,6 +89,7 @@ const makeExpected = overrides => {
       tokens: 1,
       total_mtokens: '1000',
     }],
+    request: undefined,
     safe_fee: 1,
     safe_tokens: 2,
     secret: Buffer.alloc(32).toString('hex'),

package/test/lnd_responses/test_rpc_wallet_state_as_state.js

@@ -30,6 +30,11 @@ const tests = [
     description: 'Wallet is ready',
     expected: makeExpected({is_active: true}),
   },
+  {
+    args: {state: 'SERVER_ACTIVE'},
+    description: 'Server is ready',
+    expected: makeExpected({is_active: true, is_ready: true}),
+  },
   {
     args: {state: 'LOCKED'},
     description: 'Wallet file is encrypted',

package/test/protos/protos.json

@@ -1,6 +1,6 @@
 {
   "overrides": [
-    ["lightning", 3229],
+    ["lightning", 3330],
     ["router", 100, 171],
     ["walletkit", 3],
     ["walletunlocker", 2]

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

@@ -0,0 +1,15 @@
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {deletePayment} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+const id = '0';
+
+expectError(deletePayment());
+expectError(deletePayment({}));
+expectError(deletePayment({lnd}));
+expectError(deletePayment({id}));
+
+expectType<void>(await deletePayment({lnd, id}));
+
+expectType<void>(deletePayment({lnd, id}, () => {}));

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

@@ -0,0 +1,11 @@
+import * as events from 'events';
+import {expectError, expectType} from 'tsd';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {subscribeToPastPayments} from '../../lnd_methods';
+
+const lnd = {} as AuthenticatedLnd;
+
+expectError(subscribeToPastPayments());
+expectError(subscribeToPastPayments({}));
+
+expectType<events.EventEmitter>(subscribeToPastPayments({lnd}));

package/typescript/shared.d.ts

@@ -13,7 +13,9 @@ export type UnauthenticatedLightningArgs<TArgs = undefined> =
     ? {lnd: UnauthenticatedLnd}
     : TArgs & {lnd: UnauthenticatedLnd};
 
-export type LightningError<TDetails = any> = [number, string, TDetails];
+export type LightningError<TError = {err: Error}> = TError extends undefined
+  ? [number, string]
+  : [number, string, TError];
 
 export type LightningCallback<TResult = void, TErrorDetails = any> = (
   error: LightningError<TErrorDetails> | undefined | null,