@buildonspark/issuer-sdk 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @buildonspark/issuer-sdk
 
+## 0.1.9
+
+### Patch Changes
+
+- - Freeze/Unfreeze Return Type Change: freezeTokens() and unfreezeTokens() now return impactedTokenOutputs: TokenOutputRef[] instead of impactedOutputIds: string[]. This provides richer output information including the token ID for each affected output.
+- Updated dependencies
+  - @buildonspark/spark-sdk@0.5.9
+
+## 0.1.8
+
+### Patch Changes
+
+- Updated dependencies
+  - @buildonspark/spark-sdk@0.5.8
+
 ## 0.1.7
 
 ### Patch Changes

package/README.md

@@ -1,3 +1,128 @@
-# Welcome to Spark!
+# Spark Issuer SDK
 
-You can find our official documentation at https://docs.spark.money/issuing/introduction
+For complete documentation, visit [https://docs.spark.money](https://docs.spark.money)
+
+## Installation
+
+```bash
+npm install @buildonspark/issuer-sdk @buildonspark/spark-sdk
+# or
+yarn add @buildonspark/issuer-sdk @buildonspark/spark-sdk
+# or
+pnpm add @buildonspark/issuer-sdk @buildonspark/spark-sdk
+```
+
+## Quick Start
+
+### Initialize an Issuer Wallet
+
+```typescript
+import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";
+
+// Create a new issuer wallet (generates a new mnemonic)
+const { wallet, mnemonic } = await IssuerSparkWallet.create({
+  options: {
+    network: "MAINNET", // or "REGTEST" for testing
+  },
+});
+
+// Or initialize with an existing mnemonic
+const wallet = await IssuerSparkWallet.initialize({
+  mnemonicOrSeed: "your twelve word mnemonic phrase here ...",
+  options: {
+    network: "MAINNET",
+  },
+});
+```
+
+### Create a Token
+
+```typescript
+const token = await wallet.createToken({
+  tokenName: "My Token",
+  tokenTicker: "MTK",
+  decimals: 8,
+  maxSupply: 1000000n,
+  isFreezable: true,
+});
+
+console.log(`Token created: ${token.tokenIdentifier}`);
+```
+
+### Mint Tokens
+
+```typescript
+// Mint tokens to your own wallet
+const mintResult = await wallet.mintTokens({
+  tokenIdentifier: "spark1...",
+  tokenAmount: 10000n,
+});
+
+// To distribute tokens to others, mint first then transfer
+await wallet.mintTokens({
+  tokenIdentifier: "spark1...",
+  tokenAmount: 5000n,
+});
+
+await wallet.transferTokens({
+  tokenIdentifier: "spark1...",
+  receiverSparkAddress: "sp1q...",
+  tokenAmount: 5000n,
+});
+```
+
+### Check Issuer Token Balance
+
+```typescript
+// Get balance for all tokens you've issued
+const balances = await wallet.getIssuerTokenBalances();
+for (const [tokenId, info] of balances) {
+  console.log(`${info.tokenMetadata.tokenName}: ${info.balance}`);
+}
+```
+
+### Freeze/Unfreeze Tokens
+
+```typescript
+// Freeze tokens at a Spark address (requires isFreezable: true during creation)
+await wallet.freezeTokens({
+  tokenIdentifier: "spark1...",
+  sparkAddress: "sp1q...",
+});
+
+// Unfreeze tokens at a Spark address
+await wallet.unfreezeTokens({
+  tokenIdentifier: "spark1...",
+  sparkAddress: "sp1q...",
+});
+```
+
+### Burn Tokens
+
+```typescript
+const burnResult = await wallet.burnTokens({
+  tokenIdentifier: "spark1...",
+  tokenAmount: 1000n,
+});
+```
+
+### Query Token Transactions
+
+```typescript
+const transactions = await wallet.getTokenTransactions({
+  tokenIdentifier: "spark1...",
+  limit: 50,
+});
+
+for (const tx of transactions) {
+  console.log(`TX: ${tx.id}, Amount: ${tx.amount}`);
+}
+```
+
+## Platform Support
+
+The SDK supports multiple JavaScript runtimes:
+
+- **Browser** - Web applications with WASM crypto
+- **Node.js** - Server-side applications
+- **React Native** - Mobile applications

package/dist/index.browser.d.ts

@@ -1,5 +1,5 @@
 import { AggregateFrostParams, Bech32mTokenIdentifier, ConfigOptions, ConfigOptions as ConfigOptions$1, ConnectionManager, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SparkSigner as SparkSigner$1, SparkWallet, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService, WalletConfigService as WalletConfigService$1 } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import { OutputWithPreviousTransactionData, TokenOutputRef } from "@buildonspark/spark-sdk/proto/spark_token";
 
 //#region src/issuer-wallet/types.d.ts
 /**
@@ -218,7 +218,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   freezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -235,7 +235,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -247,7 +247,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   unfreezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -266,7 +266,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**

package/dist/index.browser.js

@@ -538,7 +538,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}
@@ -569,7 +569,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}

package/dist/index.node.cjs

@@ -538,7 +538,7 @@ var IssuerSparkWallet = class extends _buildonspark_spark_sdk.SparkWallet {
 		});
 		const tokenAmount = (0, _noble_curves_utils.bytesToNumberBE)(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}
@@ -569,7 +569,7 @@ var IssuerSparkWallet = class extends _buildonspark_spark_sdk.SparkWallet {
 		});
 		const tokenAmount = (0, _noble_curves_utils.bytesToNumberBE)(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}

package/dist/index.node.d.cts

@@ -1,5 +1,5 @@
 import { AggregateFrostParams, Bech32mTokenIdentifier, ConfigOptions, ConfigOptions as ConfigOptions$1, ConnectionManager, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SparkSigner as SparkSigner$1, SparkWallet, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService, WalletConfigService as WalletConfigService$1 } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import { OutputWithPreviousTransactionData, TokenOutputRef } from "@buildonspark/spark-sdk/proto/spark_token";
 
 //#region src/issuer-wallet/types.d.ts
 /**
@@ -218,7 +218,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   freezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -235,7 +235,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -247,7 +247,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   unfreezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -266,7 +266,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**

package/dist/index.node.d.ts

@@ -1,5 +1,5 @@
 import { AggregateFrostParams, Bech32mTokenIdentifier, ConfigOptions, ConfigOptions as ConfigOptions$1, ConnectionManager, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SparkSigner as SparkSigner$1, SparkWallet, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService, WalletConfigService as WalletConfigService$1 } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import { OutputWithPreviousTransactionData, TokenOutputRef } from "@buildonspark/spark-sdk/proto/spark_token";
 
 //#region src/issuer-wallet/types.d.ts
 /**
@@ -218,7 +218,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   freezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -235,7 +235,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -247,7 +247,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   unfreezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -266,7 +266,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**

package/dist/index.node.js

@@ -538,7 +538,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}
@@ -569,7 +569,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}

package/dist/native/index.react-native.cjs

@@ -581,7 +581,7 @@ var IssuerSparkWallet = class extends _buildonspark_spark_sdk.SparkWallet {
 		});
 		const tokenAmount = (0, _noble_curves_utils.bytesToNumberBE)(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}
@@ -612,7 +612,7 @@ var IssuerSparkWallet = class extends _buildonspark_spark_sdk.SparkWallet {
 		});
 		const tokenAmount = (0, _noble_curves_utils.bytesToNumberBE)(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}

package/dist/native/index.react-native.d.cts

@@ -1,6 +1,6 @@
 
 import { AggregateFrostParams, Bech32mTokenIdentifier, ConfigOptions, ConfigOptions as ConfigOptions$1, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SparkSigner as SparkSigner$1, SparkWallet, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import { OutputWithPreviousTransactionData, TokenOutputRef } from "@buildonspark/spark-sdk/proto/spark_token";
 
 //#region src/issuer-wallet/types.d.ts
 /**
@@ -219,7 +219,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   freezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -236,7 +236,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -248,7 +248,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   unfreezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -267,7 +267,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**

package/dist/native/index.react-native.d.ts

@@ -1,6 +1,6 @@
 
 import { AggregateFrostParams, Bech32mTokenIdentifier, ConfigOptions, ConfigOptions as ConfigOptions$1, DefaultSparkSigner, DerivedHDKey, DummyTx, IKeyPackage, KeyDerivation, KeyDerivationType, KeyPair, SignFrostParams, SigningCommitment, SigningCommitmentWithOptionalNonce, SigningNonce, SparkSigner, SparkSigner as SparkSigner$1, SparkWallet, SplitSecretWithProofsParams, SubtractSplitAndEncryptParams, SubtractSplitAndEncryptResult, UnsafeStatelessSparkSigner, WalletConfig, WalletConfigService } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import { OutputWithPreviousTransactionData, TokenOutputRef } from "@buildonspark/spark-sdk/proto/spark_token";
 
 //#region src/issuer-wallet/types.d.ts
 /**
@@ -219,7 +219,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   freezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -236,7 +236,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -248,7 +248,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
        * @throws {SparkValidationError} If no tokens are found for this issuer
        */
   unfreezeTokens(sparkAddress: string): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**
@@ -267,7 +267,7 @@ declare abstract class IssuerSparkWallet extends SparkWallet {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
   }): Promise<{
-    impactedOutputIds: string[];
+    impactedTokenOutputs: TokenOutputRef[];
     impactedTokenAmount: bigint;
   }>;
   /**

package/dist/native/index.react-native.js

@@ -581,7 +581,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}
@@ -612,7 +612,7 @@ var IssuerSparkWallet = class extends SparkWallet {
 		});
 		const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 		return {
-			impactedOutputIds: response.impactedOutputIds,
+			impactedTokenOutputs: response.impactedTokenOutputs,
 			impactedTokenAmount: tokenAmount
 		};
 	}

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@buildonspark/issuer-sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Spark Issuer SDK for token issuance",
   "license": "Apache-2.0",
+  "keywords": [
+    "bitcoin",
+    "spark",
+    "token",
+    "issuing"
+  ],
   "main": "./dist/index.browser.js",
   "types": "./dist/index.browser.d.ts",
   "module": "./dist/index.browser.js",
@@ -76,7 +82,7 @@
     "types": "tsc"
   },
   "dependencies": {
-    "@buildonspark/spark-sdk": "0.5.7",
+    "@buildonspark/spark-sdk": "0.5.9",
     "@noble/curves": "^1.8.0",
     "@scure/btc-signer": "^1.5.0",
     "buffer": "^6.0.3"

package/src/issuer-wallet/issuer-spark-wallet.ts

@@ -11,7 +11,10 @@ import {
   SparkValidationError,
   type ConfigOptions,
 } from "@buildonspark/spark-sdk";
-import { OutputWithPreviousTransactionData } from "@buildonspark/spark-sdk/proto/spark_token";
+import {
+  OutputWithPreviousTransactionData,
+  TokenOutputRef,
+} from "@buildonspark/spark-sdk/proto/spark_token";
 import { bytesToHex, bytesToNumberBE, hexToBytes } from "@noble/curves/utils";
 import { TokenFreezeService } from "../services/freeze.js";
 import { IssuerTokenTransactionService } from "../services/token-transactions.js";
@@ -633,9 +636,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
    * @throws {SparkValidationError} If multiple tokens are found for this issuer
    * @throws {SparkValidationError} If no tokens are found for this issuer
    */
