@buildonspark/spark-sdk 0.2.13 → 0.3.0

package/src/spark-wallet/types.ts

@@ -5,6 +5,8 @@ import { ConfigOptions } from "../services/wallet-config.js";
 import type { SparkSigner } from "../signer/signer.js";
 import { KeyDerivation } from "../signer/types.js";
 import { Bech32mTokenIdentifier } from "../utils/token-identifier.js";
+import { SparkAddressFormat } from "../utils/address.js";
+import { WalletTransfer } from "../types/index.js";
 
 export type CreateLightningInvoiceParams = {
   amountSats: number;
@@ -27,6 +29,55 @@ export type TransferParams = {
   receiverSparkAddress: string;
 };
 
+export type TransferWithInvoiceParams = {
+  amountSats: number;
+  receiverIdentityPubkey: Uint8Array;
+  sparkInvoice?: SparkAddressFormat;
+};
+
+export type TransferWithInvoiceOutcome =
+  | { ok: true; transfer: WalletTransfer; param: TransferWithInvoiceParams }
+  | { ok: false; error: Error; param: TransferWithInvoiceParams };
+
+export type FulfillSparkInvoiceResponse = {
+  satsTransactionSuccess: {
+    invoice: SparkAddressFormat;
+    transferResponse: WalletTransfer;
+  }[];
+  tokenTransactionSuccess: {
+    tokenIdentifier: Bech32mTokenIdentifier;
+    invoices: SparkAddressFormat[];
+    txid: string;
+  }[];
+  satsTransactionErrors: {
+    invoice: SparkAddressFormat;
+    error: Error;
+  }[];
+  tokenTransactionErrors: {
+    tokenIdentifier: Bech32mTokenIdentifier;
+    invoices: SparkAddressFormat[];
+    error: Error;
+  }[];
+  invalidInvoices: InvalidInvoice[];
+};
+
+export type TokenInvoice = {
+  invoice: SparkAddressFormat;
+  identifierHex: string;
+  amount: bigint;
+};
+
+export type InvalidInvoice = {
+  invoice: SparkAddressFormat;
+  error: Error;
+};
+
+export type GroupSparkInvoicesResult = {
+  satsInvoices: TransferWithInvoiceParams[];
+  tokenInvoices: Map<string, TokenInvoice[]>;
+  invalidInvoices: InvalidInvoice[];
+};
+
 export type DepositParams = {
   keyDerivation: KeyDerivation;
   verifyingKey: Uint8Array;
@@ -98,17 +149,36 @@ export interface SparkWalletProps {
   options?: ConfigOptions;
 }
 
+export const SparkWalletEvent = {
+  All: "*",
+  TransferClaimed: "transfer:claimed",
+  DepositConfirmed: "deposit:confirmed",
+  StreamConnected: "stream:connected",
+  StreamDisconnected: "stream:disconnected",
+  StreamReconnecting: "stream:reconnecting",
+} as const;
+
+export type SparkWalletEventType =
+  (typeof SparkWalletEvent)[keyof typeof SparkWalletEvent];
+
 export interface SparkWalletEvents {
+  [SparkWalletEvent.All]: (eventName: string, ...args: unknown[]) => void;
   /** Emitted when an incoming transfer is successfully claimed. Includes the transfer ID and new total balance. */
-  "transfer:claimed": (transferId: string, updatedBalance: number) => void;
+  [SparkWalletEvent.TransferClaimed]: (
+    transferId: string,
+    updatedBalance: bigint,
+  ) => void;
   /** Emitted when a deposit is marked as available. Includes the deposit ID and new total balance. */
-  "deposit:confirmed": (depositId: string, updatedBalance: number) => void;
+  [SparkWalletEvent.DepositConfirmed]: (
+    depositId: string,
+    updatedBalance: bigint,
+  ) => void;
   /** Emitted when the stream is connected */
-  "stream:connected": () => void;
+  [SparkWalletEvent.StreamConnected]: () => void;
   /** Emitted when the stream disconnects and fails to reconnect after max attempts */
-  "stream:disconnected": (reason: string) => void;
+  [SparkWalletEvent.StreamDisconnected]: (reason: string) => void;
   /** Emitted when attempting to reconnect the stream */
-  "stream:reconnecting": (
+  [SparkWalletEvent.StreamReconnecting]: (
     attempt: number,
     maxAttempts: number,
     delayMs: number,

package/src/spark_bindings/wasm/index.ts

@@ -46,14 +46,35 @@ export function signFrost({
   statechainCommitments,
   adaptorPubKey,
 }: SignFrostParams): Uint8Array {
-  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace("signFrost", {
+  const logMsg = JSON.stringify({
     message: bytesToHex(message),
-    keyPackage: keyPackage,
-    nonce: nonce,
-    selfCommitment: selfCommitment,
-    statechainCommitments: statechainCommitments,
+    keyPackage: {
+      secretKey: bytesToHex(keyPackage.secretKey),
+      publicKey: bytesToHex(keyPackage.publicKey),
+      verifyingKey: bytesToHex(keyPackage.verifyingKey),
+    },
+    nonce: {
+      hiding: bytesToHex(nonce.hiding),
+      binding: bytesToHex(nonce.binding),
+    },
+    selfCommitment: {
+      hiding: bytesToHex(selfCommitment.hiding),
+      binding: bytesToHex(selfCommitment.binding),
+    },
+    statechainCommitments: Object.fromEntries(
+      Object.entries(statechainCommitments ?? {}).map(([k, v]) => [
+        k,
+        {
+          hiding: bytesToHex(v.hiding),
+          binding: bytesToHex(v.binding),
+        },
+      ]),
+    ),
+    adaptorPubKey: adaptorPubKey ? bytesToHex(adaptorPubKey) : undefined,
   });
-  return wasm_sign_frost(
+
+  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace("signFrost", logMsg);
+  const result = wasm_sign_frost(
     message,
     createKeyPackage(keyPackage),
     createSigningNonce(nonce),
@@ -61,6 +82,12 @@ export function signFrost({
     statechainCommitments,
     adaptorPubKey,
   );
+  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace(
+    "signFrost result",
+    bytesToHex(result),
+  );
+
+  return result;
 }
 
 export function aggregateFrost({
@@ -74,18 +101,40 @@ export function aggregateFrost({
   verifyingKey,
   adaptorPubKey,
 }: AggregateFrostParams): Uint8Array {
-  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace("aggregateFrost", {
+  const logMsg = JSON.stringify({
     message: bytesToHex(message),
-    statechainCommitments: statechainCommitments,
-    selfCommitment: selfCommitment,
-    statechainSignatures: statechainSignatures,
+    statechainCommitments: Object.fromEntries(
+      Object.entries(statechainCommitments ?? {}).map(([k, v]) => [
+        k,
+        {
+          hiding: bytesToHex(v.hiding),
+          binding: bytesToHex(v.binding),
+        },
+      ]),
+    ),
+    selfCommitment: {
+      hiding: bytesToHex(selfCommitment.hiding),
+      binding: bytesToHex(selfCommitment.binding),
+    },
+    statechainSignatures: Object.fromEntries(
+      Object.entries(statechainSignatures ?? {}).map(([k, v]) => [
+        k,
+        bytesToHex(v),
+      ]),
+    ),
     selfSignature: bytesToHex(selfSignature),
-    statechainPublicKeys: statechainPublicKeys,
+    statechainPublicKeys: Object.fromEntries(
+      Object.entries(statechainPublicKeys ?? {}).map(([k, v]) => [
+        k,
+        bytesToHex(v),
+      ]),
+    ),
     selfPublicKey: bytesToHex(selfPublicKey),
     verifyingKey: bytesToHex(verifyingKey),
     adaptorPubKey: adaptorPubKey ? bytesToHex(adaptorPubKey) : undefined,
   });
-  return wasm_aggregate_frost(
+  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace("aggregateFrost", logMsg);
+  const result = wasm_aggregate_frost(
     message,
     statechainCommitments,
     createSigningCommitment(selfCommitment),
@@ -96,6 +145,11 @@ export function aggregateFrost({
     verifyingKey,
     adaptorPubKey,
   );
+  SparkSdkLogger.get(LOGGER_NAMES.wasm).trace(
+    "aggregateFrost result",
+    bytesToHex(result),
+  );
+  return result;
 }
 
 export function createDummyTx({

package/src/tests/address.test.ts

@@ -226,12 +226,24 @@ describe("Spark Invoice Encode/Decode", () => {
 
 describe("getNetworkFromSparkAddress", () => {
   test("REGTEST", () => {
+    const network = getNetworkFromSparkAddress(
+      "sparkrt1pgssx5us3wkqjza8g80xz3a9gznx25msq6g3ty8exfym9q3ahcv86vsnxxdy83",
+    );
+    expect(network).toBe("REGTEST");
+  });
+  test("Legacy REGTEST", () => {
     const network = getNetworkFromSparkAddress(
       "sprt1pgssx63fa5g6uyv450rajp5ndwy9laxzpsp9e37su58jddmcdsvhgm5n7y0ud6",
     );
     expect(network).toBe("REGTEST");
   });
   test("MAINNET", () => {
+    const network = getNetworkFromSparkAddress(
+      "spark1pgss9qg3vdslzmt2name9v550skuvlu6lj5xt9sly90k7p0gxughlqv023jqmc",
+    );
+    expect(network).toBe("MAINNET");
+  });
+  test("Legacy MAINNET", () => {
     const network = getNetworkFromSparkAddress(
       "sp1pgssxwh6hznfdc3c0cuqrhgttder539d52a0rqcf34amge69huh664gd2ew787",
     );
@@ -240,9 +252,29 @@ describe("getNetworkFromSparkAddress", () => {
 });
 
 describe("knownSparkAddress", () => {
+  test("spark address encodes known identity public key", () => {
+    const address =
+      "sparkrt1pgssx5us3wkqjza8g80xz3a9gznx25msq6g3ty8exfym9q3ahcv86vsnxxdy83";
+    const network = getNetworkFromSparkAddress(address);
+    expect(network).toBe("REGTEST");
+    const decoded = decodeSparkAddress(address, network);
+    expect(decoded.identityPublicKey).toBe(
+      "0353908bac090ba741de6147a540a665537006911590f93249b2823dbe187d3213",
+    );
+  });
+  test("legacy spark address encodes known identity public key", () => {
+    const address =
+      "sprt1pgssx63fa5g6uyv450rajp5ndwy9laxzpsp9e37su58jddmcdsvhgm5n7y0ud6";
+    const network = getNetworkFromSparkAddress(address);
+    expect(network).toBe("REGTEST");
+    const decoded = decodeSparkAddress(address, network);
+    expect(decoded.identityPublicKey).toBe(
+      "036a29ed11ae1195a3c7d906936b885ff4c20c025cc7d0e50f26b7786c19746e93",
+    );
+  });
   test("known spark address decodes and encodes to the same address", () => {
     const address =
-      "sprt1pgss8stv8nfkamyea7mtc8werley55anfnnpgtnglff0wmxwm52mkyk6zfeqsqgjzqqe3dvr6e48l2alnpagf7ny3vlj5pr5v4ehgv3pqwd7wxx3awkku9p3epk73na6hcf9220h8kue2tmlkqx8tcrfpsf5ywsvpzgd9px9qcgvpzy8ecp35fg2yq4r39r4njq3slgcul7laarh9sndex9uejz7vwrcrz4g7n4egvwt5yspvsdyped46sflczvrzh0jzksgqnvaqlk02cz4vkwjrkwuep9zsrz5vmjp7mqxq7762tfjczy07at2fvzd7cgk2sqsxrmqdxnpy464rmq2nzdqzpuhme";
+      "sparkrt1pgssx5us3wkqjza8g80xz3a9gznx25msq6g3ty8exfym9q3ahcv86vsnzffssqgjzqqejta89sa8su5f05g0vunfzzkj5zr5v4ehgnt9d4hnyggr2wgghtqfpwn5rhnpg7j5pfn92dcqdyg4jrunyjdjsg7muxraxgfn5zcgs8dcr3sxzrqdetshygps36q8rfqg49d0p0447trnpyxh9f76kt9cwrfx4342jym5emx049chkfsz6j9qc0z8cl7ymmsckx42k76c2qm5f5n5kfvyd26x78eyw0ygs502vg42n8ls";
     const decoded = bech32mDecode(address as SparkAddressFormat);
     const payload = SparkAddress.decode(bech32m.fromWords(decoded.words));
 
@@ -262,40 +294,39 @@ describe("knownSparkAddress", () => {
 
   test("known spark address decodes to expected fields", () => {
     const address =
-      "sprt1pgss8stv8nfkamyea7mtc8werley55anfnnpgtnglff0wmxwm52mkyk6zfeqsqgjzqqe3dvr6e48l2alnpagf7ny3vl35fg2yq4r39r4njq3slgcul7laarh9sndex9uejz7vwrcrz4g7n4egvwt5yspvs4qgar9wd6ryggrn0n3350t44hpgvwgdh5vlw47zf2jnaeahx2j7lasp367q6gvzdpr5rqgjrfgf3gxzrqg3p7wqvdyped46sflczvrzh0jzksgqnvaqlk02cz4vkwjrkwuep9zsrz5vmjp7mqxq7762tfjczy07at2fvzd7cgk2sqsxrmqdxnpy464rmq2nzdqneal34";
-
+      "sparkrt1pgssx5us3wkqjza8g80xz3a9gznx25msq6g3ty8exfym9q3ahcv86vsnzfmssqgjzqqejtaxmwj8ms9rn58574nvlq4j5zr5v4ehgnt9d4hnyggr2wgghtqfpwn5rhnpg7j5pfn92dcqdyg4jrunyjdjsg7muxraxgfn5rqgandgr3sxzrqdmew8qydzvz3qpylysylkgcaw9vpm2jzspls0qtr5kfmlwz244rvuk25w5w2sgc2pyqsraqdyp8tf57a6cn2egttaas9ms3whssenmjqt8wag3lgyvdzjskfeupt8xwwdx4agxdm9f0wefzj28jmdxqeudwcwdj9vfl9sdr65x06r0tasf5fwz2";
     const decoded = decodeSparkAddress(address, "REGTEST");
 
     expect(decoded.network).toBe("REGTEST");
     expect(decoded.identityPublicKey).toBe(
-      "03c16c3cd36eec99efb6bc1dd91ff24a53b34ce6142e68fa52f76ccedd15bb12da",
+      "0353908bac090ba741de6147a540a665537006911590f93249b2823dbe187d3213",
     );
 
     const f = decoded.sparkInvoiceFields!;
     expect(f.version).toBe(1);
-    expect(f.id).toBe("0198b583-d66a-7fab-bf98-7a84fa648b3f");
+    expect(f.id).toBe("01992fa6-dba4-7dc0-a39d-0f4f566cf82b");
 
     expect(f.paymentType?.type).toBe("tokens");
     expect(
       f.paymentType && "tokenIdentifier" in f.paymentType
         ? f.paymentType.tokenIdentifier
         : undefined,
-    ).toBe("2a3894759c81187d18e7fdfef4772c26dc98bccc85e6387818aa8f4eb9431cba");
+    ).toBe("093e4813f6463ae2b03b548500fe0f02c74b277f70955a8d9cb2a8ea39504614");
     expect(
       f.paymentType && "amount" in f.paymentType
         ? f.paymentType.amount
         : undefined,
-    ).toBe(100n);
+    ).toBe(1000n);
 
-    expect(f.memo).toBe("test");
+    expect(f.memo).toBe("testMemo");
     expect(f.senderPublicKey).toBe(
-      "039be718d1ebad6e1431c86de8cfbabe125529f73db9952f7fb00c75e0690c1342",
+      "0353908bac090ba741de6147a540a665537006911590f93249b2823dbe187d3213",
     );
 
-    expect(f.expiryTime?.toISOString()).toBe("2025-08-17T00:57:52.969Z");
+    expect(f.expiryTime?.toISOString()).toBe("2025-09-09T18:09:48.419Z");
 
     expect(decoded.signature).toBe(
-      "e5b5d413fc098315df215a0804d9d07ecf56055659d21d9dcc84a280c5466e41f6c0607bda52d32c088ff756a4b04df61165401030f6069a61257551ec0a989a",
+      "9d69a7bbac4d5942d7dec0bb845d784333dc80b3bba88fd046345285939e0567339cd357a8337654bdd948a4a3cb6d3033c6bb0e6c8ac4fcb068f5433f437afb",
     );
   });
 });

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

@@ -12,7 +12,7 @@ describe("address", () => {
   ])(
     ".seedOrMnemonic(%s)",
     (seedOrMnemonic) => {
-      test.each([["LOCAL", "spl", "bcrt"]])(
+      test.each([["LOCAL", "sparkl", "bcrt"]])(
         `.network(%s)`,
         async (network, sparkAddressPrefix, blockchainAddressPrefix) => {
           const options: ConfigOptions = {

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

@@ -0,0 +1,83 @@
+import { walletTypes, createDeterministicKeys } from "../test-utils.js";
+import { SparkWalletTesting } from "../utils/spark-testing-wallet.js";
+import { WalletConfigService } from "../../services/config.js";
+import { ConnectionManager } from "../../services/connection.js";
+import { TokenTransactionService } from "../../services/token-transactions.js";
+import { ValidationError } from "../../errors/types.js";
+
+describe.each(walletTypes)(
+  "fetch owned token outputs should fail with invalid inputs",
+  ({ Signer }) => {
+    let tokenTransactionService: TokenTransactionService;
+
+    beforeEach(async () => {
+      const userWallet = await SparkWalletTesting.initialize({
+        options: {
+          network: "LOCAL",
+          tokenTransactionVersion: "V1",
+        },
+        signer: new Signer(),
+      });
+      const wallet = userWallet.wallet;
+
+      const userConfig = new WalletConfigService(
+        {
+          network: "LOCAL",
+        },
+        wallet.getSigner(),
+      );
+      const connectionManager = new ConnectionManager(userConfig);
+      tokenTransactionService = new TokenTransactionService(
+        userConfig,
+        connectionManager,
+      );
+    });
+
+    it("should fail with empty owner public keys", async () => {
+      await expect(
+        tokenTransactionService.fetchOwnedTokenOutputs({
+          ownerPublicKeys: [],
+        }),
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it("should fail with malformed owner public key", async () => {
+      const malformedKey = new Uint8Array(32).fill(1);
+
+      await expect(
+        tokenTransactionService.fetchOwnedTokenOutputs({
+          ownerPublicKeys: [malformedKey],
+        }),
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it("should fail with malformed issuer public key", async () => {
+      const { publicKey } = createDeterministicKeys(
+        expect.getState().currentTestName!,
+      );
+      const malformedKey = new Uint8Array(32).fill(1);
+
+      await expect(
+        tokenTransactionService.fetchOwnedTokenOutputs({
+          ownerPublicKeys: [publicKey],
+          issuerPublicKeys: [malformedKey],
+        }),
+      ).rejects.toThrow(ValidationError);
+    });
+
+    it("should fail with malformed token identifier", async () => {
+      const { publicKey } = createDeterministicKeys(
+        expect.getState().currentTestName!,
+      );
+      const malformedIdentifier = new Uint8Array(99).fill(1);
+
+      await expect(
+        tokenTransactionService.fetchOwnedTokenOutputs({
+          ownerPublicKeys: [publicKey],
+          issuerPublicKeys: [publicKey],
+          tokenIdentifiers: [malformedIdentifier],
+        }),
+      ).rejects.toThrow(ValidationError);
+    });
+  },
+);