tapass 0.1.0 → 0.2.0

package/src/tapd_methods/address/create_asset_address.ts

@@ -4,6 +4,8 @@ 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';
@@ -14,11 +16,8 @@ const addressVersions = [
   'ADDR_VERSION_V1',
   'ADDR_VERSION_V2',
 ];
-const assetVersions = ['ASSET_VERSION_V0', 'ASSET_VERSION_V1'];
-const bufferAsHex = (n: Buffer) => (!n.length ? undefined : n.toString('hex'));
 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 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';
@@ -39,32 +38,7 @@ export type CreateAssetAddressArgs = AuthenticatedTapdArgs<{
   version?: number;
 }>;
 
-export type CreateAssetAddressResult = {
-  /** Encoded Taproot Assets Address String */
-  address: string;
-  /** Asset Units To Receive Numeric String */
-  amount: string;
-  /** Asset Id Hex String */
-  asset_id?: string;
-  /** Asset Version Number */
-  asset_version: number;
-  /** Asset Group Key Hex String */
-  group_key?: string;
-  /** Internal Key Hex String */
-  internal_key: string;
-  /** Asset Is Collectible Bool */
-  is_collectible: boolean;
-  /** Proof Courier Address String */
-  proof_courier: string;
-  /** Script Key Hex String */
-  script_key: string;
-  /** Tapscript Sibling Preimage Hex String */
-  tapscript_sibling?: string;
-  /** Taproot Output Key Hex String */
-  taproot_output_key: string;
-  /** Address Version Number */
-  version: number;
-};
+export type CreateAssetAddressResult = Address;
 
 type Tasks = {
   createAddress: CreateAssetAddressResult;
@@ -188,50 +162,11 @@ const createAssetAddress: TapdMethod<
                 return cbk([503, 'ExpectedResponseForAssetAddressCreation']);
               }
 
-              if (!res.encoded) {
-                return cbk([503, 'ExpectedEncodedAddressInAddressResponse']);
-              }
-
-              if (!isNumeric(res.amount)) {
-                return cbk([503, 'ExpectedAmountInAssetAddressResponse']);
-              }
-
-              if (!isBuffer(res.asset_id) || !isBuffer(res.group_key)) {
-                return cbk([503, 'ExpectedAssetIdentityInAddressResponse']);
-              }
-
-              if (!isBuffer(res.internal_key) || !isBuffer(res.script_key)) {
-                return cbk([503, 'ExpectedKeysInAssetAddressResponse']);
+              try {
+                return cbk(null, rpcAddrAsAddress(res));
+              } catch (err: any) {
+                return cbk([503, err.message]);
               }
-
-              if (!isBuffer(res.taproot_output_key)) {
-                return cbk([503, 'ExpectedOutputKeyInAssetAddressResponse']);
-              }
-
-              if (!isBuffer(res.tapscript_sibling)) {
-                return cbk([503, 'ExpectedTapscriptSiblingInAddressResponse']);
-              }
-
-              const version = addressVersions.indexOf(res.address_version);
-
-              if (version === -1) {
-                return cbk([503, 'ExpectedKnownVersionInAddressResponse']);
-              }
-
-              return cbk(null, {
-                version,
-                address: res.encoded,
-                amount: res.amount,
-                asset_id: bufferAsHex(res.asset_id),
-                asset_version: assetVersions.indexOf(res.asset_version),
-                group_key: bufferAsHex(res.group_key),
-                internal_key: res.internal_key.toString('hex'),
-                is_collectible: res.asset_type === 'COLLECTIBLE',
-                proof_courier: res.proof_courier_addr,
-                script_key: res.script_key.toString('hex'),
-                tapscript_sibling: bufferAsHex(res.tapscript_sibling),
-                taproot_output_key: res.taproot_output_key.toString('hex'),
-              });
             });
           },
         ],

package/src/tapd_methods/address/decode_asset_address.ts

