tapass 0.1.0 → 0.2.0

package/src/tapd_methods/channels/send_asset_payment.ts

@@ -0,0 +1,158 @@
+import type {SubscribeToPastPaymentConfirmedEvent} from 'lightning';
+import {confirmedFromPayment} from 'lightning/lnd_responses/index.js';
+
+import type {AuthenticatedTapd} from '../../tapd_grpc/index.js';
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {assetChannelRpcError} from '../../tapd_responses/index.js';
+import {rpcSellQuoteAsQuote} from '../../tapd_responses/index.js';
+import type {SellQuote} from '../../tapd_responses/index.js';
+import type {TapdError} from '../../typescript/index.js';
+
+const {isArray} = Array;
+const failedText = /payment failed: (FAILURE_REASON_[A-Z_]+)/;
+// The errors are the same as the payment errors of lightning
+const failureErrors: Record<string, string> = {
+  FAILURE_REASON_CANCELED: 'PaymentExecutionCanceled',
+  FAILURE_REASON_INCORRECT_PAYMENT_DETAILS: 'PaymentRejectedByDestination',
+  FAILURE_REASON_INSUFFICIENT_BALANCE: 'InsufficientBalanceToAttemptPayment',
+  FAILURE_REASON_NO_ROUTE: 'PaymentPathfindingFailedToFindPossibleRoute',
+  FAILURE_REASON_TIMEOUT: 'PaymentAttemptsTimedOut',
+};
+const failedStatus = 'FAILED';
+const genericFailure = 'FailedToFindPayableRouteToDestination';
+const method = 'sendPayment';
+const succeededStatus = 'SUCCEEDED';
+const type = 'tapchannel';
+
+type Args = {
+  /** Method Name For Error Messages */
+  name: string;
+  /** tapchannel SendPayment Request Object */
+  request: object;
+  /** Authenticated tapd API Object */
+  tapd: AuthenticatedTapd;
+};
+
+export type SendAssetPaymentResult = SubscribeToPastPaymentConfirmedEvent & {
+  quotes: SellQuote[];
+};
+
+/** Error for a failed payment
+
+  <Payment Failure Reason String>
+
+  @returns
+  <Error Array>
+*/
+const failureError = (reason: string): TapdError => {
+  return [503, failureErrors[reason] || genericFailure];
+};
+
+/** Send a tapd asset payment and wait for the final payment state
+
+  {
+    name: <Method Name For Error Messages String>
+    request: <tapchannel SendPayment Request Object>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk
+  {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    ...<lightning Confirmed Payment Object>
+    quotes: [<Accepted Sell Quote Object>]
+  }
+*/
+export default (
+  {name, request, tapd}: Args,
+  cbk: (err: TapdError | null, res?: SendAssetPaymentResult) => void,
+) => {
+  const quotes = new Map<string, SellQuote>();
+  let isFinished = false;
+
+  const finish = (err: TapdError | null, res?: SendAssetPaymentResult) => {
+    // Exit early when the payment already has a result
+    if (isFinished) {
+      return;
+    }
+
+    isFinished = true;
+
+    return cbk(err, res);
+  };
+
+  const addQuote = (quote: unknown) => {
+    const mapped = rpcSellQuoteAsQuote(quote as any);
+
+    quotes.set(mapped.id, mapped);
+  };
+
+  const sub = tapd[type][method](request);
+
+  sub.on('data', (data: any) => {
+    try {
+      // The older field has the first quote, the newer field has all quotes
+      if (!!data?.accepted_sell_order) {
+        addQuote(data.accepted_sell_order);
+      }
+
+      if (isArray(data?.accepted_sell_orders?.accepted_sell_orders)) {
+        data.accepted_sell_orders.accepted_sell_orders.forEach(addQuote);
+      }
+
+      const payment = data?.payment_result;
+
+      // Exit early when there is no payment result in this update
+      if (!payment) {
+        return;
+      }
+
+      if (payment.status === failedStatus) {
+        return finish(failureError(payment.failure_reason));
+      }
+
+      // Exit early when the payment is not final yet
+      if (payment.status !== succeededStatus) {
+        return;
+      }
+
+      return finish(null, {
+        ...confirmedFromPayment(payment),
+        quotes: [...quotes.values()],
+      });
+    } catch (err: any) {
+      return finish([503, err.message]);
+    }
+  });
+
+  sub.on('end', () => {
+    return finish([503, `UnexpectedEndOfPaymentUpdatesTo${name}`]);
+  });
+
+  sub.on('error', (err: any) => {
+    if (isConnectionFailure({err})) {
+      return finish([503, `FailedToConnectToTapdTo${name}`]);
+    }
+
+    if (isPermissionDenied({err})) {
+      return finish([403, `PermissionDeniedTo${name}`]);
+    }
+
+    const failed = String(err?.details).match(failedText);
+
+    if (!!failed) {
+      return finish(failureError(failed[1]));
+    }
+
+    const knownError = assetChannelRpcError({err});
+
+    if (!!knownError) {
+      return finish(knownError);
+    }
+
+    return finish([503, `UnexpectedErrorIn${name}`, {err}]);
+  });
+
+  return;
+};

