@buildonspark/spark-sdk 0.1.44 → 0.1.46

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

@@ -43,7 +43,6 @@ import {
   QueryNodesResponse,
   SigningJob,
   SubscribeToEventsResponse,
-  TokenTransactionWithStatus,
   Transfer,
   TransferStatus,
   TransferType,
@@ -102,7 +101,7 @@ import {
   SparkAddressFormat,
 } from "../address/index.js";
 import { isReactNative } from "../constants.js";
-import { networkToJSON, Network as NetworkProto } from "../proto/spark.js";
+import { Network as NetworkProto, networkToJSON } from "../proto/spark.js";
 import {
   decodeInvoice,
   getNetworkFromInvoice,
@@ -125,9 +124,12 @@ import type {
   InitWalletResponse,
   PayLightningInvoiceParams,
   SparkWalletProps,
-  TokenInfo,
+  TokenMetadata,
   TransferParams,
+  TokenBalanceMap,
 } from "./types.js";
+import { encodeHumanReadableTokenIdentifier } from "../utils/token-identifier.js";
+import { TokenTransactionWithStatus } from "../proto/spark_token.js";
 
 /**
  * The SparkWallet class is the primary interface for interacting with the Spark network.
@@ -164,6 +166,7 @@ export class SparkWallet extends EventEmitter {
   private streamController: AbortController | null = null;
 
   protected leaves: TreeNode[] = [];
+
   protected tokenOutputs: Map<string, OutputWithPreviousTransactionData[]> =
     new Map();
 
@@ -486,8 +489,7 @@ export class SparkWallet extends EventEmitter {
                 leaf.signingKeyshare.publicKey,
                 operatorLeaf.signingKeyshare.publicKey,
               ) ||
-              !equalBytes(leaf.nodeTx, operatorLeaf.nodeTx) ||
-              !equalBytes(leaf.refundTx, operatorLeaf.refundTx)
+              !equalBytes(leaf.nodeTx, operatorLeaf.nodeTx)
             ) {
               leavesToIgnore.add(nodeId);
             }
@@ -1182,32 +1184,6 @@ export class SparkWallet extends EventEmitter {
     };
   }
 
-  /**
-   * Gets the held token info for the wallet.
-   *
-   * @deprecated The information is returned in getBalance
-   */
-  public async getTokenInfo(): Promise<TokenInfo[]> {
-    console.warn("getTokenInfo is deprecated. Use getBalance instead.");
-
-    await this.syncTokenOutputs();
-
-    const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
-    const { balance, tokenBalances } = await this.getBalance();
-
-    const tokenInfo = await lrc20Client.getTokenPubkeyInfo({
-      publicKeys: Array.from(tokenBalances.keys()).map(hexToBytes),
-    });
-
-    return tokenInfo.tokenPubkeyInfos.map((info) => ({
-      tokenPublicKey: bytesToHex(info.announcement!.publicKey!.publicKey),
-      tokenName: info.announcement!.name,
-      tokenSymbol: info.announcement!.symbol,
-      tokenDecimals: Number(bytesToNumberBE(info.announcement!.decimal)),
-      maxSupply: bytesToNumberBE(info.announcement!.maxSupply),
-    }));
-  }
-
   /**
    * Gets the current balance of the wallet.
    * You can use the forceRefetch option to synchronize your wallet and claim any
@@ -1215,24 +1191,21 @@ export class SparkWallet extends EventEmitter {
    *
    * @returns {Promise<Object>} Object containing:
    *   - balance: The wallet's current balance in satoshis
-   *   - tokenBalances: Map of token public keys to token balances and token info
+   *   - tokenBalances: Map of the human readable token identifier to token balances and token info
    */
   public async getBalance(): Promise<{
     balance: bigint;
-    tokenBalances: Map<string, { balance: bigint; tokenInfo: TokenInfo }>;
+    tokenBalances: TokenBalanceMap;
   }> {
     const leaves = await this.getLeaves(true);
     await this.syncTokenOutputs();
 
-    let tokenBalances: Map<string, { balance: bigint; tokenInfo: TokenInfo }>;
+    let tokenBalances: TokenBalanceMap;
 
     if (this.tokenOutputs.size !== 0) {
       tokenBalances = await this.getTokenBalance();
     } else {
-      tokenBalances = new Map<
-        string,
-        { balance: bigint; tokenInfo: TokenInfo }
-      >();
+      tokenBalances = new Map();
     }
 
     return {
@@ -1241,32 +1214,33 @@ export class SparkWallet extends EventEmitter {
     };
   }
 
-  private async getTokenBalance(): Promise<
-    Map<string, { balance: bigint; tokenInfo: TokenInfo }>
-  > {
-    const lrc20Client = await this.lrc20ConnectionManager.createLrc20Client();
+  private async getTokenBalance(): Promise<TokenBalanceMap> {
+    const sparkTokenClient =
+      await this.connectionManager.createSparkTokenClient(
+        this.config.getCoordinatorAddress(),
+      );
 
-    // Get token info for all tokens
-    const tokenInfo = await lrc20Client.getTokenPubkeyInfo({
-      publicKeys: Array.from(this.tokenOutputs.keys()).map(hexToBytes),
+    const tokenMetadata = await sparkTokenClient.query_token_metadata({
+      issuerPublicKeys: Array.from(this.tokenOutputs.keys()).map(hexToBytes),
     });
+    const result: TokenBalanceMap = new Map();
 
-    const result = new Map<string, { balance: bigint; tokenInfo: TokenInfo }>();
-
-    for (const info of tokenInfo.tokenPubkeyInfos) {
-      const tokenPublicKey = bytesToHex(
-        info.announcement!.publicKey!.publicKey,
-      );
+    for (const metadata of tokenMetadata.tokenMetadata) {
+      const tokenPublicKey = bytesToHex(metadata.issuerPublicKey);
       const leaves = this.tokenOutputs.get(tokenPublicKey);
-
-      result.set(tokenPublicKey, {
+      const humanReadableTokenIdentifier = encodeHumanReadableTokenIdentifier({
+        tokenIdentifier: metadata.tokenIdentifier,
+        network: this.config.getNetworkType(),
+      });
+      result.set(humanReadableTokenIdentifier, {
         balance: leaves ? calculateAvailableTokenAmount(leaves) : BigInt(0),
-        tokenInfo: {
+        tokenMetadata: {
           tokenPublicKey,
-          tokenName: info.announcement!.name,
-          tokenSymbol: info.announcement!.symbol,
-          tokenDecimals: Number(bytesToNumberBE(info.announcement!.decimal)),
-          maxSupply: bytesToNumberBE(info.announcement!.maxSupply),
+          rawTokenIdentifier: metadata.tokenIdentifier,
+          tokenName: metadata.tokenName,
+          tokenTicker: metadata.tokenTicker,
+          decimals: metadata.decimals,
+          maxSupply: bytesToNumberBE(metadata.maxSupply),
         },
       });
     }
@@ -2611,27 +2585,9 @@ export class SparkWallet extends EventEmitter {
           invoice.invoice.encodedInvoice,
         ).fallbackAddress;
 
-        if (
-          sparkFallbackAddress &&
-          isValidSparkFallback(hexToBytes(sparkFallbackAddress))
-        ) {
-          const invoiceIdentityPubkey = sparkFallbackAddress.slice(6); // remove the 3 byte header
-          const expectedIdentityPubkey =
-            receiverIdentityPubkey ?? (await this.getIdentityPublicKey());
-
-          if (invoiceIdentityPubkey !== expectedIdentityPubkey) {
-            throw new ValidationError(
-              "Mismatch between spark identity embedded in lightning invoice and designated recipient spark identity",
-              {
-                field: "sparkFallbackAddress",
-                value: invoiceIdentityPubkey,
-                expected: expectedIdentityPubkey,
-              },
-            );
-          }
-        } else {
+        if (!sparkFallbackAddress) {
           throw new ValidationError(
-            "No valid spark fallback address found in lightning invoice",
+            "No spark fallback address found in lightning invoice",
             {
               field: "sparkFallbackAddress",
               value: sparkFallbackAddress,
@@ -2639,6 +2595,20 @@ export class SparkWallet extends EventEmitter {
             },
           );
         }
+
+        const expectedIdentityPubkey =
+          receiverIdentityPubkey ?? (await this.getIdentityPublicKey());
+
+        if (sparkFallbackAddress !== expectedIdentityPubkey) {
+          throw new ValidationError(
+            "Mismatch between spark identity embedded in lightning invoice and designated recipient spark identity",
+            {
+              field: "sparkFallbackAddress",
+              value: sparkFallbackAddress,
+              expected: expectedIdentityPubkey,
+            },
+          );
+        }
       }
 
       return invoice;
@@ -2736,9 +2706,8 @@ export class SparkWallet extends EventEmitter {
           "No valid spark address found in invoice. Defaulting to lightning.",
         );
       } else {
-        const identityPublicKey = sparkFallbackAddress.slice(6); // remove the 3 byte header
         const receiverSparkAddress = encodeSparkAddress({
-          identityPublicKey,
+          identityPublicKey: sparkFallbackAddress,
           network: Network[invoiceNetwork] as NetworkType,
         });
         return await this.transfer({
@@ -3181,8 +3150,15 @@ export class SparkWallet extends EventEmitter {
    * @param {string} id - The ID of the transfer
    * @returns {Promise<Transfer | undefined>} The transfer
    */
-  public async getTransfer(id: string): Promise<Transfer | undefined> {
-    return await this.transferService.queryTransfer(id);
+  public async getTransfer(id: string): Promise<WalletTransfer | undefined> {
+    const transfer = await this.transferService.queryTransfer(id);
+    if (!transfer) {
+      return undefined;
+    }
+    return mapTransferToWalletTransfer(
+      transfer,
+      bytesToHex(await this.config.signer.getIdentityPublicKey()),
+    );
   }
 
   // ***** Token Flow *****
@@ -3197,10 +3173,9 @@ export class SparkWallet extends EventEmitter {
     this.tokenOutputs.clear();
 
     const unsortedTokenOutputs =
-      await this.tokenTransactionService.fetchOwnedTokenOutputs(
-        [await this.config.signer.getIdentityPublicKey()],
-        [],
-      );
+      await this.tokenTransactionService.fetchOwnedTokenOutputs({
+        ownerPublicKeys: [await this.config.signer.getIdentityPublicKey()],
+      });
 
     const filteredTokenOutputs = unsortedTokenOutputs.filter(
       (output) =>
@@ -3331,34 +3306,27 @@ export class SparkWallet extends EventEmitter {
    * Retrieves token transaction history for specified tokens owned by the wallet.
    * Can optionally filter by specific transaction hashes.
    *
-   * @param tokenPublicKeys - Array of token public keys to query transactions for
+   * @param ownerPublicKeys - Optional array of owner public keys to query transactions for
+   * @param issuerPublicKeys - Optional array of issuer public keys to query transactions for
    * @param tokenTransactionHashes - Optional array of specific transaction hashes to filter by
+   * @param tokenIdentifiers - Optional array of token identifiers to filter by
+   * @param outputIds - Optional array of output IDs to filter by
    * @returns Promise resolving to array of token transactions with their current status
    */
   public async queryTokenTransactions(
-    tokenPublicKeys: string[],
+    ownerPublicKeys?: string[],
+    issuerPublicKeys?: string[],
     tokenTransactionHashes?: string[],
+    tokenIdentifiers?: string[],
+    outputIds?: string[],
   ): Promise<TokenTransactionWithStatus[]> {
-    const sparkClient = await this.connectionManager.createSparkClient(
-      this.config.getCoordinatorAddress(),
-    );
-
-    let queryParams;
-    if (tokenTransactionHashes?.length) {
-      queryParams = {
-        tokenPublicKeys: tokenPublicKeys?.map(hexToBytes)!,
-        ownerPublicKeys: [hexToBytes(await this.getIdentityPublicKey())],
-        tokenTransactionHashes: tokenTransactionHashes.map(hexToBytes),
-      };
-    } else {
-      queryParams = {
-        tokenPublicKeys: tokenPublicKeys?.map(hexToBytes)!,
-        ownerPublicKeys: [hexToBytes(await this.getIdentityPublicKey())],
-      };
-    }
-
-    const response = await sparkClient.query_token_transactions(queryParams);
-    return response.tokenTransactionsWithStatus;
+    return this.tokenTransactionService.queryTokenTransactions({
+      ownerPublicKeys,
+      issuerPublicKeys,
+      tokenTransactionHashes,
+      tokenIdentifiers,
+      outputIds,
+    }) as Promise<TokenTransactionWithStatus[]>;
   }
 
   public async getTokenL1Address(): Promise<string> {

package/src/spark-wallet/types.ts

@@ -1,6 +1,7 @@
 import type { Transaction } from "@scure/btc-signer";
 import { ConfigOptions } from "../services/wallet-config.js";
 import type { SparkSigner } from "../signer/signer.js";
+import { HumanReadableTokenIdentifier } from "../utils/token-identifier.js";
 
 export type CreateLightningInvoiceParams = {
   amountSats: number;
@@ -30,14 +31,49 @@ export type DepositParams = {
   vout: number;
 };
 
-export type TokenInfo = {
+/**
+ * Token metadata containing essential information about a token.
+ * This is the wallet's internal representation with JavaScript-friendly types.
+ *
+ * rawTokenIdentifier: This is the raw binary token identifier - This is used to encode the human readable token identifier.
+ *
+ * tokenPublicKey: This is the hex-encoded public key of the token issuer - Same as issuerPublicKey.
+ *
+ * @example
+ * ```typescript
+ * const tokenMetadata: TokenMetadata = {
+ *   rawTokenIdentifier: new Uint8Array([1, 2, 3]),
+ *   tokenPublicKey: "0348fbb...",
+ *   tokenName: "SparkToken",
+ *   tokenTicker: "SPK",
+ *   decimals: 8,
+ *   maxSupply: 1000000n
+ * };
+ * ```
+ */
+export type TokenMetadata = {
+  /** Raw binary token identifier - This is used to encode the human readable token identifier */
+  rawTokenIdentifier: Uint8Array;
+  /** Hex-encoded public key of the token issuer - Same as issuerPublicKey */
   tokenPublicKey: string;
+  /** Human-readable name of the token (e.g., SparkToken)*/
   tokenName: string;
-  tokenSymbol: string;
-  tokenDecimals: number;
+  /** Short ticker symbol for the token (e.g., "SPK") */
+  tokenTicker: string;
+  /** Number of decimal places for token amounts */
+  decimals: number;
+  /** Maximum supply of tokens that can ever be minted */
   maxSupply: bigint;
 };
 
+export type TokenBalanceMap = Map<
+  HumanReadableTokenIdentifier,
+  {
+    balance: bigint;
+    tokenMetadata: TokenMetadata;
+  }
+>;
+
 export type InitWalletResponse = {
   mnemonic?: string | undefined;
 };

package/src/tests/bolt11-spark.test.ts

@@ -62,7 +62,7 @@ describe("spark bolt11 invoice decoding", () => {
       "pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpquwpc4curk03c9wlrswe78q4eyqc7d8d0xqzpuyk0sg5g70me25alkluzd2x62aysf2pyy8edtjeevuv4p2d5p76r4zkmneet7uvyakky2zr4cusd45tftc9c5fh0nnqpnl2jfll544esqchsrny";
     expect(() => {
       decodeInvoice(invoice);
-    }).toThrow('Letter "1" must be present between prefix and data only');
+    }).toThrow("Not a proper lightning payment request");
   });
 
   it("fails to decode malformed Bolt11 invoice - mixed case", () => {
@@ -73,20 +73,12 @@ describe("spark bolt11 invoice decoding", () => {
     }).toThrow("String must be lowercase or uppercase");
   });
 
-  it("fails to decode bolt11 invoice with invalid signature", () => {
-    const invoice =
-      "lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgqwgt7mcn5yqw3yx0w94pswkpq6j9uh6xfqqqtsk4tnarugeektd4hg5975x9am52rz4qskukxdmjemg92vvqz8nvmsye63r5ykel43pgz7zq0g2";
-    expect(() => {
-      decodeInvoice(invoice);
-    }).toThrow("Invalid BOLT11 signature");
-  });
-
   it("fails to decode bolt11 invoice with invalid multiplier", () => {
     const invoice =
       "lnbc2500x1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgqrrzc4cvfue4zp3hggxp47ag7xnrlr8vgcmkjxk3j5jqethnumgkpqp23z9jclu3v0a7e0aruz366e9wqdykw6dxhdzcjjhldxq0w6wgqcnu43j";
     expect(() => {
       decodeInvoice(invoice);
-    }).toThrow("Invalid multiplier: x");
+    }).toThrow("Not a valid multiplier for the amount");
   });
 
   it("fails to decode bolt11 invoice with invalid submillisatoshi precision", () => {
@@ -94,7 +86,7 @@ describe("spark bolt11 invoice decoding", () => {
       "lnbc2500000001p1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgq0lzc236j96a95uv0m3umg28gclm5lqxtqqwk32uuk4k6673k6n5kfvx3d2h8s295fad45fdhmusm8sjudfhlf6dcsxmfvkeywmjdkxcp99202x";
     expect(() => {
       decodeInvoice(invoice);
-    }).toThrow("Invalid submillisatoshi precision");
+    }).toThrow("Amount is outside of valid range");
   });
 
   it("fails to decode bolt11 invoice with invalid payment secret", () => {
@@ -107,17 +99,17 @@ describe("spark bolt11 invoice decoding", () => {
 
   it("decodes a bolt11 invoice with spark address embedded", () => {
     const invoice =
-      "lnbc1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdpl2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq9qrsgqfpml2dgykqjsjj0vxkcz9cuftlfhw5qs9720aqf4y0azyqggx29gz7gt7eadu5h5wqmn7ns8rju0ps0tk8jx70eg8jxek3usgsehql0ztdxmfjj58nqjky6w9wp324ctcnj9vnrgc8j9dpujfqjrc8lv9z4twr2pur2cgqujn2dx";
+      "lnbc13u1p5xalmkpp5z79uwgne7znz76plf0q4zxmh8t3wke6gsnm5kn67h4satpgflkmssp5azht5ywc5s4m40jf9h0nwlr959a34n72pns50lfm93zz8lvs7nqsxq9z0rgqnp4q0p92sfan5vj2a4f8q3gsfsy8qp60maeuxz858c5x0hvt5u0p0h9jr9yqtqd37k2ya0pv8pqeyjs4lklcexjyw600g9qqp62r4j0ph8fcmlfwqqqqzfv7u6g85qqqqqqqqqqthqq9qpz9cat0ndmwmfx036y9fxfhdufta3mn95ta9xw34ynlwg7euxjck85ysq0gfqqqqq7u6egqrhxk2qqn3qqcqzpgdq2w3jhxap3xv9qyyssqfahd64hu0lffl7cw2e4evu400s09yeupypvnfjvjjyq8rh05y9gzd3dqnmkvuyd9jszyhmdey75dujz8xaufgahsxkqktf3wxny8ghsqpk4mg8";
 
     const { amountMSats, fallbackAddress, paymentHash } =
       decodeInvoice(invoice);
 
-    expect(amountMSats).toBe(null);
+    expect(amountMSats).toBe(1300000n);
     expect(fallbackAddress).toBe(
-      "53504b0250949ec35b022e3895fd37750102f94fe813523fa220108328a81790bf67ade5",
+      "0222e3ab7cdbb76d267c7442a4c9bb7895f63b9968be94ce8d493fb91ecf0d2c58",
     );
     expect(paymentHash).toBe(
-      "0001020304050607080900010203040506070809000102030405060708090102",
+      "178bc72279f0a62f683f4bc1511b773ae2eb674884f74b4f5ebd61d58509fdb7",
     );
   });
 });

package/src/tests/integration/ssp/coop-exit.test.ts

@@ -41,22 +41,22 @@ describe("SSP coop exit integration", () => {
 
     expect(feeEstimate).toBeDefined();
     expect(feeEstimate?.l1BroadcastFeeFast).toBeDefined();
-    expect(feeEstimate?.l1BroadcastFeeFast).toBeGreaterThan(0);
+    expect(feeEstimate?.l1BroadcastFeeFast.originalValue).toBeGreaterThan(0);
     expect(feeEstimate?.userFeeFast).toBeDefined();
-    expect(feeEstimate?.userFeeFast).toBeGreaterThan(0);
+    expect(feeEstimate?.userFeeFast.originalValue).toBeGreaterThan(0);
 
     expect(feeEstimate?.l1BroadcastFeeMedium).toBeDefined();
-    expect(feeEstimate?.l1BroadcastFeeMedium).toBeGreaterThan(0);
+    expect(feeEstimate?.l1BroadcastFeeMedium.originalValue).toBeGreaterThan(0);
     expect(feeEstimate?.userFeeMedium).toBeDefined();
-    expect(feeEstimate?.userFeeMedium).toBeGreaterThan(0);
+    expect(feeEstimate?.userFeeMedium.originalValue).toBeGreaterThan(0);
 
     expect(feeEstimate?.l1BroadcastFeeSlow).toBeDefined();
-    expect(feeEstimate?.l1BroadcastFeeSlow).toBeGreaterThan(0);
+    expect(feeEstimate?.l1BroadcastFeeSlow.originalValue).toBeGreaterThan(0);
     expect(feeEstimate?.userFeeSlow).toBeDefined();
-    expect(feeEstimate?.userFeeSlow).toBeGreaterThan(0);
+    expect(feeEstimate?.userFeeSlow.originalValue).toBeGreaterThan(0);
   }, 60000);
 
-  it("should complete coop exit without deducting fees from withdrawal amount", async () => {
+  it.skip("should complete coop exit without deducting fees from withdrawal amount", async () => {
     const faucet = BitcoinFaucet.getInstance();
 
     const { wallet: userWallet } = await SparkWalletTesting.initialize(