@@ -0,0 +1,117 @@
+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 invalidAddressError = 'unable to decode addr';
+const method = 'decodeAddr';
+const type = 'default';
+
+export type DecodeAssetAddressArgs = AuthenticatedTapdArgs<{
+  /** Encoded Taproot Assets Address String */
+  address: string;
+}>;
+
+export type DecodeAssetAddressResult = Address;
+
+type Tasks = {
+  decode: DecodeAssetAddressResult;
+  validate: undefined;
+};
+
+/** Decode a Taproot Assets address
+
+  Requires `addresses:read` permission
+
+  The address must be for the network of tapd
+
+  {
+    address: <Encoded Taproot Assets Address String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @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 decodeAssetAddress: TapdMethod<
+  DecodeAssetAddressArgs,
+  DecodeAssetAddressResult
+> = (
+  args: DecodeAssetAddressArgs,
+  cbk?: TapdCallback<DecodeAssetAddressResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!args.address || typeof args.address !== 'string') {
+            return cbk([400, 'ExpectedAssetAddressToDecode']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToDecodeAssetAddress']);
+          }
+
+          return cbk();
+        },
+
+        // Decode the address
+        decode: [
+          'validate',
+          ({}, cbk) => {
+            const request = {addr: args.address};
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToDecodeAssetAddress']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToDecodeAssetAddress']);
+              }
+
+              if (!!err && String(err.details).includes(invalidAddressError)) {
+                return cbk([400, 'ExpectedValidAssetAddressToDecode']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorDecodingAssetAddress', {err}]);
+              }
+
+              try {
+                return cbk(null, rpcAddrAsAddress(res));
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'decode'}, cbk),
+    );
+  });
+};
+
+export default decodeAssetAddress;

package/src/tapd_methods/address/get_asset_addresses.ts

@@ -0,0 +1,212 @@
+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 asSeconds = (n?: string) => (!n ? 0 : Math.floor(Date.parse(n) / 1e3));
+const defaultLimit = 100;
+const {isArray} = Array;
+const isDate = (n: string) => Date.parse(n) > 0;
+const {isSafeInteger} = Number;
+const maxLimit = 2147483647;
+const method = 'queryAddrs';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'default';
+
+export type GetAssetAddressesArgs = AuthenticatedTapdArgs<{
+  /** Created After ISO 8601 Date String */
+  created_after?: string;
+  /** Created Before ISO 8601 Date String */
+  created_before?: string;
+  /** Page Result Limit Number */
+  limit?: number;
+  /** Opaque Paging Token String */
+  token?: string;
+}>;
+
+export type GetAssetAddressesResult = {
+  addresses: Address[];
+  /** Next Opaque Paging Token */
+  next?: string;
+};
+
+type Tasks = {
+  getAddresses: GetAssetAddressesResult;
+  validate: undefined;
+};
+
+/** Get the Taproot Assets addresses that this node created, oldest first
+
+  Requires `addresses:read` permission
+
+  Use the `next` token with the same filters to get the next page
+
+  {
+    [created_after]: <Created After ISO 8601 Date String>
+    [created_before]: <Created Before ISO 8601 Date String>
+    [limit]: <Page Result Limit Number>
+    tapd: <Authenticated tapd API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    addresses: [{
+      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>
+    }]
+    [next]: <Next Opaque Paging Token String>
+  }
+*/
+const getAssetAddresses: TapdMethod<
+  GetAssetAddressesArgs,
+  GetAssetAddressesResult
+> = (
+  args: GetAssetAddressesArgs,
+  cbk?: TapdCallback<GetAssetAddressesResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          const after = args.created_after;
+          const before = args.created_before;
+
+          if (after !== undefined && !isDate(after)) {
+            return cbk([400, 'ExpectedValidCreatedAfterDateToGetAddresses']);
+          }
+
+          if (before !== undefined && !isDate(before)) {
+            return cbk([400, 'ExpectedValidCreatedBeforeDateToGetAddresses']);
+          }
+
+          if (args.limit !== undefined && !isSafeInteger(args.limit)) {
+            return cbk([400, 'ExpectedIntegerLimitToGetAssetAddresses']);
+          }
+
+          if (args.limit !== undefined && args.limit < 1) {
+            return cbk([400, 'ExpectedPositiveLimitToGetAssetAddresses']);
+          }
+
+          if (args.limit !== undefined && args.limit > maxLimit) {
+            return cbk([400, 'ExpectedSmallerLimitToGetAssetAddresses']);
+          }
+
+          if (!!args.limit && !!args.token) {
+            return cbk([400, 'UnexpectedLimitWhenPagingAddressesWithToken']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetAddresses']);
+          }
+
+          return cbk();
+        },
+
+        // Get the addresses
+        getAddresses: [
+          'validate',
+          ({}, cbk) => {
+            let limit = args.limit || defaultLimit;
+            let offset = 0;
+
+            // tapd reads the offset as a row offset in the results
+            if (!!args.token) {
+              try {
+                const pagingToken = parse(args.token);
+
+                limit = pagingToken.limit;
+                offset = pagingToken.offset;
+              } catch (err) {
+                return cbk([
+                  400,
+                  'ExpectedValidPagingTokenToGetAddresses',
+                  {err},
+                ]);
+              }
+
+              if (!isSafeInteger(limit) || limit < 1 || limit > maxLimit) {
+                return cbk([400, 'ExpectedValidPagingTokenToGetAddresses']);
+              }
+
+              if (!isSafeInteger(offset) || offset < 0 || offset > maxLimit) {
+                return cbk([400, 'ExpectedValidPagingTokenToGetAddresses']);
+              }
+            }
+
+            const request = {
+              created_after: asSeconds(args.created_after),
+              created_before: asSeconds(args.created_before),
+              limit,
+              offset,
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetAddresses']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetAddresses']);
+              }
+
+              if (!!err) {
+                return cbk([
+                  503,
+                  'UnexpectedErrorGettingAssetAddresses',
+                  {err},
+                ]);
+              }
+
+              if (!res || !isArray(res.addrs)) {
+                return cbk([
+                  503,
+                  'ExpectedArrayOfAddressesInAddressesResponse',
+                ]);
+              }
+
+              try {
+                const addresses = res.addrs.map(rpcAddrAsAddress);
+
+                // A full page means that there can be more results
+                const isFullPage = addresses.length === limit;
+
+                const next = stringify({limit, offset: offset + limit});
+
+                return cbk(null, {
+                  addresses,
+                  next: isFullPage ? next : undefined,
+                });
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'getAddresses'}, cbk),
+    );
+  });
+};
+
+export default getAssetAddresses;

