tapass 0.0.0-stage → 0.2.0

package/src/tapd_methods/address/subscribe_to_asset_receives.ts

@@ -0,0 +1,114 @@
+import EventEmitter from 'node:events';
+
+import {emitSubscriptionError} from '../../grpc/index.js';
+import {handleRemoveListener} from '../../grpc/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {rpcReceiveEventAsReceiveUpdate} from '../../tapd_responses/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+
+const event = 'receive';
+const isDate = (n: string) => Date.parse(n) > 0;
+const method = 'subscribeReceiveEvents';
+const microsPerMilli = 1e3;
+const type = 'default';
+
+export type SubscribeToAssetReceivesArgs = AuthenticatedTapdArgs<{
+  /** Encoded Taproot Assets Address String */
+  address?: string;
+  /** Replay Events After ISO 8601 Date String */
+  created_after?: string;
+}>;
+
+/** Subscribe to inbound asset transfers to Taproot Assets addresses
+
+  Requires `assets:read` permission
+
+  With `created_after`, tapd also sends the past events after that date
+
+  {
+    [address]: <Encoded Taproot Assets Address String>
+    [created_after]: <Replay Events After ISO 8601 Date String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <EventEmitter Object>
+
+  @event 'receive'
+  {
+    address: {
+      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>
+    }
+    [confirmation_height]: <Confirmation Block Height Number>
+    [error]: <Receive Error String>
+    status: <Receive Status String>
+    [transaction_id]: <Anchor Transaction Id Hex String>
+    [transaction_vout]: <Anchor Transaction Output Index Number>
+    updated_at: <Updated At ISO 8601 Date String>
+  }
+*/
+export default (args: SubscribeToAssetReceivesArgs) => {
+  if (args.address !== undefined && typeof args.address !== 'string') {
+    throw new Error('ExpectedAssetAddressStringToSubscribeToAssetReceives');
+  }
+
+  if (args.created_after !== undefined && !isDate(args.created_after)) {
+    throw new Error('ExpectedValidCreatedAfterDateToSubscribeToReceives');
+  }
+
+  if (!isTapd({method, type, tapd: args.tapd})) {
+    throw new Error('ExpectedAuthenticatedTapdToSubscribeToAssetReceives');
+  }
+
+  const emitter = new EventEmitter();
+
+  // tapd reads the start time in microseconds
+  const start = !args.created_after
+    ? 0
+    : Date.parse(args.created_after) * microsPerMilli;
+
+  const subscription = args.tapd[type][method]({
+    filter_addr: args.address || '',
+    start_timestamp: start,
+  });
+
+  const errored = emitSubscriptionError({emitter, subscription});
+
+  // Terminate the subscription when all listeners are removed
+  handleRemoveListener({emitter, subscription, events: [event]});
+
+  subscription.on('end', () => emitter.emit('end'));
+  subscription.on('error', (err: any) => errored(err));
+  subscription.on('status', (n: unknown) => emitter.emit('status', n));
+
+  subscription.on('data', (data: any) => {
+    try {
+      emitter.emit(event, rpcReceiveEventAsReceiveUpdate(data));
+    } catch (err: any) {
+      // Exit early when there are no error listeners
+      if (!emitter.listenerCount('error')) {
+        return;
+      }
+
+      emitter.emit('error', [503, err.message]);
+    }
+
+    return;
+  });
+
+  return emitter;
+};

package/src/tapd_methods/assets/get_asset_balances.ts

