lightning 6.4.1 → 6.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Versions
 
+## 6.6.0
+
+- `getBlock`: Add method to get a raw block from the chain
+
+## 6.5.0
+
+- `getFailedPayments`, `getInvoices`, `getPayments`, `getPendingPayments`: add
+    support for date based filtering with `created_after` and `created_before`
+    arguments
+
 ## 6.4.1
 
 - `subscribeToRpcRequests`: `open_channel_request` add support for

package/README.md

@@ -139,6 +139,7 @@ variables set:
     specific channel.
 - [getBackups](https://github.com/alexbosworth/ln-service#getbackups): Get recovery details for
     all channels.
+- [getBlock](https://github.com/alexbosworth/ln-service#getblock): Get a block
 - [getChainBalance](https://github.com/alexbosworth/ln-service#getchainbalance): Get the amount
     of on-chain funds.
 - [getChainFeeEstimate](https://github.com/alexbosworth/ln-service#getchainfeeestimate):

package/grpc/grpc_services.json

@@ -4,6 +4,7 @@
   "maxReceiveMessageLength": 924288000,
   "packageTypes": {
     "Autopilot": "autopilotrpc",
+    "ChainKit": "chainrpc",
     "ChainNotifier": "chainrpc",
     "Invoices": "invoicesrpc",
     "Lightning": "lnrpc",
@@ -19,6 +20,7 @@
   },
   "protoFiles": {
     "Autopilot": "autopilot.proto",
+    "ChainKit": "chainkit.proto",
     "ChainNotifier": "chainnotifier.proto",
     "Invoices": "invoices.proto",
     "Lightning": "lightning.proto",
@@ -35,6 +37,7 @@
   "protosDir": "../grpc/protos",
   "serviceTypes": {
     "autopilot": "Autopilot",
+    "blocks": "ChainKit",
     "chain": "ChainNotifier",
     "default": "Lightning",
     "invoices": "Invoices",

package/grpc/protos/chainkit.proto

@@ -0,0 +1,59 @@
+syntax = "proto3";
+
+package chainrpc;
+
+option go_package = "github.com/lightningnetwork/lnd/lnrpc/chainrpc";
+
+// ChainKit is a service that can be used to get information from the
+// chain backend.
+service ChainKit {
+    /* lncli: `chain getblock`
+    GetBlock returns a block given the corresponding block hash.
+    */
+    rpc GetBlock (GetBlockRequest) returns (GetBlockResponse);
+
+    /* lncli: `chain getbestblock`
+    GetBestBlock returns the block hash and current height from the valid
+    most-work chain.
+    */
+    rpc GetBestBlock (GetBestBlockRequest) returns (GetBestBlockResponse);
+
+    /* lncli: `chain getblockhash`
+    GetBlockHash returns the hash of the block in the best blockchain
+    at the given height.
+    */
+    rpc GetBlockHash (GetBlockHashRequest) returns (GetBlockHashResponse);
+}
+
+message GetBlockRequest {
+    // The hash of the requested block.
+    bytes block_hash = 1;
+}
+
+// TODO(ffranr): The neutrino GetBlock response includes many
+// additional helpful fields. Consider adding them here also.
+message GetBlockResponse {
+    // The raw bytes of the requested block.
+    bytes raw_block = 1;
+}
+
+message GetBestBlockRequest {
+}
+
+message GetBestBlockResponse {
+    // The hash of the best block.
+    bytes block_hash = 1;
+
+    // The height of the best block.
+    int32 block_height = 2;
+}
+
+message GetBlockHashRequest {
+    // Block height of the target best chain block.
+    int64 block_height = 1;
+}
+
+message GetBlockHashResponse {
+    // The hash of the best block at the specified height.
+    bytes block_hash = 1;
+}

package/grpc/protos/lightning.proto

@@ -3351,7 +3351,7 @@ message Invoice {
     int64 value_msat = 23;
 
     /*
-    Whether this invoice has been fulfilled
+    Whether this invoice has been fulfilled.
 
     The field is deprecated. Use the state field instead (compare to SETTLED).
     */
@@ -3359,12 +3359,14 @@ message Invoice {
 
     /*
     When this invoice was created.
+    Measured in seconds since the unix epoch.
     Note: Output only, don't specify for creating an invoice.
     */
     int64 creation_date = 7;
 
     /*
     When this invoice was settled.
+    Measured in seconds since the unix epoch.
     Note: Output only, don't specify for creating an invoice.
     */
     int64 settle_date = 8;
@@ -3631,7 +3633,16 @@ message ListInvoiceRequest {
     specified index offset. This can be used to paginate backwards.
     */
     bool reversed = 6;
+
+    // If set, returns all invoices with a creation date greater than or equal
+    // to it. Measured in seconds since the unix epoch.
+    uint64 creation_date_start = 7;
+
+    // If set, returns all invoices with a creation date less than or equal to
+    // it. Measured in seconds since the unix epoch.
+    uint64 creation_date_end = 8;
 }
+
 message ListInvoiceResponse {
     /*
     A list of invoices from the time slice of the time series specified in the
@@ -3830,6 +3841,14 @@ message ListPaymentsRequest {
     of payments, as all of them have to be iterated through to be counted.
     */
     bool count_total_payments = 5;
+
+    // If set, returns all invoices with a creation date greater than or equal
+    // to it. Measured in seconds since the unix epoch.
+    uint64 creation_date_start = 6;
+
+    // If set, returns all invoices with a creation date less than or equal to
+    // it. Measured in seconds since the unix epoch.
+    uint64 creation_date_end = 7;
 }
 
 message ListPaymentsResponse {

package/index.js

@@ -32,6 +32,7 @@ const {getAccessIds} = require('./lnd_methods');
 const {getAutopilot} = require('./lnd_methods');
 const {getBackup} = require('./lnd_methods');
 const {getBackups} = require('./lnd_methods');
+const {getBlock} = require('./lnd_methods');
 const {getChainBalance} = require('./lnd_methods');
 const {getChainFeeEstimate} = require('./lnd_methods');
 const {getChainFeeRate} = require('./lnd_methods');
@@ -182,6 +183,7 @@ module.exports = {
   getAutopilot,
   getBackup,
   getBackups,
+  getBlock,
   getChainBalance,
   getChainFeeEstimate,
   getChainFeeRate,

package/lnd_methods/index.js

@@ -30,6 +30,7 @@ const {getAccessIds} = require('./macaroon');
 const {getAutopilot} = require('./info');
 const {getBackup} = require('./offchain');
 const {getBackups} = require('./offchain');
+const {getBlock} = require('./onchain');
 const {getChainBalance} = require('./onchain');
 const {getChainFeeEstimate} = require('./onchain');
 const {getChainFeeRate} = require('./onchain');
@@ -176,6 +177,7 @@ module.exports = {
   getAutopilot,
   getBackup,
   getBackups,
+  getBlock,
   getChainBalance,
   getChainFeeEstimate,
   getChainFeeRate,

package/lnd_methods/invoices/get_invoices.d.ts

@@ -1,6 +1,7 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  DateRangeFilterArgs,
   PaginationArgs,
 } from '../../typescript';
 
@@ -8,7 +9,7 @@ export type GetInvoicesArgs = AuthenticatedLightningArgs<
   PaginationArgs & {
     /** Omit Canceled and Settled Invoices Bool */
     is_unconfirmed?: boolean;
-  }
+  } & DateRangeFilterArgs
 >;
 
 export type GetInvoicesResult = {

package/lnd_methods/invoices/get_invoices.js

@@ -1,5 +1,3 @@
-const {createHash} = require('crypto');
-
 const asyncAuto = require('async/auto');
 const asyncRetry = require('async/retry');
 const {returnResult} = require('asyncjs-util');
@@ -9,6 +7,8 @@ const {isLnd} = require('./../../lnd_requests');
 const {rpcInvoiceAsInvoice} = require('./../../lnd_responses');
 const {sortBy} = require('./../../arrays');
 
+const asStart = n => !!n ? Math.floor(new Date(n).getTime() / 1e3) : undefined;
+const asEnd = n => !!n ? Math.ceil(new Date(n).getTime() / 1e3) : undefined;
 const createdAtSort = array => sortBy({array, attribute: 'created_at'});
 const defaultLimit = 100;
 const {isArray} = Array;
@@ -27,7 +27,12 @@ const type = 'default';
 
   Invoice `payment` is not supported on LND 0.11.1 and below
 
+  `created_after` is not supported on LND 0.15.5 and below
+  `created_before` is not supported on LND 0.15.5 and below
+
   {
+    [created_after]: <Creation Date After or Equal to ISO 8601 Date String>
+    [created_before]: <Creation Date Before or Equal to ISO 8601 Date String>
     [is_unconfirmed]: <Omit Canceled and Settled Invoices Bool>
     [limit]: <Page Result Limit Number>
     lnd: <Authenticated LND API Object>
@@ -106,16 +111,20 @@ module.exports = (args, cbk) => {
 
       // Get the list of invoices
       listInvoices: ['validate', ({}, cbk) => {
+        let after = asStart(args.created_after);
+        let before = asEnd(args.created_before);
+        let limit = args.limit || defaultLimit;
         let offset;
-        let resultsLimit = args.limit || defaultLimit;
 
         // When there is a token, parse it out into an offset and a limit
         if (!!args.token) {
           try {
             const pagingToken = parse(args.token);
 
+            after = pagingToken.after;
+            before = pagingToken.before;
             offset = pagingToken.offset;
-            resultsLimit = pagingToken.limit;
+            limit = pagingToken.limit;
           } catch (err) {
             return cbk([400, 'ExpectedValidPagingTokenForInvoicesReq', {err}]);
           }
@@ -123,8 +132,10 @@ module.exports = (args, cbk) => {
 
         return asyncRetry({}, cbk => {
           return args.lnd[type][method]({
+            creation_date_start: after,
+            creation_date_end: before,
             index_offset: offset || Number(),
-            num_max_invoices: resultsLimit,
+            num_max_invoices: limit,
             pending_only: args.is_unconfirmed === true || undefined,
             reversed: true,
           },
@@ -151,7 +162,7 @@ module.exports = (args, cbk) => {
 
             const offset = Number(res.first_index_offset);
 
-            const token = stringify({offset, limit: resultsLimit});
+            const token = stringify({after, before, limit, offset});
 
             return cbk(null, {
               invoices: res.invoices,

package/lnd_methods/macaroon/methods.json

@@ -121,6 +121,10 @@
     "method": "ExportAllChannelBackups",
     "type": "default"
   },
+  "getBlock": {
+    "method": "GetBlock",
+    "type": "blocks"
+  },
   "getChainBalance": {
     "method": "WalletBalance",
     "type": "default"

package/lnd_methods/macaroon/subscribe_to_rpc_requests.d.ts

@@ -77,6 +77,10 @@ export type SubscribeToRpcRequestsOpenChannelRequestEvent =
     partner_public_key: string;
     /** Peer Output CSV Delay Number */
     partner_csv_delay?: number;
+    /** Routing Base Fee Millitokens Charged String */
+    base_fee_mtokens?: string;
+    /** Routing Fee Rate In Millitokens Per Million Number */
+    fee_rate?: number;
   }>;
 
 /** A pay to route request was intercepted: by default it will be rejected */

package/lnd_methods/offchain/get_failed_payments.d.ts

@@ -1,10 +1,13 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  DateRangeFilterArgs,
   PaginationArgs,
 } from '../../typescript';
 
-export type GetFailedPaymentsArgs = AuthenticatedLightningArgs<PaginationArgs>;
+export type GetFailedPaymentsArgs = AuthenticatedLightningArgs<
+  PaginationArgs & DateRangeFilterArgs
+>;
 
 export type GetFailedPaymentsResult = {
   payments: {

package/lnd_methods/offchain/get_failed_payments.js

@@ -2,23 +2,21 @@ 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 listPayments = require('./list_payments');
 
-const defaultLimit = 250;
-const {isArray} = Array;
-const isFailed = payment => !!payment && payment.status === 'FAILED';
-const lastPageFirstIndexOffset = 1;
 const method = 'listPayments';
-const {parse} = JSON;
-const {stringify} = JSON;
 const type = 'default';
 
 /** Get failed payments made through channels.
 
   Requires `offchain:read` permission
 
+  `created_after` is not supported on LND 0.15.5 and below
+  `created_before` is not supported on LND 0.15.5 and below
+
   {
+    [created_after]: <Creation Date After or Equal to ISO 8601 Date String>
+    [created_before]: <Creation Date Before or Equal to ISO 8601 Date String>
     [limit]: <Page Result Limit Number>
     lnd: <Authenticated LND API Object>
     [token]: <Opaque Paging Token String>
@@ -96,16 +94,16 @@ const type = 'default';
     [next]: <Next Opaque Paging Token String>
   }
 */
-module.exports = ({limit, lnd, token}, cbk) => {
+module.exports = (args, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!!limit && !!token) {
+        if (!!args.limit && !!args.token) {
           return cbk([400, 'ExpectedNoLimitWhenPagingPayFailuresWithToken']);
         }
 
-        if (!isLnd({lnd, method, type})) {
+        if (!isLnd({method, type, lnd: args.lnd})) {
           return cbk([400, 'ExpectedLndForGetFailedPaymentsRequest']);
         }
 
@@ -114,79 +112,17 @@ module.exports = ({limit, lnd, token}, 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,
+        return listPayments({
+          created_after: args.created_after,
+          created_before: args.created_before,
+          is_failed: true,
+          limit: args.limit,
+          lnd: args.lnd,
+          token: args.token,
         },
-        (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(),
-        });
+        cbk);
       }],
     },
-    returnResult({reject, resolve, of: 'payments'}, cbk));
+    returnResult({reject, resolve, of: 'listPayments'}, cbk));
   });
 };

package/lnd_methods/offchain/get_payment.d.ts

@@ -91,7 +91,7 @@ export type GetPaymentResult = {
       tokens: number;
       /** Total Millitokens Paid On All Paths */
       total_mtokens: string;
-    }[]
+    }[];
     /** BOLT 11 Payment Request */
     request?: string;
     /** Payment Forwarding Fee Rounded Up Tokens */
@@ -147,7 +147,7 @@ export type GetPaymentResult = {
       tokens: number;
       /** Total Millitokens Pending */
       total_mtokens: string;
-    }[]
+    }[];
     /** BOLT 11 Payment Request */
     request?: string;
     /** Payment Tokens Rounded Up */

package/lnd_methods/offchain/get_payments.d.ts

@@ -1,10 +1,13 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  DateRangeFilterArgs,
   PaginationArgs,
 } from '../../typescript';
 
-export type GetPaymentsArgs = AuthenticatedLightningArgs<PaginationArgs>;
+export type GetPaymentsArgs = AuthenticatedLightningArgs<
+  PaginationArgs & DateRangeFilterArgs
+>;
 
 export type GetPaymentsResult = {
   payments: {

package/lnd_methods/offchain/get_payments.js

@@ -2,22 +2,21 @@ 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 listPayments = require('./list_payments');
 
-const defaultLimit = 250;
-const {isArray} = Array;
-const lastPageFirstIndexOffset = 1;
 const method = 'listPayments';
-const {parse} = JSON;
-const {stringify} = JSON;
 const type = 'default';
 
 /** Get payments made through channels.
 
   Requires `offchain:read` permission
 
+  `created_after` is not supported on LND 0.15.5 and below
+  `created_before` is not supported on LND 0.15.5 and below
+
   {
+    [created_after]: <Creation Date After or Equal to ISO 8601 Date String>
+    [created_before]: <Creation Date Before or Equal to ISO 8601 Date String>
     [limit]: <Page Result Limit Number>
     lnd: <Authenticated LND API Object>
     [token]: <Opaque Paging Token String>
@@ -101,16 +100,16 @@ const type = 'default';
     [next]: <Next Opaque Paging Token String>
   }
 */
-module.exports = ({limit, lnd, token}, cbk) => {
+module.exports = (args, cbk) => {
   return new Promise((resolve, reject) => {
     return asyncAuto({
       // Check arguments
       validate: cbk => {
-        if (!!limit && !!token) {
+        if (!!args.limit && !!args.token) {
           return cbk([400, 'UnexpectedLimitWhenPagingPaymentsWithToken']);
         }
 
-        if (!isLnd({lnd, method, type})) {
+        if (!isLnd({method, type, lnd: args.lnd})) {
           return cbk([400, 'ExpectedLndForGetPaymentsRequest']);
         }
 
@@ -119,79 +118,16 @@ module.exports = ({limit, lnd, token}, 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, 'ExpectedValidPagingTokenForPaymentReq', {err}]);
-          }
-        }
-
-        return lnd[type][method]({
-          include_incomplete: false,
-          index_offset: offset || Number(),
-          max_payments: resultsLimit,
-          reversed: true,
+        return listPayments({
+          created_after: args.created_after,
+          created_before: args.created_before,
+          limit: args.limit,
+          lnd: args.lnd,
+          token: args.token,
         },
-        (err, res) => {
-          if (!!err) {
-            return cbk([503, 'UnexpectedGetPaymentsError', {err}]);
-          }
-
-          if (!res || !isArray(res.payments)) {
-            return cbk([503, 'ExpectedPaymentsInListPaymentsResponse']);
-          }
-
-          if (typeof res.last_index_offset !== 'string') {
-            return cbk([503, 'ExpectedLastIndexOffsetWhenRequestingPayments']);
-          }
-
-          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,
-            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 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(),
-        });
+        cbk);
       }],
     },
-    returnResult({reject, resolve, of: 'payments'}, cbk));
+    returnResult({reject, resolve, of: 'listPayments'}, cbk));
   });
 };

package/lnd_methods/offchain/get_pending_payments.d.ts

@@ -1,10 +1,13 @@
 import {
   AuthenticatedLightningArgs,
   AuthenticatedLightningMethod,
+  DateRangeFilterArgs,
   PaginationArgs,
 } from '../../typescript';
 
-export type GetPendingPaymentsArgs = AuthenticatedLightningArgs<PaginationArgs>;
+export type GetPendingPaymentsArgs = AuthenticatedLightningArgs<
+  PaginationArgs & DateRangeFilterArgs
+>;
 
 export type GetPendingPaymentsResult = {
   payments: {