tapass 0.1.0 → 0.2.0

package/src/tapd_methods/proofs/decode_asset_proof.ts

@@ -0,0 +1,175 @@
+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 {rpcDecodedProofAsProof} from '../../tapd_responses/index.js';
+import type {Proof} 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 invalidDepthError = 'invalid depth';
+const invalidProofErrors = [
+  'could not identify decoding format',
+  'invalid proof file',
+  'unable to decode proof',
+];
+const isHex = (n: string) => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const {isSafeInteger} = Number;
+const maxDepth = 4294967295;
+const method = 'decodeProof';
+const type = 'default';
+
+export type DecodeAssetProofArgs = AuthenticatedTapdArgs<{
+  /** Proof Depth From the Last Proof In the File Number */
+  depth?: number;
+  /** Include the Asset Metadata */
+  is_including_meta?: boolean;
+  /** Asset Proof or Proof File Hex String */
+  proof: string;
+}>;
+
+export type DecodeAssetProofResult = Proof;
+
+type Tasks = {
+  decode: DecodeAssetProofResult;
+  validate: undefined;
+};
+
+/** Decode an asset proof or one proof in an asset proof file
+
+  Requires `proofs:read` permission
+
+  For a proof file, `depth` selects the proof: 0 is the last proof
+
+  {
+    [depth]: <Proof Depth From the Last Proof In the File Number>
+    [is_including_meta]: <Include the Asset Metadata Bool>
+    proof: <Asset Proof or Proof File Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    additional_inputs_count: <Additional Inputs Count Number>
+    [alt_leaves]: <Alternative Leaves Hex String>
+    asset: <Asset Object>
+    challenge_witness: [<Challenge Witness Element Hex String>]
+    depth: <Proof Depth From the Last Proof In the File Number>
+    exclusion_proofs: [<Exclusion Proof Hex String>]
+    [genesis]: {
+      asset_id: <Asset Id Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+      output_index: <Genesis Commitment Output Index Number>
+      transaction_id: <Genesis Point Transaction Id Hex String>
+      transaction_vout: <Genesis Point Transaction Output Index Number>
+    }
+    [group_key]: {
+      raw_key: <Raw Group Key Hex String>
+      [tapscript_root]: <Group Tapscript Root Hex String>
+    }
+    inclusion_proof: <Inclusion Proof Hex String>
+    is_burn: <Proof Is For a Burn Bool>
+    [meta]: {
+      data: <Metadata Hex String>
+      hash: <Metadata Hash Hex String>
+      type: <Metadata Type String>
+    }
+    proofs_count: <Proofs In the File Count Number>
+    [split_root_proof]: <Split Root Proof Hex String>
+    transaction_merkle_proof: <Transaction Merkle Proof Hex String>
+  }
+*/
+const decodeAssetProof: TapdMethod<
+  DecodeAssetProofArgs,
+  DecodeAssetProofResult
+> = (
+  args: DecodeAssetProofArgs,
+  cbk?: TapdCallback<DecodeAssetProofResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (args.depth !== undefined && !isSafeInteger(args.depth)) {
+            return cbk([400, 'ExpectedIntegerDepthToDecodeAssetProof']);
+          }
+
+          if (args.depth !== undefined && args.depth < 0) {
+            return cbk([400, 'ExpectedNonNegativeDepthToDecodeAssetProof']);
+          }
+
+          if (args.depth !== undefined && args.depth > maxDepth) {
+            return cbk([400, 'ExpectedSmallerDepthToDecodeAssetProof']);
+          }
+
+          if (!args.proof || !isHex(args.proof)) {
+            return cbk([400, 'ExpectedHexAssetProofToDecode']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToDecodeAssetProof']);
+          }
+
+          return cbk();
+        },
+
+        // Decode the proof
+        decode: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              proof_at_depth: args.depth || 0,
+              raw_proof: Buffer.from(args.proof, 'hex'),
+              with_meta_reveal: !!args.is_including_meta,
+              with_prev_witnesses: false,
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToDecodeAssetProof']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToDecodeAssetProof']);
+              }
+
+              const details = String(err?.details);
+
+              if (!!err && details.includes(invalidDepthError)) {
+                return cbk([400, 'ExpectedDepthInProofFileToDecodeAssetProof']);
+              }
+
+              if (!!err && invalidProofErrors.some(n => details.includes(n))) {
+                return cbk([400, 'ExpectedValidAssetProofToDecode']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorDecodingAssetProof', {err}]);
+              }
+
+              if (!res) {
+                return cbk([503, 'ExpectedResponseToDecodeAssetProofRequest']);
+              }
+
+              try {
+                return cbk(null, rpcDecodedProofAsProof(res.decoded_proof));
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'decode'}, cbk),
+    );
+  });
+};
+
+export default decodeAssetProof;

