@buildonspark/issuer-sdk 0.0.41 → 0.0.43

package/dist/index.cjs

@@ -345,6 +345,11 @@ var BURN_ADDRESS = "02".repeat(33);
 var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.SparkWallet {
   issuerTokenTransactionService;
   tokenFreezeService;
+  /**
+   * Initializes a new IssuerSparkWallet instance.
+   * @param options - Configuration options for the wallet
+   * @returns An object containing the initialized wallet and initialization response
+   */
   static async initialize(options) {
     const wallet = new _IssuerSparkWallet(options.options);
     const initResponse = await wallet.initWallet(options.mnemonicOrSeed);
@@ -364,6 +369,10 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       this.connectionManager
     );
   }
+  /**
+   * Gets the token balance for the issuer's token.
+   * @returns An object containing the token balance as a bigint
+   */
   async getIssuerTokenBalance() {
     const publicKey = await super.getIdentityPublicKey();
     const balanceObj = await this.getBalance();
@@ -376,6 +385,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       balance: balanceObj.tokenBalances.get(publicKey).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
+   * @throws {NetworkError} If the token info cannot be retrieved
+   */
   async getIssuerTokenInfo() {
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
     try {
@@ -399,6 +413,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       });
     }
   }
+  /**
+   * Mints new tokens
+   * @param tokenAmount - The amount of tokens to mint
+   * @returns The transaction ID of the mint operation
+   */
   async mintTokens(tokenAmount) {
     var tokenPublicKey = await super.getIdentityPublicKey();
     const tokenTransaction = await this.issuerTokenTransactionService.constructMintTokenTransaction(
@@ -409,6 +428,12 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       tokenTransaction
     );
   }
+  /**
+   * 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) {
     const burnAddress = (0, import_address.encodeSparkAddress)({
       identityPublicKey: BURN_ADDRESS,
@@ -421,6 +446,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       selectedOutputs
     });
   }
+  /**
+   * 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();
     const tokenPublicKey = await super.getIdentityPublicKey();
@@ -438,6 +468,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       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();
     const tokenPublicKey = await super.getIdentityPublicKey();
@@ -455,7 +490,25 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       impactedTokenAmount: tokenAmount
     };
   }
+  /**
+   * Retrieves the activity history for the issuer's token.
+   * @param pageSize - The number of transactions to return per page (default: 100)
+   * @param cursor - Optional cursor for pagination
+   * @param operationTypes - Optional array of operation types to filter by
+   * @param beforeTimestamp - Optional timestamp to filter transactions before
+   * @param afterTimestamp - Optional timestamp to filter transactions after
+   * @returns An object containing the token activity data
+   * @throws {ValidationError} If pageSize is not a safe integer
+   * @throws {NetworkError} If the activity data cannot be retrieved
+   */
   async getIssuerTokenActivity(pageSize = 100, cursor, operationTypes, beforeTimestamp, afterTimestamp) {
+    if (!Number.isSafeInteger(pageSize)) {
+      throw new import_spark_sdk3.ValidationError("pageSize must be less than 2^53", {
+        field: "pageSize",
+        value: pageSize,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER
+      });
+    }
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
     try {
       const transactions = await lrc20Client.listTransactions({
@@ -475,10 +528,33 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends import_spark_sdk3.Spark
       });
     }
   }
+  /**
+   * Retrieves the distribution information for the issuer's token.
+   * @throws {NotImplementedError} This feature is not yet supported
+   */
   async getIssuerTokenDistribution() {
     throw new import_spark_sdk4.NotImplementedError("Token distribution is not yet supported");
   }
