astra-lightning 1.0.0

package/lnd_methods/offchain/route_failure_keys.js

@@ -0,0 +1,49 @@
+const {chanFormat} = require('bolt07');
+
+const notFoundIndex = -1;
+
+/** Determine which public keys were associated with a payment route failure
+
+  {
+    [failure]: {
+      channel_update: {
+        chan_id: <Numeric Format Channel Id String>
+      }
+    }
+    route: {
+      hops: [{
+        channel: <Standard Format Channel Id String>
+        public_key: <Public Key Hex String>
+      }]
+    }
+  }
+
+  @returns
+  {
+    [keys]: [<Public Key Hex String>]
+  }
+*/
+module.exports = ({failure, route}) => {
+  // Exit early when there is no failure to derive failure keys for
+  if (!failure) {
+    return {};
+  }
+
+  // Exit early when no specific failure is returned
+  if (!failure.channel_update || !failure.channel_update.chan_id) {
+    return {};
+  }
+
+  const {channel} = chanFormat({number: failure.channel_update.chan_id});
+
+  const hopIndex = route.hops.findIndex(n => n.channel === channel);
+
+  // Exit early when there are no keys, or the failure is from a direct peer
+  if (!hopIndex || hopIndex === notFoundIndex) {
+    return {};
+  }
+
+  const hops = [route.hops[hopIndex], route.hops[hopIndex - [failure].length]];
+
+  return {keys: hops.filter(n => !!n).map(hop => hop.public_key)};
+};

package/lnd_methods/offchain/send_message_to_peer.d.ts

@@ -0,0 +1,28 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type LightningMessage = {
+  /** Message Hex String */
+  message: string;
+  /** To Peer Public Key Hex String */
+  public_key: string;
+  /** Message Type Number */
+  type?: number;
+};
+
+export type SendMessageToPeerArgs =
+  AuthenticatedLightningArgs<LightningMessage>;
+
+/**
+ * Send a custom message to a connected peer
+ *
+ * If specified, message type is expected to be between 32768 and 65535
+ * Message data should not be larger than 65533 bytes
+ *
+ * Note: this method is not supported in LND versions 0.13.4 and below
+ *
+ * Requires `offchain:write` permission
+ */
+export const sendMessageToPeer: AuthenticatedLightningMethod<SendMessageToPeerArgs>;

package/lnd_methods/offchain/send_message_to_peer.js

@@ -0,0 +1,70 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferFromHex = hex => Buffer.from(hex, 'hex');
+const defaultMessageType = 32768;
+const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const isPublicKey = n => !!n && /^[0-9A-F]{66}$/i.test(n);
+const method = 'sendCustomMessage';
+const type = 'default';
+
+/** Send a custom message to a connected peer
+
+  If specified, message type is expected to be between 32768 and 65535
+
+  Message data should not be larger than 65533 bytes
+
+  Note: this method is not supported in LND versions 0.13.4 and below
+
+  Requires `offchain:write` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+    message: <Message Hex String>
+    public_key: <To Peer Public Key Hex String>
+    [type]: <Message Type Number>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToSendMessageToPeer']);
+        }
+
+        if (!isHex(args.message)) {
+          return cbk([400, 'ExpectedCustomMessageDataToSendToPeer']);
+        }
+
+        if (!isPublicKey(args.public_key)) {
+          return cbk([400, 'ExpectedPeerPublicKeyToSendMessageTo']);
+        }
+
+        return cbk();
+      },
+
+      // Send the message to the peer
+      send: ['validate', ({}, cbk) => {
+        return args.lnd[type][method]({
+          data: bufferFromHex(args.message),
+          peer: bufferFromHex(args.public_key),
+          type: args.type || defaultMessageType,
+        },
+        err => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorSendingMessageToPeer', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/offchain/subscribe_to_backups.d.ts

@@ -0,0 +1,21 @@
+import {AuthenticatedLightningSubscription} from '../../typescript';
+
+export type SubscribeToBackupsBackupEvent = {
+  /** Backup Hex */
+  backup: string;
+  channels: {
+    /** Backup Hex */
+    backup: string;
+    /** Funding Transaction Id Hex */
+    transaction_id: string;
+    /** Funding Transaction Output Index */
+    transaction_vout: number;
+  }[];
+};
+
+/**
+ * Subscribe to backup snapshot updates
+ *
+ * Requires `offchain:read` permission
+ */
+export const subscribeToBackups: AuthenticatedLightningSubscription;

package/lnd_methods/offchain/subscribe_to_backups.js

