lightning 9.2.1 → 9.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Versions
 
+## 9.3.0
+
+- `subscribeToPastPayment`, `subscribeToPayViaDetails`,
+    `subscribeToPayViaRequest`, `subscribeToPayments`: Add `id` for `failed`
+    payment hash
+
 ## 9.2.1
 
 - `getChannels`: Add support for `type` to show channel type

package/lnd_methods/offchain/subscribe_to_past_payment.d.ts

@@ -56,6 +56,8 @@ export type SubscribeToPastPaymentConfirmedEvent = {
 };
 
 export type SubscribeToPastPaymentFailedEvent = {
+  /** Payment Hash Hex */
+  id: string;
   /** Failed Due To Lack of Balance */
   is_insufficient_balance: boolean;
   /** Failed Due to Payment Rejected At Destination */

package/lnd_methods/offchain/subscribe_to_past_payment.js

@@ -77,6 +77,7 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
 
   @event 'failed'
   {
+    id: <Payment Hash Hex String>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Payment Rejected At Destination Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay.d.ts

@@ -138,6 +138,8 @@ export type SubscribeToPayConfirmedEvent = {
 };
 
 export type SubscribeToPayFailedEvent = {
+  /** Payment Hash Hex */
+  id: string;
   /** Failed Due To Lack of Balance Bool> */
   is_insufficient_balance: boolean;
   /** Failed Due to Invalid Payment Bool> */

package/lnd_methods/offchain/subscribe_to_pay.js

@@ -125,6 +125,7 @@ const unknownServiceErr = 'unknown service verrpc.Versioner';
 
   @event 'failed'
   {
+    id: <Payment Hash Hex String>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay_via_details.js

@@ -97,6 +97,7 @@ const type = 'router';
 
   @event 'failed'
   {
+    id: <Payment Hash Hex String>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_pay_via_request.js

@@ -77,6 +77,7 @@ const type = 'router';
 
   @event 'failed'
   {
+    id: <Payment Hash Hex String>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Invalid Payment Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_methods/offchain/subscribe_to_payments.js

@@ -63,6 +63,7 @@ const type = 'router';
 
   @event 'failed'
   {
+    id: <Payment Hash Hex String>
     is_insufficient_balance: <Failed Due To Lack of Balance Bool>
     is_invalid_payment: <Failed Due to Payment Rejected At Destination Bool>
     is_pathfinding_timeout: <Failed Due to Pathfinding Timeout Bool>

package/lnd_responses/failure_from_payment.d.ts

@@ -1,10 +1,13 @@
 import {FailureReason} from '../typescript';
 
 export type FailureFromPaymentArgs = {
+  payment_hash: string;
   failure_reason: FailureReason;
 };
 
 export type FailureFromPaymentResult = {
+  /** Payment Hash Hex String */
+  id: string;
   /** Payment Failed Due to Insufficient Balance Bool */
   is_insufficient_balance: boolean;
   /** Payment Failed Due to Invalid Details Rejection Bool */
@@ -16,32 +19,40 @@ export type FailureFromPaymentResult = {
 };
 
 export function failureFromPayment(payment: {
+  payment_hash: string,
   failure_reason: 'FAILURE_REASON_INSUFFICIENT_BALANCE';
 }): {
+  id: string,
   is_insufficient_balance: true;
   is_invalid_payment: false;
   is_pathfinding_timeout: false;
   is_route_not_found: false;
 };
 export function failureFromPayment(payment: {
+  payment_hash: string,
   failure_reason: 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS';
 }): {
+  id: string,
   is_insufficient_balance: false;
   is_invalid_payment: true;
   is_pathfinding_timeout: false;
   is_route_not_found: false;
 };
 export function failureFromPayment(payment: {
+  payment_hash: string,
   failure_reason: 'FAILURE_REASON_TIMEOUT';
 }): {
+  id: string,
   is_insufficient_balance: false;
   is_invalid_payment: false;
   is_pathfinding_timeout: true;
   is_route_not_found: false;
 };
 export function failureFromPayment(payment: {
+  payment_hash: string,
   failure_reason: 'FAILURE_REASON_NO_ROUTE';
 }): {
+  id: string,
   is_insufficient_balance: false;
   is_invalid_payment: false;
   is_pathfinding_timeout: false;

package/lnd_responses/failure_from_payment.js

@@ -1,13 +1,20 @@
 const {failureReason} = require('./constants');
 
+const is256Hex = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+
 /** Derive failure status from payment
 
   {
     failure_reason: <Payment Failure Reason String>
+    payment_hash: <Payment SHA256 Hash Hex String>
   }
 
+  @throws
+  <Error>
+
   @returns
   {
+     id: <Payment Hash Hex String>
      is_insufficient_balance: <Payment Failed Due to Insufficient Balance Bool>
      is_invalid_payment: <Payment Failed Due to Invalid Details Rejection Bool>
      is_pathfinding_timeout: <Failure Due To Pathfinding Timeout Failure Bool>
@@ -17,7 +24,12 @@ const {failureReason} = require('./constants');
 module.exports = payment => {
   const state = payment.failure_reason;
 
+  if (!is256Hex(payment.payment_hash)) {
+    throw new Error('ExpectedPaymentHashForPaymentAsFailedPayment');
+  }
+
   return {
+    id: payment.payment_hash,
     is_insufficient_balance: state === failureReason.insufficient_balance,
     is_invalid_payment: state === failureReason.invalid_payment,
     is_pathfinding_timeout: state === failureReason.pathfinding_timeout_failed,

package/package.json

@@ -10,7 +10,7 @@
     "@grpc/grpc-js": "1.8.14",
     "@grpc/proto-loader": "0.7.6",
     "@types/express": "4.17.17",
-    "@types/node": "18.16.2",
+    "@types/node": "18.16.3",
     "@types/request": "2.48.8",
     "@types/ws": "8.5.4",
     "async": "3.2.4",
@@ -59,5 +59,5 @@
     "directory": "test/typescript"
   },
   "types": "index.d.ts",
-  "version": "9.2.1"
+  "version": "9.3.0"
 }

package/test/lnd_responses/test_failure_from_payment.js

@@ -2,8 +2,11 @@ const {test} = require('@alexbosworth/tap');
 
 const {failureFromPayment} = require('./../../lnd_responses');
 
+const id = Buffer.alloc(32).toString('hex')
+
 const makeExpected = overrides => {
   const expected = {
+    id,
     is_insufficient_balance: false,
     is_invalid_payment: false,
     is_pathfinding_timeout: false,
@@ -17,25 +20,42 @@ const makeExpected = overrides => {
 
 const tests = [
   {
-    args: {failure_reason: 'FAILURE_REASON_INSUFFICIENT_BALANCE'},
+    args: {
+      failure_reason: 'FAILURE_REASON_INSUFFICIENT_BALANCE',
+      payment_hash: id,
+    },
     description: 'Insufficient balance mapped',
     expected: makeExpected({is_insufficient_balance: true}),
   },
   {
-    args: {failure_reason: 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS'},
+    args: {
+      failure_reason: 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS',
+      payment_hash: id,
+    },
     description: 'Invalid payment is mapped',
     expected: makeExpected({is_invalid_payment: true}),
   },
   {
-    args: {failure_reason: 'FAILURE_REASON_NO_ROUTE'},
+    args: {
+      failure_reason: 'FAILURE_REASON_NO_ROUTE',
+      payment_hash: id,
+    },
     description: 'No route is mapped',
     expected: makeExpected({is_route_not_found: true}),
   },
   {
-    args: {failure_reason: 'FAILURE_REASON_TIMEOUT'},
+    args: {
+      failure_reason: 'FAILURE_REASON_TIMEOUT',
+      payment_hash: id,
+    },
     description: 'Timeout is mapped',
     expected: makeExpected({is_pathfinding_timeout: true}),
   },
+  {
+    args: {payment_hash: undefined},
+    description: 'A payment hash is expected',
+    error: 'ExpectedPaymentHashForPaymentAsFailedPayment',
+  },
 ];
 
 tests.forEach(({args, description, error, expected}) => {

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

@@ -1,41 +1,49 @@
 import {expectError, expectType} from 'tsd';
 import {failureFromPayment} from '../../lnd_responses/failure_from_payment';
 
+const payment_hash = Buffer.alloc(32).toString('hex')
+
 expectError(failureFromPayment());
 expectError(failureFromPayment({}));
-expectError(failureFromPayment({failure_reason: 'invalid failure reason'}));
+expectError(failureFromPayment({payment_hash, failure_reason: 'invalid failure reason'}));
 
 expectType<{
+  id: string;
   is_insufficient_balance: boolean;
   is_invalid_payment: boolean;
   is_pathfinding_timeout: boolean;
   is_route_not_found: boolean;
-}>(failureFromPayment({failure_reason: 'FAILURE_REASON_NONE'}));
+}>(failureFromPayment({payment_hash, failure_reason: 'FAILURE_REASON_NONE'}));
 expectType<{
+  id: string;
   is_insufficient_balance: true;
   is_invalid_payment: false;
   is_pathfinding_timeout: false;
   is_route_not_found: false;
-}>(failureFromPayment({failure_reason: 'FAILURE_REASON_INSUFFICIENT_BALANCE'}));
+}>(failureFromPayment({payment_hash, failure_reason: 'FAILURE_REASON_INSUFFICIENT_BALANCE'}));
 expectType<{
+  id: string;
   is_insufficient_balance: false;
   is_invalid_payment: true;
   is_pathfinding_timeout: false;
   is_route_not_found: false;
 }>(
   failureFromPayment({
+    payment_hash,
     failure_reason: 'FAILURE_REASON_INCORRECT_PAYMENT_DETAILS',
   })
 );
 expectType<{
+  id: string;
   is_insufficient_balance: false;
   is_invalid_payment: false;
   is_pathfinding_timeout: true;
   is_route_not_found: false;
-}>(failureFromPayment({failure_reason: 'FAILURE_REASON_TIMEOUT'}));
+}>(failureFromPayment({payment_hash, failure_reason: 'FAILURE_REASON_TIMEOUT'}));
 expectType<{
+  id: string;
   is_insufficient_balance: false;
   is_invalid_payment: false;
   is_pathfinding_timeout: false;
   is_route_not_found: true;
-}>(failureFromPayment({failure_reason: 'FAILURE_REASON_NO_ROUTE'}));
+}>(failureFromPayment({payment_hash, failure_reason: 'FAILURE_REASON_NO_ROUTE'}));