lightning 4.14.2 → 4.14.3

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Versions
 
-## 4.14.2
+## 4.14.3
 
 - `getPayment`, `subscribeToPastPayment`: Add `pending` for pending payment details
 

package/lnd_methods/offchain/emit_payment.js

@@ -1,8 +1,10 @@
 const {confirmedFromPayment} = require('./../../lnd_responses');
 const {failureFromPayment} = require('./../../lnd_responses');
 const {pendingFromPayment} = require('./../../lnd_responses');
+const {routingFailureFromHtlc} = require('./../../lnd_responses');
 const {states} = require('./payment_states');
 
+const failedStatus = 'FAILED';
 const {isArray} = Array;
 
 /** Emit payment from payment event
@@ -31,6 +33,16 @@ module.exports = ({data, emitter}) => {
         return;
       }
 
+      // Emit routing failures
+      data.htlcs.filter(n => n.status === failedStatus).forEach(htlc => {
+        return emitter.emit('routing_failure', routingFailureFromHtlc(htlc));
+      });
+
+      // Exit early when the HTLCs have no pending payments
+      if (!data.htlcs.find(n => n.status === states.paying)) {
+        return;
+      }
+
       return emitter.emit('paying', pendingFromPayment(data));
 
     default:

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -146,7 +146,62 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
   }
 
   @event 'paying'
-  {}
+  {
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Pending String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      fee_mtokens: <Total Fee Millitokens Pending String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Tokens Rounded Down Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Pending String>
+      safe_fee: <Total Fee Tokens Pending Rounded Up Number>
+      safe_tokens: <Total Tokens Pending, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_tokens: <Total Tokens Pending, Rounded Up Number>
+    [timeout]: <Expiration Block Height Number>
+    tokens: <Total Tokens Pending Rounded Down Number>
+  }
+
+  @event 'routing_failure'
+  {
+    [channel]: <Standard Format Channel Id String>
+    index: <Failure Index Number>
+    [mtokens]: <Millitokens String>
+    [public_key]: <Public Key Hex String>
+    reason: <Failure Reason String>
+    route: {
+      fee: <Total Route Fee Tokens To Pay Number>
+      fee_mtokens: <Total Route Fee Millitokens To Pay String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Route Millitokens String>
+      [payment]: <Payment Identifier Hex String>
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Route Tokens Number>
+      [total_mtokens]: <Total Millitokens String>
+    }
+  }
 */
 module.exports = args => {
   if (!!args.cltv_delta && !!args.request) {
@@ -316,7 +371,7 @@ module.exports = args => {
         last_hop_pubkey: hexToBuf(args.incoming_peer),
         max_parts: args.max_paths || defaultMaxPaths,
         max_shard_size_msat: args.max_path_mtokens || undefined,
-        no_inflight_updates: true,
+        no_inflight_updates: false,
         outgoing_chan_id: !hasOutIds ? singleOut : undefined,
         outgoing_chan_ids: outgoingChannelIds,
         payment_addr: !!args.payment ? hexToBuf(args.payment) : undefined,

package/lnd_methods/offchain/subscribe_to_pay_via_details.js

@@ -120,7 +120,61 @@ const type = 'router';
   }
 
   @event 'paying'
-  {}
+  {
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Pending String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      fee_mtokens: <Total Fee Millitokens Pending String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Tokens Rounded Down Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Pending String>
+      safe_fee: <Total Fee Tokens Pending Rounded Up Number>
+      safe_tokens: <Total Tokens Pending, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    safe_tokens: <Total Tokens Pending, Rounded Up Number>
+    [timeout]: <Expiration Block Height Number>
+    tokens: <Total Tokens Pending Rounded Down Number>
+  }
+
+  @event 'routing_failure'
+  {
+    [channel]: <Standard Format Channel Id String>
+    index: <Failure Index Number>
+    [mtokens]: <Millitokens String>
+    [public_key]: <Public Key Hex String>
+    reason: <Failure Reason String>
+    route: {
+      fee: <Total Route Fee Tokens To Pay Number>
+      fee_mtokens: <Total Route Fee Millitokens To Pay String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Route Millitokens String>
+      [payment]: <Payment Identifier Hex String>
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Route Tokens Number>
+      [total_mtokens]: <Total Millitokens String>
+    }
+  }
 */
 module.exports = args => {
   if (!isPublicKey(args.destination)) {

package/lnd_methods/offchain/subscribe_to_pay_via_request.js

@@ -100,7 +100,62 @@ const type = 'router';
   }
 
   @event 'paying'
-  {}
+  {
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Pending String>
+    paths: [{
+      fee: <Total Fee Tokens Pending Number>
+      fee_mtokens: <Total Fee Millitokens Pending String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Tokens Rounded Down Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Pending String>
+      safe_fee: <Total Fee Tokens Pending Rounded Up Number>
+      safe_tokens: <Total Tokens Pending, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_tokens: <Total Tokens Pending, Rounded Up Number>
+    [timeout]: <Expiration Block Height Number>
+    tokens: <Total Tokens Pending Rounded Down Number>
+  }
+
+  @event 'routing_failure'
+  {
+    [channel]: <Standard Format Channel Id String>
+    index: <Failure Index Number>
+    [mtokens]: <Millitokens String>
+    [public_key]: <Public Key Hex String>
+    reason: <Failure Reason String>
+    route: {
+      fee: <Total Route Fee Tokens To Pay Number>
+      fee_mtokens: <Total Route Fee Millitokens To Pay String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Route Millitokens String>
+      [payment]: <Payment Identifier Hex String>
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Route Tokens Number>
+      [total_mtokens]: <Total Millitokens String>
+    }
+  }
 */
 module.exports = args => {
   if (!args.request) {

package/lnd_responses/index.js

@@ -14,6 +14,7 @@ const pendingAsPendingChannels = require('./pending_as_pending_channels');
 const pendingFromPayment = require('./pending_from_payment');
 const policyFromChannelUpdate = require('./policy_from_channel_update');
 const routesFromQueryRoutes = require('./routes_from_query_routes');
+const routingFailureFromHtlc = require('./routing_failure_from_htlc');
 const rpcAttemptHtlcAsAttempt = require('./rpc_attempt_htlc_as_attempt');
 const rpcChannelAsChannel = require('./rpc_channel_as_channel');
 const rpcChannelAsOldRpcChannel = require('./rpc_channel_as_old_rpc_channel');
@@ -57,6 +58,7 @@ module.exports = {
   pendingFromPayment,
   policyFromChannelUpdate,
   routesFromQueryRoutes,
+  routingFailureFromHtlc,
   rpcAttemptHtlcAsAttempt,
   rpcChannelAsChannel,
   rpcChannelAsOldRpcChannel,

package/lnd_responses/routing_failure_from_htlc.js

@@ -0,0 +1,105 @@
+const paymentFailure = require('./payment_failure');
+const rpcRouteAsRoute = require('./rpc_route_as_route');
+
+/** Derive routing failure details from an HTLC
+
+  {
+    attempt_time_ns: <HTLC Sent At Epoch Time Nanoseconds String>
+    failure: {
+      [channel_update]: {
+        base_fee: <Base Fee Millitokens Number>
+        chain_hash: <Chain Hash Buffer Object>
+        [chan_id]: <Numeric Channel Id String>
+        channel_flags: <Channel Flags Number>
+        extra_opaque_data: <Extra Opaque Data Buffer Object>
+        fee_rate: <Fee Rate Number>
+        htlc_maximum_msat: <Maximum HTLC Millitokens Number>
+        htlc_minimum_msat: <Minimum HTLC Millitokens Number>
+        message_flags: <Message Flags Number>
+        signature: <Signature Buffer Object>
+        time_lock_delta: <CLTV Delta Number>
+        timestamp: <Update Epoch Time Seconds Number>
+      }
+      code: <Failure Code String>
+      [failure_source_index]: <Failed Hop Index Number>
+      height: <Height Number>
+      htlc_msat: <HTLC Millitokens String>
+    }
+    resolve_time_ns: <HTLC Resolved At Epoch Time Nanoseconds String>
+    route: {
+      hops: [{
+        amt_to_forward: <Tokens to Forward String>
+        amt_to_forward_msat: <Millitokens to Forward String>
+        chan_id: <Numeric Format Channel Id String>
+        chan_capacity: <Channel Capacity Number>
+        expiry: <Timeout Chain Height Number>
+        fee: <Fee in Tokens Number>
+        fee_msat: <Fee in Millitokens Number>
+        [mpp_record]: {
+          payment_addr: <Payment Identifier Buffer>
+          total_amt_msat: <Total Payment Millitokens Amount String>
+        }
+        pub_key: <Next Hop Public Key Hex String>
+        tlv_payload: <Has Extra TLV Data Bool>
+      }]
+      total_amt: <Total Tokens String>
+      total_amt_msat: <Route Total Millitokens String>
+      total_fees: <Route Fee Tokens String>
+      total_fees_msat: <Route Total Fees Millitokens String>
+      total_time_lock: <Route Total Timelock Number>
+    }
+    status: <HTLC Status String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [channel]: <Standard Format Channel Id String>
+    index: <Failure Index Number>
+    [mtokens]: <Millitokens String>
+    [public_key]: <Public Key Hex String>
+    reason: <Failure Reason String>
+    route: {
+      fee: <Total Route Fee Tokens To Pay Number>
+      fee_mtokens: <Total Route Fee Millitokens To Pay String>
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        channel_capacity: <Channel Capacity Tokens Number>
+        fee: <Fee Number>
+        fee_mtokens: <Fee Millitokens String>
+        forward: <Forward Tokens Number>
+        forward_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Route Millitokens String>
+      [payment]: <Payment Identifier Hex String>
+      timeout: <Expiration Block Height Number>
+      tokens: <Total Route Tokens Number>
+      [total_mtokens]: <Total Millitokens String>
+    }
+  }
+*/
+module.exports = htlc => {
+  const from = htlc.route.hops[htlc.failure.failure_source_index - 1] || {};
+
+  const failure = paymentFailure({
+    channel: htlc.channel,
+    failure: htlc.failure,
+    index: htlc.index,
+    key: from.pub_key,
+  });
+
+  const route = rpcRouteAsRoute(htlc.route);
+
+  return {
+    route,
+    channel: failure.details.channel,
+    index: failure.details.index,
+    mtokens: route.mtokens,
+    public_key: from.pub_key,
+    reason: failure.message,
+  };
+};

package/package.json

@@ -15,7 +15,7 @@
     "@types/ws": "8.2.0",
     "async": "3.2.2",
     "asyncjs-util": "1.2.7",
-    "bitcoinjs-lib": "5.2.0",
+    "bitcoinjs-lib": "6.0.0",
     "bn.js": "5.2.0",
     "body-parser": "1.19.0",
     "bolt07": "1.7.4",
@@ -56,5 +56,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "4.14.2"
+  "version": "4.14.3"
 }

package/test/lnd_responses/test_routing_failure_from_htlc.js

@@ -0,0 +1,137 @@
+const {test} = require('@alexbosworth/tap');
+
+const {routingFailureFromHtlc} = require('./../../lnd_responses');
+
+const makeHtlc = overrides => {
+  const htlc = {
+    attempt_time_ns: '1',
+    failure: {
+      channel_update: {
+        base_fee: 1,
+        chain_hash: Buffer.alloc(32),
+        chan_id: '1',
+        channel_flags: 1,
+        extra_opaque_data: Buffer.alloc(0),
+        fee_rate: 1,
+        htlc_maximum_msat: 1,
+        htlc_minimum_msat: 1,
+        message_flags: 1,
+        signature: Buffer.alloc(0),
+        time_lock_delta: 1,
+        timestamp: 1,
+      },
+      code: 'TEMPORARY_CHANNEL_FAILURE',
+      failure_source_index: 0,
+      height: 1,
+      htlc_msat: '1000',
+    },
+    resolve_time_ns: '1',
+    route: {
+      hops: [{
+        amt_to_forward: '1',
+        amt_to_forward_msat: '1000',
+        chan_id: '1',
+        chan_capacity: 1,
+        expiry: 1,
+        fee: 0,
+        fee_msat: '0',
+        pub_key: Buffer.alloc(33, 3).toString('hex'),
+        tlv_payload: true,
+      }],
+      total_amt: '1',
+      total_amt_msat: '1000',
+      total_fees: 0,
+      total_fees_msat: '0',
+      total_time_lock: 1,
+    },
+    status: 'FAILED',
+  };
+
+  Object.keys(overrides || {}).forEach(k => htlc[k] = overrides[k]);
+
+  return htlc;
+};
+
+const makeExpected = overrides => {
+  const expected = {
+    route: {
+      fee: 0,
+      fee_mtokens: '0',
+      hops: [
+        {
+          channel: '0x0x1',
+          channel_capacity: 1,
+          fee: 0,
+          fee_mtokens: '0',
+          forward: 1,
+          forward_mtokens: '1000',
+          public_key: '030303030303030303030303030303030303030303030303030303030303030303',
+          timeout: 1,
+        }
+      ],
+      mtokens: '1000',
+      payment: undefined,
+      timeout: 1,
+      tokens: 1,
+      total_mtokens: undefined,
+    },
+    channel: '0x0x1',
+    index: 0,
+    mtokens: '1000',
+    public_key: undefined,
+    reason: 'TemporaryChannelFailure',
+  };
+
+  Object.keys(overrides || {}).forEach(key => expected[key] = overrides[key]);
+
+  return expected;
+};
+
+const tests = [
+  {
+    args: makeHtlc({}),
+    description: 'HTLC is mapped to a routing failure',
+    expected: makeExpected({}),
+  },
+  {
+    args: makeHtlc({
+      failure: {
+        channel_update: {
+          base_fee: 1,
+          chain_hash: Buffer.alloc(32),
+          chan_id: '1',
+          channel_flags: 1,
+          extra_opaque_data: Buffer.alloc(0),
+          fee_rate: 1,
+          htlc_maximum_msat: 1,
+          htlc_minimum_msat: 1,
+          message_flags: 1,
+          signature: Buffer.alloc(0),
+          time_lock_delta: 1,
+          timestamp: 1,
+        },
+        code: 'TEMPORARY_CHANNEL_FAILURE',
+        failure_source_index: 1,
+        height: 1,
+        htlc_msat: '1000',
+      },
+    }),
+    description: 'HTLC is mapped to a routing failure with key',
+    expected: makeExpected({
+      index: 1,
+      public_key: Buffer.alloc(33, 3).toString('hex'),
+    }),
+  },
+];
+
+tests.forEach(({args, description, error, expected}) => {
+  return test(description, ({end, strictSame, throws}) => {
+    if (!!error) {
+      throws(() => routingFailureFromHtlc(args), new Error(error), 'Got err');
+    } else {
+      strictSame(routingFailureFromHtlc(args), expected, 'HTLC mapped');
+    }
+
+    return end();
+  });
+});