+  /**
+   * Announces a new token on the L1 (Bitcoin) network.
+   * @param tokenName - The name of the token
+   * @param tokenTicker - The ticker symbol for the token
+   * @param decimals - The number of decimal places for the token
+   * @param maxSupply - The maximum supply of the token
+   * @param isFreezable - Whether the token can be frozen
+   * @param feeRateSatsPerVb - The fee rate in satoshis per virtual byte (default: 4.0)
+   * @returns The transaction ID of the announcement
+   * @throws {ValidationError} If decimals is not a safe integer
+   * @throws {NetworkError} If the announcement transaction cannot be broadcast
+   */
   async announceTokenL1(tokenName, tokenTicker, decimals, maxSupply, isFreezable, feeRateSatsPerVb = 4) {
+    if (!Number.isSafeInteger(decimals)) {
+      throw new import_spark_sdk3.ValidationError("Decimals must be less than 2^53", {
+        field: "decimals",
+        value: decimals,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER
+      });
+    }
     await this.lrc20Wallet.syncWallet();
     const tokenPublicKey = new import_lrc20_sdk2.TokenPubkey(this.lrc20Wallet.pubkey);
     const announcement = new import_lrc20_sdk2.TokenPubkeyAnnouncement(

package/dist/index.d.cts

@@ -12,30 +12,97 @@ type IssuerTokenInfo = {
     maxSupply: bigint;
     isFreezable: boolean;
 };
+/**
+ * Represents a Spark wallet with minting capabilities.
+ * This class extends the base SparkWallet with additional functionality for token minting,
+ * burning, and freezing operations.
+ */
 declare class IssuerSparkWallet extends SparkWallet {
     private issuerTokenTransactionService;
     private tokenFreezeService;
+    /**
+     * Initializes a new IssuerSparkWallet instance.
+     * @param options - Configuration options for the wallet
+     * @returns An object containing the initialized wallet and initialization response
+     */
     static initialize(options: SparkWalletProps): Promise<{
         mnemonic?: string | undefined;
         wallet: IssuerSparkWallet;
     }>;
     protected constructor(configOptions?: ConfigOptions);
+    /**
+     * Gets the token balance for the issuer's token.
+     * @returns An object containing the token balance as a bigint
+     */
     getIssuerTokenBalance(): Promise<{
         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
+     * @throws {NetworkError} If the token info cannot be retrieved
+     */
     getIssuerTokenInfo(): Promise<IssuerTokenInfo | null>;
+    /**
+     * Mints new tokens
+     * @param tokenAmount - The amount of tokens to mint
+     * @returns The transaction ID of the mint operation
+     */
     mintTokens(tokenAmount: bigint): Promise<string>;
+    /**
+     * 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
+     */
     burnTokens(tokenAmount: bigint, selectedOutputs?: OutputWithPreviousTransactionData[]): Promise<string>;
+    /**
+     * 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
+     */
     freezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * 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
+     */
     unfreezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * Retrieves the activity history for the issuer's token.
+     * @param pageSize - The number of transactions to return per page (default: 100)
+     * @param cursor - Optional cursor for pagination
+     * @param operationTypes - Optional array of operation types to filter by
+     * @param beforeTimestamp - Optional timestamp to filter transactions before
+     * @param afterTimestamp - Optional timestamp to filter transactions after
+     * @returns An object containing the token activity data
+     * @throws {ValidationError} If pageSize is not a safe integer
+     * @throws {NetworkError} If the activity data cannot be retrieved
+     */
     getIssuerTokenActivity(pageSize?: number, cursor?: ListAllTokenTransactionsCursor, operationTypes?: OperationType[], beforeTimestamp?: Date, afterTimestamp?: Date): Promise<GetTokenActivityResponse>;
+    /**
+     * Retrieves the distribution information for the issuer's token.
+     * @throws {NotImplementedError} This feature is not yet supported
+     */
     getIssuerTokenDistribution(): Promise<TokenDistribution>;
+    /**
+     * Announces a new token on the L1 (Bitcoin) network.
+     * @param tokenName - The name of the token
+     * @param tokenTicker - The ticker symbol for the token
+     * @param decimals - The number of decimal places for the token
+     * @param maxSupply - The maximum supply of the token
+     * @param isFreezable - Whether the token can be frozen
+     * @param feeRateSatsPerVb - The fee rate in satoshis per virtual byte (default: 4.0)
+     * @returns The transaction ID of the announcement
+     * @throws {ValidationError} If decimals is not a safe integer
+     * @throws {NetworkError} If the announcement transaction cannot be broadcast
+     */
     announceTokenL1(tokenName: string, tokenTicker: string, decimals: number, maxSupply: bigint, isFreezable: boolean, feeRateSatsPerVb?: number): Promise<string>;
 }
 

package/dist/index.d.ts

@@ -12,30 +12,97 @@ type IssuerTokenInfo = {
     maxSupply: bigint;
     isFreezable: boolean;
 };
+/**
+ * Represents a Spark wallet with minting capabilities.
+ * This class extends the base SparkWallet with additional functionality for token minting,
+ * burning, and freezing operations.
+ */
 declare class IssuerSparkWallet extends SparkWallet {
     private issuerTokenTransactionService;
     private tokenFreezeService;
+    /**
+     * Initializes a new IssuerSparkWallet instance.
+     * @param options - Configuration options for the wallet
+     * @returns An object containing the initialized wallet and initialization response
+     */
     static initialize(options: SparkWalletProps): Promise<{
         mnemonic?: string | undefined;
         wallet: IssuerSparkWallet;
     }>;
     protected constructor(configOptions?: ConfigOptions);
+    /**
+     * Gets the token balance for the issuer's token.
+     * @returns An object containing the token balance as a bigint
+     */
     getIssuerTokenBalance(): Promise<{
         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
+     * @throws {NetworkError} If the token info cannot be retrieved
+     */
     getIssuerTokenInfo(): Promise<IssuerTokenInfo | null>;
+    /**
+     * Mints new tokens
+     * @param tokenAmount - The amount of tokens to mint
+     * @returns The transaction ID of the mint operation
+     */
     mintTokens(tokenAmount: bigint): Promise<string>;
+    /**
+     * 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
+     */
     burnTokens(tokenAmount: bigint, selectedOutputs?: OutputWithPreviousTransactionData[]): Promise<string>;
+    /**
+     * 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
+     */
     freezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * 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
+     */
     unfreezeTokens(sparkAddress: string): Promise<{
         impactedOutputIds: string[];
         impactedTokenAmount: bigint;
     }>;
+    /**
+     * Retrieves the activity history for the issuer's token.
+     * @param pageSize - The number of transactions to return per page (default: 100)
+     * @param cursor - Optional cursor for pagination
+     * @param operationTypes - Optional array of operation types to filter by
+     * @param beforeTimestamp - Optional timestamp to filter transactions before
+     * @param afterTimestamp - Optional timestamp to filter transactions after
+     * @returns An object containing the token activity data
+     * @throws {ValidationError} If pageSize is not a safe integer
+     * @throws {NetworkError} If the activity data cannot be retrieved
+     */
     getIssuerTokenActivity(pageSize?: number, cursor?: ListAllTokenTransactionsCursor, operationTypes?: OperationType[], beforeTimestamp?: Date, afterTimestamp?: Date): Promise<GetTokenActivityResponse>;
+    /**
+     * Retrieves the distribution information for the issuer's token.
+     * @throws {NotImplementedError} This feature is not yet supported
+     */
     getIssuerTokenDistribution(): Promise<TokenDistribution>;
+    /**
+     * Announces a new token on the L1 (Bitcoin) network.
+     * @param tokenName - The name of the token
+     * @param tokenTicker - The ticker symbol for the token
+     * @param decimals - The number of decimal places for the token
+     * @param maxSupply - The maximum supply of the token
+     * @param isFreezable - Whether the token can be frozen
+     * @param feeRateSatsPerVb - The fee rate in satoshis per virtual byte (default: 4.0)
+     * @returns The transaction ID of the announcement
+     * @throws {ValidationError} If decimals is not a safe integer
+     * @throws {NetworkError} If the announcement transaction cannot be broadcast
+     */
     announceTokenL1(tokenName: string, tokenTicker: string, decimals: number, maxSupply: bigint, isFreezable: boolean, feeRateSatsPerVb?: number): Promise<string>;
 }
 

package/dist/index.js

@@ -4,7 +4,8 @@ import "./chunk-GB7N6I5O.js";
 import { TokenPubkey, TokenPubkeyAnnouncement } from "@buildonspark/lrc20-sdk";
 import {
   NetworkError as NetworkError2,
-  SparkWallet
+  SparkWallet,
+  ValidationError as ValidationError2
 } from "@buildonspark/spark-sdk";
 import {
   decodeSparkAddress,
@@ -322,6 +323,11 @@ var BURN_ADDRESS = "02".repeat(33);
 var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
   issuerTokenTransactionService;
   tokenFreezeService;
+  /**
+   * Initializes a new IssuerSparkWallet instance.
+   * @param options - Configuration options for the wallet
+   * @returns An object containing the initialized wallet and initialization response
+   */
   static async initialize(options) {
     const wallet = new _IssuerSparkWallet(options.options);
     const initResponse = await wallet.initWallet(options.mnemonicOrSeed);
@@ -341,6 +347,10 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       this.connectionManager
     );
   }
+  /**
+   * Gets the token balance for the issuer's token.
+   * @returns An object containing the token balance as a bigint
+   */
   async getIssuerTokenBalance() {
     const publicKey = await super.getIdentityPublicKey();
     const balanceObj = await this.getBalance();
@@ -353,6 +363,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       balance: balanceObj.tokenBalances.get(publicKey).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
+   * @throws {NetworkError} If the token info cannot be retrieved
+   */
   async getIssuerTokenInfo() {
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
     try {
@@ -376,6 +391,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       });
     }
   }
+  /**
+   * Mints new tokens
+   * @param tokenAmount - The amount of tokens to mint
+   * @returns The transaction ID of the mint operation
+   */
   async mintTokens(tokenAmount) {
     var tokenPublicKey = await super.getIdentityPublicKey();
     const tokenTransaction = await this.issuerTokenTransactionService.constructMintTokenTransaction(
@@ -386,6 +406,12 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       tokenTransaction
     );
   }
+  /**
+   * 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) {
     const burnAddress = encodeSparkAddress({
       identityPublicKey: BURN_ADDRESS,
@@ -398,6 +424,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       selectedOutputs
     });
   }
+  /**
+   * 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();
     const tokenPublicKey = await super.getIdentityPublicKey();
@@ -415,6 +446,11 @@ var IssuerSparkWallet = class _IssuerSparkWallet 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();
     const tokenPublicKey = await super.getIdentityPublicKey();
@@ -432,7 +468,25 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       impactedTokenAmount: tokenAmount
     };
   }
+  /**
+   * Retrieves the activity history for the issuer's token.
+   * @param pageSize - The number of transactions to return per page (default: 100)
+   * @param cursor - Optional cursor for pagination
+   * @param operationTypes - Optional array of operation types to filter by
+   * @param beforeTimestamp - Optional timestamp to filter transactions before
+   * @param afterTimestamp - Optional timestamp to filter transactions after
+   * @returns An object containing the token activity data
+   * @throws {ValidationError} If pageSize is not a safe integer
+   * @throws {NetworkError} If the activity data cannot be retrieved
+   */
   async getIssuerTokenActivity(pageSize = 100, cursor, operationTypes, beforeTimestamp, afterTimestamp) {
+    if (!Number.isSafeInteger(pageSize)) {
+      throw new ValidationError2("pageSize must be less than 2^53", {
+        field: "pageSize",
+        value: pageSize,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER
+      });
+    }
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
     try {
       const transactions = await lrc20Client.listTransactions({
@@ -452,10 +506,33 @@ var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
       });
     }
   }
+  /**
+   * Retrieves the distribution information for the issuer's token.
+   * @throws {NotImplementedError} This feature is not yet supported
+   */
   async getIssuerTokenDistribution() {
     throw new NotImplementedError("Token distribution is not yet supported");
   }
+  /**
+   * Announces a new token on the L1 (Bitcoin) network.
+   * @param tokenName - The name of the token
+   * @param tokenTicker - The ticker symbol for the token
+   * @param decimals - The number of decimal places for the token
+   * @param maxSupply - The maximum supply of the token
+   * @param isFreezable - Whether the token can be frozen
+   * @param feeRateSatsPerVb - The fee rate in satoshis per virtual byte (default: 4.0)
+   * @returns The transaction ID of the announcement
+   * @throws {ValidationError} If decimals is not a safe integer
+   * @throws {NetworkError} If the announcement transaction cannot be broadcast
+   */
   async announceTokenL1(tokenName, tokenTicker, decimals, maxSupply, isFreezable, feeRateSatsPerVb = 4) {
+    if (!Number.isSafeInteger(decimals)) {
+      throw new ValidationError2("Decimals must be less than 2^53", {
+        field: "decimals",
+        value: decimals,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER
+      });
+    }
     await this.lrc20Wallet.syncWallet();
     const tokenPublicKey = new TokenPubkey(this.lrc20Wallet.pubkey);
     const announcement = new TokenPubkeyAnnouncement(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildonspark/issuer-sdk",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Spark Issuer SDK for token issuance",
   "license": "Apache-2.0",
   "module": "./dist/index.js",
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.5",
-    "@buildonspark/lrc20-sdk": "0.0.38",
-    "@buildonspark/spark-sdk": "0.1.10",
+    "@buildonspark/lrc20-sdk": "0.0.40",
+    "@buildonspark/spark-sdk": "0.1.12",
     "@noble/curves": "^1.8.0",
     "@scure/btc-signer": "^1.5.0",
     "bitcoinjs-lib": "^6.1.5",

package/src/issuer-spark-wallet.ts

@@ -7,6 +7,7 @@ import {
   NetworkError,
   SparkWallet,
   SparkWalletProps,
+  ValidationError,
 } from "@buildonspark/spark-sdk";
 import {
   decodeSparkAddress,
@@ -36,10 +37,20 @@ export type IssuerTokenInfo = {
   isFreezable: boolean;
 };
 
+/**
+ * Represents a Spark wallet with minting capabilities.
+ * This class extends the base SparkWallet with additional functionality for token minting,
+ * burning, and freezing operations.
+ */
 export class IssuerSparkWallet extends SparkWallet {
   private issuerTokenTransactionService: IssuerTokenTransactionService;
   private tokenFreezeService: TokenFreezeService;
 
+  /**
+   * Initializes a new IssuerSparkWallet instance.
+   * @param options - Configuration options for the wallet
+   * @returns An object containing the initialized wallet and initialization response
+   */
   public static async initialize(options: SparkWalletProps) {
     const wallet = new IssuerSparkWallet(options.options);
 
@@ -62,6 +73,10 @@ export class IssuerSparkWallet extends SparkWallet {
     );
   }
 
+  /**
+   * Gets the token balance for the issuer's token.
+   * @returns An object containing the token balance as a bigint
+   */
   public async getIssuerTokenBalance(): Promise<{
     balance: bigint;
   }> {
@@ -78,6 +93,11 @@ export class IssuerSparkWallet extends SparkWallet {
     };
   }
 
+  /**
+   * Retrieves information about the issuer's token.
+   * @returns An object containing token information including public key, name, symbol, decimals, max supply, and freeze status
+   * @throws {NetworkError} If the token info cannot be retrieved
+   */
   public async getIssuerTokenInfo(): Promise<IssuerTokenInfo | null> {
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
 
@@ -104,6 +124,11 @@ export class IssuerSparkWallet extends SparkWallet {
     }
   }
 
+  /**
+   * Mints new tokens
+   * @param tokenAmount - The amount of tokens to mint
+   * @returns The transaction ID of the mint operation
+   */
   public async mintTokens(tokenAmount: bigint): Promise<string> {
     var tokenPublicKey = await super.getIdentityPublicKey();
 
@@ -118,6 +143,12 @@ export class IssuerSparkWallet 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
+   */
   public async burnTokens(
     tokenAmount: bigint,
     selectedOutputs?: OutputWithPreviousTransactionData[],
@@ -134,6 +165,11 @@ export class IssuerSparkWallet extends SparkWallet {
     });
   }
 
+  /**
+   * 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
+   */
   public async freezeTokens(
     sparkAddress: string,
   ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }> {
@@ -157,6 +193,11 @@ export class IssuerSparkWallet extends SparkWallet {
     };
   }
 
+  /**
+   * 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
+   */
   public async unfreezeTokens(
     sparkAddress: string,
   ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }> {
@@ -178,6 +219,17 @@ export class IssuerSparkWallet extends SparkWallet {
     };
   }
 
+  /**
+   * Retrieves the activity history for the issuer's token.
+   * @param pageSize - The number of transactions to return per page (default: 100)
+   * @param cursor - Optional cursor for pagination
+   * @param operationTypes - Optional array of operation types to filter by
+   * @param beforeTimestamp - Optional timestamp to filter transactions before
+   * @param afterTimestamp - Optional timestamp to filter transactions after
+   * @returns An object containing the token activity data
+   * @throws {ValidationError} If pageSize is not a safe integer
+   * @throws {NetworkError} If the activity data cannot be retrieved
+   */
   public async getIssuerTokenActivity(
     pageSize: number = 100,
     cursor?: ListAllTokenTransactionsCursor,
@@ -185,6 +237,14 @@ export class IssuerSparkWallet extends SparkWallet {
     beforeTimestamp?: Date,
     afterTimestamp?: Date,
   ): Promise<GetTokenActivityResponse> {
+    if (!Number.isSafeInteger(pageSize)) {
+      throw new ValidationError("pageSize must be less than 2^53", {
+        field: "pageSize",
+        value: pageSize,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER,
+      });
+    }
+
     const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
 
     try {
@@ -207,10 +267,26 @@ export class IssuerSparkWallet extends SparkWallet {
     }
   }
 
+  /**
+   * Retrieves the distribution information for the issuer's token.
+   * @throws {NotImplementedError} This feature is not yet supported
+   */
   public async getIssuerTokenDistribution(): Promise<TokenDistribution> {
     throw new NotImplementedError("Token distribution is not yet supported");
   }
 
+  /**
+   * Announces a new token on the L1 (Bitcoin) network.
+   * @param tokenName - The name of the token
+   * @param tokenTicker - The ticker symbol for the token
+   * @param decimals - The number of decimal places for the token
+   * @param maxSupply - The maximum supply of the token
+   * @param isFreezable - Whether the token can be frozen
+   * @param feeRateSatsPerVb - The fee rate in satoshis per virtual byte (default: 4.0)
+   * @returns The transaction ID of the announcement
+   * @throws {ValidationError} If decimals is not a safe integer
+   * @throws {NetworkError} If the announcement transaction cannot be broadcast
+   */
   public async announceTokenL1(
     tokenName: string,
     tokenTicker: string,
@@ -219,8 +295,15 @@ export class IssuerSparkWallet extends SparkWallet {
     isFreezable: boolean,
     feeRateSatsPerVb: number = 4.0,
   ): Promise<string> {
-    await this.lrc20Wallet!.syncWallet();
+    if (!Number.isSafeInteger(decimals)) {
+      throw new ValidationError("Decimals must be less than 2^53", {
+        field: "decimals",
+        value: decimals,
+        expected: "smaller or equal to " + Number.MAX_SAFE_INTEGER,
+      });
+    }
 
+    await this.lrc20Wallet!.syncWallet();
     const tokenPublicKey = new TokenPubkey(this.lrc20Wallet!.pubkey);
 
     const announcement = new TokenPubkeyAnnouncement(

package/src/tests/integration/spark.test.ts

@@ -30,13 +30,34 @@ describe("token integration tests", () => {
     },
   );
 
+  brokenTestFn(
+    "should fail when announce decimal is greater than 2^53",
+    async () => {
+      const tokenAmount: bigint = 1000n;
+      const { wallet } = await IssuerSparkWalletTesting.initialize({
+        options: LOCAL_WALLET_CONFIG_ECDSA,
+      });
+
+      await expect(
+        await fundAndAnnounce(
+          wallet,
+          tokenAmount,
+          2 ** 53,
+          "TestToken",
+          "TT1",
+          false,
+        ),
+      ).rejects.toThrow();
+    },
+  );
+
   brokenTestFn("should fail when minting more than max supply", async () => {
     const tokenAmount: bigint = 1000n;
     const { wallet } = await IssuerSparkWalletTesting.initialize({
       options: LOCAL_WALLET_CONFIG_SCHNORR,
     });
 
-    await fundAndAnnounce(wallet, 2n, "MaxSupplyToken", "MST");
+    await fundAndAnnounce(wallet, 2n, 0, "MaxSupplyToken", "MST");
     await expect(wallet.mintTokens(tokenAmount)).rejects.toThrow();
   });
 
@@ -50,7 +71,7 @@ describe("token integration tests", () => {
         options: LOCAL_WALLET_CONFIG_SCHNORR,
       });
 
-      await fundAndAnnounce(wallet, 100000n, tokenName, tokenSymbol);
+      await fundAndAnnounce(wallet, 100000n, 0, tokenName, tokenSymbol);
 
       const publicKeyInfo = await wallet.getIssuerTokenInfo();
 
@@ -95,7 +116,13 @@ describe("token integration tests", () => {
         },
       );
 
-      await fundAndAnnounce(issuerWallet, 100000n, "ECDSATransferToken", "ETT");
+      await fundAndAnnounce(
+        issuerWallet,
+        100000n,
+        0,
+        "ECDSATransferToken",
+        "ETT",
+      );
 
       await issuerWallet.mintTokens(tokenAmount);
       await issuerWallet.transferTokens({
@@ -128,7 +155,7 @@ describe("token integration tests", () => {
       options: LOCAL_WALLET_CONFIG_ECDSA,
     });
 
-    await fundAndAnnounce(issuerWallet, 100000n, "MonitoringToken", "MOT");
+    await fundAndAnnounce(issuerWallet, 100000n, 0, "MonitoringToken", "MOT");
 
     await issuerWallet.mintTokens(tokenAmount);
     await issuerWallet.transferTokens({
@@ -175,6 +202,7 @@ describe("token integration tests", () => {
       await fundAndAnnounce(
         issuerWallet,
         100000n,
+        0,
         "SchnorrTransferToken",
         "STT",
       );
@@ -207,7 +235,13 @@ describe("token integration tests", () => {
           options: LOCAL_WALLET_CONFIG_ECDSA,
         });
 
-      await fundAndAnnounce(issuerWallet, 100000n, "ECDSAFreezeToken", "EFT");
+      await fundAndAnnounce(
+        issuerWallet,
+        100000n,
+        0,
+        "ECDSAFreezeToken",
+        "EFT",
+      );
       await issuerWallet.mintTokens(tokenAmount);
 
       // Check issuer balance after minting
@@ -261,7 +295,13 @@ describe("token integration tests", () => {
           options: LOCAL_WALLET_CONFIG_SCHNORR,
         });
 
-      await fundAndAnnounce(issuerWallet, 100000n, "SchnorrFreezeToken", "SFT");
+      await fundAndAnnounce(
+        issuerWallet,
+        100000n,
+        0,
+        "SchnorrFreezeToken",
+        "SFT",
+      );
 
       await issuerWallet.mintTokens(tokenAmount);
 
@@ -315,7 +355,7 @@ describe("token integration tests", () => {
           options: LOCAL_WALLET_CONFIG_ECDSA,
         });
 
-      await fundAndAnnounce(issuerWallet, 100000n, "ECDSABurnToken", "EBT");
+      await fundAndAnnounce(issuerWallet, 100000n, 0, "ECDSABurnToken", "EBT");
       await issuerWallet.mintTokens(tokenAmount);
 
       const issuerTokenBalance = (await issuerWallet.getIssuerTokenBalance())
@@ -340,7 +380,13 @@ describe("token integration tests", () => {
           options: LOCAL_WALLET_CONFIG_SCHNORR,
         });
 
-      await fundAndAnnounce(issuerWallet, 100000n, "SchnorrBurnToken", "SBT");
+      await fundAndAnnounce(
+        issuerWallet,
+        100000n,
+        0,
+        "SchnorrBurnToken",
+        "SBT",
+      );
       await issuerWallet.mintTokens(tokenAmount);
 
       const issuerTokenBalance = (await issuerWallet.getIssuerTokenBalance())
@@ -373,8 +419,10 @@ describe("token integration tests", () => {
       await fundAndAnnounce(
         issuerWallet,
         100000n,
+        0,
         "ECDSAFullCycleToken",
         "EFCT",
+        false,
       );
       await issuerWallet.mintTokens(tokenAmount);
 
@@ -445,6 +493,7 @@ describe("token integration tests", () => {
       await fundAndAnnounce(
         issuerWallet,
         100000n,
+        0,
         "SchnorrFullCycleToken",
         "SFCT",
       );
@@ -506,8 +555,10 @@ describe("token integration tests", () => {
 async function fundAndAnnounce(
   wallet: IssuerSparkWallet,
   maxSupply: bigint = 100000n,
+  decimals: number = 0,
   tokenName: string = "TestToken1",
   tokenSymbol: string = "TT1",
+  isFreezable: boolean = false,
 ) {
   // Faucet funds to the Issuer wallet because announcing a token
   // requires ownership of an L1 UTXO.
@@ -522,9 +573,9 @@ async function fundAndAnnounce(
     const response = await wallet.announceTokenL1(
       tokenName,
       tokenSymbol,
-      0,
+      decimals,
       maxSupply,
-      false,
+      isFreezable,
     );
     console.log("Announce token response:", response);
   } catch (error: any) {