tapass 0.0.0-stage → 0.2.0

package/src/grpc/emit_subscription_error.ts

@@ -0,0 +1,39 @@
+import type {EventEmitter} from 'node:events';
+
+import type {ClientReadableStream} from '@grpc/grpc-js';
+
+const cancelError = 'Cancelled on client';
+
+type Args = {
+  emitter: EventEmitter;
+  subscription: ClientReadableStream<unknown>;
+};
+
+/** Get a function that emits an error from a gRPC subscription proxy
+
+  {
+    emitter: <Event Subscription Proxy Object>
+    subscription: <gRPC Subscription Object>
+  }
+
+  @returns
+  <Error Emission Function>
+*/
+export default ({emitter, subscription}: Args) => {
+  return (err?: {details?: string}) => {
+    subscription.cancel();
+
+    if (!!err && err.details === cancelError) {
+      subscription.removeAllListeners();
+    }
+
+    // Exit early when there are no error listeners
+    if (!emitter.listenerCount('error')) {
+      return;
+    }
+
+    emitter.emit('error', err);
+
+    return;
+  };
+};

package/src/grpc/grpc_services.ts

@@ -0,0 +1,45 @@
+/** gRPC settings for tapd
+
+  `includeDirs` and `protoFiles` paths are relative to `protosDir`.
+  `protosDir` is relative to the `tapd_grpc` directory.
+*/
+export default {
+  defaultSocket: 'localhost:10029',
+  grpcSslCipherSuites:
+    'HIGH+ECDSA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384',
+  includeDirs: ['taprpc', 'lnrpc'],
+  keepaliveTimeMs: 60000,
+  keepaliveTimeoutMs: 120000,
+  maxReceiveMessageLength: 924288000,
+  packageTypes: {
+    AssetWallet: 'assetwalletrpc',
+    Mailbox: 'authmailboxrpc',
+    Mint: 'mintrpc',
+    Rfq: 'rfqrpc',
+    TapDev: 'tapdevrpc',
+    TaprootAssetChannels: 'tapchannelrpc',
+    TaprootAssets: 'taprpc',
+    Universe: 'universerpc',
+  },
+  protoFiles: {
+    AssetWallet: 'taprpc/assetwalletrpc/assetwallet.proto',
+    Mailbox: 'taprpc/authmailboxrpc/mailbox.proto',
+    Mint: 'taprpc/mintrpc/mint.proto',
+    Rfq: 'taprpc/rfqrpc/rfq.proto',
+    TapDev: 'taprpc/tapdevrpc/tapdev.proto',
+    TaprootAssetChannels: 'taprpc/tapchannelrpc/tapchannel.proto',
+    TaprootAssets: 'taprpc/taprootassets.proto',
+    Universe: 'taprpc/universerpc/universe.proto',
+  },
+  protosDir: '../../protos/',
+  serviceTypes: {
+    assetwallet: 'AssetWallet',
+    default: 'TaprootAssets',
+    mailbox: 'Mailbox',
+    mint: 'Mint',
+    rfq: 'Rfq',
+    tapchannel: 'TaprootAssetChannels',
+    tapdev: 'TapDev',
+    universe: 'Universe',
+  },
+} as const;

package/src/grpc/handle_remove_listener.ts

@@ -0,0 +1,35 @@
+import type {EventEmitter} from 'node:events';
+
+import type {ClientReadableStream} from '@grpc/grpc-js';
+
+const sumOf = (arr: number[]) => arr.reduce((sum, n) => sum + n, Number());
+
+type Args = {
+  emitter: EventEmitter;
+  events: string[];
+  subscription: ClientReadableStream<unknown>;
+};
+
+/** Cancel a gRPC subscription when all its event listeners are removed
+
+  {
+    emitter: <EventEmitter Subscription Proxy Object>
+    events: [<Event Name String>]
+    subscription: <gRPC Subscription Object>
+  }
+*/
+export default ({emitter, events, subscription}: Args) => {
+  // Cancel the subscription when all listeners are removed
+  emitter.on('removeListener', () => {
+    const counts = events.map(n => emitter.listenerCount(n));
+
+    // Exit early when there are still active listeners
+    if (!!sumOf(counts)) {
+      return;
+    }
+
+    subscription.cancel();
+
+    return;
+  });
+};