@@ -0,0 +1,84 @@
+const EventEmitter = require('events');
+
+const {backupsFromSnapshot} = require('./../../lnd_responses');
+const {isLnd} = require('./../../lnd_requests');
+
+const cancelError = 'Cancelled on client';
+const method = 'subscribeChannelBackups';
+const type = 'default';
+
+/** Subscribe to backup snapshot updates
+
+  Requires `offchain:read` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <EventEmitter Object>
+
+  @event 'backup'
+  {
+    backup: <Backup Hex String>
+    channels: [{
+      backup: <Backup Hex String>
+      transaction_id: <Funding Transaction Id Hex String>
+      transaction_vout: <Funding Transaction Output Index Number>
+    }]
+  }
+*/
+module.exports = ({lnd}) => {
+  if (!isLnd({lnd, method, type})) {
+    throw new Error('ExpectedAuthenticatedLndToSubscribeToBackups');
+  }
+
+  const eventEmitter = new EventEmitter();
+  const subscription = lnd[type][method]({});
+
+  // Cancel the subscription when all listeners are removed
+  eventEmitter.on('removeListener', () => {
+    // Exit early when there are still listeners
+    if (!!eventEmitter.listenerCount('backup')) {
+      return;
+    }
+
+    subscription.cancel();
+
+    return;
+  });
+
+  const emitError = err => {
+    subscription.cancel();
+
+    if (!!err && err.details === cancelError) {
+      subscription.removeAllListeners();
+    }
+
+    // Exit early when there are no error listeners
+    if (!eventEmitter.listenerCount('error')) {
+      return;
+    }
+
+    eventEmitter.emit('error', err);
+
+    return;
+  };
+
+  subscription.on('data', snapshot => {
+    try {
+      return eventEmitter.emit('backup', backupsFromSnapshot(snapshot));
+    } catch (err) {
+      return emitError([503, err.message]);
+    }
+  });
+
+  subscription.on('end', () => eventEmitter.emit('end'));
+  subscription.on('error', err => emitError(err));
+  subscription.on('status', status => eventEmitter.emit('status', status));
+
+  return eventEmitter;
+};

package/lnd_methods/offchain/subscribe_to_channels.d.ts

