astra-lightning 1.0.0

package/lnd_methods/invoices/subscribe_to_invoices.js

@@ -0,0 +1,177 @@
+const EventEmitter = require('events');
+
+const asyncDoUntil = require('async/doUntil');
+
+const {handleRemoveListener} = require('./../../grpc');
+const {isLnd} = require('./../../lnd_requests');
+const {rpcInvoiceAsInvoice} = require('./../../lnd_responses');
+
+const connectionFailureMessage = 'failed to connect to all addresses';
+const events = ['end', 'error', 'invoice_updated', 'status'];
+const msPerSec = 1e3;
+const restartSubscriptionMs = 1000 * 30;
+const sumOf = arr => arr.reduce((sum, n) => sum + n, Number());
+const updateEvent = 'invoice_updated';
+
+/** Subscribe to invoices
+
+  Requires `invoices:read` permission
+
+  `payment` is not supported on LND 0.11.1 and below
+
+  {
+    [added_after]: <Invoice Added After Index Number>
+    [confirmed_after]: <Invoice Confirmed After Index Number>
+    lnd: <Authenticated LND API Object>
+    [restart_delay_ms]: <Restart Subscription Delay Milliseconds Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <EventEmitter Object>
+
+  @event 'invoice_updated'
+  {
+    [chain_address]: <Fallback Chain Address String>
+    cltv_delta: <Final CLTV Delta Number>
+    [confirmed_at]: <Confirmed At ISO 8601 Date String>
+    [confirmed_index]: <Confirmed Index Number>
+    created_at: <Created At ISO 8601 Date String>
+    description: <Description String>
+    description_hash: <Description Hash Hex String>
+    expires_at: <Expires At ISO 8601 Date String>
+    features: [{
+      bit: <Feature Bit Number>
+      is_known: <Is Known Feature Bool>
+      is_required: <Feature Is Required Bool>
+      name: <Feature Name String>
+    }]
+    id: <Invoice Payment Hash Hex String>
+    index: <Invoice Index Number>
+    is_confirmed: <Invoice is Confirmed Bool>
+    [is_push]: <Invoice is Push Payment Bool>
+    mtokens: <Invoiced Millitokens String>
+    [payment]: <Payment Identifying Secret Hex String>
+    payments: [{
+      [confirmed_at]: <Payment Settled At ISO 8601 Date String>
+      created_at: <Payment Held Since ISO 860 Date String>
+      created_height: <Payment Held Since Block Height Number>
+      in_channel: <Incoming Payment Through Channel Id String>
+      is_canceled: <Payment is Canceled Bool>
+      is_confirmed: <Payment is Confirmed Bool>
+      is_held: <Payment is Held Bool>
+      messages: [{
+        type: <Message Type Number String>
+        value: <Raw Value Hex String>
+      }]
+      mtokens: <Incoming Payment Millitokens String>
+      [pending_index]: <Pending Payment Channel HTLC Index Number>
+      tokens: <Payment Tokens Number>
+      [total_mtokens]: <Total Payment Millitokens String>
+    }]
+    received: <Received Tokens Number>
+    received_mtokens: <Received Millitokens String>
+    [request]: <BOLT 11 Payment Request String>
+    secret: <Payment Secret Hex String>
+    tokens: <Invoiced Tokens Number>
+  }
+*/
+module.exports = args => {
+  if (!isLnd({lnd: args.lnd, method: 'subscribeInvoices', type: 'default'})) {
+    throw new Error('ExpectedAuthenticatedLndToSubscribeInvoices');
+  }
+
+  let addIndex = args.added_after;
+  let confirmedAfter = args.confirmed_after;
+  const eventEmitter = new EventEmitter();
+
+  asyncDoUntil(cbk => {
+    // Safeguard the callback from being fired multiple times
+    let isFinished = false;
+
+    // Start the subscription to invoices
+    const subscription = args.lnd.default.subscribeInvoices({
+      add_index: !!addIndex ? addIndex.toString() : undefined,
+      settle_index: !!confirmedAfter ? confirmedAfter.toString() : undefined,
+    });
+
+    // Terminate subscription when all listeners are removed
+    handleRemoveListener({subscription, events, emitter: eventEmitter});
+
+    // Subscription finished callback
+    const finished = err => {
+      if (!!eventEmitter.listenerCount('error')) {
+        eventEmitter.emit('error', err);
+      }
+
+      // Exit early when this subscription is already over
+      if (!!isFinished) {
+        return;
+      }
+
+      isFinished = true;
+
+      const listenerCount = eventEmitter.listenerCount(updateEvent);
+
+      // Exit early when there are no listeners
+      if (!listenerCount) {
+        return cbk(null, {listener_count: listenerCount});
+      }
+
+      // Delay restart when there are listeners
+      return setTimeout(() => {
+        return cbk(null, {listener_count: listenerCount});
+      },
+      args.restart_delay_ms || restartSubscriptionMs);
+    };
+
+    // Finish early when all listeners are removed
+    eventEmitter.on('removeListener', () => {
+      // Exit early when there are still active listeners
+      if (!!sumOf(events.map(n => eventEmitter.listenerCount(n)))) {
+        return;
+      }
+
+      return finished();
+    });
+
+    // Relay invoice updates to the emitter
+    subscription.on('data', invoice => {
+      try {
+        const updated = rpcInvoiceAsInvoice(invoice);
+
+        eventEmitter.emit(updateEvent, updated);
+
+        // Update cursors for possible restart of subscription
+        addIndex = updated.index;
+        confirmedAfter = updated.confirmed_index;
+
+        return;
+      } catch (err) {
+        return finished([503, err.message]);
+      }
+    });
+
+    // Subscription finished will trigger a re-subscribe
+    subscription.on('end', () => finished());
+
+    // Subscription errors fail the subscription, trigger subscription restart
+    subscription.on('error', err => {
+      return finished([503, 'UnexpectedInvoiceSubscriptionError', {err}]);
+    });
+
+    // Relay status messages
+    subscription.on('status', n => eventEmitter.emit('status', n));
+
+    return;
+  },
+  (res, cbk) => {
+    // Terminate the subscription when there are no listeners
+    return cbk(null, res.listener_count === [].length);
+  },
+  () => eventEmitter.emit('end'));
+
+  return eventEmitter;
+};