package/src/tapd_methods/proofs/export_asset_proof.ts

@@ -0,0 +1,169 @@
+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 isAssetId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isScriptKey = (n: string) => /^([0-9A-F]{2})?[0-9A-F]{64}$/i.test(n);
+const {isSafeInteger} = Number;
+const isTransactionId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const maxVout = 4294967295;
+const method = 'exportProof';
+const multipleProofsError = 'multiple proofs found';
+const notFoundError = 'unable to find proof';
+const type = 'default';
+
+export type ExportAssetProofArgs = AuthenticatedTapdArgs<{
+  /** Asset Id Hex String */
+  asset_id: string;
+  /** Script Key Hex String */
+  script_key: string;
+  /** Anchor Transaction Id Hex String */
+  transaction_id?: string;
+  /** Anchor Transaction Output Index Number */
+  transaction_vout?: number;
+}>;
+
+export type ExportAssetProofResult = {
+  /** Asset Proof File Hex */
+  proof: string;
+};
+
+type Tasks = {
+  export: ExportAssetProofResult;
+  validate: undefined;
+};
+
+/** Export the proof file of an asset
+
+  Requires `proofs:read` permission
+
+  If there is more than one proof for the asset id and the script key, an
+  anchor outpoint is necessary: `transaction_id` and `transaction_vout`
+
+  {
+    asset_id: <Asset Id Hex String>
+    script_key: <Script Key Hex String>
+    tapd: <Authenticated tapd API Object>
+    [transaction_id]: <Anchor Transaction Id Hex String>
+    [transaction_vout]: <Anchor Transaction Output Index Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    proof: <Asset Proof File Hex String>
+  }
+*/
+const exportAssetProof: TapdMethod<
+  ExportAssetProofArgs,
+  ExportAssetProofResult
+> = (
+  args: ExportAssetProofArgs,
+  cbk?: TapdCallback<ExportAssetProofResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          const id = args.transaction_id;
+          const vout = args.transaction_vout;
+
+          if (!args.asset_id || !isAssetId(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToExportAssetProof']);
+          }
+
+          if (!args.script_key || !isScriptKey(args.script_key)) {
+            return cbk([400, 'ExpectedScriptKeyHexToExportAssetProof']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToExportAssetProof']);
+          }
+
+          if ((id === undefined) !== (vout === undefined)) {
+            return cbk([400, 'ExpectedTransactionIdAndVoutToExportAssetProof']);
+          }
+
+          if (id !== undefined && !isTransactionId(id)) {
+            return cbk([400, 'ExpectedTransactionIdHexToExportAssetProof']);
+          }
+
+          if (vout !== undefined && !isSafeInteger(vout)) {
+            return cbk([400, 'ExpectedIntegerOutputIndexToExportAssetProof']);
+          }
+
+          if (vout !== undefined && (vout < 0 || vout > maxVout)) {
+            return cbk([400, 'ExpectedValidOutputIndexToExportAssetProof']);
+          }
+
+          return cbk();
+        },
+
+        // Export the proof file
+        export: [
+          'validate',
+          ({}, cbk) => {
+            const id = args.transaction_id;
+
+            // tapd reads the transaction id in the internal byte order
+            const outpoint = !id
+              ? undefined
+              : {
+                  output_index: args.transaction_vout,
+                  txid: Buffer.from(id, 'hex').reverse(),
+                };
+
+            const request = {
+              asset_id: Buffer.from(args.asset_id, 'hex'),
+              outpoint,
+              script_key: Buffer.from(args.script_key, 'hex'),
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToExportAssetProof']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToExportAssetProof']);
+              }
+
+              if (!!err && String(err.details).includes(notFoundError)) {
+                return cbk([404, 'AssetProofNotFound']);
+              }
+
+              if (!!err && String(err.details).includes(multipleProofsError)) {
+                return cbk([400, 'ExpectedAnchorOutpointToSelectAssetProof']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorExportingAssetProof', {err}]);
+              }
+
+              if (!res || !isBuffer(res.raw_proof_file)) {
+                return cbk([503, 'ExpectedProofFileInExportProofResponse']);
+              }
+
+              if (!res.raw_proof_file.length) {
+                return cbk([503, 'ExpectedProofFileInExportProofResponse']);
+              }
+
+              return cbk(null, {proof: res.raw_proof_file.toString('hex')});
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'export'}, cbk),
+    );
+  });
+};
+
+export default exportAssetProof;