@@ -0,0 +1,150 @@
+import {AuthenticatedLightningSubscription} from '../../typescript';
+
+export type SubscribeToChannelsChannelActiveChangedEvent = {
+  /** Channel Is Active */
+  is_active: boolean;
+  /** Channel Funding Transaction Id */
+  transaction_id: string;
+  /** Channel Funding Transaction Output Index */
+  transaction_vout: number;
+};
+
+export type SubscribeToChannelsChannelClosedEvent = {
+  /** Closed Channel Capacity Tokens */
+  capacity: number;
+  /** Channel Balance Output Spent By Tx Id */
+  close_balance_spent_by?: string;
+  /** Channel Balance Close Tx Output Index */
+  close_balance_vout?: number;
+  /** Channel Close Confirmation Height */
+  close_confirm_height?: number;
+  close_payments: {
+    /** Payment Is Outgoing */
+    is_outgoing: boolean;
+    /** Payment Is Claimed With Preimage */
+    is_paid: boolean;
+    /** Payment Resolution Is Pending */
+    is_pending: boolean;
+    /** Payment Timed Out And Went Back To Payer */
+    is_refunded: boolean;
+    /** Close Transaction Spent By Transaction Id Hex */
+    spent_by?: string;
+    /** Associated Tokens */
+    tokens: number;
+    /** Transaction Id Hex */
+    transaction_id: string;
+    /** Transaction Output Index */
+    transaction_vout: number;
+  }[];
+  /** Closing Transaction Id Hex */
+  close_transaction_id?: string;
+  /** Channel Close Final Local Balance Tokens */
+  final_local_balance: number;
+  /** Closed Channel Timelocked Tokens */
+  final_time_locked_balance: number;
+  /** Closed Standard Format Channel Id */
+  id?: string;
+  /** Is Breach Close */
+  is_breach_close: boolean;
+  /** Is Cooperative Close */
+  is_cooperative_close: boolean;
+  /** Is Funding Cancelled Close */
+  is_funding_cancel: boolean;
+  /** Is Local Force Close */
+  is_local_force_close: boolean;
+  /** Channel Was Closed By Channel Peer */
+  is_partner_closed?: boolean;
+  /** Channel Was Initiated By Channel Peer */
+  is_partner_initiated?: boolean;
+  /** Is Remote Force Close */
+  is_remote_force_close: boolean;
+  /** Other Channel Ids */
+  other_ids: string[];
+  /** Partner Public Key Hex */
+  partner_public_key: string;
+  /** Channel Funding Transaction Id Hex */
+  transaction_id: string;
+  /** Channel Funding Output Index */
+  transaction_vout: number;
+};
+
+export type SubscribeToChannelsChannelOpenedEvent = {
+  /** Channel Token Capacity */
+  capacity: number;
+  /** Commit Transaction Fee */
+  commit_transaction_fee: number;
+  /** Commit Transaction Weight */
+  commit_transaction_weight: number;
+  /** Coop Close Restricted to Address */
+  cooperative_close_address?: string;
+  /** Prevent Coop Close Until Height */
+  cooperative_close_delay_height?: number;
+  /** Standard Format Channel Id */
+  id: string;
+  /** Channel Active */
+  is_active: boolean;
+  /** Channel Is Closing */
+  is_closing: boolean;
+  /** Channel Is Opening */
+  is_opening: boolean;
+  /** Channel Partner Opened Channel */
+  is_partner_initiated: boolean;
+  /** Channel Is Private */
+  is_private: boolean;
+  /** Funding Output is Trusted */
+  is_trusted_funding: boolean;
+  /** Local Balance Tokens */
+  local_balance: number;
+  /** Local Initially Pushed Tokens */
+  local_given?: number;
+  /** Local Reserved Tokens */
+  local_reserve: number;
+  /** Channel Partner Public Key */
+  partner_public_key: string;
+  /** Total Count of Past Channel States */
+  past_states: number;
+  pending_payments: {
+    /** Payment Preimage Hash Hex */
+    id: string;
+    /** Payment Is Outgoing */
+    is_outgoing: boolean;
+    /** Chain Height Expiration */
+    timeout: number;
+    /** Payment Tokens */
+    tokens: number;
+  }[];
+  /** Received Tokens */
+  received: number;
+  /** Remote Balance Tokens */
+  remote_balance: number;
+  /** Remote Initially Pushed Tokens */
+  remote_given?: number;
+  /** Remote Reserved Tokens */
+  remote_reserve: number;
+  /** Sent Tokens */
+  sent: number;
+  /** Blockchain Transaction Id */
+  transaction_id: string;
+  /** Blockchain Transaction Vout */
+  transaction_vout: number;
+  /** Channel Commitment Transaction Type */
+  type?: string;
+  /** Unsettled Balance Tokens */
+  unsettled_balance: number;
+};
+
+export type SubscribeToChannelsChannelOpeningEvent = {
+  /** Blockchain Transaction Id Hex */
+  transaction_id: string;
+  /** Blockchain Transaction Output Index */
+  transaction_vout: number;
+};
+
+/**
+ * Subscribe to channel updates
+ *
+ * Requires `offchain:read` permission
+ *
+ * `is_trusted_funding`, `other_ids` are not supported on LND 0.15.0 and below
+ */
+export const subscribeToChannels: AuthenticatedLightningSubscription;

package/lnd_methods/offchain/subscribe_to_channels.js