package/lnd_methods/macaroon/accept_rpc_request.js

@@ -0,0 +1,44 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const feedback = {replace_response: false};
+
+/** Accept an RPC request
+
+  {
+    id: <Request or Response Id Number To Accept>
+    subscription: <RPC Request Stream Object>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = ({id, subscription}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!id) {
+          return cbk([400, 'ExpectedRequestIdToAcceptRpcRequest']);
+        }
+
+        if (!subscription) {
+          return cbk([400, 'ExpectedRpcSubscriptionToAcceptRpcRequest']);
+        }
+
+        return cbk();
+      },
+
+      // Send accept feedback to the stream
+      accept: ['validate', ({}, cbk) => {
+        return subscription.write({feedback, ref_msg_id: id}, err => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorAcceptingRpcRequest', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/macaroon/get_access_ids.d.ts

@@ -0,0 +1,19 @@
+import {AuthenticatedLnd} from '../../lnd_grpc';
+import {AuthenticatedLightningMethod} from '../../typescript';
+
+export type GetAccessIdsResult = {
+  /** Root Access Id Numbers */
+  ids: number[];
+};
+
+/**
+ * Get outstanding access ids given out
+ *
+ * Note: this method is not supported in LND versions 0.11.1 and below
+ *
+ * Requires `macaroon:read` permission
+ */
+export const getAccessIds: AuthenticatedLightningMethod<
+  {lnd: AuthenticatedLnd},
+  GetAccessIdsResult
+>;