@@ -0,0 +1,249 @@
+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 {scriptKeyTypeQuery} from '../../tapd_requests/index.js';
+import {rpcAssetBalanceAsBalance} from '../../tapd_responses/index.js';
+import type {Balance} 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 {from} = Buffer;
+const isAssetId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isGroupKey = (n: string) => /^0[23][0-9A-F]{64}$/i.test(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const method = 'listBalances';
+const type = 'default';
+const {values} = Object;
+
+export type GetAssetBalancesArgs = AuthenticatedTapdArgs<{
+  /** Asset Id Hex String */
+  asset_id?: string;
+  /** Asset Group Key Hex String */
+  group_key?: string;
+  /** Include Leased Assets */
+  is_including_leased?: boolean;
+  /** Script Key Type */
+  script_key_type?: string;
+}>;
+
+export type GetAssetBalancesResult = {
+  balances: Balance[];
+  group_balances: {
+    /** Balance Asset Units Numeric String */
+    balance: string;
+    /** Asset Group Key Hex */
+    group_key: string;
+  }[];
+  /** Unconfirmed Transfers Count */
+  unconfirmed_transfers: number;
+};
+
+type Tasks = {
+  getAssetBalances: {balances: Balance[]; unconfirmed_transfers: number};
+  getBalances: GetAssetBalancesResult;
+  getGroupBalances: GetAssetBalancesResult['group_balances'];
+  validate: undefined;
+};
+
+/** Get the asset balances of this node, by asset and by asset group
+
+  Requires `assets:read` permission
+
+  By default, tapd includes only assets with a BIP-86 script key. Use
+  `script_key_type` to get other assets, for example assets in channels.
+
+  An `asset_id` or a `group_key` is a filter, but not both. With an
+  `asset_id`, there are no group balances.
+
+  {
+    [asset_id]: <Asset Id Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    [is_including_leased]: <Include Leased Assets Bool>
+    [script_key_type]: <Script Key Type String> // all, bip86, burn, channel,
+                                               // script_path_external,
+                                               // tombstone, unique_pedersen
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    balances: [{
+      asset_id: <Asset Id Hex String>
+      balance: <Balance Asset Units Numeric String>
+      [group_key]: <Asset Group Key Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+    }]
+    group_balances: [{
+      balance: <Balance Asset Units Numeric String>
+      group_key: <Asset Group Key Hex String>
+    }]
+    unconfirmed_transfers: <Unconfirmed Transfers Count Number>
+  }
+*/
+const getAssetBalances: TapdMethod<
+  GetAssetBalancesArgs,
+  GetAssetBalancesResult
+> = (
+  args: GetAssetBalancesArgs,
+  cbk?: TapdCallback<GetAssetBalancesResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!!args.asset_id && !!args.group_key) {
+            return cbk([400, 'ExpectedAssetIdOrGroupKeyNotBothToGetBalances']);
+          }
+
+          if (args.asset_id !== undefined && !isAssetId(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToGetAssetBalances']);
+          }
+
+          if (args.group_key !== undefined && !isGroupKey(args.group_key)) {
+            return cbk([400, 'ExpectedGroupKeyHexToGetAssetBalances']);
+          }
+
+          try {
+            scriptKeyTypeQuery(args.script_key_type);
+          } catch {
+            return cbk([400, 'ExpectedKnownScriptKeyTypeToGetAssetBalances']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetBalances']);
+          }
+
+          return cbk();
+        },
+
+        // Get the balances by asset id
+        getAssetBalances: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              asset_filter: from(args.asset_id || '', 'hex'),
+              asset_id: true,
+              include_leased: !!args.is_including_leased,
+              script_key_type: scriptKeyTypeQuery(args.script_key_type),
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetBalances']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetBalances']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetBalances', {err}]);
+              }
+
+              if (!res || !res.asset_balances) {
+                return cbk([503, 'ExpectedAssetBalancesInBalancesResponse']);
+              }
+
+              const groupKey = args.group_key?.toLowerCase();
+
+              try {
+                const balances = values(res.asset_balances as object)
+                  .map(rpcAssetBalanceAsBalance)
+                  .filter(n => !groupKey || n.group_key === groupKey)
+                  .sort((a, b) => a.asset_id.localeCompare(b.asset_id));
+
+                return cbk(null, {
+                  balances,
+                  unconfirmed_transfers: Number(res.unconfirmed_transfers),
+                });
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+
+        // Get the balances by asset group key
+        getGroupBalances: [
+          'validate',
+          ({}, cbk) => {
+            // Exit early when the balances are for one asset id
+            if (!!args.asset_id) {
+              return cbk(null, []);
+            }
+
+            const request = {
+              group_key: true,
+              group_key_filter: from(args.group_key || '', 'hex'),
+              include_leased: !!args.is_including_leased,
+              script_key_type: scriptKeyTypeQuery(args.script_key_type),
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetBalances']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetBalances']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingGroupBalances', {err}]);
+              }
+
+              if (!res || !res.asset_group_balances) {
+                return cbk([503, 'ExpectedGroupBalancesInBalancesResponse']);
+              }
+
+              const groupBalances = values(res.asset_group_balances as object);
+
+              if (groupBalances.some(n => !isNumeric(n?.balance))) {
+                return cbk([503, 'ExpectedBalanceInRpcAssetGroupBalance']);
+              }
+
+              if (groupBalances.some(n => !isBuffer(n.group_key))) {
+                return cbk([503, 'ExpectedGroupKeyInRpcAssetGroupBalance']);
+              }
+
+              return cbk(
+                null,
+                groupBalances
+                  .map(n => ({
+                    balance: n.balance as string,
+                    group_key: (n.group_key as Buffer).toString('hex'),
+                  }))
+                  .sort((a, b) => a.group_key.localeCompare(b.group_key)),
+              );
+            });
+          },
+        ],
+
+        // Final balances
+        getBalances: [
+          'getAssetBalances',
+          'getGroupBalances',
+          ({getAssetBalances, getGroupBalances}, cbk) => {
+            return cbk(null, {
+              balances: getAssetBalances.balances,
+              group_balances: getGroupBalances,
+              unconfirmed_transfers: getAssetBalances.unconfirmed_transfers,
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'getBalances'}, cbk),
+    );
+  });
+};
+
+export default getAssetBalances;

package/src/tapd_methods/assets/get_asset_burns.ts