package/src/grpc/index.ts

@@ -0,0 +1,18 @@
+import emitSubscriptionError from './emit_subscription_error.js';
+import grpcServices from './grpc_services.js';
+import handleRemoveListener from './handle_remove_listener.js';
+
+export const {
+  defaultSocket,
+  grpcSslCipherSuites,
+  includeDirs,
+  keepaliveTimeMs,
+  keepaliveTimeoutMs,
+  maxReceiveMessageLength,
+  packageTypes,
+  protoFiles,
+  protosDir,
+  serviceTypes,
+} = grpcServices;
+
+export {emitSubscriptionError, handleRemoveListener};

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from './tapd_grpc/index.js';
+export * from './tapd_methods/index.js';
+export type {Address} from './tapd_responses/index.js';
+export type {AssetAmount} from './tapd_responses/index.js';
+export type {AssetForward} from './tapd_responses/index.js';
+export type {AssetInvoice} from './tapd_responses/index.js';
+export type {AssetPaymentRequest} from './tapd_responses/index.js';
+export type {AssetPayment} from './tapd_responses/index.js';
+export type {Asset} from './tapd_responses/index.js';
+export type {Balance} from './tapd_responses/index.js';
+export type {Batch} from './tapd_responses/index.js';
+export type {Burn} from './tapd_responses/index.js';
+export type {BuyQuote} from './tapd_responses/index.js';
+export type {Group} from './tapd_responses/index.js';
+export type {Metadata} from './tapd_responses/index.js';
+export type {PendingAsset} from './tapd_responses/index.js';
+export type {Proof} from './tapd_responses/index.js';
+export type {ReceiveUpdate} from './tapd_responses/index.js';
+export type {Receive} from './tapd_responses/index.js';
+export type {SellQuote} from './tapd_responses/index.js';
+export type {SendEvent} from './tapd_responses/index.js';
+export type {Transfer} from './tapd_responses/index.js';
+export type {Utxo} from './tapd_responses/index.js';
+export type * from './typescript/index.js';

package/src/tapd_grpc/api_for_proto.ts

@@ -0,0 +1,42 @@
+import grpc from '@grpc/grpc-js';
+import type {ChannelCredentials, ChannelOptions} from '@grpc/grpc-js';
+import {loadSync} from '@grpc/proto-loader';
+
+import grpcOptions from './grpc_options.js';
+
+type Args = {
+  credentials: ChannelCredentials;
+  includes: string[];
+  params: ChannelOptions;
+  path: string;
+  service: string;
+  socket: string;
+  type: string;
+};
+
+/** Get an api for a proto file
+
+  {
+    credentials: <gRPC Credentials Object>
+    includes: [<Proto Import Directory Path String>]
+    params: <gRPC Channel Options Object>
+    path: <Proto File Path String>
+    service: <Service Name String>
+    socket: <Host:Port Network Address String>
+    type: <RPC Type String>
+  }
+
+  @returns
+  <API Object>
+*/
+export default (args: Args) => {
+  const options = {...grpcOptions, includeDirs: args.includes};
+
+  const rpc = grpc.loadPackageDefinition(loadSync(args.path, options)) as any;
+
+  return new rpc[args.type][args.service](
+    args.socket,
+    args.credentials,
+    args.params,
+  );
+};

package/src/tapd_grpc/authenticated_tapd_grpc.ts

