lightning 6.5.0 → 6.7.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Versions
 
+## 6.7.0
+
+- `getBlock`: add `height` to allow fetching a raw block at a specified height
+
+## 6.6.0
+
+- `getBlock`: Add method to get a raw block from the chain
+
 ## 6.5.0
 
 - `getFailedPayments`, `getInvoices`, `getPayments`, `getPendingPayments`: add

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/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/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_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_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: {

package/lnd_methods/onchain/get_block.js

@@ -0,0 +1,149 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const errorNotFound = '-5: Block not found';
+const errorUnknownMethod = 'unknown service chainrpc.ChainKit';
+const hexAsReversedBuffer = hex => Buffer.from(hex, 'hex').reverse();
+const {isBuffer} = Buffer;
+const isNumber = n => !isNaN(n);
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const method = 'getBlock';
+const type = 'blocks';
+
+/** Get a block in the chain
+
+  This method requires LND built with `chainkit` build tag
+
+  Requires `onchain:read` permission
+
+  This method is not supported on LND 0.15.5 and below
+
+  {
+    [height]: <Block Height Number>
+    [id]: <Block Hash Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    block: <Raw Block Bytes Hex String>
+  }
+*/
+module.exports = ({height, id, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (height !== undefined && !isNumber(height)) {
+          return cbk([400, 'ExpectedNumericBlockHeightOfBlockToRetrieve']);
+        }
+
+        if (!!id && !isHash(id)) {
+          return cbk([400, 'ExpectedIdentifyingBlockHashOfBlockToRetrieve']);
+        }
+
+        if (height !== undefined && !!id) {
+          return cbk([400, 'ExpectedEitherHeightOrIdNotBoth']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToRetrieveBlock']);
+        }
+
+        return cbk();
+      },
+
+      // Get the best block in the chain to find the default block hash
+      getTip: ['validate', ({}, cbk) => {
+        // Exit early when a specific block is requested
+        if (height !== undefined || !!id) {
+          return cbk();
+        }
+
+        return lnd[type].getBestBlock({}, (err, res) => {
+          if (!!err && err.details === errorUnknownMethod) {
+            return cbk([501, 'GetBestBlockMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorGettingBestBlock', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForBestBlockRequest']);
+          }
+
+          if (!isBuffer(res.block_hash)) {
+            return cbk([503, 'ExpectedChainTipInfoInGetBestBlockResponse']);
+          }
+
+          return cbk(null, res.block_hash);
+        });
+      }],
+
+      // Get the hash of the block to fetch
+      getHash: ['getTip', ({getTip}, cbk) => {
+        // Exit early when the hash to get is specified
+        if (!!id) {
+          return cbk(null, hexAsReversedBuffer(id));
+        }
+
+        // Exit early when the hash comes from the chain tip
+        if (!!getTip) {
+          return cbk(null, getTip);
+        }
+
+        return lnd[type].getBlockHash({block_height: height}, (err, res) => {
+          if (!!err && err.details === errorUnknownMethod) {
+            return cbk([501, 'GetBlockHashMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorGettingBlockHash', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForGetBlockHashRequest']);
+          }
+
+          if (!isBuffer(res.block_hash)) {
+            return cbk([503, 'ExpectedBlockHashInGetBlockHashResponse']);
+          }
+
+          return cbk(null, res.block_hash);
+        });
+      }],
+
+      // Get the block
+      getBlock: ['getHash', ({getHash}, cbk) => {
+        return lnd[type][method]({block_hash: getHash}, (err, res) => {
+          if (!!err && err.details === errorNotFound) {
+            return cbk([404, 'BlockNotFound']);
+          }
+
+          if (!!err && err.details === errorUnknownMethod) {
+            return cbk([501, 'GetBlockMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorWhenGettingChainBlock', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForChainBlockRequest']);
+          }
+
+          if (!isBuffer(res.raw_block)) {
+            return cbk([503, 'ExpectedRawBlockInChainBlockResponse']);
+          }
+
+          return cbk(null, {block: bufferAsHex(res.raw_block)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getBlock'}, cbk));
+  });
+};

package/lnd_methods/onchain/index.js

@@ -3,6 +3,7 @@ const cancelPendingChannel = require('./cancel_pending_channel');
 const closeChannel = require('./close_channel');
 const fundPendingChannels = require('./fund_pending_channels');
 const fundPsbt = require('./fund_psbt');
+const getBlock = require('./get_block');
 const getChainBalance = require('./get_chain_balance');
 const getChainFeeEstimate = require('./get_chain_fee_estimate');
 const getChainFeeRate = require('./get_chain_fee_rate');
@@ -37,6 +38,7 @@ module.exports = {
   closeChannel,
   fundPendingChannels,
   fundPsbt,
+  getBlock,
   getChainBalance,
   getChainFeeEstimate,
   getChainFeeRate,

package/package.json

@@ -9,8 +9,8 @@
   "dependencies": {
     "@grpc/grpc-js": "1.8.0",
     "@grpc/proto-loader": "0.7.4",
-    "@types/express": "4.17.14",
-    "@types/node": "18.11.13",
+    "@types/express": "4.17.15",
+    "@types/node": "18.11.16",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.3",
     "async": "3.2.4",
@@ -26,7 +26,7 @@
     "invoices": "2.2.2",
     "psbt": "2.7.1",
     "tiny-secp256k1": "2.2.1",
-    "type-fest": "3.3.0"
+    "type-fest": "3.4.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "6.5.0"
+  "version": "6.7.0"
 }

package/test/lnd_grpc/test_authenticated_lnd_grpc.js

@@ -4,6 +4,7 @@ const {authenticatedLndGrpc} = require('./../../');
 
 const expectedServices = [
   'autopilot',
+  'blocks',
   'chain',
   'default',
   'invoices',

package/test/lnd_methods/onchain/test_get_block.js

@@ -0,0 +1,231 @@
+const {test} = require('@alexbosworth/tap');
+
+const {getBlock} = require('./../../../lnd_methods');
+
+const tests = [
+  {
+    args: {height: 'invalid'},
+    description: 'A valid height is expected to get a block',
+    error: [400, 'ExpectedNumericBlockHeightOfBlockToRetrieve'],
+  },
+  {
+    args: {id: 'invalid'},
+    description: 'A valid id is expected to get a block',
+    error: [400, 'ExpectedIdentifyingBlockHashOfBlockToRetrieve'],
+  },
+  {
+    args: {height: 1, id: Buffer.alloc(32).toString('hex')},
+    description: 'Only a height or an id is required',
+    error: [400, 'ExpectedEitherHeightOrIdNotBoth'],
+  },
+  {
+    args: {id: Buffer.alloc(32).toString('hex')},
+    description: 'An lnd object is required to get a block',
+    error: [400, 'ExpectedAuthenticatedLndToRetrieveBlock'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk({
+            details: 'unknown service chainrpc.ChainKit',
+          }),
+          getBlock: ({}, cbk) => cbk('err'),
+        },
+      },
+    },
+    description: 'An unsupported error is returned',
+    error: [501, 'GetBestBlockMethodNotSupported'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk('err'),
+          getBlock: ({}, cbk) => cbk('getBlockErr'),
+        },
+      },
+    },
+    description: 'An error is returned',
+    error: [503, 'UnexpectedErrorGettingBestBlock', {err: 'err'}],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(),
+          getBlock: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An error is returned when there is no best block result',
+    error: [503, 'ExpectedResponseForBestBlockRequest'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(null, {}),
+          getBlock: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An error is returned when there is no result info',
+    error: [503, 'ExpectedChainTipInfoInGetBestBlockResponse'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(),
+          getBlockHash: ({}, cbk) => cbk({
+            details: 'unknown service chainrpc.ChainKit',
+          }),
+        },
+      },
+    },
+    description: 'An error is returned when get hash for height unsupported',
+    error: [501, 'GetBlockHashMethodNotSupported'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(),
+          getBlockHash: ({}, cbk) => cbk('err'),
+        },
+      },
+    },
+    description: 'An unexpected error for getting block hash is returned',
+    error: [503, 'UnexpectedErrorGettingBlockHash', {err: 'err'}],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(),
+          getBlockHash: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'A result is expected for getting a block hash',
+    error: [503, 'ExpectedResponseForGetBlockHashRequest'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(),
+          getBlockHash: ({}, cbk) => cbk(null, {}),
+        },
+      },
+    },
+    description: 'A result hash is expected for getting a block hash',
+    error: [503, 'ExpectedBlockHashInGetBlockHashResponse'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk({details: '-5: Block not found'}),
+        },
+      },
+    },
+    description: 'An error is returned when a block is not found',
+    error: [404, 'BlockNotFound'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk({
+            details: 'unknown service chainrpc.ChainKit',
+          }),
+        },
+      },
+    },
+    description: 'An error is returned when the method is not supported',
+    error: [501, 'GetBlockMethodNotSupported'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlock: ({}, cbk) => cbk('err')}},
+    },
+    description: 'An error is returned',
+    error: [503, 'UnexpectedErrorWhenGettingChainBlock', {err: 'err'}],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlock: ({}, cbk) => cbk()}},
+    },
+    description: 'A result is expected',
+    error: [503, 'ExpectedResponseForChainBlockRequest'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlock: ({}, cbk) => cbk(null, {})}},
+    },
+    description: 'A resulting block is expected',
+    error: [503, 'ExpectedRawBlockInChainBlockResponse'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(null, {block_hash: Buffer.alloc(1)}),
+          getBlock: ({}, cbk) => cbk(null, {raw_block: Buffer.alloc(1)}),
+        },
+      },
+    },
+    description: 'The chain tip block is returned',
+    expected: {block: '00'},
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(null, {raw_block: Buffer.alloc(1)}),
+          getBlockHash: ({}, cbk) => cbk(null, {block_hash: Buffer.alloc(1)}),
+        },
+      },
+    },
+    description: 'A block at a height is returned',
+    expected: {block: '00'},
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlock: ({}, cbk) => cbk(null, {raw_block: Buffer.alloc(1)}),
+        },
+      },
+    },
+    description: 'A block is returned',
+    expected: {block: '00'},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({deepEqual, end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(() => getBlock(args), error, 'Got expected error');
+    } else {
+      const res = await getBlock(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/typescript/shared.d.ts

@@ -94,3 +94,10 @@ export type PaginationArgs = MergeExclusive<
     token?: string;
   }
 >;
+
+export type DateRangeFilterArgs = {
+  /** Creation Date After or Equal to ISO 8601 Date String */
+  created_after?: string;
+  /** Creation Date Before or Equal to ISO 8601 Date String */
+  created_before?: string;
+};