package/src/tapd_methods/channels/subscribe_to_asset_invoices.ts

@@ -0,0 +1,134 @@
+import {EventEmitter} from 'node:events';
+
+import {emitSubscriptionError} from '../../grpc/index.js';
+import {handleRemoveListener} from '../../grpc/index.js';
+import type {AuthenticatedTapd} from '../../tapd_grpc/index.js';
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isMethodUnsupported} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {rpcAssetInvoiceAsInvoice} from '../../tapd_responses/index.js';
+
+const cancelError = 'Cancelled on client';
+const events = ['error', 'invoice_updated'];
+const isIndex = (n: unknown) => Number.isSafeInteger(n) && (n as number) > 0;
+const method = 'subscribeInvoices';
+const type = 'tapchannel';
+
+export type SubscribeToAssetInvoicesArgs = {
+  /** Invoice Add Index To Start After Number */
+  added_after?: number;
+  /** Invoice Confirmed Index To Start After Number */
+  confirmed_after?: number;
+  /** Authenticated tapd API Object */
+  tapd: AuthenticatedTapd;
+};
+
+/** Subscribe to invoices that receive an asset
+
+  tapd only sends updates of invoices that involve an asset
+
+  Use `added_after` and `confirmed_after` to get past updates after an index
+
+  Requires `channels:read` permission
+
+  This method needs tapd v0.8.1 or later
+
+  The invoice fields are the same as in lightning getInvoices
+
+  {
+    [added_after]: <Invoice Add Index To Start After Number>
+    [confirmed_after]: <Invoice Confirmed Index To Start After Number>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Subscription EventEmitter Object>
+
+  @event 'invoice_updated'
+  {
+    assets: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      [group_key]: <Asset Group Key Hex String>
+    }]
+    created_at: <ISO 8601 Date String>
+    id: <Payment Hash Hex String>
+    index: <Invoice Add Index Number>
+    is_confirmed: <Invoice is Confirmed Bool>
+    ...<lightning Invoice Object>
+  }
+*/
+export default (args: SubscribeToAssetInvoicesArgs) => {
+  if (args.added_after !== undefined && !isIndex(args.added_after)) {
+    throw new Error('ExpectedAddIndexToSubscribeToAssetInvoices');
+  }
+
+  if (args.confirmed_after !== undefined && !isIndex(args.confirmed_after)) {
+    throw new Error('ExpectedConfirmedIndexToSubscribeToAssetInvoices');
+  }
+
+  if (!isTapd({method, tapd: args.tapd, type})) {
+    throw new Error('ExpectedAuthenticatedTapdToSubscribeToAssetInvoices');
+  }
+
+  const emitter = new EventEmitter();
+
+  const subscription = args.tapd[type][method]({
+    request: {
+      add_index: args.added_after || 0,
+      settle_index: args.confirmed_after || 0,
+    },
+  });
+
+  // The error helper only reads `details` to find a client cancel
+  const emitError = emitSubscriptionError({emitter, subscription}) as (
+    err: unknown,
+  ) => void;
+
+  // Cancel the subscription when all event listeners are removed
+  handleRemoveListener({emitter, events, subscription});
+
+  subscription.on('data', (data: unknown) => {
+    try {
+      return emitter.emit(
+        'invoice_updated',
+        rpcAssetInvoiceAsInvoice(data as any),
+      );
+    } catch (err: any) {
+      return emitError([503, err.message]);
+    }
+  });
+
+  subscription.on('end', () => emitter.emit('end'));
+
+  subscription.on('error', (err: any) => {
+    // Exit early when the client cancelled the subscription
+    if (err?.details === cancelError) {
+      return subscription.removeAllListeners();
+    }
+
+    if (isConnectionFailure({err})) {
+      return emitError([503, 'FailedToConnectToTapdToSubscribeToInvoices']);
+    }
+
+    if (isPermissionDenied({err})) {
+      return emitError([403, 'PermissionDeniedToSubscribeToAssetInvoices']);
+    }
+
+    if (isMethodUnsupported({err})) {
+      return emitError([501, 'ExpectedNewerTapdToSubscribeToAssetInvoices']);
+    }
+
+    return emitError([
+      503,
+      'UnexpectedErrorInAssetInvoicesSubscription',
+      {err},
+    ]);
+  });
+
+  return emitter;
+};

