@buildonspark/spark-sdk 0.1.41 → 0.1.43

package/src/native/index.ts

@@ -4,4 +4,5 @@ export { ReactNativeSparkSigner } from "../signer/signer.react-native.js";
 export { ReactNativeSparkSigner as DefaultSparkSigner } from "../signer/signer.react-native.js";
 export { SparkWallet } from "../spark-wallet/spark-wallet.js";
 export { getLatestDepositTxId } from "../utils/mempool.js";
+export { createDummyTx } from "../spark_bindings/native/index.js";
 export * from "../utils/index.js";

package/src/services/config.ts

@@ -118,6 +118,10 @@ export class WalletConfigService
     return this.config.tokenTransactionVersion;
   }
 
+  public getTokenValidityDurationSeconds(): number {
+    return this.config.tokenValidityDurationSeconds;
+  }
+
   public getElectrsUrl(): string {
     return this.config.electrsUrl;
   }

package/src/services/connection.ts

@@ -7,7 +7,7 @@ import type {
   Channel as ChannelWeb,
   ClientFactory as ClientFactoryWeb,
 } from "nice-grpc-web";
-import { isBun, isReactNative } from "../constants.js";
+import { isBun, isReactNative, clientEnv } from "../constants.js";
 import { AuthenticationError, NetworkError } from "../errors/types.js";
 import { MockServiceClient, MockServiceDefinition } from "../proto/mock.js";
 import { SparkServiceClient, SparkServiceDefinition } from "../proto/spark.js";
@@ -283,13 +283,50 @@ export class ConnectionManager {
     certPath?: string,
   ): Promise<SparkAuthnServiceClient & { close?: () => void }> {
     const channel = await this.createChannelWithTLS(address, certPath);
+    const authnMiddleware = this.createAuthnMiddleware();
     return this.createGrpcClient<SparkAuthnServiceClient>(
       SparkAuthnServiceDefinition,
       channel,
       false,
+      authnMiddleware,
     );
   }
 