@@ -0,0 +1,88 @@
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {defaultSocket} from '../grpc/index.js';
+import {grpcSslCipherSuites} from '../grpc/index.js';
+import {includeDirs} from '../grpc/index.js';
+import {keepaliveTimeMs} from '../grpc/index.js';
+import {keepaliveTimeoutMs} from '../grpc/index.js';
+import {packageTypes} from '../grpc/index.js';
+import {protoFiles} from '../grpc/index.js';
+import {protosDir} from '../grpc/index.js';
+import {serviceTypes} from '../grpc/index.js';
+import apiForProto from './api_for_proto.js';
+import grpcCredentials from './grpc_credentials.js';
+import type {AuthenticatedTapd} from './types.js';
+import type {TapdAuthentication} from './types.js';
+import type {TapdServiceType} from './types.js';
+
+const defaultProtosPath = fileURLToPath(new URL(protosDir, import.meta.url));
+const {GRPC_SSL_CIPHER_SUITES} = process.env;
+const {keys} = Object;
+
+/** Initiate a gRPC API Methods Object for authenticated methods
+
+  Both the cert and macaroon expect the entire serialized tapd generated file
+
+  {
+    [cert]: <Base64 or Hex Serialized tapd TLS Cert String>
+    [macaroon]: <Base64 or Hex Serialized Macaroon String>
+    [path]: <Path to Protos Directory With taprpc and lnrpc Directories String>
+    [socket]: <Host:Port Network Address String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    tapd: {
+      assetwallet: <AssetWallet API Methods Object>
+      default: <TaprootAssets API Methods Object>
+      mailbox: <Mailbox API Methods Object>
+      mint: <Mint API Methods Object>
+      rfq: <Rfq API Methods Object>
+      tapchannel: <TaprootAssetChannels API Methods Object>
+      tapdev: <TapDev API Methods Object>
+      universe: <Universe API Methods Object>
+    }
+  }
+*/
+export default (args: TapdAuthentication): {tapd: AuthenticatedTapd} => {
+  const {credentials} = grpcCredentials(args);
+  const protosPath = args.path || defaultProtosPath;
+
+  if (!!args.cert && GRPC_SSL_CIPHER_SUITES !== grpcSslCipherSuites) {
+    process.env.GRPC_SSL_CIPHER_SUITES = grpcSslCipherSuites;
+  }
+
+  const includes = includeDirs.map(dir => join(protosPath, dir));
+
+  const params = {
+    'grpc.keepalive_time_ms': keepaliveTimeMs,
+    'grpc.keepalive_timeout_ms': keepaliveTimeoutMs,
+    'grpc.max_receive_message_length': -1,
+    'grpc.max_send_message_length': -1,
+  };
+
+  const types = keys(serviceTypes) as TapdServiceType[];
+
+  // Assemble different services from their proto files
+  return {
+    tapd: types.reduce((services, type) => {
+      const service = serviceTypes[type];
+
+      services[type] = apiForProto({
+        credentials,
+        includes,
+        params,
+        service,
+        path: join(protosPath, protoFiles[service]),
+        socket: args.socket || defaultSocket,
+        type: packageTypes[service],
+      });
+
+      return services;
+    }, {} as AuthenticatedTapd),
+  };
+};

package/src/tapd_grpc/decode_serialized.ts

@@ -0,0 +1,25 @@
+const {from} = Buffer;
+const isHex = (n: string) => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+
+/** Get decoded Base64 or Hex encoded data
+
+  {
+    [serialized]: <Serialized Data String>
+  }
+
+  @returns
+  {
+    [decoded]: <Deserialized Data Buffer>
+  }
+*/
+export default ({serialized}: {serialized?: string}): {decoded?: Buffer} => {
+  if (!!serialized && !isHex(serialized)) {
+    return {decoded: from(serialized, 'base64')};
+  }
+
+  if (!!serialized && isHex(serialized)) {
+    return {decoded: from(serialized, 'hex')};
+  }
+
+  return {};
+};

package/src/tapd_grpc/grpc_credentials.ts