package/src/tapd_methods/channels/subscribe_to_asset_payments.ts

@@ -0,0 +1,126 @@
+import {EventEmitter} from 'node:events';
+
+import {emitSubscriptionError} from '../../grpc/index.js';
+import {handleRemoveListener} from '../../grpc/index.js';
+import type {AuthenticatedTapd} from '../../tapd_grpc/index.js';
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isMethodUnsupported} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import emitAssetPayment from './emit_asset_payment.js';
+
+const cancelError = 'Cancelled on client';
+const events = ['confirmed', 'error', 'failed', 'paying'];
+const method = 'subscribePayments';
+const type = 'tapchannel';
+
+export type SubscribeToAssetPaymentsArgs = {
+  /** Authenticated tapd API Object */
+  tapd: AuthenticatedTapd;
+};
+
+/** Subscribe to the status of current outgoing asset payments
+
+  The events are the same as in lightning subscribeToPayments, and each
+  event also has the asset amounts of the payment
+
+  tapd only sends updates of payments that involve an asset
+
+  Requires `channels:read` permission
+
+  This method needs tapd v0.8.1 or later
+
+  {
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Subscription EventEmitter Object>
+
+  @event 'confirmed'
+  {
+    assets: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      [group_key]: <Asset Group Key Hex String>
+    }]
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    ...<lightning Confirmed Payment Object>
+  }
+
+  @event 'failed'
+  {
+    assets: [<Asset Amount Object>]
+    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'
+  {
+    assets: [<Asset Amount Object>]
+    created_at: <Payment Created At ISO 8601 Date String>
+    ...<lightning Pending Payment Object>
+  }
+*/
+export default ({tapd}: SubscribeToAssetPaymentsArgs) => {
+  if (!isTapd({method, tapd, type})) {
+    throw new Error('ExpectedAuthenticatedTapdToSubscribeToAssetPayments');
+  }
+
+  const emitter = new EventEmitter();
+
+  const subscription = tapd[type][method]({
+    request: {no_inflight_updates: false},
+  });
+
+  // The error helper only reads `details` to find a client cancel
+  const emitError = emitSubscriptionError({emitter, subscription}) as (
+    err: unknown,
+  ) => void;
+
+  // Cancel the subscription when all event listeners are removed
+  handleRemoveListener({emitter, events, subscription});
+
+  subscription.on('data', (data: unknown) => {
+    return emitAssetPayment({data, emitError, emitter});
+  });
+
+  subscription.on('end', () => emitter.emit('end'));
+
+  subscription.on('error', (err: any) => {
+    // Exit early when the client cancelled the subscription
+    if (err?.details === cancelError) {
+      return subscription.removeAllListeners();
+    }
+
+    if (isConnectionFailure({err})) {
+      return emitError([
+        503,
+        'FailedToConnectToTapdToSubscribeToAssetPayments',
+      ]);
+    }
+
+    if (isPermissionDenied({err})) {
+      return emitError([403, 'PermissionDeniedToSubscribeToAssetPayments']);
+    }
+
+    if (isMethodUnsupported({err})) {
+      return emitError([501, 'ExpectedNewerTapdToSubscribeToAssetPayments']);
+    }
+
+    return emitError([
+      503,
+      'UnexpectedErrorInAssetPaymentsSubscription',
+      {err},
+    ]);
+  });
+
+  return emitter;
+};