+  private createAuthnMiddleware() {
+    if (isNode) {
+      return async function* (
+        this: ConnectionManager,
+        call: ClientMiddlewareCall<any, any>,
+        options: SparkCallOptions,
+      ) {
+        const metadata = Metadata(options.metadata).set(
+          "X-Client-Env",
+          clientEnv,
+        );
+        return yield* call.next(call.request, {
+          ...options,
+          metadata,
+        });
+      }.bind(this);
+    } else {
+      return async function* (
+        this: ConnectionManager,
+        call: ClientMiddlewareCall<any, any>,
+        options: SparkCallOptions,
+      ) {
+        const metadata = Metadata(options.metadata)
+          .set("X-Requested-With", "XMLHttpRequest")
+          .set("X-Grpc-Web", "1")
+          .set("X-Client-Env", clientEnv)
+          .set("Content-Type", "application/grpc-web+proto");
+        return yield* call.next(call.request, {
+          ...options,
+          metadata,
+        });
+      }.bind(this);
+    }
+  }
+
   private createMiddleware(address: string, authToken: string) {
     if (isNode) {
       return this.createNodeMiddleware(address, authToken);
@@ -304,27 +341,30 @@ export class ConnectionManager {
       call: ClientMiddlewareCall<any, any>,
       options: SparkCallOptions,
     ) {
+      const metadata = Metadata(options.metadata).set(
+        "X-Client-Env",
+        clientEnv,
+      );
       try {
         return yield* call.next(call.request, {
           ...options,
-          metadata: Metadata(options.metadata)
-            .set(
-              "Authorization",
-              `Bearer ${this.clients.get(address)?.authToken || initialAuthToken}`,
-            )
-            .set("User-Agent", "spark-js-sdk"),
+          metadata: metadata.set(
+            "Authorization",
+            `Bearer ${this.clients.get(address)?.authToken || initialAuthToken}`,
+          ),
         });
       } catch (error: any) {
         if (error.message?.includes("token has expired")) {
           const newAuthToken = await this.authenticate(address);
-          // @ts-ignore - We can only get here if the client exists
-          this.clients.get(address).authToken = newAuthToken;
+          const clientData = this.clients.get(address);
+          if (!clientData) {
+            throw new Error(`No client found for address: ${address}`);
+          }
+          clientData.authToken = newAuthToken;
 
           return yield* call.next(call.request, {
             ...options,
-            metadata: Metadata(options.metadata)
-              .set("Authorization", `Bearer ${newAuthToken}`)
-              .set("User-Agent", "spark-js-sdk"),
+            metadata: metadata.set("Authorization", `Bearer ${newAuthToken}`),
           });
         }
         throw error;
@@ -338,33 +378,32 @@ export class ConnectionManager {
       call: ClientMiddlewareCall<any, any>,
       options: SparkCallOptions,
     ) {
+      const metadata = Metadata(options.metadata)
+        .set("X-Requested-With", "XMLHttpRequest")
+        .set("X-Grpc-Web", "1")
+        .set("X-Client-Env", clientEnv)
+        .set("Content-Type", "application/grpc-web+proto");
+
       try {
         return yield* call.next(call.request, {
           ...options,
-          metadata: Metadata(options.metadata)
-            .set(
-              "Authorization",
-              `Bearer ${this.clients.get(address)?.authToken || initialAuthToken}`,
-            )
-            .set("X-Requested-With", "XMLHttpRequest")
-            .set("X-Grpc-Web", "1")
-            .set("Content-Type", "application/grpc-web+proto")
-            .set("User-Agent", "spark-js-sdk"),
+          metadata: metadata.set(
+            "Authorization",
+            `Bearer ${this.clients.get(address)?.authToken || initialAuthToken}`,
+          ),
         });
       } catch (error: any) {
         if (error.message?.includes("token has expired")) {
           const newAuthToken = await this.authenticate(address);
-          // @ts-ignore - We can only get here if the client exists
-          this.clients.get(address).authToken = newAuthToken;
+          const clientData = this.clients.get(address);
+          if (!clientData) {
+            throw new Error(`No client found for address: ${address}`);
+          }
+          clientData.authToken = newAuthToken;
 
           return yield* call.next(call.request, {
             ...options,
-            metadata: Metadata(options.metadata)
-              .set("Authorization", `Bearer ${newAuthToken}`)
-              .set("X-Requested-With", "XMLHttpRequest")
-              .set("X-Grpc-Web", "1")
-              .set("Content-Type", "application/grpc-web+proto")
-              .set("User-Agent", "spark-js-sdk"),
+            metadata: metadata.set("Authorization", `Bearer ${newAuthToken}`),
           });
         }
         throw error;

package/src/services/coop-exit.ts

@@ -50,7 +50,7 @@ export class CoopExitService extends BaseTransferService {
       connectorOutputs,
       receiverPubKey,
     );
-    const transferTweak = await this.sendTransferTweakKey(
+    const transferTweak = await this.deliverTransferPackage(
       transfer,
       leaves,
       signaturesMap,

package/src/services/lightning.ts

@@ -52,6 +52,7 @@ export type SwapNodesForPreimageParams = {
   invoiceString?: string;
   isInboundPayment: boolean;
   feeSats?: number;
+  amountSatsToSend?: number;
 };
 
 export class LightningService {
@@ -182,6 +183,7 @@ export class LightningService {
     invoiceString,
     isInboundPayment,
     feeSats = 0,
+    amountSatsToSend,
   }: SwapNodesForPreimageParams): Promise<InitiatePreimageSwapResponse> {
     const sparkClient = await this.connectionManager.createSparkClient(
       this.config.getCoordinatorAddress(),
@@ -222,7 +224,29 @@ export class LightningService {
         console.error("Error decoding invoice", error);
       }
 
-      amountSats = amountMsats / 1000;
+      const isZeroAmountInvoice = !amountMsats;
+
+      if (isZeroAmountInvoice && amountSatsToSend === undefined) {
+        throw new ValidationError(
+          "Invalid amount. User must specify amountSatsToSend for 0 amount lightning invoice",
+          {
+            field: "amountSatsToSend",
+            value: amountSatsToSend,
+            expected: "positive number",
+          },
+        );
+      }
+
+      amountSats = isZeroAmountInvoice ? amountSatsToSend! : amountMsats / 1000;
+
+      if (isNaN(amountSats) || amountSats <= 0) {
+        throw new ValidationError("Invalid amount", {
+          field: "amountSats",
+          value: amountSats,
+          expected: "greater than 0",
+        });
+      }
+
       bolt11String = invoiceString;
     }
 

package/src/services/lrc-connection.ts

@@ -6,7 +6,7 @@ import type {
   Channel as ChannelWeb,
   ClientFactory as ClientFactoryWeb,
 } from "nice-grpc-web";
-import { isBun, isReactNative } from "../constants.js";
+import { isBun, isReactNative, clientEnv } from "../constants.js";
 import { NetworkError } from "../errors/types.js";
 import { SparkServiceClient, SparkServiceDefinition } from "../proto/lrc20.js";
 import { RetryOptions, SparkCallOptions } from "../types/grpc.js";
@@ -126,7 +126,7 @@ export class Lrc20ConnectionManager {
     ) {
       return yield* call.next(call.request, {
         ...options,
-        metadata: Metadata(options.metadata).set("User-Agent", "spark-js-sdk"),
+        metadata: Metadata(options.metadata).set("X-Client-Env", clientEnv),
       });
     }.bind(this);
   }
@@ -143,7 +143,7 @@ export class Lrc20ConnectionManager {
           .set("X-Requested-With", "XMLHttpRequest")
           .set("X-Grpc-Web", "1")
           .set("Content-Type", "application/grpc-web+proto")
-          .set("User-Agent", "spark-js-sdk"),
+          .set("X-Client-Env", clientEnv),
       });
     }.bind(this);
   }

package/src/services/token-transactions.ts

@@ -14,6 +14,7 @@ import { secp256k1 } from "@noble/curves/secp256k1";
 import { SparkCallOptions } from "../types/grpc.js";
 import {
   hashOperatorSpecificTokenTransactionSignablePayload,
+  hashTokenTransactionV0,
   hashTokenTransaction,
 } from "../utils/token-hashing.js";
 import {
@@ -456,7 +457,7 @@ export class TokenTransactionService {
       this.config.getCoordinatorAddress(),
     );
 
-    const partialTokenTransactionHash = hashTokenTransaction(
+    const partialTokenTransactionHash = hashTokenTransactionV0(
       tokenTransaction,
       true,
     );
@@ -547,7 +548,7 @@ export class TokenTransactionService {
     );
 
     const finalTokenTransaction = startResponse.finalTokenTransaction;
-    const finalTokenTransactionHash = hashTokenTransaction(
+    const finalTokenTransactionHash = hashTokenTransactionV0(
       finalTokenTransaction,
       false,
     );
@@ -635,6 +636,9 @@ export class TokenTransactionService {
       {
         identityPublicKey: await this.config.signer.getIdentityPublicKey(),
         partialTokenTransaction: tokenTransaction,
+        validityDurationSeconds:
+          await this.config.getTokenValidityDurationSeconds(),
+        partialTokenTransactionOwnerSignatures: ownerSignaturesWithIndex,
       },
       {
         retry: true,

package/src/services/wallet-config.ts

@@ -141,6 +141,7 @@ export type ConfigOptions = MayHaveLrc20WalletApiConfig &
     readonly lrc20Address?: string;
     readonly threshold?: number;
     readonly tokenSignatures?: "ECDSA" | "SCHNORR";
+    readonly tokenValidityDurationSeconds?: number;
     readonly tokenTransactionVersion?: "V0" | "V1";
     readonly electrsUrl?: string;
     readonly lrc20ApiConfig?: LRC20WalletApiConfig;
@@ -175,6 +176,7 @@ const BASE_CONFIG: Required<ConfigOptions> = {
   signingOperators: getLocalSigningOperators(),
   tokenSignatures: "SCHNORR",
   tokenTransactionVersion: "V0",
+  tokenValidityDurationSeconds: 180,
   electrsUrl: getElectrsUrl("LOCAL"),
   expectedWithdrawBondSats: 10000,
   expectedWithdrawRelativeBlockLocktime: 1000,

package/src/signer/signer.ts

@@ -48,6 +48,9 @@ import { Transaction } from "@scure/btc-signer";
 import { taprootTweakPrivKey } from "@scure/btc-signer/utils";
 import type { Psbt } from "bitcoinjs-lib";
 
+export { Receipt, PARITY, fromPrivateKey } from "@buildonspark/lrc20-sdk";
+export { MultisigReceiptInput } from "@buildonspark/lrc20-sdk/lrc/types";
+
 export type SigningNonce = {
   binding: Uint8Array;
   hiding: Uint8Array;
@@ -934,4 +937,4 @@ class TaprootSparkSigner extends DefaultSparkSigner {
 }
 
 export { DefaultSparkSigner, TaprootSparkSigner, TaprootOutputKeysGenerator };
-export type { SparkSigner };
+export type { SparkSigner, TokenSigner };

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

@@ -2532,12 +2532,14 @@ export class SparkWallet extends EventEmitter {
    * @param {Object} params - Parameters for paying the invoice
    * @param {string} params.invoice - The BOLT11-encoded Lightning invoice to pay
    * @param {boolean} [params.preferSpark] - Whether to prefer a spark transfer over lightning for the payment
+   * @param {number} [params.amountSatsToSend] - The amount in sats to send. This is only valid for 0 amount lightning invoices.
    * @returns {Promise<LightningSendRequest>} The Lightning payment request details
    */
   public async payLightningInvoice({
     invoice,
     maxFeeSats,
     preferSpark = false,
+    amountSatsToSend,
   }: PayLightningInvoiceParams) {
     const invoiceNetwork = getNetworkFromInvoice(invoice);
     const walletNetwork = this.config.getNetwork();
@@ -2553,10 +2555,45 @@ export class SparkWallet extends EventEmitter {
     }
 
     const decodedInvoice = decodeInvoice(invoice);
-    const amountSats =
-      decodedInvoice.amountMSats !== null
-        ? Number(decodedInvoice.amountMSats / 1000n)
-        : 0;
+    const amountMSats = decodedInvoice.amountMSats;
+    const isZeroAmountInvoice = !amountMSats;
+
+    // Check if user is trying to send amountSatsToSend for non 0 amount lightning invoice
+    if (!isZeroAmountInvoice && amountSatsToSend !== undefined) {
+      throw new ValidationError(
+        "Invalid amount. User can only specify amountSatsToSend for 0 amount lightning invoice",
+        {
+          field: "amountMSats",
+          value: Number(amountMSats),
+          expected: "0",
+        },
+      );
+    }
+
+    // If 0 amount lightning invoice, check that user has specified amountSatsToSend
+    if (isZeroAmountInvoice && amountSatsToSend === undefined) {
+      throw new ValidationError(
+        "Invalid amount. User must specify amountSatsToSend for 0 amount lightning invoice",
+        {
+          field: "amountMSats",
+          value: Number(amountMSats),
+          expected: "0",
+        },
+      );
+    }
+
+    const amountSats = isZeroAmountInvoice
+      ? amountSatsToSend!
+      : Number(amountMSats / 1000n);
+
+    if (isNaN(amountSats) || amountSats <= 0) {
+      throw new ValidationError("Invalid amount", {
+        field: "amountSats",
+        value: amountSats,
+        expected: "greater than 0",
+      });
+    }
+
     const sparkFallbackAddress = decodedInvoice.fallbackAddress;
     const paymentHash = decodedInvoice.paymentHash;
 
@@ -2586,16 +2623,10 @@ export class SparkWallet extends EventEmitter {
     return await this.withLeaves(async () => {
       const sspClient = this.getSspClient();
 
-      if (isNaN(amountSats) || amountSats <= 0) {
-        throw new ValidationError("Invalid amount", {
-          field: "amountSats",
-          value: amountSats,
-          expected: "positive number",
-        });
-      }
-
+      // If 0 amount lightning invoice, use amountSatsToSend for fee estimate
       const feeEstimate = await this.getLightningSendFeeEstimate({
         encodedInvoice: invoice,
+        amountSats: isZeroAmountInvoice ? amountSatsToSend! : undefined,
       });
 
       if (maxFeeSats < feeEstimate) {
@@ -2641,13 +2672,14 @@ export class SparkWallet extends EventEmitter {
         isInboundPayment: false,
         invoiceString: invoice,
         feeSats: feeEstimate,
+        amountSatsToSend: amountSatsToSend,
       });
 
       if (!swapResponse.transfer) {
         throw new Error("Failed to swap nodes for preimage");
       }
 
-      const transfer = await this.transferService.sendTransferTweakKey(
+      await this.transferService.deliverTransferPackage(
         swapResponse.transfer,
         leavesToSend,
         new Map(),
@@ -2656,6 +2688,7 @@ export class SparkWallet extends EventEmitter {
       const sspResponse = await sspClient.requestLightningSend({
         encodedInvoice: invoice,
         idempotencyKey: paymentHash,
+        amountSats: isZeroAmountInvoice ? amountSatsToSend! : undefined,
       });
 
       if (!sspResponse) {
@@ -2677,11 +2710,14 @@ export class SparkWallet extends EventEmitter {
    */
   public async getLightningSendFeeEstimate({
     encodedInvoice,
+    amountSats,
   }: LightningSendFeeEstimateInput): Promise<number> {
     const sspClient = this.getSspClient();
 
-    const feeEstimate =
-      await sspClient.getLightningSendFeeEstimate(encodedInvoice);
+    const feeEstimate = await sspClient.getLightningSendFeeEstimate(
+      encodedInvoice,
+      amountSats,
+    );
 
     if (!feeEstimate) {
       throw new Error("Failed to get lightning send fee estimate");

package/src/spark-wallet/types.ts

@@ -15,6 +15,7 @@ export type PayLightningInvoiceParams = {
   invoice: string;
   maxFeeSats: number;
   preferSpark?: boolean;
+  amountSatsToSend?: number;
 };
 
 export type TransferParams = {

package/src/tests/errors.test.ts

@@ -0,0 +1,58 @@
+import { SparkSDKError } from "../errors/base.js";
+
+describe("SparkSDKError", () => {
+  it("should not throw and should stringify BigInt values in context", () => {
+    const bigNumber = 123n;
+
+    const err = new SparkSDKError("Test BigInt", { big: bigNumber });
+
+    expect(err.message).toContain("Context:");
+    // BigInt should be converted to a string representation
+    expect(err.message).toContain('big: "123"');
+  });
+
+  it("should stringify regular primitives correctly", () => {
+    const err = new SparkSDKError("Test primitives", {
+      num: 1,
+      str: "abc",
+      bool: true,
+    });
+
+    expect(err.message).toContain("num: 1");
+    expect(err.message).toContain('str: "abc"');
+    expect(err.message).toContain("bool: true");
+  });
+
+  it("should include original error message when provided", () => {
+    const original = new Error("something broke");
+    const err = new SparkSDKError("Wrapper error", {}, original);
+
+    expect(err.message).toContain("Original Error: something broke");
+  });
+
+  it("should stringify Uint8Array values correctly", () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    const err = new SparkSDKError("Uint8Array test", { bytes });
+
+    expect(err.message).toContain("bytes:");
+    expect(err.message).toMatch(/Uint8Array\(0x010203\)/);
+  });
+
+  it("should generate the correct full error message", () => {
+    const original = new Error("root cause");
+    const context = {
+      big: 123n,
+      bytes: new Uint8Array([1, 2, 3]),
+      num: 42,
+    } as const;
+
+    const err = new SparkSDKError("Something went wrong", context, original);
+
+    const expectedMessage =
+      "SparkSDKError: Something went wrong\n" +
+      'Context: big: "123", bytes: "Uint8Array(0x010203)", num: 42\n' +
+      "Original Error: root cause";
+
+    expect(err.message).toBe(expectedMessage);
+  });
+});