package/src/tapd_methods/proofs/index.ts

@@ -0,0 +1,12 @@
+export {default as decodeAssetProof} from './decode_asset_proof.js';
+export type {DecodeAssetProofArgs} from './decode_asset_proof.js';
+export type {DecodeAssetProofResult} from './decode_asset_proof.js';
+export {default as exportAssetProof} from './export_asset_proof.js';
+export type {ExportAssetProofArgs} from './export_asset_proof.js';
+export type {ExportAssetProofResult} from './export_asset_proof.js';
+export {default as unpackAssetProofFile} from './unpack_asset_proof_file.js';
+export type {UnpackAssetProofFileArgs} from './unpack_asset_proof_file.js';
+export type {UnpackAssetProofFileResult} from './unpack_asset_proof_file.js';
+export {default as verifyAssetProof} from './verify_asset_proof.js';
+export type {VerifyAssetProofArgs} from './verify_asset_proof.js';
+export type {VerifyAssetProofResult} from './verify_asset_proof.js';

package/src/tapd_methods/proofs/unpack_asset_proof_file.ts

@@ -0,0 +1,126 @@
+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 invalidFileError = 'unable to decode proof file';
+const {isArray} = Array;
+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 method = 'unpackProofFile';
+const type = 'default';
+
+export type UnpackAssetProofFileArgs = AuthenticatedTapdArgs<{
+  /** Asset Proof File Hex String */
+  proof: string;
+}>;
+
+export type UnpackAssetProofFileResult = {
+  /** Asset Proofs Hex, First Proof First */
+  proofs: string[];
+};
+
+type Tasks = {
+  unpack: UnpackAssetProofFileResult;
+  validate: undefined;
+};
+
+/** Get the individual proofs in an asset proof file
+
+  Requires `proofs:read` permission
+
+  The first proof in the list is the first proof in the proof chain
+
+  {
+    proof: <Asset Proof File Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    proofs: [<Asset Proof Hex String>]
+  }
+*/
+const unpackAssetProofFile: TapdMethod<
+  UnpackAssetProofFileArgs,
+  UnpackAssetProofFileResult
+> = (
+  args: UnpackAssetProofFileArgs,
+  cbk?: TapdCallback<UnpackAssetProofFileResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!args.proof || !isHex(args.proof)) {
+            return cbk([400, 'ExpectedHexAssetProofFileToUnpack']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([
+              400,
+              'ExpectedAuthenticatedTapdToUnpackAssetProofFile',
+            ]);
+          }
+
+          return cbk();
+        },
+
+        // Unpack the proof file
+        unpack: [
+          'validate',
+          ({}, cbk) => {
+            const request = {raw_proof_file: Buffer.from(args.proof, 'hex')};
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([
+                  503,
+                  'FailedToConnectToTapdToUnpackAssetProofFile',
+                ]);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToUnpackAssetProofFile']);
+              }
+
+              if (!!err && String(err.details).includes(invalidFileError)) {
+                return cbk([400, 'ExpectedValidAssetProofFileToUnpack']);
+              }
+
+              if (!!err) {
+                return cbk([
+                  503,
+                  'UnexpectedErrorUnpackingAssetProofFile',
+                  {err},
+                ]);
+              }
+
+              if (!res || !isArray(res.raw_proofs)) {
+                return cbk([503, 'ExpectedRawProofsInUnpackProofFileResponse']);
+              }
+
+              if (!res.raw_proofs.every(isBuffer)) {
+                return cbk([503, 'ExpectedRawProofsInUnpackProofFileResponse']);
+              }
+
+              return cbk(null, {
+                proofs: res.raw_proofs.map((n: Buffer) => n.toString('hex')),
+              });
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'unpack'}, cbk),
+    );
+  });
+};
+
+export default unpackAssetProofFile;