package/src/tapd_methods/address/get_asset_receives.ts

@@ -0,0 +1,265 @@
+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 {receiveStatuses} from '../../tapd_responses/index.js';
+import {rpcAddrEventAsReceive} from '../../tapd_responses/index.js';
+import type {Receive} 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 asSeconds = (n?: string) => (!n ? 0 : Math.floor(Date.parse(n) / 1e3));
+const defaultLimit = 100;
+const {entries} = Object;
+const invalidAddressError = 'unable to decode addr';
+const {isArray} = Array;
+const isDate = (n: string) => Date.parse(n) > 0;
+const {isSafeInteger} = Number;
+const maxLimit = 16384;
+const maxOffset = 2147483647;
+const method = 'addrReceives';
+const newestFirst = 'SORT_DIRECTION_DESC';
+const noStatusFilter = 'ADDR_EVENT_STATUS_UNKNOWN';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'default';
+const unknownAssetError = 'unknown asset=';
+
+// Address event statuses by receive status type
+const statuses = Object.fromEntries(
+  entries(receiveStatuses)
+    .filter(([status]) => status !== noStatusFilter)
+    .map(([status, statusType]) => [statusType, status]),
+);
+
+export type GetAssetReceivesArgs = AuthenticatedTapdArgs<{
+  /** Encoded Taproot Assets Address String */
+  address?: string;
+  /** Created After ISO 8601 Date String */
+  created_after?: string;
+  /** Created Before ISO 8601 Date String */
+  created_before?: string;
+  /** Page Result Limit Number */
+  limit?: number;
+  /** Receive Status String */
+  status?:
+    | 'completed'
+    | 'proof_received'
+    | 'transaction_confirmed'
+    | 'transaction_detected';
+  /** Opaque Paging Token String */
+  token?: string;
+}>;
+
+export type GetAssetReceivesResult = {
+  /** Next Opaque Paging Token */
+  next?: string;
+  receives: Receive[];
+};
+
+type Tasks = {
+  getReceives: GetAssetReceivesResult;
+  validate: undefined;
+};
+
+/** Get the inbound asset transfers to Taproot Assets addresses, newest first
+
+  Requires `addresses:read` permission
+
+  Use the `next` token with the same filters to get the next page
+
+  The maximum `limit` is 16384
+
+  {
+    [address]: <Encoded Taproot Assets Address String>
+    [created_after]: <Created After ISO 8601 Date String>
+    [created_before]: <Created Before ISO 8601 Date String>
+    [limit]: <Page Result Limit Number>
+    [status]: <Receive Status String>
+    tapd: <Authenticated tapd API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    [next]: <Next Opaque Paging Token String>
+    receives: [{
+      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>
+      created_at: <Receive Detected At ISO 8601 Date String>
+      is_proof_available: <Proof File Is Available Bool>
+      status: <Receive Status String>
+      [tapscript_sibling]: <Tapscript Sibling Hash Hex String>
+      tokens: <Satoshis In the Anchor Output Number>
+      transaction_id: <Anchor Transaction Id Hex String>
+      transaction_vout: <Anchor Transaction Output Index Number>
+    }]
+  }
+*/
+const getAssetReceives: TapdMethod<
+  GetAssetReceivesArgs,
+  GetAssetReceivesResult
+> = (
+  args: GetAssetReceivesArgs,
+  cbk?: TapdCallback<GetAssetReceivesResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          const after = args.created_after;
+          const before = args.created_before;
+
+          if (args.address !== undefined && typeof args.address !== 'string') {
+            return cbk([400, 'ExpectedAssetAddressStringToGetAssetReceives']);
+          }
+
+          if (after !== undefined && !isDate(after)) {
+            return cbk([400, 'ExpectedValidCreatedAfterDateToGetReceives']);
+          }
+
+          if (before !== undefined && !isDate(before)) {
+            return cbk([400, 'ExpectedValidCreatedBeforeDateToGetReceives']);
+          }
+
+          if (args.limit !== undefined && !isSafeInteger(args.limit)) {
+            return cbk([400, 'ExpectedIntegerLimitToGetAssetReceives']);
+          }
+
+          if (args.limit !== undefined && args.limit < 1) {
+            return cbk([400, 'ExpectedPositiveLimitToGetAssetReceives']);
+          }
+
+          if (args.limit !== undefined && args.limit > maxLimit) {
+            return cbk([400, 'ExpectedSmallerLimitToGetAssetReceives']);
+          }
+
+          if (!!args.limit && !!args.token) {
+            return cbk([400, 'UnexpectedLimitWhenPagingReceivesWithToken']);
+          }
+
+          if (args.status !== undefined && !statuses[args.status]) {
+            return cbk([400, 'ExpectedKnownStatusToGetAssetReceives']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetReceives']);
+          }
+
+          return cbk();
+        },
+
+        // Get the receives
+        getReceives: [
+          'validate',
+          ({}, cbk) => {
+            let limit = args.limit || defaultLimit;
+            let offset = 0;
+
+            // tapd reads the offset as a row offset in the results
+            if (!!args.token) {
+              try {
+                const pagingToken = parse(args.token);
+
+                limit = pagingToken.limit;
+                offset = pagingToken.offset;
+              } catch (err) {
+                return cbk([
+                  400,
+                  'ExpectedValidPagingTokenToGetReceives',
+                  {err},
+                ]);
+              }
+
+              if (!isSafeInteger(limit) || limit < 1 || limit > maxLimit) {
+                return cbk([400, 'ExpectedValidPagingTokenToGetReceives']);
+              }
+
+              if (!isSafeInteger(offset) || offset < 0 || offset > maxOffset) {
+                return cbk([400, 'ExpectedValidPagingTokenToGetReceives']);
+              }
+            }
+
+            const request = {
+              direction: newestFirst,
+              end_timestamp: asSeconds(args.created_before),
+              filter_addr: args.address || '',
+              filter_status: !!args.status
+                ? statuses[args.status]
+                : noStatusFilter,
+              limit,
+              offset,
+              start_timestamp: asSeconds(args.created_after),
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetReceives']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetReceives']);
+              }
+
+              if (!!err && String(err.details).includes(invalidAddressError)) {
+                return cbk([400, 'ExpectedValidAssetAddressToGetReceives']);
+              }
+
+              if (!!err && String(err.details).includes(unknownAssetError)) {
+                return cbk([404, 'AssetNotFound']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetReceives', {err}]);
+              }
+
+              if (!res || !isArray(res.events)) {
+                return cbk([
+                  503,
+                  'ExpectedArrayOfEventsInAddrReceivesResponse',
+                ]);
+              }
+
+              try {
+                const receives = res.events.map(rpcAddrEventAsReceive);
+
+                // A full page means that there can be more results
+                const isFullPage = receives.length === limit;
+
+                const next = stringify({limit, offset: offset + limit});
+
+                return cbk(null, {
+                  next: isFullPage ? next : undefined,
+                  receives,
+                });
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'getReceives'}, cbk),
+    );
+  });
+};
+
+export default getAssetReceives;