astra-lightning 1.0.0

package/lnd_methods/offchain/subscribe_to_past_payment.js

@@ -0,0 +1,156 @@
+const {createHash} = require('crypto');
+const EventEmitter = require('events');
+
+const asyncAuto = require('async/auto');
+const {chanFormat} = require('bolt07');
+
+const {confirmedFromPayment} = require('./../../lnd_responses');
+const {confirmedFromPaymentStatus} = require('./../../lnd_responses');
+const emitPayment = require('./emit_payment');
+const {failureFromPayment} = require('./../../lnd_responses');
+const {handleRemoveListener} = require('./../../grpc');
+const {isLnd} = require('./../../lnd_requests');
+const {safeTokens} = require('./../../bolt00');
+const {states} = require('./payment_states');
+
+const events = ['confirmed', 'failed', 'paying'];
+const hexToBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const isHash = n => /^[0-9A-F]{64}$/i.test(n);
+const method = 'trackPaymentV2';
+const mtokensPerToken = BigInt(1e3);
+const {nextTick} = process;
+const paymentNotInitiatedErr = `payment isn't initiated`;
+const sha256 = preimage => createHash('sha256').update(preimage).digest();
+const type = 'router';
+const unknownServiceErr = 'unknown service verrpc.Versioner';
+
+/** Subscribe to the status of a past payment
+
+  Requires `offchain:read` permission
+
+  {
+    id: <Payment Request Hash Hex String>
+    lnd: <Authenticated LND API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Subscription EventEmitter Object>
+
+  @event 'confirmed'
+  {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    fee: <Total Fee Tokens Paid Rounded Down Number>
+    fee_mtokens: <Total Fee Millitokens Paid String>
+    id: <Payment Hash Hex String>
+    mtokens: <Total Millitokens Paid String>
+    paths: [{
+      fee: <Total Fee Tokens Paid Number>
+      fee_mtokens: <Total Fee Millitokens Paid 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 Paid String>
+      safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+      safe_tokens: <Total Tokens Paid, Rounded Up Number>
+      timeout: <Expiration Block Height Number>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+    safe_tokens: <Total Tokens Paid, Rounded Up Number>
+    secret: <Payment Preimage Hex String>
+    timeout: <Expiration Block Height Number>
+    tokens: <Total Tokens Paid Rounded Down Number>
+  }
+
+  @event 'failed'
+  {
+    id: <Payment Hash Hex String>
+    is_canceled: <Payment Canceled Bool>
+    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>
+    is_route_not_found: <Failed Due to Absence of Path Through Graph Bool>
+  }
+
+  @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>
+  }
+*/
+module.exports = args => {
+  if (!isHash(args.id)) {
+    throw new Error('ExpectedIdOfPastPaymentToSubscribeTo');
+  }
+
+  if (!isLnd({method, type, lnd: args.lnd})) {
+    throw new Error('ExpectedAuthenticatedLndToSubscribeToPastPaymentStatus');
+  }
+
+  const emitter = new EventEmitter();
+  const hash = hexToBuffer(args.id);
+
+  const emitError = err => {
+    if (!emitter.listenerCount('error')) {
+      return;
+    }
+
+    if (!!isArray(err)) {
+      return emitter.emit('error', err);
+    }
+
+    if (err.details === paymentNotInitiatedErr) {
+      return emitter.emit('error', [404, 'SentPaymentNotFound']);
+    }
+
+    return emitter.emit('error', [503, 'UnexpectedGetPaymentError', {err}]);
+  };
+
+  const sub = args.lnd[type][method]({payment_hash: hash});
+
+  // Terminate subscription when all listeners are removed
+  handleRemoveListener({emitter, events, subscription: sub});
+
+  sub.on('data', data => emitPayment({data, emitter}));
+  sub.on('end', () => emitter.emit('end'));
+  sub.on('error', err => emitError(err));
+
+  return emitter;
+};

package/lnd_methods/offchain/subscribe_to_past_payments.d.ts

