@buildonspark/issuer-sdk 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # @buildonspark/issuer-sdk
 
+## 0.1.4
+
+### Patch Changes
+
+- ## Multi-Token Issuance Support
+
+  Introduces support for issuer wallets to create and manage multiple tokens. Each token is uniquely identified by a bech32m token identifier derived from the token's creation parameters.
+
+  **Deprecated Methods**
+
+  The following methods are now marked deprecated and will throw `SparkValidationError` when multiple tokens exist for an issuer. These methods will be removed in a future major version:
+  - `getIssuerTokenBalance()` - Use `getIssuerTokenBalances()` instead
+  - `getIssuerTokenMetadata()` - Use `getIssuerTokensMetadata()` instead
+  - `getIssuerTokenIdentifier()` - Use `getIssuerTokenIdentifiers()` instead
+  - `mintTokens(amount)` - Use `mintTokens({ tokenAmount, tokenIdentifier })` instead
+  - `burnTokens(amount, selectedOutputs?)` - Use `burnTokens({ tokenAmount, tokenIdentifier, selectedOutputs })` instead
+  - `freezeTokens(sparkAddress)` - Use `freezeTokens({ tokenIdentifier, sparkAddress })` instead
+  - `unfreezeTokens(sparkAddress)` - Use `unfreezeTokens({ tokenIdentifier, sparkAddress })` instead
+
+  ### New Features
+
+  **Token Creation with Identifier**
+
+  `createToken()` now accepts an optional `returnIdentifierForCreate` parameter to return both the transaction hash and token identifier:
+
+  ```ts
+  const result = await wallet.createToken({
+    tokenName: "MyToken",
+    tokenTicker: "MTK",
+    decimals: 8,
+    maxSupply: 1000000n,
+    isFreezable: false,
+    returnIdentifierForCreate: true, // Returns TokenCreationDetails
+  });
+  ```
+
+  **Return issuer info for all issuer tokens**
+  - `getIssuerTokenBalances()` - Returns an array of token balances for all tokens owned by the issuer
+  - `getIssuerTokensMetadata()` - Returns an array of metadata for all tokens created by the issuer
+  - `getIssuerTokenIdentifiers()` - Returns an array of bech32m token identifiers for all issuer tokens
+
+  **Method Overloads**
+
+  All token operation methods now support optional `tokenIdentifier` parameters:
+
+  ```ts
+  // Mint tokens for a specific token
+  await wallet.mintTokens({
+      tokenAmount: 1000n,
+      tokenIdentifier: "btkn1..."
+  });
+
+  // Burn tokens for a specific token
+  await wallet.burnTokens({
+      tokenAmount: 500n,
+      tokenIdentifier: "btkn1...",
+      selectedOutputs: [...] // optional
+  });
+
+  // Freeze tokens for a specific token and address
+  await wallet.freezeTokens({
+      tokenIdentifier: "btkn1...",
+      sparkAddress: "spark1..."
+  });
+
+  // Unfreeze tokens for a specific token and address
+  await wallet.unfreezeTokens({
+      tokenIdentifier: "btkn1...",
+      sparkAddress: "spark1..."
+  });
+  ```
+
+  ### Backward Compatibility
+
+  Legacy method signatures continue to work for issuers with a single token. When multiple tokens are detected, these methods will throw descriptive errors guiding developers to use the new multi-token methods.
+
+  ### Migration Guide
+
+  **For Single-Token Issuers**
+
+  Existing code consuming older SDK versions will continue to work.
+
+  **For Multi-Token Issuers**
+
+  Update your code to use the new multi-token methods:
+
+  ```ts
+  // Before
+  await wallet.mintTokens(100n);
+
+  // After
+  const metadata = await wallet.getIssuerTokensMetadata();
+  const tokenIdentifier = metadata[1].bech32mTokenIdentifier;
+  await wallet.mintTokens({
+    tokenAmount: 100n,
+    tokenIdentifier: tokenIdentifier,
+  });
+  ```
+
+- Updated dependencies
+  - @buildonspark/spark-sdk@0.5.4
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @buildonspark/spark-sdk@0.5.3
+
 ## 0.1.2
 
 ### Patch Changes

package/dist/index.browser.d.ts