package/src/tapd_methods/channels/subscribe_to_past_asset_payment.ts

@@ -0,0 +1,132 @@
+import {EventEmitter} from 'node:events';
+
+import {emitSubscriptionError} from '../../grpc/index.js';
+import {handleRemoveListener} from '../../grpc/index.js';
+import type {AuthenticatedTapd} from '../../tapd_grpc/index.js';
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isMethodUnsupported} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import emitAssetPayment from './emit_asset_payment.js';
+
+const cancelError = 'Cancelled on client';
+const events = ['confirmed', 'error', 'failed', 'paying'];
+const isHash = (n: unknown) => /^[0-9A-F]{64}$/i.test(String(n));
+const method = 'trackPayment';
+const notInitiatedError = `payment isn't initiated`;
+const type = 'tapchannel';
+
+export type SubscribeToPastAssetPaymentArgs = {
+  /** Payment Hash Hex String */
+  id: string;
+  /** Authenticated tapd API Object */
+  tapd: AuthenticatedTapd;
+};
+
+/** Subscribe to the status of a past asset payment
+
+  The events are the same as in lightning subscribeToPastPayment, and each
+  event also has the asset amounts of the payment
+
+  tapd only sends updates of a payment that involves an asset
+
+  Requires `channels:read` permission
+
+  This method needs tapd v0.8.1 or later
+
+  {
+    id: <Payment Hash Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Subscription EventEmitter Object>
+
+  @event 'confirmed'
+  {
+    assets: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      [group_key]: <Asset Group Key Hex String>
+    }]
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    ...<lightning Confirmed Payment Object>
+  }
+
+  @event 'failed'
+  {
+    assets: [<Asset Amount Object>]
+    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'
+  {
+    assets: [<Asset Amount Object>]
+    created_at: <Payment Created At ISO 8601 Date String>
+    ...<lightning Pending Payment Object>
+  }
+*/
+export default ({id, tapd}: SubscribeToPastAssetPaymentArgs) => {
+  if (!isHash(id)) {
+    throw new Error('ExpectedPaymentHashToSubscribeToPastAssetPayment');
+  }
+
+  if (!isTapd({method, tapd, type})) {
+    throw new Error('ExpectedAuthenticatedTapdToSubscribeToPastAssetPayment');
+  }
+
+  const emitter = new EventEmitter();
+
+  const subscription = tapd[type][method]({
+    request: {no_inflight_updates: false, payment_hash: Buffer.from(id, 'hex')},
+  });
+
+  // The error helper only reads `details` to find a client cancel
+  const emitError = emitSubscriptionError({emitter, subscription}) as (
+    err: unknown,
+  ) => void;
+
+  // Cancel the subscription when all event listeners are removed
+  handleRemoveListener({emitter, events, subscription});
+
+  subscription.on('data', (data: unknown) => {
+    return emitAssetPayment({data, emitError, emitter});
+  });
+
+  subscription.on('end', () => emitter.emit('end'));
+
+  subscription.on('error', (err: any) => {
+    // Exit early when the client cancelled the subscription
+    if (err?.details === cancelError) {
+      return subscription.removeAllListeners();
+    }
+
+    if (isConnectionFailure({err})) {
+      return emitError([503, 'FailedToConnectToTapdToTrackAssetPayment']);
+    }
+
+    if (isPermissionDenied({err})) {
+      return emitError([403, 'PermissionDeniedToTrackAssetPayment']);
+    }
+
+    if (isMethodUnsupported({err})) {
+      return emitError([501, 'ExpectedNewerTapdToTrackAssetPayment']);
+    }
+
+    if (String(err?.details).includes(notInitiatedError)) {
+      return emitError([404, 'SentAssetPaymentNotFound']);
+    }
+
+    return emitError([503, 'UnexpectedErrorTrackingAssetPayment', {err}]);
+  });
+
+  return emitter;
+};