package/lnd_methods/macaroon/get_access_ids.js

@@ -0,0 +1,67 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const {isArray} = Array;
+const method = 'listMacaroonIDs';
+const notSupported = /unknown/;
+const type = 'default';
+
+/** Get outstanding access ids given out
+
+  Note: this method is not supported in LND versions 0.11.1 and below
+
+  Requires `macaroon:read` permission
+
+  {
+    lnd: <Authenticated LND API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    ids: [<Root Access Id Number>]
+  }
+*/
+module.exports = ({id, lnd}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndApiObjectToGetAccessIds']);
+        }
+
+        return cbk();
+      },
+
+      // Get access ids
+      getIds: ['validate', ({}, cbk) => {
+        return lnd[type][method]({}, (err, res) => {
+          if (!!err && notSupported.test(err.details)) {
+            return cbk([501, 'ListRootMacaroonIdsMethodNotSupported']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorInListRootIdsResponse', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForListMacaroonRootIdsRequest']);
+          }
+
+          if (!isArray(res.root_key_ids)) {
+            return cbk([503, 'ExpectedArrayOfRootKeyIdsInListIdsResponse']);
+          }
+
+          if (!!res.root_key_ids.filter(n => !n).length) {
+            return cbk([503, 'UnexpectedEmptyMacarootRootIdInListResponse']);
+          }
+
+          return cbk(null, {ids: res.root_key_ids});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'getIds'}, cbk));
+  });
+};

package/lnd_methods/macaroon/grant_access.d.ts

@@ -0,0 +1,75 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type GrantAccessArgs = AuthenticatedLightningArgs<{
+  /** Macaroon Id Positive Numeric */
+  id?: string;
+  /** Can Add or Remove Peers */
+  is_ok_to_adjust_peers?: boolean;
+  /** Can Make New Addresses */
+  is_ok_to_create_chain_addresses?: boolean;
+  /** Can Create Lightning Invoices */
+  is_ok_to_create_invoices?: boolean;
+  /** Can Create Macaroons */
+  is_ok_to_create_macaroons?: boolean;
+  /** Can Derive Public Keys */
+  is_ok_to_derive_keys?: boolean;
+  /** Can List Access Ids */
+  is_ok_to_get_access_ids?: boolean;
+  /** Can See Chain Transactions */
+  is_ok_to_get_chain_transactions?: boolean;
+  /** Can See Invoices */
+  is_ok_to_get_invoices?: boolean;
+  /** Can General Graph and Wallet Information */
+  is_ok_to_get_wallet_info?: boolean;
+  /** Can Get Historical Lightning Transactions */
+  is_ok_to_get_payments?: boolean;
+  /** Can Get Node Peers Information */
+  is_ok_to_get_peers?: boolean;
+  /** Can Send Funds or Edit Lightning Payments */
+  is_ok_to_pay?: boolean;
+  /** Can Revoke Access Ids */
+  is_ok_to_revoke_access_ids?: boolean;
+  /** Can Send Coins On Chain */
+  is_ok_to_send_to_chain_addresses?: boolean;
+  /** Can Sign Bytes From Node Keys */
+  is_ok_to_sign_bytes?: boolean;
+  /** Can Sign Messages From Node Key */
+  is_ok_to_sign_messages?: boolean;
+  /** Can Terminate Node or Change Operation Mode */
+  is_ok_to_stop_daemon?: boolean;
+  /** Can Verify Signatures of Bytes */
+  is_ok_to_verify_bytes_signatures?: boolean;
+  /** Can Verify Messages From Node Keys */
+  is_ok_to_verify_messages?: boolean;
+  /** Method Name */
+  methods?: string[];
+  /** Entity:Action */
+  permissions?: string[];
+}>;
+
+export type GrantAccessResult = {
+  /** Base64 Encoded Macaroon */
+  macaroon: string;
+  /** Entity:Action */
+  permissions: string[];
+};
+
+/**
+ * Give access to the node by making a macaroon access credential
+ * 
+ * Specify `id` to allow for revoking future access
+ *
+ * Requires `macaroon:generate` permission
+ *
+ * Note: access once given cannot be revoked. Access is defined at the LND level
+and version differences in LND can result in expanded access.
+ *
+ * Note: `id` is not supported in LND versions 0.11.0 and below
+ */
+export const grantAccess: AuthenticatedLightningMethod<
+  GrantAccessArgs,
+  GrantAccessResult
+>;