@@ -1,4 +1,4 @@
-import { SparkWallet, ConfigOptions, SparkSigner, Bech32mTokenIdentifier, WalletConfigService, ConnectionManager } from '@buildonspark/spark-sdk';
+import { Bech32mTokenIdentifier, SparkWallet, ConfigOptions, SparkSigner, WalletConfigService, ConnectionManager } from '@buildonspark/spark-sdk';
 export { AggregateFrostParams, ConfigOptions, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService } from '@buildonspark/spark-sdk';
 import { OutputWithPreviousTransactionData } from '@buildonspark/spark-sdk/proto/spark_token';
 
@@ -40,6 +40,8 @@ type IssuerTokenMetadata = {
     isFreezable: boolean;
     /** Extra metadata of the token */
     extraMetadata?: Uint8Array;
+    /** Bech32m encoded token identifier */
+    bech32mTokenIdentifier: Bech32mTokenIdentifier;
 };
 interface TokenDistribution {
     totalCirculatingSupply: bigint;
@@ -48,6 +50,26 @@ interface TokenDistribution {
     numHoldingAddress: number;
     numConfirmedTransactions: bigint;
 }
+/**
+ * Details of a token creation.
+ *
+ * tokenIdentifier: The Bech32m encoded token identifier.
+ * transactionHash: The hash of the transaction that created the token.
+ *
+ * @example
+ * ```typescript
+ * const tokenCreationDetails: TokenCreationDetails = {
+ *   tokenIdentifier: "btkn1...",
+ *   transactionHash: "1234567890abcdef...",
+ * };
+ * ```
+ */
+interface TokenCreationDetails {
+    /** Bech32m encoded token identifier */
+    tokenIdentifier: Bech32mTokenIdentifier;
+    /** Transaction hash of the announcement */
+    transactionHash: string;
+}
 
 /**
  * Represents a Spark wallet with minting capabilities.
@@ -65,24 +87,51 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     constructor(configOptions?: ConfigOptions, signer?: SparkSigner);
     /**
      * 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
      */
     getIssuerTokenBalance(): Promise<{
         tokenIdentifier: Bech32mTokenIdentifier | undefined;
         balance: bigint;
     }>;
+    /**
+     * Gets the token balances for the tokens that were issued by this user.
+     * @returns An array of objects containing the token identifier and balance
+     */
+    getIssuerTokenBalances(): Promise<{
+        tokenIdentifier: Bech32mTokenIdentifier | undefined;
+        balance: bigint;
+    }[]>;
     /**
      * 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
      */
     getIssuerTokenMetadata(): Promise<IssuerTokenMetadata>;
+    /**
+     * 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
+     */
+    getIssuerTokensMetadata(): Promise<IssuerTokenMetadata[]>;
     /**
      * 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
      */
     getIssuerTokenIdentifier(): Promise<Bech32mTokenIdentifier>;
+    /**
+     * 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
+     */
+    getIssuerTokenIdentifiers(): Promise<Bech32mTokenIdentifier[]>;
     /**
      * Create a new token on Spark.
      *
@@ -93,51 +142,126 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
      * @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.
-     *
+     * @param params.returnIdentifierForCreate - (Optional) Whether to return the token identifier in addition to the transaction hash. Defaults to <code>false</code>.
+     * @returns The transaction hash of the announcement or TokenCreationDetails if `returnIdentifierForCreate` is true.
      * @throws {SparkValidationError} If `decimals` is not a safe integer or other validation fails.
      * @throws {SparkRequestError} If the announcement transaction cannot be broadcast.
      */
-    createToken({ tokenName, tokenTicker, decimals, isFreezable, maxSupply, extraMetadata, }: {
+    createToken(params: {
         tokenName: string;
         tokenTicker: string;
         decimals: number;
         isFreezable: boolean;
         maxSupply?: bigint;
         extraMetadata?: Uint8Array;
+        returnIdentifierForCreate?: false;
     }): Promise<string>;
+    createToken(params: {
+        tokenName: string;
+        tokenTicker: string;
+        decimals: number;
+        isFreezable: boolean;
+        maxSupply?: bigint;
+        extraMetadata?: Uint8Array;
+        returnIdentifierForCreate: true;
+    }): Promise<TokenCreationDetails>;
+    /**
+     * @deprecated Use mintTokens({ tokenAmount, tokenIdentifier }) instead. This method will be removed in a future version.
+     * @param amount - The amount of tokens to mint
+     * @returns The transaction ID of the mint operation
+     * @throws {SparkValidationError} If multiple tokens are found for this issuer
+     * @throws {SparkValidationError} If no tokens are found for this issuer
+     */
+    mintTokens(amount: bigint): Promise<string>;
     /**
      * Mints new tokens
-     * @param tokenAmount - The amount of tokens to mint
+     * @param params - Object containing token minting parameters.
+     * @param params.tokenAmount - The amount of tokens to mint
+     * @param params.tokenIdentifier - The bech32m encoded token identifier
      * @returns The transaction ID of the mint operation
+     * @throws {SparkValidationError} If no tokens are found for this issuer
      */
-    mintTokens(tokenAmount: bigint): Promise<string>;
+    mintTokens({ tokenAmount, tokenIdentifier, }: {
+        tokenAmount: bigint;
+        tokenIdentifier?: Bech32mTokenIdentifier;
+    }): Promise<string>;
     /**
      * Burns issuer's tokens
+     * @deprecated Use burnTokens({ tokenAmount, tokenIdentifier, selectedOutputs }) instead. This method will be removed in a future version.
      * @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
+     * @throws {SparkValidationError} If multiple tokens are found for this issuer
+     * @throws {SparkValidationError} If no tokens are found for this issuer
      */
     burnTokens(tokenAmount: bigint, selectedOutputs?: OutputWithPreviousTransactionData[]): Promise<string>;
+    /**
+     * Burns issuer's tokens
+     * @param params - Object containing token burning parameters.
+     * @param params.tokenAmount - The amount of tokens to burn
+     * @param params.tokenIdentifier - The bech32m encoded token identifier
+     * @param params.selectedOutputs - Optional array of outputs to use for the burn operation
+     * @returns The transaction ID of the burn operation
+     */
+    burnTokens({ tokenAmount, tokenIdentifier, selectedOutputs, }: {
+        tokenAmount: bigint;
+        tokenIdentifier?: Bech32mTokenIdentifier;
+        selectedOutputs?: OutputWithPreviousTransactionData[];
+    }): Promise<string>;
     /**
      * Freezes tokens associated with a specific Spark address.
+     * @deprecated Use freezeToken({ tokenIdentifier, sparkAddress }) instead. This method will be removed in a future version.
      * @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
+     * @throws {SparkValidationError} If multiple tokens are found for this issuer
+     * @throws {SparkValidationError} If no tokens are found for this issuer
      */
     freezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * Freezes tokens associated with a specific Spark address.
+     * @param params - Object containing token freezing parameters.
+     * @param params.tokenIdentifier - The bech32m encoded token identifier
+     * @param params.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
+     */
+    freezeTokens({ tokenIdentifier, sparkAddress, }: {
+        tokenIdentifier: Bech32mTokenIdentifier;
+        sparkAddress: string;
+    }): Promise<{
+        impactedOutputIds: string[];
+        impactedTokenAmount: bigint;
+    }>;
     /**
      * Unfreezes previously frozen tokens associated with a specific Spark address.
+     * @deprecated Use unfreezeToken({ tokenIdentifier, sparkAddress }) instead. This method will be removed in a future version.
      * @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
+     * @throws {SparkValidationError} If multiple tokens are found for this issuer
+     * @throws {SparkValidationError} If no tokens are found for this issuer
      */
     unfreezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * Unfreezes previously frozen tokens associated with a specific Spark address.
+     * @param params - Object containing token unfreezing parameters.
+     * @param params.tokenIdentifier - The bech32m encoded token identifier
+     * @param params.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
+     * @throws {SparkValidationError} If multiple tokens are found for this issuer
+     * @throws {SparkValidationError} If no tokens are found for this issuer
+     */
+    unfreezeTokens({ tokenIdentifier, sparkAddress, }: {
+        tokenIdentifier: Bech32mTokenIdentifier;
+        sparkAddress: string;
+    }): Promise<{
+        impactedOutputIds: string[];
+        impactedTokenAmount: bigint;
+    }>;
     /**
      * Retrieves the distribution information for the issuer's token.
      * @throws {SparkError} This feature is not yet supported
@@ -152,4 +276,4 @@ declare class IssuerSparkWalletBrowser extends IssuerSparkWallet {
     protected buildConnectionManager(config: WalletConfigService): ConnectionManager;
 }
 
-export { IssuerSparkWalletBrowser as IssuerSparkWallet, type IssuerTokenMetadata, type TokenDistribution };
+export { IssuerSparkWalletBrowser as IssuerSparkWallet, type IssuerTokenMetadata, type TokenCreationDetails, type TokenDistribution };