package/src/tapd_methods/daemon/create_tapd_macaroon.ts

@@ -0,0 +1,153 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+import type {TapdCallback} from '../../typescript/index.js';
+import type {TapdError} from '../../typescript/index.js';
+import type {TapdMethod} from '../../typescript/index.js';
+
+const disabledError = 'macaroon authentication disabled';
+const hexAsBase64 = (n: string) => Buffer.from(n, 'hex').toString('base64');
+const {isArray} = Array;
+const isHex = (n: unknown) =>
+  typeof n === 'string' && /^([0-9A-F]{2})+$/i.test(n);
+const isPermission = (n: any) => !!n?.action && !!n?.entity;
+const isRootKeyId = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const method = 'bakeMacaroon';
+const permissionErrors = ['invalid permission', 'unsupported permission'];
+const type = 'default';
+
+export type CreateTapdMacaroonArgs = AuthenticatedTapdArgs<{
+  /** Allow Permissions That tapd Does Not Know */
+  is_external_allowed?: boolean;
+  permissions: {
+    /** Permission Action String */
+    action: string;
+    /** Permission Entity String */
+    entity: string;
+  }[];
+  /** Root Key Id Numeric String */
+  root_key_id?: string;
+}>;
+
+export type CreateTapdMacaroonResult = {
+  /** Macaroon Base64 */
+  macaroon: string;
+};
+
+type Tasks = {
+  create: CreateTapdMacaroonResult;
+  validate: undefined;
+};
+
+/** Create a tapd macaroon with specific permissions
+
+  tapd adds no caveats. Add caveats to the macaroon after you create it.
+
+  Use the entity `uri` and an RPC method URI as the action, to give access to
+  one RPC method
+
+  Requires `macaroon:write` permission
+
+  {
+    [is_external_allowed]: <Allow Permissions That tapd Does Not Know Bool>
+    permissions: [{
+      action: <Permission Action String>
+      entity: <Permission Entity String>
+    }]
+    [root_key_id]: <Root Key Id Numeric String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    macaroon: <Macaroon Base64 String>
+  }
+*/
+const createTapdMacaroon: TapdMethod<
+  CreateTapdMacaroonArgs,
+  CreateTapdMacaroonResult
+> = (
+  args: CreateTapdMacaroonArgs,
+  cbk?: TapdCallback<CreateTapdMacaroonResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!isArray(args.permissions) || !args.permissions.length) {
+            return cbk([400, 'ExpectedPermissionsToCreateTapdMacaroon']);
+          }
+
+          if (!args.permissions.every(isPermission)) {
+            return cbk([400, 'ExpectedActionAndEntityForTapdPermission']);
+          }
+
+          const rootKeyId = args.root_key_id;
+
+          if (rootKeyId !== undefined && !isRootKeyId(rootKeyId)) {
+            return cbk([400, 'ExpectedNumericRootKeyIdToCreateTapdMacaroon']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToCreateTapdMacaroon']);
+          }
+
+          return cbk();
+        },
+
+        // Create the macaroon
+        create: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              allow_external_permissions: !!args.is_external_allowed,
+              permissions: args.permissions.map(n => ({
+                action: n.action,
+                entity: n.entity,
+              })),
+              root_key_id: args.root_key_id || '0',
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToCreateTapdMacaroon']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToCreateTapdMacaroon']);
+              }
+
+              const details = String(err?.details);
+
+              if (!!err && permissionErrors.some(n => details.includes(n))) {
+                return cbk([400, 'ExpectedKnownPermissionsForTapdMacaroon']);
+              }
+
+              if (!!err && details.includes(disabledError)) {
+                return cbk([501, 'MacaroonsAreDisabledInTapd']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorCreatingTapdMacaroon', {err}]);
+              }
+
+              if (!res || !isHex(res.macaroon)) {
+                return cbk([503, 'ExpectedHexMacaroonInBakeMacaroonResponse']);
+              }
+
+              return cbk(null, {macaroon: hexAsBase64(res.macaroon)});
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'create'}, cbk),
+    );
+  });
+};
+
+export default createTapdMacaroon;