package/lnd_methods/macaroon/grant_access.js

@@ -0,0 +1,146 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+const permissions = require('./permissions');
+const urisForMethod = require('./uris_for_method');
+
+const accessDenied = 'permission denied';
+const flatten = arr => [].concat(...arr);
+const hexAsBase64 = hex => Buffer.from(hex, 'hex').toString('base64');
+const isHex = n => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const {keys} = Object;
+const method = 'bakeMacaroon';
+const notSupported = 'unknown service lnrpc.Lightning';
+const permissionSeparator = ':';
+const type = 'default';
+const uniq = arr => Array.from(new Set(arr));
+const uriAsPermission = uri => `uri:${uri}`;
+
+/** Give access to the node by making a macaroon access credential
+
+  Specify `id` to allow for revoking future access
+
+  Requires `macaroon:generate` permission
+
+  Note: access once given cannot be revoked. Access is defined at the LND level
+  and version differences in LND can result in expanded access.
+
+  Note: `id` is not supported in LND versions 0.11.0 and below
+
+  `methods` is not supported in LND versions 0.11.0 and below
+
+  {
+    [id]: <Macaroon Id Positive Numeric String>
+    [is_ok_to_adjust_peers]: <Can Add or Remove Peers Bool>
+    [is_ok_to_create_chain_addresses]: <Can Make New Addresses Bool>
+    [is_ok_to_create_invoices]: <Can Create Lightning Invoices Bool>
+    [is_ok_to_create_macaroons]: <Can Create Macaroons Bool>
+    [is_ok_to_derive_keys]: <Can Derive Public Keys Bool>
+    [is_ok_to_get_access_ids]: <Can List Access Ids Bool>
+    [is_ok_to_get_chain_transactions]: <Can See Chain Transactions Bool>
+    [is_ok_to_get_invoices]: <Can See Invoices Bool>
+    [is_ok_to_get_wallet_info]: <Can General Graph and Wallet Information Bool>
+    [is_ok_to_get_payments]: <Can Get Historical Lightning Transactions Bool>
+    [is_ok_to_get_peers]: <Can Get Node Peers Information Bool>
+    [is_ok_to_pay]: <Can Send Funds or Edit Lightning Payments Bool>
+    [is_ok_to_revoke_access_ids]: <Can Revoke Access Ids Bool>
+    [is_ok_to_send_to_chain_addresses]: <Can Send Coins On Chain Bool>
+    [is_ok_to_sign_bytes]: <Can Sign Bytes From Node Keys Bool>
+    [is_ok_to_sign_messages]: <Can Sign Messages From Node Key Bool>
+    [is_ok_to_stop_daemon]: <Can Terminate Node or Change Operation Mode Bool>
+    [is_ok_to_verify_bytes_signatures]: <Can Verify Signatures of Bytes Bool>
+    [is_ok_to_verify_messages]: <Can Verify Messages From Node Keys Bool>
+    lnd: <Authenticated LND API Object>
+    [methods]: [<Method Name String>]
+    [permissions]: [<Entity:Action String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    macaroon: <Base64 Encoded Macaroon String>
+    permissions: [<Entity:Action String>]
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!keys(args).length) {
+          return cbk([400, 'ExpectedAccessPrivilegeToGrantAccessCredential']);
+        }
+
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpectedLndToGrantAccessCredential']);
+        }
+
+        return cbk();
+      },
+
+      // Derive URI permissions
+      uris: ['validate', ({}, cbk) => {
+        try {
+          const uris = (args.methods || []).map(method => {
+            return urisForMethod({method}).uris;
+          });
+
+          const permissions = uniq(flatten(uris)).map(uriAsPermission);
+
+          return cbk(null, permissions);
+        } catch (err) {
+          return cbk([400, err.message]);
+        }
+      }],
+
+      // Permissions to grant
+      permissions: ['uris', ({uris}, cbk) => {
+        const access = []
+          .concat(uris)
+          .concat(keys(permissions).filter(n => !!args[permissions[n]]))
+          .concat(args.permissions || []);
+
+        return cbk(null, access.map(permission => {
+          const [entity, action] = permission.split(permissionSeparator);
+
+          return {action, entity};
+        }));
+      }],
+
+      // Make macaroon
+      createMacaroon: ['permissions', ({permissions}, cbk) => {
+        return args.lnd[type][method]({
+          permissions,
+          root_key_id: args.id || undefined,
+        },
+        (err, res) => {
+          if (!!err && err.details === notSupported) {
+            return cbk([501, 'GrantAccessMethodNotSupported']);
+          }
+
+          if (!!err && err.details === accessDenied) {
+            return cbk([403, 'PermissionDeniedToBakeMacaroon']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorFromBakeMacaroon', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseFromBakeMacaroonRequest']);
+          }
+
+          if (!isHex(res.macaroon)) {
+            return cbk([503, 'ExpectedHexSerializedMacaroonCredentials']);
+          }
+
+          const actions = permissions.map(n => `${n.entity}:${n.action}`);
+          const macaroon = hexAsBase64(res.macaroon);
+
+          return cbk(null, {macaroon, permissions: actions});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'createMacaroon'}, cbk));
+  });
+};

package/lnd_methods/macaroon/handle_rpc_request_update.js

@@ -0,0 +1,151 @@
+const acceptRpcRequest = require('./accept_rpc_request');
+const {closeChannelRequest} = require('./../../lnd_messages');
+const {openChannelRequest} = require('./../../lnd_messages');
+const {payViaRouteRequest} = require('./../../lnd_messages');
+const rejectRpcRequest = require('./reject_rpc_request');
+const {rpcRequestUpdateAsEvent} = require('./../../lnd_responses');
+
+const isChanClose = n => !!n && n === '/lnrpc.Lightning/CloseChannel';
+const isChanOpen = n => !!n && n.startsWith('/lnrpc.Lightning/OpenChannel');
+const isPayViaRoute = n => !!n && n === '/routerrpc.Router/SendToRouteV2';
+
+/** Handle an update from the RPC request stream
+
+  {
+    [is_intercepting_close_channel_requests]: <Intercept Channel Closes Bool>
+    [is_intercepting_open_channel_requests]: <Is Handling Open Requests Bool>
+    [is_intercepting_pay_via_routes_requests]: <Is Handling Route Reqs Bool>
+    subscription: <Stream Subscription Object>
+    update: {
+      msg_id: <Message Id Number String>
+      request_id: <Request Id Number String>
+      raw_macaroon: <Raw Macaroon Buffer Object>
+      custom_caveat_condition: <Custom Caveat Condition String>
+      [request]: {
+        method_full_uri: <Method URI String>
+        serialized: <Raw Protobuf Request Buffer Object>
+        stream_rpc: <Is String RPC Bool>
+        type_name: <RPC Message Type String>
+      }
+      [response]: {
+        method_full_uri: <Method URI String>
+        serialized: <Raw Protobuf Response Buffer Object>
+        stream_rpc: <Is String RPC Bool>
+        type_name: <RPC Message Type String>
+      }
+      [stream_auth]: {
+        method_full_uri: <Method URI String>
+      }
+      intercept_type: <RPC Update Type String>
+    }
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [accept]: ({}, cbk) => {}
+    data: {
+      [accept]: ({}, cbk) => {}
+      call: <Call Id Number>
+      id: <Message Id Number>
+      [macaroon]: <Base64 Encoded Macaroon String>
+      [reject]: ({}, cbk) => {}
+      [request]: {
+        [chain_fee_tokens_per_vbyte]: <Chain Fee Tokens Per VByte Number>
+        [cooperative_close_address]: <Prefer Cooperative Close Address String>
+        [give_tokens]: <Tokens to Gift To Partner Number>
+        [is_private]: <Channel is Private Bool>
+        local_tokens: <Local Tokens Number>
+        [min_confirmations]: <Spend UTXOs With Minimum Confirmations Number>
+        [min_htlc_mtokens]: <Minimum HTLC Millitokens String>
+        partner_public_key: <Public Key Hex String>
+        [partner_csv_delay]: <Peer Output CSV Delay Number>
+      }
+      [uri]: <RPC URI String>
+    }
+    event: <Event Name String>
+  }
+*/
+module.exports = args => {
+  const details = rpcRequestUpdateAsEvent(args.update);
+  const isInterceptCloseChans = !!args.is_intercepting_close_channel_requests;
+  const isInterceptOpenChans = !!args.is_intercepting_open_channel_requests;
+  const isInterceptPayOnRoute = !!args.is_intercepting_pay_via_routes_requests;
+
+  const {call} = details;
+  const {event} = details;
+  const {id} = details;
+  const {macaroon} = details;
+  const {request} = args.update;
+  const {subscription} = args;
+  const {uri} = details;
+
+  const accept = ({}, cbk) => acceptRpcRequest({id, subscription}, cbk);
+
+  // Exit early when intercepting channel closes
+  if (!!isInterceptCloseChans && !!request && isChanClose(uri)) {
+    const req = args.lnd.default.CloseChannel.requestDeserialize(
+      args.update.request.serialized
+    );
+
+    return {
+      event: 'close_channel_request',
+      data: {
+        accept,
+        id,
+        macaroon,
+        uri,
+        reject: ({message}, cbk) => {
+          return rejectRpcRequest({id, message, subscription}, cbk);
+        },
+        request: closeChannelRequest(req),
+      },
+    };
+  }
+
+  // Exit early when intercepting channel opens
+  if (!!isInterceptOpenChans && !!request && isChanOpen(uri)) {
+    const req = args.lnd.default.OpenChannel.requestDeserialize(
+      args.update.request.serialized
+    );
+
+    return {
+      event: 'open_channel_request',
+      data: {
+        accept,
+        id,
+        macaroon,
+        uri,
+        reject: ({message}, cbk) => {
+          return rejectRpcRequest({id, message, subscription}, cbk);
+        },
+        request: openChannelRequest(req),
+      },
+    };
+  }
+
+  // Exit early when intercepting pay via route requests
+  if (!!isInterceptPayOnRoute && !!request && isPayViaRoute(uri)) {
+    const req = args.lnd.router.SendToRouteV2.requestDeserialize(
+      args.update.request.serialized
+    );
+
+    return {
+      event: 'pay_via_route_request',
+      data: {
+        accept,
+        id,
+        macaroon,
+        uri,
+        reject: ({message}, cbk) => {
+          return rejectRpcRequest({id, message, subscription}, cbk);
+        },
+        request: payViaRouteRequest(req),
+      },
+    };
+  }
+
+  return {accept, event, data: {call, id, macaroon, uri}};
+};

package/lnd_methods/macaroon/index.d.ts

@@ -0,0 +1,5 @@
+export * from './get_access_ids';
+export * from './grant_access';
+export * from './revoke_access';
+export * from './subscribe_to_rpc_requests';
+export * from './verify_access';