@@ -0,0 +1,48 @@
+import grpc from '@grpc/grpc-js';
+
+import decodeSerialized from './decode_serialized.js';
+import grpcSsl from './grpc_ssl.js';
+
+const {combineChannelCredentials} = grpc.credentials;
+const {createFromMetadataGenerator} = grpc.credentials;
+const {Metadata} = grpc;
+
+const generate = (macaroon: Buffer) => {
+  const metadata = new Metadata();
+
+  metadata.add('macaroon', macaroon.toString('hex'));
+
+  return metadata;
+};
+
+/** Credentials for gRPC
+
+  {
+    [cert]: <Base64 or Hex Serialized tapd TLS Cert String>
+    [macaroon]: <Base64 or Hex Serialized Macaroon String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    credentials: <gRPC Credentials Object>
+  }
+*/
+export default ({cert, macaroon}: {cert?: string; macaroon?: string}) => {
+  if (!macaroon) {
+    return {credentials: grpcSsl({cert}).ssl};
+  }
+
+  const mac = decodeSerialized({serialized: macaroon}).decoded;
+
+  if (!mac?.length) {
+    throw new Error('ExpectedBase64OrHexEncodedMacaroonToCreateCredentials');
+  }
+
+  const creds = createFromMetadataGenerator((_, c) => c(null, generate(mac)));
+  const {ssl} = grpcSsl({cert});
+
+  return {credentials: combineChannelCredentials(ssl, creds)};
+};

package/src/tapd_grpc/grpc_options.ts

@@ -0,0 +1,10 @@
+import type {Options} from '@grpc/proto-loader';
+
+/** Proto loader options */
+export default {
+  defaults: true,
+  enums: String,
+  keepCase: true,
+  longs: String,
+  oneofs: true,
+} satisfies Options;

package/src/tapd_grpc/grpc_ssl.ts

@@ -0,0 +1,20 @@
+import grpc from '@grpc/grpc-js';
+
+import decodeSerialized from './decode_serialized.js';
+
+const {createSsl} = grpc.credentials;
+
+/** Get SSL for gRPC
+
+  {
+    [cert]: <Cert Hex or Base64 String>
+  }
+
+  @returns
+  {
+    ssl: <SSL gRPC Object>
+  }
+*/
+export default ({cert}: {cert?: string}) => {
+  return {ssl: createSsl(decodeSerialized({serialized: cert}).decoded)};
+};

package/src/tapd_grpc/index.ts

@@ -0,0 +1,5 @@
+export {default as authenticatedTapdGrpc} from './authenticated_tapd_grpc.js';
+export type {AuthenticatedTapd} from './types.js';
+export type {TapdAuthentication} from './types.js';
+export type {TapdService} from './types.js';
+export type {TapdServiceType} from './types.js';

package/src/tapd_grpc/types.ts

@@ -0,0 +1,35 @@
+/** gRPC methods of one tapd service */
+export type TapdService = {[method: string]: (...args: any[]) => any};
+
+/** Authenticated tapd gRPC API Object */
+export type AuthenticatedTapd = {
+  /** AssetWallet Methods */
+  assetwallet: TapdService;
+  /** TaprootAssets Methods */
+  default: TapdService;
+  /** Mailbox Methods */
+  mailbox: TapdService;
+  /** Mint Methods */
+  mint: TapdService;
+  /** Rfq Methods */
+  rfq: TapdService;
+  /** TaprootAssetChannels Methods */
+  tapchannel: TapdService;
+  /** TapDev Methods */
+  tapdev: TapdService;
+  /** Universe Methods */
+  universe: TapdService;
+};
+
+export type TapdServiceType = keyof AuthenticatedTapd;
+
+export type TapdAuthentication = {
+  /** Base64 or Hex Serialized tapd TLS Cert String */
+  cert?: string;
+  /** Base64 or Hex Serialized Macaroon String */
+  macaroon?: string;
+  /** Path to Protos Directory With taprpc and lnrpc Directories String */
+  path?: string;
+  /** Host:Port Network Address String */
+  socket?: string;
+};

package/src/tapd_methods/address/create_asset_address.ts

