lightning 6.2.7 → 6.3.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Versions
 
+## 6.3.1
+
+- `getSettlementStatus`: Add method to lookup received htlc settlement status
+
 ## 6.2.7
 
 - `getWalletInfo`: Add support for LND 0.14.5

package/README.md

@@ -212,6 +212,8 @@ variables set:
     Calculate a route through specified nodes.
 - [getRouteToDestination](https://github.com/alexbosworth/ln-service#getroutetodestination):
     Calculate a route through the graph to a destination.
+- [getSettlementStatus](https://github.com/alexbosworth/ln-service#getsettlementstatus):
+    Lookup the status of a received payment output
 - [getSweepTransactions](https://github.com/alexbosworth/ln-service#getsweeptransactions): List
     transactions that are sweeping funds on-chain.
 - [getTowerServerInfo](https://github.com/alexbosworth/ln-service#gettowerserverinfo): General

package/grpc/protos/lightning.proto

@@ -577,6 +577,20 @@ service Lightning {
     zero conf).
     */
     rpc ListAliases (ListAliasesRequest) returns (ListAliasesResponse);
+
+    rpc LookupHtlc (LookupHtlcRequest) returns (LookupHtlcResponse);
+}
+
+message LookupHtlcRequest {
+    uint64 chan_id = 1;
+
+    uint64 htlc_index = 2;
+}
+
+message LookupHtlcResponse {
+    bool settled = 1;
+
+    bool offchain = 2;
 }
 
 message SubscribeCustomMessagesRequest {
@@ -2217,6 +2231,13 @@ message OpenChannelRequest {
     to use the default fee rate value specified in the config or 0.
     */
     bool use_fee_rate = 24;
+
+    /*
+    The number of satoshis we require the remote peer to reserve. This value,
+    if specified, must be above the dust limit and below 20% of the channel
+    capacity.
+    */
+    uint64 remote_chan_reserve_sat = 25;
 }
 message OpenStatusUpdate {
     oneof update {
@@ -3047,6 +3068,9 @@ message LightningNode {
     repeated NodeAddress addresses = 4;
     string color = 5;
     map<uint32, Feature> features = 6;
+
+    // Custom node announcement tlv records.
+    map<uint64, bytes> custom_records = 7;
 }
 
 message NodeAddress {
@@ -3062,6 +3086,9 @@ message RoutingPolicy {
     bool disabled = 5;
     uint64 max_htlc_msat = 6;
     uint32 last_update = 7;
+
+    // Custom channel update tlv records.
+    map<uint64, bytes> custom_records = 8;
 }
 
 /*
@@ -3089,6 +3116,9 @@ message ChannelEdge {
 
     RoutingPolicy node1_policy = 7;
     RoutingPolicy node2_policy = 8;
+
+    // Custom channel announcement tlv records.
+    map<uint64, bytes> custom_records = 9;
 }
 
 message ChannelGraphRequest {
@@ -3371,6 +3401,8 @@ message Invoice {
     repeated RouteHint route_hints = 14;
 
     // Whether this invoice should include routing hints for private channels.
+    // Note: When enabled, if value and value_msat are zero, a large number of
+    // hints with these channels can be included, which might not be desirable.
     bool private = 15;
 
     /*
@@ -4042,6 +4074,10 @@ message ForwardingHistoryRequest {
 
     // The max number of events to return in the response to this query.
     uint32 num_max_events = 4;
+
+    // Informs the server if the peer alias should be looked up for each
+    // forwarding event.
+    bool peer_alias_lookup = 5;
 }
 message ForwardingEvent {
     // Timestamp is the time (unix epoch offset) that this circuit was
@@ -4081,6 +4117,12 @@ message ForwardingEvent {
     // circuit was completed.
     uint64 timestamp_ns = 11;
 
+    // The peer alias of the incoming channel.
+    string peer_alias_in = 12;
+
+    // The peer alias of the outgoing channel.
+    string peer_alias_out = 13;
+
     // TODO(roasbeef): add settlement latency?
     //  * use FPE on the chan id?
     //  * also list failures?

package/index.js

@@ -69,6 +69,7 @@ const {getPublicKey} = require('./lnd_methods');
 const {getRouteConfidence} = require('./lnd_methods');
 const {getRouteThroughHops} = require('./lnd_methods');
 const {getRouteToDestination} = require('./lnd_methods');
+const {getSettlementStatus} = require('./lnd_methods');
 const {getSweepTransactions} = require('./lnd_methods');
 const {getTowerServerInfo} = require('./lnd_methods');
 const {getUtxos} = require('./lnd_methods');
@@ -218,6 +219,7 @@ module.exports = {
   getRouteConfidence,
   getRouteThroughHops,
   getRouteToDestination,
+  getSettlementStatus,
   getSweepTransactions,
   getTowerServerInfo,
   getUtxos,

package/lnd_methods/index.js

@@ -67,6 +67,7 @@ const {getPublicKey} = require('./address');
 const {getRouteConfidence} = require('./generic');
 const {getRouteThroughHops} = require('./offchain');
 const {getRouteToDestination} = require('./info');
+const {getSettlementStatus} = require('./offchain');
 const {getSweepTransactions} = require('./onchain');
 const {getTowerServerInfo} = require('./info');
 const {getUtxos} = require('./onchain');
@@ -212,6 +213,7 @@ module.exports = {
   getRouteConfidence,
   getRouteThroughHops,
   getRouteToDestination,
+  getSettlementStatus,
   getSweepTransactions,
   getTowerServerInfo,
   getUtxos,

package/lnd_methods/macaroon/methods.json

@@ -276,6 +276,10 @@
     "method": "QueryRoutes",
     "type": "default"
   },
+  "getSettlementStatus": {
+    "method": "LookupHtlc",
+    "type": "default"
+  },
   "getSweepTransactions": {
     "method": "ListSweeps",
     "type": "default"

package/lnd_methods/offchain/get_settlement_status.d.ts

@@ -0,0 +1,30 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type GetSettlementStatusArgs = AuthenticatedLightningArgs<{
+  /** Standard Format Channel Id String */
+  channel: string;
+  /** Payment Id Number */
+  payment: number;
+}>;
+
+export type GetSettlementStatusResult = {
+  /** Payment Went to Chain Bool */
+  is_onchain: boolean;
+  /** Payment Is Settled Into Non-HTLC Balance Bool */
+  is_settled: boolean;
+};
+
+/**
+ * Get the settlement status of a received HTLC
+ *
+ * Note: this method is not supported in LND versions 0.15.4 and below
+ *
+ * Requires `offchain:read` permissions
+ */
+export const getSettlementStatus: AuthenticatedLightningMethod<
+  GetSettlementStatusArgs,
+  GetSettlementStatusResult
+>;

package/lnd_methods/offchain/get_settlement_status.js

@@ -0,0 +1,91 @@
+const asyncAuto = require('async/auto');
+const {chanNumber} = require('bolt07');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const errorNotFound = 'htlc unknown';
+const errorUnimplemented = 'unknown method LookupHtlc for service lnrpc.Lightning';
+const isBoolean = n => n === false || n === true;
+const method = 'lookupHtlc';
+const type = 'default';
+
+/** Get the settlement status of a received HTLC
+
+  Note: this method is not supported in LND versions 0.15.4 and below
+
+  Requires `offchain:read` permissions
+
+  {
+    channel: <Standard Format Channel Id String>
+    lnd: <Authenticated LND API Object>
+    payment: <Payment Id Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    is_onchain: <Payment Went to Chain Bool>
+    is_settled: <Payment Is Settled Into Non-HTLC Balance Bool>
+  }
+*/
+module.exports = ({channel, lnd, payment}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!channel) {
+          return cbk([400, 'ExpectedChannelIdToGetSettlementStatus']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndToGetSettlementStatus']);
+        }
+
+        if (payment === undefined) {
+          return cbk([400, 'ExpectedHtlcIndexToGetSettlementStatus']);
+        }
+
+        return cbk();
+      },
+
+      // Get the settlement status of an HTLC
+      getStatus: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          chan_id: chanNumber({channel}).number,
+          htlc_index: payment.toString(),
+        },
+        (err, res) => {
+          if (!!err && err.details === errorNotFound) {
+            return cbk([404, 'PaymentNotFound']);
+          }
+
+          if (!!err && err.details === errorUnimplemented) {
+            return cbk([501, 'LookupHtlcMethodUnsupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedLookupHltcError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedHtlcLookupResponse']);
+          }
+
+          if (!isBoolean(res.offchain)) {
+            return cbk([503, 'ExpectedOffchainStatusInHtlcLookupResponse']);
+          }
+
+          if (!isBoolean(res.settled)) {
+            return cbk([503, 'ExpectedSettledStatusInHtlcLookupResponse']);
+          }
+
+          return cbk(null, {
+            is_onchain: !res.offchain,
+            is_settled: res.settled,
+          });
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getStatus'}, cbk));
+  });
+};

package/lnd_methods/offchain/index.d.ts

@@ -27,6 +27,7 @@ export * from './get_payments';
 export * from './get_pending_channels';
 export * from './get_pending_payments';
 export * from './get_route_through_hops';
+export * from './get_settlement_status';
 export * from './is_destination_payable';
 export * from './pay_via_payment_details';
 export * from './pay_via_payment_request';

package/lnd_methods/offchain/index.js

@@ -27,6 +27,7 @@ const getPayments = require('./get_payments');
 const getPendingChannels = require('./get_pending_channels');
 const getPendingPayments = require('./get_pending_payments');
 const getRouteThroughHops = require('./get_route_through_hops');
+const getSettlementStatus = require('./get_settlement_status');
 const isDestinationPayable = require('./is_destination_payable');
 const pay = require('./pay');
 const payViaPaymentDetails = require('./pay_via_payment_details');
@@ -85,6 +86,7 @@ module.exports = {
   getPendingChannels,
   getPendingPayments,
   getRouteThroughHops,
+  getSettlementStatus,
   isDestinationPayable,
   pay,
   payViaPaymentDetails,

package/lnd_methods/offchain/subscribe_to_forward_requests.js

@@ -83,7 +83,7 @@ module.exports = ({lnd}) => {
       const request = rpcForwardAsForwardRequest(data);
 
       return emitter.emit(event, {
-        accept: () => sub.write({
+        accept: async () => await sub.write({
           action: forwardPaymentActions.accept,
           incoming_circuit_key: data.incoming_circuit_key,
         }),
@@ -97,11 +97,11 @@ module.exports = ({lnd}) => {
         mtokens: request.mtokens,
         onion: request.onion,
         out_channel: request.out_channel,
-        reject: () => sub.write({
+        reject: async () => await sub.write({
           action: forwardPaymentActions.reject,
           incoming_circuit_key: data.incoming_circuit_key,
         }),
-        settle: ({secret}) => sub.write({
+        settle: async ({secret}) => await sub.write({
           action: forwardPaymentActions.settle,
           incoming_circuit_key: data.incoming_circuit_key,
           preimage: bufferFromHex(secret),

package/package.json

@@ -23,18 +23,18 @@
     "cbor": "8.1.0",
     "ecpair": "2.1.0",
     "express": "4.18.2",
-    "invoices": "2.2.0",
+    "invoices": "2.2.2",
     "psbt": "2.7.1",
     "tiny-secp256k1": "2.2.1",
-    "type-fest": "3.1.0"
+    "type-fest": "3.2.0"
   },
   "description": "Lightning Network client library",
   "devDependencies": {
     "@alexbosworth/node-fetch": "2.6.2",
     "@alexbosworth/tap": "15.0.11",
     "tsd": "0.24.1",
-    "typescript": "4.8.4",
-    "ws": "8.10.0"
+    "typescript": "4.9.3",
+    "ws": "8.11.0"
   },
   "engines": {
     "node": ">=14"
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "6.2.7"
+  "version": "6.3.1"
 }

package/test/lnd_methods/address/test_get_public_key.js

@@ -54,12 +54,54 @@ const tests = [
     args: {
       family: 1,
       index: 1,
+      lnd: {wallet: {deriveKey: ({}, cbk) => cbk(null, {
+        raw_key_bytes: Buffer.alloc(1),
+      })}},
+    },
+    description: 'Expects result key loc',
+    error: [503, 'ExpectedKeyLocatorInPublicKeyResponse'],
+  },
+  {
+    args: {
+      family: 1,
+      index: 1,
+      lnd: {wallet: {deriveKey: ({}, cbk) => cbk(null, {
+        key_loc: {},
+        raw_key_bytes: Buffer.alloc(1),
+      })}},
+    },
+    description: 'Expects result key loc index',
+    error: [503, 'ExpectedKeyIndexInPublicKeyResponse'],
+  },
+  {
+    args: {
+      family: 1,
+      index: 1,
+      lnd: {
+        wallet: {
+          deriveKey: ({}, cbk) => cbk(null, {
+            key_loc: {key_index: 0},
+            raw_key_bytes: Buffer.alloc(1),
+          }),
+        },
+      },
+    },
+    description: 'Got public key result',
+    expected: {public_key: '00'},
+  },
+  {
+    args: {
+      family: 1,
       lnd: {
         wallet: {
           deriveKey: ({}, cbk) => cbk(null, {
             key_loc: {key_index: 0},
             raw_key_bytes: Buffer.alloc(1),
           }),
+          deriveNextKey: ({}, cbk) => cbk(null, {
+            key_loc: {key_index: 0},
+            raw_key_bytes: Buffer.alloc(1),
+          }),
         },
       },
     },

package/test/lnd_methods/info/test_get_wallet_info.js

@@ -36,6 +36,11 @@ const tests = [
     description: 'Connect fails returns error',
     error: [503, 'FailedToConnectToDaemon'],
   },
+  {
+    args: {lnd: makeLnd({err: {details: 'No connection established'}})},
+    description: 'Connect fails returns error',
+    error: [503, 'FailedToConnectToDaemon'],
+  },
   {
     args: {lnd: makeLnd({err: 'err'})},
     description: 'Generic failure returns back the error',

package/test/lnd_methods/offchain/test_disconnect_watchtower.js

@@ -42,6 +42,10 @@ const tests = [
     description: 'Server error is returned',
     error: [503, 'UnexpectedErrDisconnectingWatchtower', {err: 'err'}],
   },
+  {
+    args: makeArgs({lnd: makeLnd({details: 'tower not found'})}),
+    description: 'Ignore removed already errors',
+  },
   {
     args: makeArgs({}),
     description: 'A tower is added',

package/test/lnd_methods/offchain/test_get_settlement_status.js

@@ -0,0 +1,84 @@
+const {test} = require('@alexbosworth/tap');
+
+const {getSettlementStatus} = require('./../../../');
+
+const makeLnd = ({err, res}) => {
+  const result = res === undefined ? {offchain: true, settled: true} : res;
+
+  return {default: {lookupHtlc: ({}, cbk) => cbk(err, result)}};
+};
+
+const makeArgs = overrides => {
+  const args = {channel: '0x0x0', lnd: makeLnd({}), payment: 0};
+
+  Object.keys(overrides).forEach(k => args[k] = overrides[k]);
+
+  return args;
+};
+
+const tests = [
+  {
+    args: makeArgs({channel: undefined}),
+    description: 'A channel id is required',
+    error: [400, 'ExpectedChannelIdToGetSettlementStatus'],
+  },
+  {
+    args: makeArgs({lnd: undefined}),
+    description: 'LND object is required',
+    error: [400, 'ExpectedLndToGetSettlementStatus'],
+  },
+  {
+    args: makeArgs({payment: undefined}),
+    description: 'A payment index is required',
+    error: [400, 'ExpectedHtlcIndexToGetSettlementStatus'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: {details: 'htlc unknown'}})}),
+    description: 'An HTLC not found error is returned',
+    error: [404, 'PaymentNotFound'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: {details: 'unknown method LookupHtlc for service lnrpc.Lightning'}})}),
+    description: 'A method not supported error is returned',
+    error: [501, 'LookupHtlcMethodUnsupported'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({err: 'err'})}),
+    description: 'A generic error is returned',
+    error: [503, 'UnexpectedLookupHltcError', {err: 'err'}],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: null})}),
+    description: 'A response is expected',
+    error: [503, 'ExpectedHtlcLookupResponse'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: {}})}),
+    description: 'A chain status is expected',
+    error: [503, 'ExpectedOffchainStatusInHtlcLookupResponse'],
+  },
+  {
+    args: makeArgs({lnd: makeLnd({res: {offchain: true}})}),
+    description: 'A settlement status is expected',
+    error: [503, 'ExpectedSettledStatusInHtlcLookupResponse'],
+  },
+  {
+    args: makeArgs({}),
+    description: 'Settlement status is returned',
+    expected: {is_onchain: false, is_settled: true},
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, async ({deepEqual, end, rejects, strictSame}) => {
+    if (!!error) {
+      await rejects(getSettlementStatus(args), error, 'Got expected error');
+    } else {
+      const res = await getSettlementStatus(args);
+
+      strictSame(res, expected, 'Got expected result');
+    }
+
+    return end();
+  });
+});

package/test/lnd_methods/onchain/test_get_chain_fee_estimate.js

@@ -94,6 +94,23 @@ const tests = [
     description: 'Passing 0 UTXO confirmations is supported',
     expected: {fee: 1, tokens_per_vbyte: 1},
   },
+  {
+    args: {
+      lnd: {
+        default: {
+          estimateFee: ({}, cbk) => cbk(null, {
+            fee_sat: '1',
+            feerate_sat_per_byte: '1',
+            sat_per_vbyte: '2',
+          }),
+        },
+      },
+      send_to: [{address: 'address', tokens: 1}],
+      utxo_confirmations: 0,
+    },
+    description: 'Sat per vbyte result is supported',
+    expected: {fee: 1, tokens_per_vbyte: 2},
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/onchain/test_lock_utxo.js

@@ -17,6 +17,11 @@ const makeArgs = overrides => {
 };
 
 const tests = [
+  {
+    args: makeArgs({expires_at: '1970'}),
+    description: 'Cannot give a past expiry',
+    error: [400, 'ExpectedLaterDateToSetLockExpirationDateTo'],
+  },
   {
     args: makeArgs({lnd: undefined}),
     description: 'LND is required to lock a utxo',

package/test/lnd_methods/signer/test_sign_transaction.js

@@ -84,6 +84,17 @@ const tests = [
     description: 'Buffers in raw sigs array are expected',
     expected: {signature: '00'},
   },
+  {
+    args: makeArgs({
+      override: {
+        inputs: [{
+          output_script: '51200000000000000000000000000000000000000000000000000000000000000000',
+        }],
+      },
+    }),
+    description: 'A taproot tx is signed',
+    expected: {signature: '00'},
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

package/test/lnd_methods/unauthenticated/test_create_wallet.js

@@ -18,6 +18,26 @@ const tests = [
     description: 'Seed is required',
     error: [400, 'ExpectedSeedMnemonicForWalletCreation'],
   },
+  {
+    args: {
+      lnd: {unlocker: {initWallet: ({}, cbk) => cbk()}},
+      passphrase: 'passphrase',
+      password: 'pass',
+      seed: 'seed',
+    },
+    description: 'A wallet creation is expected',
+    error: [503, 'ExpectedResponseForInitWallet'],
+  },
+  {
+    args: {
+      lnd: {unlocker: {initWallet: ({}, cbk) => cbk(null, {})}},
+      passphrase: 'passphrase',
+      password: 'pass',
+      seed: 'seed',
+    },
+    description: 'An admin macaroon is expected',
+    error: [503, 'ExpectedAdminMacaroonToCrateWallet'],
+  },
   {
     args: {
       lnd: {unlocker: {initWallet: ({}, cbk) => cbk('err')}},

package/test/lnd_methods/unauthenticated/test_subscribe_to_wallet_status.js

@@ -86,6 +86,18 @@ const tests = [
     args: {lnd: makeLnd({state: 'RPC_ACTIVE'})},
     description: 'Active wallet state emitted',
   },
+  {
+    args: {lnd: makeLnd({state: 'SERVER_ACTIVE'})},
+    description: 'Active server state emitted',
+  },
+  {
+    args: {lnd: makeLnd({state: 'WAITING_TO_START'})},
+    description: 'Server waiting to start',
+  },
+  {
+    args: {lnd: makeLnd({state: 'undefined_state'})},
+    description: 'Server emitted an unknown event',
+  },
   {
     args: {lnd: makeLnd({state: 'UNLOCKED'})},
     description: 'Starting state emitted',

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

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