-  public async freezeTokens(
-    sparkAddress: string,
-  ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }>;
+  public async freezeTokens(sparkAddress: string): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }>;
 
   /**
    * Freezes tokens associated with a specific Spark address.
@@ -650,7 +654,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
   }: {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
-  }): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }>;
+  }): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }>;
 
   public async freezeTokens(
     sparkAddressOrParams:
@@ -659,7 +666,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
           tokenIdentifier: Bech32mTokenIdentifier;
           sparkAddress: string;
         },
-  ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }> {
+  ): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }> {
     let bech32mTokenIdentifier: Bech32mTokenIdentifier | undefined;
     let sparkAddress: string;
 
@@ -711,7 +721,7 @@ export abstract class IssuerSparkWallet extends SparkWallet {
     const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 
     return {
-      impactedOutputIds: response.impactedOutputIds,
+      impactedTokenOutputs: response.impactedTokenOutputs,
       impactedTokenAmount: tokenAmount,
     };
   }
@@ -724,9 +734,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
    * @throws {SparkValidationError} If multiple tokens are found for this issuer
    * @throws {SparkValidationError} If no tokens are found for this issuer
    */
-  public async unfreezeTokens(
-    sparkAddress: string,
-  ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }>;
+  public async unfreezeTokens(sparkAddress: string): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }>;
 
   /**
    * Unfreezes previously frozen tokens associated with a specific Spark address.
@@ -743,7 +754,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
   }: {
     tokenIdentifier: Bech32mTokenIdentifier;
     sparkAddress: string;
-  }): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }>;
+  }): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }>;
 
   public async unfreezeTokens(
     sparkAddressOrParams:
@@ -752,7 +766,10 @@ export abstract class IssuerSparkWallet extends SparkWallet {
           tokenIdentifier: Bech32mTokenIdentifier;
           sparkAddress: string;
         },
-  ): Promise<{ impactedOutputIds: string[]; impactedTokenAmount: bigint }> {
+  ): Promise<{
+    impactedTokenOutputs: TokenOutputRef[];
+    impactedTokenAmount: bigint;
+  }> {
     let bech32mTokenIdentifier: Bech32mTokenIdentifier | undefined;
     let sparkAddress: string;
 
@@ -802,7 +819,7 @@ export abstract class IssuerSparkWallet extends SparkWallet {
     const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
 
     return {
-      impactedOutputIds: response.impactedOutputIds,
+      impactedTokenOutputs: response.impactedTokenOutputs,
       impactedTokenAmount: tokenAmount,
     };
   }

package/src/tests/integration/multi-token-issuer.test.ts

@@ -248,7 +248,7 @@ describe.each(TEST_CONFIGS)(
         tokenIdentifier: firstTokenIdentifier,
         sparkAddress: receiverAddress,
       });
-      expect(freezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(freezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(freezeResponse.impactedTokenAmount).toEqual(TOKEN_AMOUNT);
 
       // Should fail to transfer tokens because the outputs are frozen
@@ -281,7 +281,7 @@ describe.each(TEST_CONFIGS)(
         tokenIdentifier: firstTokenIdentifier,
         sparkAddress: receiverAddress,
       });
-      expect(unfreezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(unfreezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(unfreezeResponse.impactedTokenAmount).toEqual(TOKEN_AMOUNT);
 
       // Outputs unfrozen, transfer should succeed
@@ -418,7 +418,7 @@ describe.each(TEST_CONFIGS)(
       // Legacy single token issuer method should succeed when only one token is created
       const freezeResponse =
         await issuerWallet.freezeTokens(receiverSparkAddress);
-      expect(freezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(freezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(freezeResponse.impactedTokenAmount).toEqual(TOKEN_AMOUNT);
 
       // Should fail to transfer tokens because the outputs are frozen
@@ -434,7 +434,7 @@ describe.each(TEST_CONFIGS)(
       // Legacy single token issuer method should succeed when only one token is created
       const unfreezeResponse =
         await issuerWallet.unfreezeTokens(receiverSparkAddress);
-      expect(unfreezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(unfreezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(unfreezeResponse.impactedTokenAmount).toEqual(TOKEN_AMOUNT);
 
       const transferBackToIssuerOfUnfrozenToken =

package/src/tests/integration/token-invoices.test.ts

@@ -435,6 +435,8 @@ describe.each(TEST_CONFIGS)(
         3_000n,
       );
 
+      await faucet.mineBlocksAndWaitForMiningToComplete(3);
+
       await sdk.claimDeposit(oneThousand.id);
       await sdk.claimDeposit(twoThousand.id);
       await sdk.claimDeposit(threeThousand.id);

package/src/tests/integration/token-lifecycle.test.ts

@@ -58,12 +58,12 @@ describe.each(TEST_CONFIGS)(
       expect(userBalanceAfterTransfer.balance).toEqual(tokenAmount);
 
       const freezeResponse = await issuerWallet.freezeTokens(userSparkAddress);
-      expect(freezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(freezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(freezeResponse.impactedTokenAmount).toEqual(tokenAmount);
 
       const unfreezeResponse =
         await issuerWallet.unfreezeTokens(userSparkAddress);
-      expect(unfreezeResponse.impactedOutputIds.length).toBeGreaterThan(0);
+      expect(unfreezeResponse.impactedTokenOutputs.length).toBeGreaterThan(0);
       expect(unfreezeResponse.impactedTokenAmount).toEqual(tokenAmount);
     });
 

package/src/tests/integration/token-monitoring.test.ts

@@ -1,6 +1,9 @@
-import { filterTokenBalanceForTokenIdentifier } from "@buildonspark/spark-sdk";
+import {
+  filterTokenBalanceForTokenIdentifier,
+  NetworkType,
+} from "@buildonspark/spark-sdk";
 import { jest } from "@jest/globals";
-import { bytesToHex } from "@noble/curves/utils";
+import { bytesToHex, bytesToNumberBE } from "@noble/curves/utils";
 import { IssuerSparkWalletTesting } from "../utils/issuer-test-wallet.js";
 import { SparkWalletTesting } from "@buildonspark/spark-sdk/test-utils";
 import { TEST_CONFIGS } from "./test-configs.js";
@@ -109,7 +112,7 @@ describe.each(TEST_CONFIGS)(
 
       await issuerWallet.burnTokens(250n);
 
-      const res = await issuerWallet.queryTokenTransactions({
+      const res = await issuerWallet.queryTokenTransactionsWithFilters({
         tokenIdentifiers: [tokenIdentifier!],
         sparkAddresses: [await issuerWallet.getSparkAddress()],
       });
@@ -156,8 +159,11 @@ describe.each(TEST_CONFIGS)(
       });
 
       const tokenIdentifier = await issuerWallet.getIssuerTokenIdentifier();
+      const issuerPublicKey = await issuerWallet.getIdentityPublicKey();
+      const issuerSparkAddress = await issuerWallet.getSparkAddress();
+      const userSparkAddress = await userWallet.getSparkAddress();
 
-      await issuerWallet.mintTokens(tokenAmount);
+      const mintTxHash = await issuerWallet.mintTokens(tokenAmount);
 
       {
         const res = await issuerWallet.queryTokenTransactions({
@@ -168,10 +174,19 @@ describe.each(TEST_CONFIGS)(
         expect(amount_of_transactions).toEqual(1);
       }
 
+      {
+        const res = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+        });
+        const transactions = res.tokenTransactionsWithStatus;
+        const amount_of_transactions = transactions.length;
+        expect(amount_of_transactions).toEqual(1);
+      }
+
       await issuerWallet.transferTokens({
         tokenAmount,
         tokenIdentifier: tokenIdentifier!,
-        receiverSparkAddress: await userWallet.getSparkAddress(),
+        receiverSparkAddress: userSparkAddress,
       });
 
       {
@@ -183,16 +198,52 @@ describe.each(TEST_CONFIGS)(
         expect(amount_of_transactions).toEqual(2);
       }
 
+      {
+        const res = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+        });
+        const transactions = res.tokenTransactionsWithStatus;
+        const amount_of_transactions = transactions.length;
+        expect(amount_of_transactions).toEqual(2);
+      }
+
       for (let index = 0; index < 100; ++index) {
         const dynamicAmount = BigInt(index + 1);
         await issuerWallet.mintTokens(dynamicAmount);
         await issuerWallet.transferTokens({
           tokenAmount: dynamicAmount,
           tokenIdentifier: tokenIdentifier!,
-          receiverSparkAddress: await userWallet.getSparkAddress(),
+          receiverSparkAddress: userSparkAddress,
         });
       }
 
+      {
+        const res = await issuerWallet.queryTokenTransactionsByTxHashes([
+          mintTxHash!,
+        ]);
+        const transactions = res.tokenTransactionsWithStatus;
+        expect(transactions.length).toEqual(1);
+        expect(bytesToHex(transactions[0].tokenTransactionHash)).toEqual(
+          mintTxHash,
+        );
+        expect(transactions[0].tokenTransaction?.tokenInputs?.$case).toEqual(
+          "mintInput",
+        );
+        expect(
+          bytesToHex(
+            transactions[0].tokenTransaction?.tokenOutputs?.[0]
+              ?.ownerPublicKey!,
+          ),
+        ).toEqual(issuerPublicKey);
+        expect(
+          BigInt(
+            bytesToNumberBE(
+              transactions[0].tokenTransaction?.tokenOutputs?.[0]?.tokenAmount!,
+            ),
+          ),
+        ).toEqual(tokenAmount);
+      }
+
       {
         const res = await issuerWallet.queryTokenTransactions({
           tokenIdentifiers: [tokenIdentifier!],
@@ -203,6 +254,79 @@ describe.each(TEST_CONFIGS)(
         expect(amount_of_transactions).toEqual(10);
       }
 
+      {
+        const res = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+          pageSize: 10,
+        });
+        const transactions = res.tokenTransactionsWithStatus;
+        const amount_of_transactions = transactions.length;
+        expect(amount_of_transactions).toEqual(10);
+      }
+
+      {
+        const res = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+          issuerPublicKeys: [issuerPublicKey],
+          pageSize: 10,
+        });
+        const transactions = res.tokenTransactionsWithStatus;
+        const amount_of_transactions = transactions.length;
+        expect(amount_of_transactions).toEqual(10);
+      }
+
+      {
+        const res = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+          sparkAddresses: [issuerSparkAddress],
+          pageSize: 5,
+        });
+        const transactions = res.tokenTransactionsWithStatus;
+        const pageInfo = res.pageResponse;
+        expect(transactions.length).toEqual(5);
+        expect(pageInfo?.hasNextPage).toEqual(true);
+        expect(pageInfo?.nextCursor).not.toEqual("");
+        const nextCursor = pageInfo?.nextCursor ?? "";
+
+        const nextRes = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+          sparkAddresses: [issuerSparkAddress],
+          pageSize: 5,
+          cursor: nextCursor,
+        });
+        const nextTransactions = nextRes.tokenTransactionsWithStatus;
+        const nextPageInfo = nextRes.pageResponse;
+        expect(nextTransactions.length).toEqual(5);
+        expect(nextPageInfo?.hasPreviousPage).toEqual(true);
+        expect(nextPageInfo?.previousCursor).not.toEqual("");
+
+        const seenHashes = new Set(
+          transactions.map((tx) => bytesToHex(tx.tokenTransactionHash)),
+        );
+        nextTransactions.forEach((tx) => {
+          const hash = bytesToHex(tx.tokenTransactionHash);
+          expect(seenHashes.has(hash)).toEqual(false);
+        });
+
+        const prevRes = await issuerWallet.queryTokenTransactionsWithFilters({
+          tokenIdentifiers: [tokenIdentifier!],
+          sparkAddresses: [issuerSparkAddress],
+          pageSize: 5,
+          cursor: nextPageInfo?.previousCursor ?? "",
+          direction: "PREVIOUS",
+        });
+        const prevTransactions = prevRes.tokenTransactionsWithStatus;
+        expect(prevTransactions.length).toEqual(5);
+
+        const prevHashes = new Set(
+          prevTransactions.map((tx) => bytesToHex(tx.tokenTransactionHash)),
+        );
+        transactions.forEach((tx) => {
+          const hash = bytesToHex(tx.tokenTransactionHash);
+          expect(prevHashes.has(hash)).toEqual(true);
+        });
+      }
+
       {
         let hashset_of_all_transactions: Set<String> = new Set();