@@ -0,0 +1,75 @@
+import type {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningSubscription,
+  LightningError,
+} from '../../typescript';
+
+export type SubscribeToPastPaymentsArgs = AuthenticatedLightningArgs;
+
+export type SubscribeToPastPaymentsErrorEvent = LightningError;
+
+export type SubscribeToPastPaymentsPaymentEvent = {
+  /** Payment Confirmed At ISO 8601 Date String */
+  confirmed_at: string;
+  /** Created at ISO-8601 Date */
+  created_at: string;
+  /** Payment Destination Public Key Hex */
+  destination: string;
+  /** Paid Routing Fee Rounded Down Tokens Number */
+  fee: number;
+  /** Paid Routing Fee in Millitokens String */
+  fee_mtokens: string;
+  /** Payment Preimage Hash String */
+  id: string;
+  /** Millitokens Sent to Destination String */
+  mtokens: string;
+  paths: [
+    {
+      /** Total Fee Millitokens Paid String */
+      fee_mtokens: string;
+      hops: [
+        {
+          /** Standard Format Channel Id String */
+          channel: string;
+          /** Channel Capacity Tokens Number */
+          channel_capacity: number;
+          /** Fee Tokens Rounded Down Number */
+          fee: number;
+          /** Fee Millitokens String */
+          fee_mtokens: string;
+          /** Forward Millitokens String */
+          forward_mtokens: string;
+          /** Public Key Hex String */
+          public_key: string;
+          /** Timeout Block Height Number */
+          timeout: number;
+        }
+      ];
+      /** Total Millitokens Paid String */
+      mtokens: string;
+    }
+  ];
+  /** BOLT 11 Payment Request */
+  request?: string;
+  /** Total Fee Tokens Paid Rounded Up Number */
+  safe_fee: number;
+  /** Total Tokens Paid, Rounded Up Number */
+  safe_tokens: number;
+  /** Payment Preimage Hex String */
+  secret: string;
+  /** Expiration Block Height Number */
+  timeout: number;
+  /** Total Tokens Paid Rounded Down Number */
+  tokens: number;
+};
+
+/**
+ * Subscribe to successful outgoing payments
+ *
+ * Payments may be omitted if LND does not finalize the payment record
+ *
+ * Requires `offchain:read` permission
+ *
+ * Note: Method not supported on LND 0.13.4 and below
+ */
+export const subscribeToPastPayments: AuthenticatedLightningSubscription<SubscribeToPastPaymentsArgs>;

package/lnd_methods/offchain/subscribe_to_past_payments.js

@@ -0,0 +1,126 @@
+const {createHash} = require('crypto');
+const EventEmitter = require('events');
+
+const asyncDoUntil = require('async/doUntil');
+const {chanFormat} = require('bolt07');
+
+const {emitSubscriptionError} = require('./../../grpc');
+const {forwardFromHtlcEvent} = require('./../../lnd_responses');
+const getPayment = require('./get_payment');
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const cancelError = 'Cancelled on client';
+const event = 'payment';
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const method = 'subscribeHtlcEvents';
+const restartForwardListenerDelayMs = 1e3;
+const sha256 = preimage => createHash('sha256').update(preimage).digest();
+const type = 'router';
+const unknownFailureMessage = '2 UNKNOWN: unknown failure detail type: <nil>';
+
+/** Subscribe to successful outgoing payments
+
+  Payments may be omitted if LND does not finalize the payment record
+
+  Requires `offchain:read` permission
+
+  Note: Method not supported on LND 0.13.4 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Subscription EventEmitter Object>
+
+  @event 'error'
+  <Error Object>
+
+  @event 'payment'
+  {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Hex String>
+    fee: <Paid Routing Fee Rounded Down Tokens Number>
+    fee_mtokens: <Paid Routing Fee in Millitokens String>
+    id: <Payment Preimage Hash String>
+    mtokens: <Millitokens Sent to Destination String>
+    paths: [{
+      fee_mtokens: <Total Fee Millitokens Paid 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_mtokens: <Forward Millitokens String>
+        public_key: <Public Key Hex String>
+        timeout: <Timeout Block Height Number>
+      }]
+      mtokens: <Total Millitokens Paid String>
+    }]
+    [request]: <BOLT 11 Encoded Payment Request String>
+    safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+    safe_tokens: <Total Tokens Paid, Rounded Up Number>
+    secret: <Payment Preimage Hex String>
+    timeout: <Expiration Block Height Number>
+    tokens: <Total Tokens Paid Rounded Down Number>
+  }
+*/
+module.exports = ({lnd}) => {
+  if (!isLnd({lnd, method, type})) {
+    throw new Error('ExpectedAuthenticatedLndToSubscribeToPayments');
+  }
+
+  const emitter = new EventEmitter();
+  const sub = lnd[type][method]({});
+
+  const emitErr = emitSubscriptionError({emitter, subscription: sub});
+
+  sub.on('data', data => {
+    // Exit early on subscribed events
+    if (!!data && !!data.subscribed_event) {
+      return;
+    }
+
+    if (!!data && !!data.final_htlc_event) {
+      return;
+    }
+
+    try {
+      const htlc = forwardFromHtlcEvent(data);
+
+      // Exit early when the HTLC is not a send
+      if (!htlc.is_send || !htlc.secret) {
+        return;
+      }
+
+      return getPayment({
+        lnd,
+        id: bufferAsHex(sha256(hexAsBuffer(htlc.secret))),
+      },
+      (err, res) => {
+        if (!!err) {
+          return;
+        }
+
+        // Exit early when there is no payment
+        if (!res.payment) {
+          return;
+        }
+
+        // Emit payment details
+        return emitter.emit(event, res.payment);
+      });
+    } catch (err) {
+      return emitErr([503, err.message]);
+    }
+  });
+
+  sub.on('error', err => emitErr([503, 'UnexpectedPastPaymentsErr', {err}]));
+
+  return emitter;
+};