@@ -0,0 +1,179 @@
+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 {rpcAddrAsAddress} from '../../tapd_responses/index.js';
+import type {Address} from '../../tapd_responses/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 addressVersions = [
+  'ADDR_VERSION_V0',
+  'ADDR_VERSION_V1',
+  'ADDR_VERSION_V2',
+];
+const {from} = Buffer;
+const isAssetId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const isHex = (n: string) => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const method = 'newAddr';
+const notFoundError = 'unable to find asset or group';
+const type = 'default';
+const unspecifiedVersion = 'ADDR_VERSION_UNSPECIFIED';
+
+export type CreateAssetAddressArgs = AuthenticatedTapdArgs<{
+  /** Asset Units To Receive Numeric String */
+  amount?: string;
+  /** Asset Id Hex String */
+  asset_id?: string;
+  /** Asset Group Key Hex String */
+  group_key?: string;
+  /** Proof Courier Address String */
+  proof_courier?: string;
+  /** Address Version Number */
+  version?: number;
+}>;
+
+export type CreateAssetAddressResult = Address;
+
+type Tasks = {
+  createAddress: CreateAssetAddressResult;
+  validate: undefined;
+};
+
+/** Create a Taproot Assets address to receive an asset
+
+  Requires `addresses:write` permission
+
+  An `asset_id` or a `group_key` is required, but not both
+
+  When there is a `group_key` and no `version`, tapd makes a V2 address
+
+  {
+    [amount]: <Asset Units To Receive Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    [proof_courier]: <Proof Courier Address String>
+    tapd: <Authenticated tapd API Object>
+    [version]: <Address Version Number> // 0 || 1 || 2
+  }
+
+  @returns via cbk or Promise
+  {
+    address: <Encoded Taproot Assets Address String>
+    amount: <Asset Units To Receive Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    asset_version: <Asset Version Number>
+    [group_key]: <Asset Group Key Hex String>
+    internal_key: <Internal Key Hex String>
+    is_collectible: <Asset Is Collectible Bool>
+    proof_courier: <Proof Courier Address String>
+    script_key: <Script Key Hex String>
+    [tapscript_sibling]: <Tapscript Sibling Preimage Hex String>
+    taproot_output_key: <Taproot Output Key Hex String>
+    version: <Address Version Number>
+  }
+*/
+const createAssetAddress: TapdMethod<
+  CreateAssetAddressArgs,
+  CreateAssetAddressResult
+> = (
+  args: CreateAssetAddressArgs,
+  cbk?: TapdCallback<CreateAssetAddressResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (args.amount !== undefined && !isNumeric(args.amount)) {
+            return cbk([400, 'ExpectedNumericAmountToCreateAssetAddress']);
+          }
+
+          if (!args.asset_id && !args.group_key) {
+            return cbk([400, 'ExpectedAssetIdOrGroupKeyToCreateAssetAddress']);
+          }
+
+          if (!!args.asset_id && !!args.group_key) {
+            return cbk([400, 'UnexpectedAssetIdAndGroupKeyForAssetAddress']);
+          }
+
+          if (!!args.asset_id && !isAssetId(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToCreateAssetAddress']);
+          }
+
+          if (!!args.group_key && !isHex(args.group_key)) {
+            return cbk([400, 'ExpectedGroupKeyHexToCreateAssetAddress']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToCreateAssetAddress']);
+          }
+
+          if (args.version !== undefined && !addressVersions[args.version]) {
+            return cbk([400, 'ExpectedKnownVersionToCreateAssetAddress']);
+          }
+
+          return cbk();
+        },
+
+        // Create the address
+        createAddress: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              address_version:
+                args.version === undefined
+                  ? unspecifiedVersion
+                  : addressVersions[args.version],
+              amt: args.amount || '0',
+              asset_id: from(args.asset_id || '', 'hex'),
+              group_key: from(args.group_key || '', 'hex'),
+              proof_courier_addr: args.proof_courier || '',
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToCreateAssetAddress']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToCreateAssetAddress']);
+              }
+
+              if (!!err && String(err.details).includes(notFoundError)) {
+                const isGroup = !!args.group_key;
+
+                return cbk([
+                  404,
+                  isGroup ? 'AssetGroupNotFound' : 'AssetNotFound',
+                ]);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorCreatingAssetAddress', {err}]);
+              }
+
+              if (!res) {
+                return cbk([503, 'ExpectedResponseForAssetAddressCreation']);
+              }
+
+              try {
+                return cbk(null, rpcAddrAsAddress(res));
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'createAddress'}, cbk),
+    );
+  });
+};
+
+export default createAssetAddress;