package/src/tapd_methods/proofs/verify_asset_proof.ts

@@ -0,0 +1,156 @@
+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 {rpcDecodedProofAsProof} from '../../tapd_responses/index.js';
+import type {Proof} 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 invalidFileErrors = ['invalid proof file', 'unable to decode proof file'];
+const isHex = (n: string) => !!n && !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const method = 'verifyProof';
+const notFileError = 'invalid raw proof, expect file';
+const type = 'default';
+
+export type VerifyAssetProofArgs = AuthenticatedTapdArgs<{
+  /** Asset Proof File Hex String */
+  proof: string;
+}>;
+
+export type VerifyAssetProofResult = {
+  /** Proof File Is Valid */
+  is_valid: boolean;
+  /** Last Proof In the File */
+  proof?: Proof;
+};
+
+type Tasks = {
+  verify: VerifyAssetProofResult;
+  validate: undefined;
+};
+
+/** Verify an asset proof file
+
+  Requires `proofs:read` permission
+
+  A valid proof file also returns its last proof, decoded
+
+  {
+    proof: <Asset Proof File Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    is_valid: <Proof File Is Valid Bool>
+    [proof]: {
+      additional_inputs_count: <Additional Inputs Count Number>
+      [alt_leaves]: <Alternative Leaves Hex String>
+      asset: <Asset Object>
+      challenge_witness: [<Challenge Witness Element Hex String>]
+      depth: <Proof Depth From the Last Proof In the File Number>
+      exclusion_proofs: [<Exclusion Proof Hex String>]
+      [genesis]: {
+        asset_id: <Asset Id Hex String>
+        is_collectible: <Asset Is Collectible Bool>
+        meta_hash: <Asset Metadata Hash Hex String>
+        name: <Asset Name String>
+        output_index: <Genesis Commitment Output Index Number>
+        transaction_id: <Genesis Point Transaction Id Hex String>
+        transaction_vout: <Genesis Point Transaction Output Index Number>
+      }
+      [group_key]: {
+        raw_key: <Raw Group Key Hex String>
+        [tapscript_root]: <Group Tapscript Root Hex String>
+      }
+      inclusion_proof: <Inclusion Proof Hex String>
+      is_burn: <Proof Is For a Burn Bool>
+      proofs_count: <Proofs In the File Count Number>
+      [split_root_proof]: <Split Root Proof Hex String>
+      transaction_merkle_proof: <Transaction Merkle Proof Hex String>
+    }
+  }
+*/
+const verifyAssetProof: TapdMethod<
+  VerifyAssetProofArgs,
+  VerifyAssetProofResult
+> = (
+  args: VerifyAssetProofArgs,
+  cbk?: TapdCallback<VerifyAssetProofResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!args.proof || !isHex(args.proof)) {
+            return cbk([400, 'ExpectedHexAssetProofFileToVerify']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToVerifyAssetProof']);
+          }
+
+          return cbk();
+        },
+
+        // Verify the proof file
+        verify: [
+          'validate',
+          ({}, cbk) => {
+            const request = {raw_proof_file: Buffer.from(args.proof, 'hex')};
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToVerifyAssetProof']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToVerifyAssetProof']);
+              }
+
+              const details = String(err?.details);
+
+              if (!!err && details.includes(notFileError)) {
+                return cbk([400, 'ExpectedProofFileNotSingleProofToVerify']);
+              }
+
+              if (!!err && invalidFileErrors.some(n => details.includes(n))) {
+                return cbk([400, 'ExpectedValidAssetProofFileToVerify']);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorVerifyingAssetProof', {err}]);
+              }
+
+              if (!res) {
+                return cbk([503, 'ExpectedResponseToVerifyAssetProofRequest']);
+              }
+
+              // Exit early when the proof file is not valid
+              if (!res.valid) {
+                return cbk(null, {is_valid: false});
+              }
+
+              try {
+                const proof = rpcDecodedProofAsProof(res.decoded_proof);
+
+                return cbk(null, {proof, is_valid: true});
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'verify'}, cbk),
+    );
+  });
+};
+
+export default verifyAssetProof;