package/lnd_methods/offchain/subscribe_to_pay.d.ts

@@ -0,0 +1,299 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningSubscription,
+} from '../../typescript';
+import {MergeExclusive} from 'type-fest';
+
+export type SubscribeToPayWithDestinationArgs = {
+  /** Destination Public Key String> */
+  destination: string;
+  /** Payment Request Hash Hex String> */
+  id: string;
+  /** Final CLTV Delta Number> */
+  cltv_delta?: number;
+};
+
+export type SubscribeToPayWithRequestArgs = {
+  /** BOLT 11 Payment Request String> */
+  request: string;
+};
+
+export type SubscribeToPayWithDestinationOrRequestArgs = MergeExclusive<
+  SubscribeToPayWithDestinationArgs,
+  SubscribeToPayWithRequestArgs
+>;
+
+export type SubscribeToPayOptionsArgs = {
+  features?: {
+    /** Feature Bit Number> */
+    bit: number;
+  }[];
+  /** Pay Through Specific Final Hop Public Key Hex String> */
+  incoming_peer?: string;
+  /** Maximum Fee Tokens To Pay Number> */
+  max_fee?: number;
+  /** Maximum Fee Millitokens to Pay String> */
+  max_fee_mtokens?: string;
+  /** Maximum Millitokens For A Multi-Path Path */
+  max_path_mtokens?: string;
+  /** Maximum Simultaneous Paths Number> */
+  max_paths?: number;
+  /** Maximum Height of Payment Timeout Number> */
+  max_timeout_height?: number;
+  messages?: {
+    /** Message Type Number String> */
+    type: string;
+    /** Message Raw Value Hex Encoded String> */
+    value: string;
+  }[];
+  /** Millitokens to Pay String> */
+  mtokens?: string;
+  /** Pay Out of Outgoing Channel Id String> */
+  outgoing_channel?: string;
+  /** Pay Out of Outgoing Channel Ids String> */
+  outgoing_channels?: string[];
+  /** Time to Spend Finding a Route Milliseconds Number> */
+  pathfinding_timeout?: number;
+  /** Payment Identifier Hex String> */
+  payment?: string;
+  routes?: {
+    /** Base Routing Fee In Millitokens String> */
+    base_fee_mtokens?: string;
+    /** Standard Format Channel Id String> */
+    channel?: string;
+    /** CLTV Blocks Delta Number> */
+    cltv_delta?: number;
+    /** Fee Rate In Millitokens Per Million Number> */
+    fee_rate?: number;
+    /** Forward Edge Public Key Hex String> */
+    public_key: string;
+  }[][];
+  /** Tokens to Pay Number> */
+  tokens?: number;
+};
+
+export type SubscribeToPayArgs = AuthenticatedLightningArgs<
+  SubscribeToPayWithDestinationOrRequestArgs & SubscribeToPayOptionsArgs
+>;
+
+export type SubscribeToPayConfirmedEvent = {
+  /** Payment Confirmed At ISO 8601 Date String */
+  confirmed_at: string;
+  /** Total Fee Tokens Paid Rounded Down Number> */
+  fee: number;
+  /** Total Fee Millitokens Paid String> */
+  fee_mtokens: string;
+  hops: {
+    /** First Route Standard Format Channel Id String> */
+    channel: string;
+    /** First Route Channel Capacity Tokens Number> */
+    channel_capacity: number;
+    /** First Route Fee Tokens Rounded Down Number> */
+    fee: number;
+    /** First Route Fee Millitokens String> */
+    fee_mtokens: string;
+    /** First Route Forward Millitokens String> */
+    forward_mtokens: string;
+    /** First Route Public Key Hex String> */
+    public_key: string;
+    /** First Route Timeout Block Height Number> */
+    timeout: number;
+  }[];
+  /** Payment Hash Hex String> */
+  id: string;
+  /** Payment Index String */
+  index: string;
+  /** Total Millitokens Paid String> */
+  mtokens: string;
+  paths: {
+    /** Total Fee Millitokens Paid String> */
+    fee_mtokens: string;
+    hops: {
+      /** First Route Standard Format Channel Id String> */
+      channel: string;
+      /** First Route Channel Capacity Tokens Number> */
+      channel_capacity: number;
+      /** First Route Fee Tokens Rounded Down Number> */
+      fee: number;
+      /** First Route Fee Millitokens String> */
+      fee_mtokens: string;
+      /** First Route Forward Millitokens String> */
+      forward_mtokens: string;
+      /** First Route Public Key Hex String> */
+      public_key: string;
+      /** First Route Timeout Block Height Number> */
+      timeout: number;
+    }[];
+    /** Total Millitokens Paid String> */
+    mtokens: string;
+  }[];
+  /** Total Fee Tokens Paid Rounded Up Number> */
+  safe_fee: number;
+  /** Total Tokens Paid, Rounded Up Number> */
+  safe_tokens: number;
+  /** Payment Preimage Hex String> */
+  secret: string;
+  /** Expiration Block Height Number> */
+  timeout: number;
+  /** Total Tokens Paid Rounded Down Number> */
+  tokens: number;
+};
+
+export type SubscribeToPayFailedEvent = {
+  /** Payment Hash Hex */
+  id: string;
+  /** Payment Canceled */
+  is_canceled: boolean;
+  /** Failed Due To Lack of Balance */
+  is_insufficient_balance: boolean;
+  /** Failed Due to Invalid Payment Bool> */
+  is_invalid_payment: boolean;
+  /** Failed Due to Pathfinding Timeout Bool> */
+  is_pathfinding_timeout: boolean;
+  /** Failed Due to Route Not Found Bool> */
+  is_route_not_found: boolean;
+  route?: {
+    /** Route Total Fee Tokens Rounded Down Number> */
+    fee: number;
+    /** Route Total Fee Millitokens String> */
+    fee_mtokens: string;
+    hops: {
+      /** Standard Format Channel Id String> */
+      channel: string;
+      /** Channel Capacity Tokens Number> */
+      channel_capacity: number;
+      /** Hop Forwarding Fee Rounded Down Tokens Number> */
+      fee: number;
+      /** Hop Forwarding Fee Millitokens String> */
+      fee_mtokens: string;
+      /** Hop Forwarding Tokens Rounded Down Number> */
+      forward: number;
+      /** Hop Forwarding Millitokens String> */
+      forward_mtokens: string;
+      /** Hop Sending To Public Key Hex String> */
+      public_key: string;
+      /** Hop CTLV Expiration Height Number> */
+      timeout: number;
+    }[];
+    /** Payment Sending Millitokens String> */
+    mtokens: string;
+    /** Payment Forwarding Fee Rounded Up Tokens Number> */
+    safe_fee: number;
+    /** Payment Sending Tokens Rounded Up Number> */
+    safe_tokens: number;
+    /** Payment CLTV Expiration Height Number> */
+    timeout: number;
+    /** Payment Sending Tokens Rounded Down Number> */
+    tokens: number;
+  };
+};
+
+export type SubscribeToPayPayingEvent = {
+  /** Payment Created At ISO 8601 Date String> */
+  created_at: string;
+  /** Payment Destination Hex String> */
+  destination: string;
+  /** Payment Hash Hex String> */
+  id: string;
+  /** Payment Index String */
+  index: string;
+  /** Total Millitokens Pending String> */
+  mtokens: string;
+  paths: {
+    /** Total Fee Tokens Pending Number> */
+    fee: number;
+    /** Total Fee Millitokens Pending String> */
+    fee_mtokens: string;
+    hops: {
+      /** Standard Format Channel Id String> */
+      channel: string;
+      /** Channel Capacity Tokens Number> */
+      channel_capacity: number;
+      /** Fee Tokens Rounded Down Number> */
+      fee: number;
+      /** Fee Millitokens String> */
+      fee_mtokens: string;
+      /** Forward Tokens Number> */
+      forward: number;
+      /** Forward Millitokens String> */
+      forward_mtokens: string;
+      /** Public Key Hex String> */
+      public_key: string;
+      /** Timeout Block Height Number> */
+      timeout: number;
+    }[];
+    /** Total Millitokens Pending String> */
+    mtokens: string;
+    /** Total Fee Tokens Pending Rounded Up Number> */
+    safe_fee: number;
+    /** Total Tokens Pending, Rounded Up Number> */
+    safe_tokens: number;
+    /** Expiration Block Height Number> */
+    timeout: number;
+  }[];
+  /** BOLT 11 Encoded Payment Request String> */
+  request?: string;
+  /** Total Tokens Pending, Rounded Up Number> */
+  safe_tokens: number;
+  /** Expiration Block Height Number> */
+  timeout?: number;
+  /** Total Tokens Pending Rounded Down Number> */
+  tokens: number;
+};
+
+export type SubscribeToRoutingFailureEvent = {
+  /** Standard Format Channel Id String> */
+  channel?: string;
+  /** Failure Index Number> */
+  index: number;
+  /** Millitokens String> */
+  mtokens?: string;
+  /** Public Key Hex String> */
+  public_key?: string;
+  /** Failure Reason String> */
+  reason: string;
+  route: {
+    /** Total Route Fee Tokens To Pay Number> */
+    fee: number;
+    /** Total Route Fee Millitokens To Pay String> */
+    fee_mtokens: string;
+    hops: {
+      /** Standard Format Channel Id String> */
+      channel: string;
+      /** Channel Capacity Tokens Number> */
+      channel_capacity: number;
+      /** Fee Number> */
+      fee: number;
+      /** Fee Millitokens String> */
+      fee_mtokens: string;
+      /** Forward Tokens Number> */
+      forward: number;
+      /** Forward Millitokens String> */
+      forward_mtokens: string;
+      /** Public Key Hex String> */
+      public_key: string;
+      /** Timeout Block Height Number> */
+      timeout: number;
+    }[];
+    /** Total Route Millitokens String> */
+    mtokens: string;
+    /** Payment Identifier Hex String> */
+    payment?: string;
+    /** Expiration Block Height Number> */
+    timeout: number;
+    /** Total Route Tokens Number> */
+    tokens: number;
+    /** Total Millitokens String> */
+    total_mtokens?: string;
+  };
+};
+
+/**
+ * Initiate and subscribe to the outcome of a payment
+ *
+ * Either a request or a destination, id, and tokens amount is required
+ *
+ * `max_path_mtokens` is not supported in LND 0.12.0 or below
+ *
+ */
+export const subscribeToPay: AuthenticatedLightningSubscription<SubscribeToPayArgs>;