@@ -0,0 +1,133 @@
+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 {rpcAssetBurnAsBurn} from '../../tapd_responses/index.js';
+import type {Burn} 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 {from} = Buffer;
+const internalOrder = (n?: string) => from(n || '', 'hex').reverse();
+const {isArray} = Array;
+const isGroupKey = (n: string) => /^0[23][0-9A-F]{64}$/i.test(n);
+const isHash = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const method = 'listBurns';
+const type = 'default';
+
+export type GetAssetBurnsArgs = AuthenticatedTapdArgs<{
+  /** Asset Id Hex String */
+  asset_id?: string;
+  /** Asset Group Key Hex String */
+  group_key?: string;
+  /** Burn Anchor Transaction Id Hex String */
+  transaction_id?: string;
+}>;
+
+export type GetAssetBurnsResult = {
+  burns: Burn[];
+};
+
+type Tasks = {
+  getBurns: GetAssetBurnsResult;
+  validate: undefined;
+};
+
+/** Get the asset burns that this node made
+
+  Requires `assets:read` permission
+
+  {
+    [asset_id]: <Asset Id Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    tapd: <Authenticated tapd API Object>
+    [transaction_id]: <Burn Anchor Transaction Id Hex String>
+  }
+
+  @returns via cbk or Promise
+  {
+    burns: [{
+      amount: <Burned Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      [group_key]: <Asset Group Key Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      [note]: <Burn Note String>
+      transaction_id: <Burn Anchor Transaction Id Hex String>
+    }]
+  }
+*/
+const getAssetBurns: TapdMethod<GetAssetBurnsArgs, GetAssetBurnsResult> = (
+  args: GetAssetBurnsArgs,
+  cbk?: TapdCallback<GetAssetBurnsResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (args.asset_id !== undefined && !isHash(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToGetAssetBurns']);
+          }
+
+          if (args.group_key !== undefined && !isGroupKey(args.group_key)) {
+            return cbk([400, 'ExpectedGroupKeyHexToGetAssetBurns']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetBurns']);
+          }
+
+          if (!!args.transaction_id && !isHash(args.transaction_id)) {
+            return cbk([400, 'ExpectedTransactionIdHexToGetAssetBurns']);
+          }
+
+          return cbk();
+        },
+
+        // Get the burns
+        getBurns: [
+          'validate',
+          ({}, cbk) => {
+            // tapd compares the anchor transaction id in internal byte order
+            const request = {
+              anchor_txid: internalOrder(args.transaction_id),
+              asset_id: from(args.asset_id || '', 'hex'),
+              tweaked_group_key: from(args.group_key || '', 'hex'),
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetBurns']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetBurns']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetBurns', {err}]);
+              }
+
+              if (!res || !isArray(res.burns)) {
+                return cbk([503, 'ExpectedArrayOfBurnsInAssetBurnsResponse']);
+              }
+
+              try {
+                return cbk(null, {burns: res.burns.map(rpcAssetBurnAsBurn)});
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'getBurns'}, cbk),
+    );
+  });
+};
+
+export default getAssetBurns;

package/src/tapd_methods/assets/get_asset_groups.ts

@@ -0,0 +1,109 @@
+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 {rpcGroupedAssetsAsGroup} from '../../tapd_responses/index.js';
+import type {Group} 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 {entries} = Object;
+const method = 'listGroups';
+const type = 'default';
+
+export type GetAssetGroupsArgs = AuthenticatedTapdArgs;
+
+export type GetAssetGroupsResult = {
+  groups: Group[];
+};
+
+type Tasks = {
+  getGroups: GetAssetGroupsResult;
+  validate: undefined;
+};
+
+/** Get the asset groups of the assets that this node owns
+
+  Requires `assets:read` permission
+
+  {
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    groups: [{
+      assets: [{
+        amount: <Asset Units Numeric String>
+        asset_id: <Asset Id Hex String>
+        is_collectible: <Asset Is Collectible Bool>
+        [lock_time]: <Lock Time Number>
+        meta_hash: <Asset Metadata Hash Hex String>
+        name: <Asset Name String>
+        [relative_lock_time]: <Relative Lock Time Number>
+        version: <Asset Version Number>
+      }]
+      key: <Tweaked Group Key Hex String>
+    }]
+  }
+*/
+const getAssetGroups: TapdMethod<GetAssetGroupsArgs, GetAssetGroupsResult> = (
+  args: GetAssetGroupsArgs,
+  cbk?: TapdCallback<GetAssetGroupsResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetGroups']);
+          }
+
+          return cbk();
+        },
+
+        // Get the groups
+        getGroups: [
+          'validate',
+          ({}, cbk) => {
+            return args.tapd[type][method]({}, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetGroups']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetGroups']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetGroups', {err}]);
+              }
+
+              if (!res || !res.groups) {
+                return cbk([503, 'ExpectedGroupsInAssetGroupsResponse']);
+              }
+
+              try {
+                const groups = entries(res.groups as object)
+                  .map(([key, group]) => rpcGroupedAssetsAsGroup({group, key}))
+                  .sort((a, b) => a.key.localeCompare(b.key));
+
+                return cbk(null, {groups});
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'getGroups'}, cbk),
+    );
+  });
+};
+
+export default getAssetGroups;