@@ -0,0 +1,229 @@
+const EventEmitter = require('events');
+
+const {isLnd} = require('./../../lnd_requests');
+const {rpcChannelAsChannel} = require('./../../lnd_responses');
+const {rpcClosedChannelAsClosed} = require('./../../lnd_responses');
+const {rpcOutpointAsUpdate} = require('./../../lnd_responses');
+
+const asError = msg => new Error(msg);
+const emptyTxId = Buffer.alloc(32).toString('hex');
+const eventActive = 'channel_active_changed';
+const eventClosed = 'channel_closed';
+const eventOpen = 'channel_opened';
+const eventOpening = 'channel_opening';
+const method = 'subscribeChannelEvents';
+const shutDownMessage = 'Cancelled';
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const type = 'default';
+const updateActive = 'active_channel';
+const updateInactive = 'inactive_channel';
+const updateClosed = 'closed_channel';
+const updateOpened = 'open_channel';
+const updateOpening = 'pending_open_channel';
+
+/** Subscribe to channel updates
+
+  Requires `offchain:read` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  `is_trusted_funding`, `other_ids` are not supported on LND 0.15.0 and below
+
+  `description` is not supported on LND 0.16.4 and below
+
+  @throws
+  <Error>
+
+  @returns
+  <EventEmitter Object>
+
+  @event 'channel_active_changed'
+  {
+    is_active: <Channel Is Active Bool>
+    transaction_id: <Channel Funding Transaction Id String>
+    transaction_vout: <Channel Funding Transaction Output Index Number>
+  }
+
+  @event 'channel_closed'
+  {
+    capacity: <Closed Channel Capacity Tokens Number>
+    [close_balance_spent_by]: <Channel Balance Output Spent By Tx Id String>
+    [close_balance_vout]: <Channel Balance Close Tx Output Index Number>
+    [close_confirm_height]: <Channel Close Confirmation Height Number>
+    close_payments: [{
+      is_outgoing: <Payment Is Outgoing Bool>
+      is_paid: <Payment Is Claimed With Preimage Bool>
+      is_pending: <Payment Resolution Is Pending Bool>
+      is_refunded: <Payment Timed Out And Went Back To Payer Bool>
+      [spent_by]: <Close Transaction Spent By Transaction Id Hex String>
+      tokens: <Associated Tokens Number>
+      transaction_id: <Transaction Id Hex String>
+      transaction_vout: <Transaction Output Index Number>
+    }]
+    [close_transaction_id]: <Closing Transaction Id Hex String>
+    final_local_balance: <Channel Close Final Local Balance Tokens Number>
+    final_time_locked_balance: <Closed Channel Timelocked Tokens Number>
+    [id]: <Closed Standard Format Channel Id String>
+    is_breach_close: <Is Breach Close Bool>
+    is_cooperative_close: <Is Cooperative Close Bool>
+    is_funding_cancel: <Is Funding Cancelled Close Bool>
+    is_local_force_close: <Is Local Force Close Bool>
+    is_partner_closed: <Channel Was Closed By Channel Peer Bool>
+    is_partner_initiated: <Channel Was Initiated By Channel Peer Bool>
+    is_remote_force_close: <Is Remote Force Close Bool>
+    other_ids: [<Other Channel Id String>]
+    partner_public_key: <Partner Public Key Hex String>
+    transaction_id: <Channel Funding Transaction Id Hex String>
+    transaction_vout: <Channel Funding Output Index Number>
+  }
+
+  @event 'channel_opened'
+  {
+    capacity: <Channel Token Capacity Number>
+    commit_transaction_fee: <Commit Transaction Fee Number>
+    commit_transaction_weight: <Commit Transaction Weight Number>
+    [cooperative_close_address]: <Coop Close Restricted to Address String>
+    [cooperative_close_delay_height]: <Prevent Coop Close Until Height Number>
+    [description]: <Channel Description String>
+    id: <Standard Format Channel Id String>
+    is_active: <Channel Active Bool>
+    is_closing: <Channel Is Closing Bool>
+    is_opening: <Channel Is Opening Bool>
+    is_partner_initiated: <Channel Partner Opened Channel Bool>
+    is_private: <Channel Is Private Bool>
+    [is_trusted_funding]: <Funding Output is Trusted Bool>
+    local_balance: <Local Balance Tokens Number>
+    local_given: <Local Initially Pushed Tokens Number>
+    local_reserve: <Local Reserved Tokens Number>
+    partner_public_key: <Channel Partner Public Key String>
+    past_states: <Total Count of Past Channel States Number>
+    pending_payments: [{
+      id: <Payment Preimage Hash Hex String>
+      is_outgoing: <Payment Is Outgoing Bool>
+      timeout: <Chain Height Expiration Number>
+      tokens: <Payment Tokens Number>
+    }]
+    received: <Received Tokens Number>
+    remote_balance: <Remote Balance Tokens Number>
+    remote_given: <Remote Initially Pushed Tokens Number>
+    remote_reserve: <Remote Reserved Tokens Number>
+    sent: <Sent Tokens Number>
+    transaction_id: <Blockchain Transaction Id String>
+    transaction_vout: <Blockchain Transaction Vout Number>
+    [type]: <Channel Commitment Transaction Type String>
+    unsettled_balance: <Unsettled Balance Tokens Number>
+  }
+
+  @event 'channel_opening'
+  {
+    transaction_id: <Blockchain Transaction Id Hex String>
+    transaction_vout: <Blockchain Transaction Output Index Number>
+  }
+*/
+module.exports = ({lnd}) => {
+  if (!isLnd({lnd, method, type})) {
+    throw new Error('ExpectedAuthenticatedLndToSubscribeToChannels');
+  }
+
+  const eventEmitter = new EventEmitter();
+  const subscription = lnd[type][method]({});
+
+  // Cancel the subscription when all listeners are removed
+  eventEmitter.on('removeListener', () => {
+    const events = [eventActive, eventClosed, eventOpen, eventOpening];
+
+    const listenerCounts = events.map(n => eventEmitter.listenerCount(n));
+
+    // Exit early when there are still listeners
+    if (!!sumOf(listenerCounts)) {
+      return;
+    }
+
+    subscription.cancel();
+
+    return;
+  });
+
+  const emitError = err => {
+    if (err.details === shutDownMessage) {
+      subscription.removeAllListeners();
+    } else {
+      subscription.cancel();
+    }
+
+    // Exit early when no one is listening to the error
+    if (!eventEmitter.listenerCount('error')) {
+      return;
+    }
+
+    return eventEmitter.emit('error', err);
+  };
+
+  subscription.on('data', update => {
+    if (!update) {
+      return emitError(asError('ExpectedEventDetailsInChannelSubscription'));
+    }
+
+    if (!update.type || !update.type.toLowerCase) {
+      return emitError(asError('ExpectedEventTypeInChannelSubscription'));
+    }
+
+    const updateType = update.type.toLowerCase();
+
+    const details = update[updateType];
+
+    if (!details) {
+      return emitError(asError('ExpectedEventDetailsForTypeInChannelSub'));
+    }
+
+    try {
+      switch (updateType) {
+      case updateActive:
+        eventEmitter.emit(eventActive, {
+          is_active: true,
+          transaction_id: rpcOutpointAsUpdate(details).transaction_id,
+          transaction_vout: rpcOutpointAsUpdate(details).transaction_vout,
+        });
+        break;
+
+      case updateClosed:
+        eventEmitter.emit(eventClosed, rpcClosedChannelAsClosed(details));
+        break;
+
+      case updateInactive:
+        eventEmitter.emit(eventActive, {
+          is_active: false,
+          transaction_id: rpcOutpointAsUpdate(details).transaction_id,
+          transaction_vout: rpcOutpointAsUpdate(details).transaction_vout,
+        });
+        break;
+
+      case updateOpened:
+        eventEmitter.emit(eventOpen, rpcChannelAsChannel(details));
+        break;
+
+      case updateOpening:
+        eventEmitter.emit(eventOpening, {
+          transaction_id: rpcOutpointAsUpdate(details).transaction_id,
+          transaction_vout: rpcOutpointAsUpdate(details).transaction_vout,
+        });
+        break;
+
+      default:
+        break;
+      }
+    } catch (err) {
+      return emitError(err);
+    }
+
+    return;
+  });
+
+  subscription.on('end', () => eventEmitter.emit('end'));
+  subscription.on('error', err => emitError(err));
+  subscription.on('status', status => eventEmitter.emit('status', status));
+
+  return eventEmitter;
+};

