@buildonspark/issuer-sdk 0.1.2 → 0.1.4

package/dist/index.node.d.cts

@@ -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
@@ -153,4 +277,4 @@ declare class IssuerSparkWalletNodeJS extends IssuerSparkWallet {
     protected initializeTracerEnv({ spanProcessors, traceUrls, }: Parameters<IssuerSparkWallet["initializeTracerEnv"]>[0]): void;
 }
 
-export { IssuerSparkWalletNodeJS as IssuerSparkWallet, type IssuerTokenMetadata, type TokenDistribution };
+export { IssuerSparkWalletNodeJS as IssuerSparkWallet, type IssuerTokenMetadata, type TokenCreationDetails, type TokenDistribution };

package/dist/index.node.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
@@ -153,4 +277,4 @@ declare class IssuerSparkWalletNodeJS extends IssuerSparkWallet {
     protected initializeTracerEnv({ spanProcessors, traceUrls, }: Parameters<IssuerSparkWallet["initializeTracerEnv"]>[0]): void;
 }
 
-export { IssuerSparkWalletNodeJS as IssuerSparkWallet, type IssuerTokenMetadata, type TokenDistribution };
+export { IssuerSparkWalletNodeJS as IssuerSparkWallet, type IssuerTokenMetadata, type TokenCreationDetails, type TokenDistribution };