@buildonspark/issuer-sdk 0.1.2 → 0.1.4

package/dist/index.node.js

@@ -250,6 +250,9 @@ var IssuerTokenTransactionService = class extends TokenTransactionService {
   }
 };
 
+// src/issuer-wallet/issuer-spark-wallet.ts
+import { hashFinalTokenTransaction } from "@buildonspark/spark-sdk";
+
 // src/utils/create-validation.ts
 import { SparkValidationError as SparkValidationError2 } from "@buildonspark/spark-sdk";
 function isNfcNormalized(value) {
@@ -357,49 +360,70 @@ var IssuerSparkWallet = class extends SparkWallet {
   }
   /**
    * Gets the token balance for the issuer's token.
+   * @deprecated Use getIssuerTokenBalances() instead. This method will be removed in a future version.
    * @returns An object containing the token balance as a bigint
+   *
+   * @throws {SparkValidationError} If multiple tokens are found for this issuer
    */
   async getIssuerTokenBalance() {
     const publicKey = await super.getIdentityPublicKey();
     const balanceObj = await this.getBalance();
-    const issuerBalance = [...balanceObj.tokenBalances.entries()].find(
+    const issuerBalance = [...balanceObj.tokenBalances.entries()].filter(
       ([, info]) => info.tokenMetadata.tokenPublicKey === publicKey
     );
-    if (!balanceObj.tokenBalances || issuerBalance === void 0) {
+    if (issuerBalance.length > 1) {
+      throw new SparkValidationError3(
+        "Multiple tokens found for this issuer. Use getIssuerTokenBalances() instead.",
+        {
+          field: "issuerTokenBalance",
+          expected: "single token",
+          actual: `${issuerBalance.length} tokens`
+        }
+      );
+    }
+    if (issuerBalance.length === 0) {
       return {
         tokenIdentifier: void 0,
         balance: 0n
       };
     }
     return {
-      tokenIdentifier: issuerBalance[0] ?? void 0,
-      balance: issuerBalance[1].balance
+      tokenIdentifier: issuerBalance[0][0],
+      balance: issuerBalance[0][1].balance
     };
   }
+  /**
+   * Gets the token balances for the tokens that were issued by this user.
+   * @returns An array of objects containing the token identifier and balance
+   */
+  async getIssuerTokenBalances() {
+    const publicKey = await super.getIdentityPublicKey();
+    const balanceObj = await this.getBalance();
+    const issuerBalance = [...balanceObj.tokenBalances.entries()].filter(
+      ([, info]) => info.tokenMetadata.tokenPublicKey === publicKey
+    );
+    if (issuerBalance.length === 0) {
+      return [
+        {
+          tokenIdentifier: void 0,
+          balance: 0n
+        }
+      ];
+    }
+    return issuerBalance.map(([tokenIdentifier, { balance }]) => ({
+      tokenIdentifier,
+      balance
+    }));
+  }
   /**
    * Retrieves information about the issuer's token.
-   * @returns An object containing token information including public key, name, symbol, decimals, max supply, and freeze status
+   * @deprecated Use getIssuerTokensMetadata() instead. This method will be removed in a future version.
+   * @returns An object containing token information including public key, name, symbol, decimals, max supply, freeze status, and extra metadata
    * @throws {SparkRequestError} If the token metadata cannot be retrieved
+   * @throws {SparkValidationError} If multiple tokens are found for this issuer
    */
   async getIssuerTokenMetadata() {
     const issuerPublicKey = await super.getIdentityPublicKey();
-    const tokenMetadata = this.tokenMetadata;
-    const cachedIssuerTokenMetadata = [...tokenMetadata.entries()].find(
-      ([, metadata]) => bytesToHex(metadata.issuerPublicKey) === issuerPublicKey
-    );
-    if (cachedIssuerTokenMetadata !== void 0) {
-      const metadata = cachedIssuerTokenMetadata[1];
-      return {
-        tokenPublicKey: bytesToHex(metadata.issuerPublicKey),
-        rawTokenIdentifier: metadata.tokenIdentifier,
-        tokenName: metadata.tokenName,
-        tokenTicker: metadata.tokenTicker,
-        decimals: metadata.decimals,
-        maxSupply: bytesToNumberBE(metadata.maxSupply),
-        isFreezable: metadata.isFreezable,
-        extraMetadata: metadata.extraMetadata ? new Uint8Array(metadata.extraMetadata) : void 0
-      };
-    }
     const sparkTokenClient = await this.connectionManager.createSparkTokenClient(
       this.config.getCoordinatorAddress()
     );
@@ -419,12 +443,21 @@ var IssuerSparkWallet = class extends SparkWallet {
           }
         );
       }
+      if (response.tokenMetadata.length > 1) {
+        throw new SparkValidationError3(
+          "Multiple tokens found for this issuer. Please migrate to getIssuerTokensMetadata() instead.",
+          {
+            field: "tokenMetadata",
+            value: response.tokenMetadata
+          }
+        );
+      }
       const metadata = response.tokenMetadata[0];
-      const tokenIdentifier = encodeBech32mTokenIdentifier({
+      const bech32mTokenIdentifier = encodeBech32mTokenIdentifier({
         tokenIdentifier: metadata.tokenIdentifier,
         network: this.config.getNetworkType()
       });
-      this.tokenMetadata.set(tokenIdentifier, metadata);
+      this.tokenMetadata.set(bech32mTokenIdentifier, metadata);
       return {
         tokenPublicKey: bytesToHex(metadata.issuerPublicKey),
         rawTokenIdentifier: metadata.tokenIdentifier,
@@ -433,47 +466,110 @@ var IssuerSparkWallet = class extends SparkWallet {
         decimals: metadata.decimals,
         maxSupply: bytesToNumberBE(metadata.maxSupply),
         isFreezable: metadata.isFreezable,
-        extraMetadata: metadata.extraMetadata
+        extraMetadata: metadata.extraMetadata ? new Uint8Array(metadata.extraMetadata) : void 0,
+        bech32mTokenIdentifier
       };
     } catch (error) {
       throw new SparkRequestError2("Failed to fetch token metadata", { error });
     }
   }
+  /**
+   * Retrieves information about the tokens that were issued by this user.
+   * @returns An array of objects containing token information including public key, name, symbol, decimals, max supply, freeze status, and extra metadata
+   * @throws {SparkRequestError} If the token metadata cannot be retrieved
+   */
+  async getIssuerTokensMetadata() {
+    const issuerPublicKey = await super.getIdentityPublicKey();
+    const sparkTokenClient = await this.connectionManager.createSparkTokenClient(
+      this.config.getCoordinatorAddress()
+    );
+    try {
+      const response = await sparkTokenClient.query_token_metadata({
+        issuerPublicKeys: Array.of(hexToBytes2(issuerPublicKey))
+      });
+      if (response.tokenMetadata.length === 0) {
+        throw new SparkValidationError3(
+          "Token metadata not found - If a token has not yet been created, please create it first. Try again in a few seconds.",
+          {
+            field: "tokenMetadata",
+            value: response.tokenMetadata,
+            expected: "non-empty array",
+            actualLength: response.tokenMetadata.length,
+            expectedLength: 1
+          }
+        );
+      }
+      const tokenMetadata = [];
+      for (const metadata of response.tokenMetadata) {
+        const bech32mTokenIdentifier = encodeBech32mTokenIdentifier({
+          tokenIdentifier: metadata.tokenIdentifier,
+          network: this.config.getNetworkType()
+        });
+        this.tokenMetadata.set(bech32mTokenIdentifier, metadata);
+        tokenMetadata.push({
+          tokenPublicKey: bytesToHex(metadata.issuerPublicKey),
+          rawTokenIdentifier: metadata.tokenIdentifier,
+          tokenName: metadata.tokenName,
+          tokenTicker: metadata.tokenTicker,
+          decimals: metadata.decimals,
+          maxSupply: bytesToNumberBE(metadata.maxSupply),
+          isFreezable: metadata.isFreezable,
+          extraMetadata: metadata.extraMetadata ? new Uint8Array(metadata.extraMetadata) : void 0,
+          bech32mTokenIdentifier
+        });
+      }
+      return tokenMetadata;
+    } catch (error) {
+      throw new SparkRequestError2("Failed to fetch token metadata", { error });
+    }
+  }
   /**
    * Retrieves the bech32m encoded token identifier for the issuer's token.
+   * @deprecated Use getIssuerTokenIdentifiers() instead. This method will be removed in a future version.
    * @returns The bech32m encoded token identifier for the issuer's token
    * @throws {SparkRequestError} If the token identifier cannot be retrieved
+   * @throws {SparkValidationError} If multiple tokens are found for this issuer
    */
   async getIssuerTokenIdentifier() {
-    const tokenMetadata = await this.getIssuerTokenMetadata();
-    return encodeBech32mTokenIdentifier({
-      tokenIdentifier: tokenMetadata.rawTokenIdentifier,
-      network: this.config.getNetworkType()
-    });
+    const tokensMetadata = await this.getIssuerTokensMetadata();
+    if (tokensMetadata.length > 1) {
+      throw new SparkValidationError3(
+        "Multiple tokens found. Use getIssuerTokenIdentifiers() instead.",
+        {
+          method: "getIssuerTokenIdentifier",
+          availableTokens: tokensMetadata.map((t) => ({
+            tokenName: t.tokenName,
+            tokenTicker: t.tokenTicker,
+            bech32mTokenIdentifier: encodeBech32mTokenIdentifier({
+              tokenIdentifier: t.rawTokenIdentifier,
+              network: this.config.getNetworkType()
+            })
+          }))
+        }
+      );
+    }
+    if (tokensMetadata.length === 0) {
+      throw new SparkValidationError3("No tokens found. Create a token first.");
+    }
+    return tokensMetadata[0].bech32mTokenIdentifier;
   }
   /**
-   * Create a new token on Spark.
-   *
-   * @param params - Object containing token creation parameters.
-   * @param params.tokenName - The name of the token.
-   * @param params.tokenTicker - The ticker symbol for the token.
-   * @param params.decimals - The number of decimal places for the token.
-   * @param params.isFreezable - Whether the token can be frozen.
-   * @param [params.maxSupply=0n] - (Optional) The maximum supply of the token. Defaults to <code>0n</code>.
-   * @param params.extraMetadata - (Optional) This can be used to store additional bytes data to be associated with a token, like image data.
-   *
-   * @returns The transaction ID of the announcement.
-   *
-   * @throws {SparkValidationError} If `decimals` is not a safe integer or other validation fails.
-   * @throws {SparkRequestError} If the announcement transaction cannot be broadcast.
+   * Retrieves the bech32m encoded token identifier for the issuer's token.
+   * @returns The bech32m encoded token identifier for the issuer's token
+   * @throws {SparkRequestError} If the token identifier cannot be retrieved
    */
+  async getIssuerTokenIdentifiers() {
+    const tokensMetadata = await this.getIssuerTokensMetadata();
+    return tokensMetadata.map((metadata) => metadata.bech32mTokenIdentifier);
+  }
   async createToken({
     tokenName,
     tokenTicker,
     decimals,
     isFreezable,
     maxSupply = 0n,
-    extraMetadata
+    extraMetadata,
+    returnIdentifierForCreate = false
   }) {
     validateTokenParameters(
       tokenName,
@@ -493,9 +589,30 @@ var IssuerSparkWallet = class extends SparkWallet {
         isFreezable,
         extraMetadata
       );
-      return await this.issuerTokenTransactionService.broadcastTokenTransaction(
+      const { finalTokenTransactionHash, tokenIdentifier } = await this.issuerTokenTransactionService.broadcastTokenTransactionDetailed(
         tokenTransaction
       );
+      const txHash = bytesToHex(finalTokenTransactionHash);
+      if (returnIdentifierForCreate) {
+        if (!tokenIdentifier) {
+          throw new SparkRequestError2(
+            "Server response missing expected field: tokenIdentifier",
+            {
+              operation: "broadcast_transaction",
+              field: "tokenIdentifier"
+            }
+          );
+        }
+        const bech32mTokenIdentifier = encodeBech32mTokenIdentifier({
+          tokenIdentifier,
+          network: this.config.getNetworkType()
+        });
+        return {
+          tokenIdentifier: bech32mTokenIdentifier,
+          transactionHash: txHash
+        };
+      }
+      return txHash;
     } else {
       const partialTokenTransaction = await this.issuerTokenTransactionService.constructPartialCreateTokenTransaction(
         hexToBytes2(issuerPublicKey),
@@ -506,21 +623,75 @@ var IssuerSparkWallet = class extends SparkWallet {
         isFreezable,
         extraMetadata
       );
-      return await this.issuerTokenTransactionService.broadcastTokenTransactionV3(
+      const broadcastResponse = await this.issuerTokenTransactionService.broadcastTokenTransactionV3Detailed(
         partialTokenTransaction
       );
+      const finalHash = await hashFinalTokenTransaction(
+        broadcastResponse.finalTokenTransaction
+      );
+      const finalTransactionHash = bytesToHex(finalHash);
+      if (returnIdentifierForCreate) {
+        if (!broadcastResponse.tokenIdentifier) {
+          throw new SparkRequestError2(
+            "Server response missing expected field: tokenIdentifier",
+            {
+              operation: "broadcast_transaction",
+              field: "tokenIdentifier"
+            }
+          );
+        }
+        const tokenIdentifier = encodeBech32mTokenIdentifier({
+          tokenIdentifier: broadcastResponse.tokenIdentifier,
+          network: this.config.getNetworkType()
+        });
+        return {
+          tokenIdentifier,
+          transactionHash: finalTransactionHash
+        };
+      }
+      return finalTransactionHash;
     }
   }
-  /**
-   * Mints new tokens
-   * @param tokenAmount - The amount of tokens to mint
-   * @returns The transaction ID of the mint operation
-   */
-  async mintTokens(tokenAmount) {
+  async mintTokens(tokenAmountOrParams) {
+    let tokenAmount;
+    let bech32mTokenIdentifier;
+    if (typeof tokenAmountOrParams === "bigint") {
+      tokenAmount = tokenAmountOrParams;
+      bech32mTokenIdentifier = void 0;
+    } else {
+      tokenAmount = tokenAmountOrParams.tokenAmount;
+      bech32mTokenIdentifier = tokenAmountOrParams.tokenIdentifier;
+    }
     const issuerTokenPublicKey = await super.getIdentityPublicKey();
     const issuerTokenPublicKeyBytes = hexToBytes2(issuerTokenPublicKey);
-    const tokenMetadata = await this.getIssuerTokenMetadata();
-    const rawTokenIdentifier = tokenMetadata.rawTokenIdentifier;
+    const tokensMetadata = await this.getIssuerTokensMetadata();
+    if (bech32mTokenIdentifier === void 0) {
+      if (tokensMetadata.length > 1) {
+        throw new SparkValidationError3(
+          "Multiple tokens found. Please use mintTokens({ tokenAmount, tokenIdentifier }) instead.",
+          {
+            field: "tokenIdentifier",
+            availableTokens: tokensMetadata.map((t) => ({
+              tokenName: t.tokenName,
+              tokenTicker: t.tokenTicker,
+              bech32mTokenIdentifier: encodeBech32mTokenIdentifier({
+                tokenIdentifier: t.rawTokenIdentifier,
+                network: this.config.getNetworkType()
+              })
+            }))
+          }
+        );
+      }
+      const encodedTokenIdentifier = encodeBech32mTokenIdentifier({
+        tokenIdentifier: tokensMetadata[0].rawTokenIdentifier,
+        network: this.config.getNetworkType()
+      });
+      bech32mTokenIdentifier = encodedTokenIdentifier;
+    }
+    const rawTokenIdentifier = decodeBech32mTokenIdentifier(
+      bech32mTokenIdentifier,
+      this.config.getNetworkType()
+    ).tokenIdentifier;
     if (this.config.getTokenTransactionVersion() === "V2") {
       const tokenTransaction = await this.issuerTokenTransactionService.constructMintTokenTransaction(
         rawTokenIdentifier,
@@ -541,39 +712,108 @@ var IssuerSparkWallet = class extends SparkWallet {
       );
     }
   }
-  /**
-   * Burns issuer's tokens
-   * @param tokenAmount - The amount of tokens to burn
-   * @param selectedOutputs - Optional array of outputs to use for the burn operation
-   * @returns The transaction ID of the burn operation
-   */
-  async burnTokens(tokenAmount, selectedOutputs) {
+  async burnTokens(tokenAmountOrParams, selectedOutputs) {
+    let bech32mTokenIdentifier;
+    let tokenAmount;
+    let outputs;
+    if (typeof tokenAmountOrParams === "bigint") {
+      tokenAmount = tokenAmountOrParams;
+      outputs = selectedOutputs;
+      const tokenIdentifiers = await this.getIssuerTokenIdentifiers();
+      if (tokenIdentifiers.length > 1) {
+        throw new SparkValidationError3(
+          "Multiple tokens found. Use burnTokens({ tokenIdentifier, tokenAmount, selectedOutputs }) to specify which token to burn.",
+          {
+            field: "tokenIdentifier",
+            availableTokens: tokenIdentifiers
+          }
+        );
+      }
+      if (tokenIdentifiers.length === 0) {
+        throw new SparkValidationError3(
+          "No tokens found. Create a token first."
+        );
+      }
+      bech32mTokenIdentifier = tokenIdentifiers[0];
+    } else {
+      tokenAmount = tokenAmountOrParams.tokenAmount;
+      outputs = tokenAmountOrParams.selectedOutputs;
+      if (tokenAmountOrParams.tokenIdentifier) {
+        const tokenIdentifiers = await this.getIssuerTokenIdentifiers();
+        const tokenIdentifier = tokenIdentifiers.find(
+          (identifier) => identifier === tokenAmountOrParams.tokenIdentifier
+        );
+        if (!tokenIdentifier) {
+          throw new SparkValidationError3("Token not found for this issuer", {
+            field: "tokenIdentifier",
+            value: tokenAmountOrParams.tokenIdentifier
+          });
+        }
+        bech32mTokenIdentifier = tokenAmountOrParams.tokenIdentifier;
+      } else {
+        const tokenIdentifiers = await this.getIssuerTokenIdentifiers();
+        if (tokenIdentifiers.length === 0) {
+          throw new SparkValidationError3(
+            "No tokens found. Create a token first."
+          );
+        }
+        if (tokenIdentifiers.length > 1) {
+          throw new SparkValidationError3(
+            "Multiple tokens found. Please specify tokenIdentifier in parameters.",
+            {
+              field: "tokenIdentifier",
+              availableTokens: tokenIdentifiers
+            }
+          );
+        }
+        bech32mTokenIdentifier = tokenIdentifiers[0];
+      }
+    }
     const burnAddress = encodeSparkAddress({
       identityPublicKey: BURN_ADDRESS,
       network: this.config.getNetworkType()
     });
-    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
     return await this.transferTokens({
-      tokenIdentifier: issuerTokenIdentifier,
+      tokenIdentifier: bech32mTokenIdentifier,
       tokenAmount,
       receiverSparkAddress: burnAddress,
-      selectedOutputs
+      selectedOutputs: outputs
     });
   }
-  /**
-   * Freezes tokens associated with a specific Spark address.
-   * @param sparkAddress - The Spark address whose tokens should be frozen
-   * @returns An object containing the IDs of impacted outputs and the total amount of frozen tokens
-   */
-  async freezeTokens(sparkAddress) {
-    await this.syncTokenOutputs();
+  async freezeTokens(sparkAddressOrParams) {
+    let bech32mTokenIdentifier;
+    let sparkAddress;
+    if (typeof sparkAddressOrParams === "string") {
+      sparkAddress = sparkAddressOrParams;
+      bech32mTokenIdentifier = void 0;
+    } else {
+      sparkAddress = sparkAddressOrParams.sparkAddress;
+      bech32mTokenIdentifier = sparkAddressOrParams.tokenIdentifier;
+    }
     const decodedOwnerPubkey = decodeSparkAddress(
       sparkAddress,
       this.config.getNetworkType()
     );
-    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
+    if (bech32mTokenIdentifier === void 0) {
+      const tokenIdentifiers = await this.getIssuerTokenIdentifiers();
+      if (tokenIdentifiers.length === 0) {
+        throw new SparkValidationError3(
+          "No tokens found. Create a token first."
+        );
+      }
+      if (tokenIdentifiers.length > 1) {
+        throw new SparkValidationError3(
+          "Multiple tokens found. Use freezeTokens({ tokenIdentifier, sparkAddress }) instead.",
+          {
+            field: "tokenIdentifier",
+            availableTokens: tokenIdentifiers
+          }
+        );
+      }
+      bech32mTokenIdentifier = tokenIdentifiers[0];
+    }
     const rawTokenIdentifier = decodeBech32mTokenIdentifier(
-      issuerTokenIdentifier,
+      bech32mTokenIdentifier,
       this.config.getNetworkType()
     ).tokenIdentifier;
     const response = await this.tokenFreezeService.freezeTokens({
@@ -586,20 +826,35 @@ var IssuerSparkWallet = class extends SparkWallet {
       impactedTokenAmount: tokenAmount
     };
   }
-  /**
-   * Unfreezes previously frozen tokens associated with a specific Spark address.
-   * @param sparkAddress - The Spark address whose tokens should be unfrozen
-   * @returns An object containing the IDs of impacted outputs and the total amount of unfrozen tokens
-   */
-  async unfreezeTokens(sparkAddress) {
-    await this.syncTokenOutputs();
+  async unfreezeTokens(sparkAddressOrParams) {
+    let bech32mTokenIdentifier;
+    let sparkAddress;
+    if (typeof sparkAddressOrParams === "string") {
+      sparkAddress = sparkAddressOrParams;
+      bech32mTokenIdentifier = void 0;
+    } else {
+      sparkAddress = sparkAddressOrParams.sparkAddress;
+      bech32mTokenIdentifier = sparkAddressOrParams.tokenIdentifier;
+    }
+    if (bech32mTokenIdentifier === void 0) {
+      const tokenIdentifiers = await this.getIssuerTokenIdentifiers();
+      if (tokenIdentifiers.length > 1) {
+        throw new SparkValidationError3(
+          "Multiple tokens found. Use unfreezeTokens({ tokenIdentifier, sparkAddress }) instead.",
+          {
+            field: "tokenIdentifier",
+            availableTokens: tokenIdentifiers
+          }
+        );
+      }
+      bech32mTokenIdentifier = tokenIdentifiers[0];
+    }
     const decodedOwnerPubkey = decodeSparkAddress(
       sparkAddress,
       this.config.getNetworkType()
     );
-    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
     const rawTokenIdentifier = decodeBech32mTokenIdentifier(
-      issuerTokenIdentifier,
+      bech32mTokenIdentifier,
       this.config.getNetworkType()
     ).tokenIdentifier;
     const response = await this.tokenFreezeService.unfreezeTokens({
@@ -645,8 +900,11 @@ var IssuerSparkWallet = class extends SparkWallet {
 };
 var PUBLIC_ISSUER_SPARK_WALLET_METHODS = [
   "getIssuerTokenBalance",
+  "getIssuerTokenBalances",
   "getIssuerTokenMetadata",
+  "getIssuerTokensMetadata",
   "getIssuerTokenIdentifier",
+  "getIssuerTokenIdentifiers",
   "createToken",
   "mintTokens",
   "burnTokens",