package/lnd_methods/offchain/subscribe_to_forward_requests.d.ts

@@ -0,0 +1,49 @@
+import {AuthenticatedLightningSubscription} from '../../typescript';
+
+export type SubscribeToForwardRequestsForwardRequestEvent = {
+  accept: () => void;
+  /** Difference Between Out and In CLTV Height */
+  cltv_delta: number;
+  /** Routing Fee Tokens Rounded Down */
+  fee: number;
+  /** Routing Fee Millitokens */
+  fee_mtokens: string;
+  /** Payment Hash Hex */
+  hash: string;
+  /** Inbound Standard Format Channel Id */
+  in_channel: string;
+  /** Inbound Channel Payment Id */
+  in_payment: number;
+  messages: {
+    /** Message Type number */
+    type: string;
+    /** Raw Value Hex */
+    value: string;
+  }[];
+  /** Millitokens to Forward To Next Peer */
+  mtokens: string;
+  /** Hex Serialized Next-Hop Onion Packet To Forward */
+  onion?: string;
+  /** Requested Outbound Channel Standard Format Id */
+  out_channel: string;
+  /** Reject Forward */
+  reject: () => void;
+  /** Short Circuit */
+  settle: (args: {secret: string}) => void;
+  /** CLTV Timeout Height */
+  timeout: number;
+  /** Tokens to Forward to Next Peer Rounded Down */
+  tokens: number;
+};
+
+/**
+ * Subscribe to requests to forward payments
+ * 
+ * Note that the outbound channel is only the requested channel, another may be
+selected internally to complete the forward.
+ *
+ * Requires `offchain:read`, `offchain:write` permission
+ *
+ * `onion` is not supported in LND 0.11.1 and below
+ */
+export const subscribeToForwardRequests: AuthenticatedLightningSubscription;