lightning 10.0.1 → 10.1.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 10.1.1
+
+- `getBlockHeader`: Add method to get the header portion of a block
+
 ## 10.0.1
 
 - Add support for LND 0.17.0-beta

package/README.md

@@ -143,6 +143,8 @@ variables set:
 - [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
+- [getBlockHeader](https://github.com/alexbosworth/ln-service#getblockheader):
+    Get a block header
 - [getChainAddresses](https://github.com/alexbosworth/ln-service#getchainaddresses):
     Get a list of created chain addresses
 - [getChainBalance](https://github.com/alexbosworth/ln-service#getchainbalance): Get the amount

package/grpc/protos/chainkit.proto

@@ -12,6 +12,11 @@ service ChainKit {
     */
     rpc GetBlock (GetBlockRequest) returns (GetBlockResponse);
 
+    /* lncli: `chain getblockheader`
+    GetBlockHeader returns a block header with a particular block hash.
+    */
+    rpc GetBlockHeader (GetBlockHeaderRequest) returns (GetBlockHeaderResponse);
+
     /* lncli: `chain getbestblock`
     GetBestBlock returns the block hash and current height from the valid
     most-work chain.
@@ -37,6 +42,16 @@ message GetBlockResponse {
     bytes raw_block = 1;
 }
 
+message GetBlockHeaderRequest {
+    // The hash of the block with the requested header.
+    bytes block_hash = 1;
+}
+
+message GetBlockHeaderResponse {
+    // The header of the block with the requested hash.
+    bytes raw_block_header = 1;
+}
+
 message GetBestBlockRequest {
 }
 

package/index.js

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

package/lnd_methods/index.js

@@ -31,6 +31,7 @@ const {getAutopilot} = require('./info');
 const {getBackup} = require('./offchain');
 const {getBackups} = require('./offchain');
 const {getBlock} = require('./onchain');
+const {getBlockHeader} = require('./onchain');
 const {getChainAddresses} = require('./onchain');
 const {getChainBalance} = require('./onchain');
 const {getChainFeeEstimate} = require('./onchain');
@@ -181,6 +182,7 @@ module.exports = {
   getBackup,
   getBackups,
   getBlock,
+  getBlockHeader,
   getChainAddresses,
   getChainBalance,
   getChainFeeEstimate,

package/lnd_methods/macaroon/methods.json

@@ -125,6 +125,10 @@
     "methods": ["GetBestBlock", "GetBlock", "GetBlockHash"],
     "type": "blocks"
   },
+  "getBlockHeader": {
+    "methods": ["GetBestBlock", "GetBlockHash", "GetBlockHeader"],
+    "type": "blocks"
+  },
   "getChainAddresses": {
     "method": "ListAddresses",
     "type": "wallet"

package/lnd_methods/onchain/get_block.d.ts

@@ -25,7 +25,7 @@ export type GetBlockResult = {
 /**
  * Get a block in the chain
  *
- * This method requires LND built with `chainkit` build tag
+ * This method requires LND built with `chainrpc` build tag
  *
  * Requires `onchain:read` permission
  *

package/lnd_methods/onchain/get_block.js

@@ -15,7 +15,7 @@ const type = 'blocks';
 
 /** Get a block in the chain
 
-  This method requires LND built with `chainkit` build tag
+  This method requires LND built with `chainrpc` build tag
 
   Requires `onchain:read` permission
 

package/lnd_methods/onchain/get_block_header.d.ts

@@ -0,0 +1,37 @@
+import type {MergeExclusive} from 'type-fest';
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type GetBlockHeaderArgs = AuthenticatedLightningArgs<
+  MergeExclusive<
+    {
+      /** Block Height Number */
+      height: number;
+    },
+    {
+      /** Block Hash Hex String */
+      id: string;
+    }
+  >
+>;
+
+export type GetBlockHeaderResult = {
+  /** Raw Block Header Bytes Hex String */
+  header: string;
+};
+
+/**
+ * Get a block header in the chain
+ *
+ * This method requires LND built with `chainrpc` build tag
+ *
+ * Requires `onchain:read` permission
+ *
+ * This method is not supported on LND 0.17.0 and below
+ */
+export const getBlockHeader: AuthenticatedLightningMethod<
+  GetBlockHeaderArgs,
+  GetBlockHeaderResult
+>;

package/lnd_methods/onchain/get_block_header.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 method GetBlockHeader for 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 = 'getBlockHeader';
+const type = 'blocks';
+
+/** Get a block header in the best chain
+
+  This method requires LND built with `chainrpc` build tag
+
+  Requires `onchain:read` permission
+
+  This method is not supported on LND 0.17.0 and below
+
+  {
+    [height]: <Block Height Number>
+    [id]: <Block Hash Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    header: <Raw Block Header 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, 'ExpectedNumericBlockHeightOfHeaderToRetrieve']);
+        }
+
+        if (!!id && !isHash(id)) {
+          return cbk([400, 'ExpectedIdentifyingBlockHashOfHeaderToRetrieve']);
+        }
+
+        if (height !== undefined && !!id) {
+          return cbk([400, 'ExpectedEitherHeightOrIdNotBothForHeaderFetch']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToRetrieveBlockHeader']);
+        }
+
+        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 header
+      getBlockHeader: ['getHash', ({getHash}, cbk) => {
+        return lnd[type][method]({block_hash: getHash}, (err, res) => {
+          if (!!err && err.details === errorNotFound) {
+            return cbk([404, 'BlockForHeaderNotFound']);
+          }
+
+          if (!!err && err.details === errorUnknownMethod) {
+            return cbk([501, 'GetBlockHeaderMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorWhenGettingBlockHeader', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForChainBlockHeaderRequest']);
+          }
+
+          if (!isBuffer(res.raw_block_header)) {
+            return cbk([503, 'ExpectedRawHeaderInChainBlockHeaderResponse']);
+          }
+
+          return cbk(null, {header: bufferAsHex(res.raw_block_header)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getBlockHeader'}, cbk));
+  });
+};

package/lnd_methods/onchain/index.d.ts

@@ -4,6 +4,7 @@ export * from './close_channel';
 export * from './fund_pending_channels';
 export * from './fund_psbt';
 export * from './get_block';
+export * from './get_block_header';
 export * from './get_chain_addresses';
 export * from './get_chain_balance';
 export * from './get_chain_fee_estimate';

package/lnd_methods/onchain/index.js

@@ -4,6 +4,7 @@ const closeChannel = require('./close_channel');
 const fundPendingChannels = require('./fund_pending_channels');
 const fundPsbt = require('./fund_psbt');
 const getBlock = require('./get_block');
+const getBlockHeader = require('./get_block_header');
 const getChainAddresses = require('./get_chain_addresses');
 const getChainBalance = require('./get_chain_balance');
 const getChainFeeEstimate = require('./get_chain_fee_estimate');
@@ -42,6 +43,7 @@ module.exports = {
   fundPendingChannels,
   fundPsbt,
   getBlock,
+  getBlockHeader,
   getChainAddresses,
   getChainBalance,
   getChainFeeEstimate,

package/package.json

@@ -7,11 +7,11 @@
     "url": "https://github.com/alexbosworth/lightning/issues"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.9.5",
+    "@grpc/grpc-js": "1.9.9",
     "@grpc/proto-loader": "0.7.10",
-    "@types/node": "20.8.4",
-    "@types/request": "2.48.10",
-    "@types/ws": "8.5.7",
+    "@types/node": "20.8.10",
+    "@types/request": "2.48.11",
+    "@types/ws": "8.5.8",
     "async": "3.2.4",
     "asyncjs-util": "1.2.12",
     "bitcoinjs-lib": "6.1.5",
@@ -22,7 +22,7 @@
     "invoices": "3.0.0",
     "psbt": "3.0.0",
     "tiny-secp256k1": "2.2.3",
-    "type-fest": "4.4.0"
+    "type-fest": "4.6.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
@@ -53,5 +53,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "10.0.1"
+  "version": "10.1.1"
 }

package/test/lnd_methods/onchain/test_get_block_header.js

@@ -0,0 +1,243 @@
+const {deepStrictEqual} = require('node:assert').strict;
+const {rejects} = require('node:assert').strict;
+const test = require('node:test');
+
+const {getBlockHeader} = require('./../../../lnd_methods');
+
+const tests = [
+  {
+    args: {height: 'invalid'},
+    description: 'A valid height is expected to get a block header',
+    error: [400, 'ExpectedNumericBlockHeightOfHeaderToRetrieve'],
+  },
+  {
+    args: {id: 'invalid'},
+    description: 'A valid id is expected to get a block header',
+    error: [400, 'ExpectedIdentifyingBlockHashOfHeaderToRetrieve'],
+  },
+  {
+    args: {height: 1, id: Buffer.alloc(32).toString('hex')},
+    description: 'Only a height or an id is required',
+    error: [400, 'ExpectedEitherHeightOrIdNotBothForHeaderFetch'],
+  },
+  {
+    args: {id: Buffer.alloc(32).toString('hex')},
+    description: 'An lnd object is required to get a block header',
+    error: [400, 'ExpectedAuthenticatedLndToRetrieveBlockHeader'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk({
+            details: 'unknown method GetBlockHeader for service chainrpc.ChainKit',
+          }),
+          getBlockHeader: ({}, cbk) => cbk('err'),
+        },
+      },
+    },
+    description: 'An unsupported error is returned',
+    error: [501, 'GetBestBlockMethodNotSupported'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk('err'),
+          getBlockHeader: ({}, cbk) => cbk('getBlockErr'),
+        },
+      },
+    },
+    description: 'An error is returned',
+    error: [503, 'UnexpectedErrorGettingBestBlock', {err: 'err'}],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An error is returned when there is no best block result',
+    error: [503, 'ExpectedResponseForBestBlockRequest'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(null, {}),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An error is returned when there is no result info',
+    error: [503, 'ExpectedChainTipInfoInGetBestBlockResponse'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlockHash: ({}, cbk) => cbk({
+            details: 'unknown method GetBlockHeader for service chainrpc.ChainKit',
+          }),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An error is returned when get hash for height unsupported',
+    error: [501, 'GetBlockHashMethodNotSupported'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlockHash: ({}, cbk) => cbk('err'),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'An unexpected error for getting block hash is returned',
+    error: [503, 'UnexpectedErrorGettingBlockHash', {err: 'err'}],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlockHash: ({}, cbk) => cbk(),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'A result is expected for getting a block hash',
+    error: [503, 'ExpectedResponseForGetBlockHashRequest'],
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlockHash: ({}, cbk) => cbk(null, {}),
+          getBlockHeader: ({}, cbk) => cbk(),
+        },
+      },
+    },
+    description: 'A result hash is expected for getting a block hash',
+    error: [503, 'ExpectedBlockHashInGetBlockHashResponse'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlockHeader: ({}, cbk) => cbk({details: '-5: Block not found'}),
+        },
+      },
+    },
+    description: 'An error is returned when a block is not found',
+    error: [404, 'BlockForHeaderNotFound'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlockHeader: ({}, cbk) => cbk({
+            details: 'unknown method GetBlockHeader for service chainrpc.ChainKit',
+          }),
+        },
+      },
+    },
+    description: 'An error is returned when the method is not supported',
+    error: [501, 'GetBlockHeaderMethodNotSupported'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlockHeader: ({}, cbk) => cbk('err')}},
+    },
+    description: 'An error is returned',
+    error: [503, 'UnexpectedErrorWhenGettingBlockHeader', {err: 'err'}],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlockHeader: ({}, cbk) => cbk()}},
+    },
+    description: 'A result is expected',
+    error: [503, 'ExpectedResponseForChainBlockHeaderRequest'],
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {blocks: {getBlockHeader: ({}, cbk) => cbk(null, {})}},
+    },
+    description: 'A resulting block header is expected',
+    error: [503, 'ExpectedRawHeaderInChainBlockHeaderResponse'],
+  },
+  {
+    args: {
+      lnd: {
+        blocks: {
+          getBestBlock: ({}, cbk) => cbk(null, {
+            block_hash: Buffer.alloc(1),
+          }),
+          getBlockHeader: ({}, cbk) => cbk(null, {
+            raw_block_header: Buffer.alloc(1),
+          }),
+        },
+      },
+    },
+    description: 'The chain tip block header is returned',
+    expected: {header: '00'},
+  },
+  {
+    args: {
+      height: 1,
+      lnd: {
+        blocks: {
+          getBlockHash: ({}, cbk) => cbk(null, {
+            block_hash: Buffer.alloc(1),
+          }),
+          getBlockHeader: ({}, cbk) => cbk(null, {
+            raw_block_header: Buffer.alloc(1),
+          }),
+        },
+      },
+    },
+    description: 'A block header at a height is returned',
+    expected: {header: '00'},
+  },
+  {
+    args: {
+      id: Buffer.alloc(32).toString('hex'),
+      lnd: {
+        blocks: {
+          getBlockHeader: ({}, cbk) => cbk(null, {
+            raw_block_header: Buffer.alloc(1),
+          }),
+        },
+      },
+    },
+    description: 'A block header is returned',
+    expected: {header: '00'},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async () => {
+    if (!!error) {
+      await rejects(() => getBlockHeader(args), error, 'Got expected error');
+    } else {
+      const res = await getBlockHeader(args);
+
+      deepStrictEqual(res, expected, 'Got expected result');
+    }
+
+    return;
+  });
+});

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

@@ -0,0 +1,26 @@
+import {expectError, expectType} from 'tsd';
+import {getBlockHeader, GetBlockHeaderResult} from '../../lnd_methods';
+import {AuthenticatedLnd} from '../../lnd_grpc';
+
+const lnd = {} as AuthenticatedLnd;
+const height = 0;
+const id = 'id';
+
+expectError(getBlockHeader());
+expectError(getBlockHeader({}));
+expectError(getBlockHeader({lnd}));
+expectError(getBlockHeader({height, id}));
+
+expectType<GetBlockHeaderResult>(await getBlockHeader({lnd, height}));
+expectType<GetBlockHeaderResult>(await getBlockHeader({lnd, id}));
+
+expectType<void>(
+  getBlockHeader({lnd, height}, (error, result) => {
+    expectType<GetBlockHeaderResult>(result);
+  })
+);
+expectType<void>(
+  getBlockHeader({lnd, id}, (error, result) => {
+    expectType<GetBlockHeaderResult>(result);
+  })
+);