@buildonspark/spark-sdk 0.1.34 → 0.1.36

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

@@ -37,12 +37,14 @@ import {
 import {
   DepositAddressQueryResult,
   OutputWithPreviousTransactionData,
+  SigningJob,
   SubscribeToEventsResponse,
   TokenTransactionWithStatus,
   Transfer,
   TransferStatus,
   TransferType,
   TreeNode,
+  UtxoSwapRequestType,
 } from "../proto/spark.js";
 import { WalletConfigService } from "../services/config.js";
 import { ConnectionManager } from "../services/connection.js";
@@ -119,6 +121,7 @@ import type {
   TokenInfo,
   TransferParams,
 } from "./types.js";
+import { networkToJSON } from "../proto/spark.js";
 
 /**
  * The SparkWallet class is the primary interface for interacting with the Spark network.
@@ -1196,7 +1199,7 @@ export class SparkWallet extends EventEmitter {
     return address.depositAddress.address;
   }
 
-  private async queryStaticDepositAddresses(): Promise<string[]> {
+  public async queryStaticDepositAddresses(): Promise<string[]> {
     const sparkClient = await this.connectionManager.createSparkClient(
       this.config.getCoordinatorAddress(),
     );
@@ -1286,6 +1289,7 @@ export class SparkWallet extends EventEmitter {
       transactionId,
       outputIndex,
       network.toLowerCase(),
+      UtxoSwapRequestType.Fixed,
       creditAmountSats,
       sspSignature,
     );
@@ -1312,10 +1316,173 @@ export class SparkWallet extends EventEmitter {
     return response;
   }
 
+  /**
+   * Refunds a static deposit to a destination address.
+   *
+   * @param {string} depositTransactionId - The ID of the transaction
+   * @param {number} [outputIndex] - The index of the output
+   * @param {string} destinationAddress - The destination address
+   * @param {number} fee - The fee to refund
+   * @returns {Promise<string>} The hex of the refund transaction
+   */
+  public async refundStaticDeposit({
+    depositTransactionId,
+    outputIndex,
+    destinationAddress,
+    fee,
+  }: {
+    depositTransactionId: string;
+    outputIndex?: number;
+    destinationAddress: string;
+    fee: number;
+  }): Promise<string> {
+    if (fee <= 300) {
+      throw new ValidationError("Fee must be greater than 300", {
+        field: "fee",
+        value: fee,
+      });
+    }
+
+    let network = this.config.getNetwork();
+    let networkType = this.config.getNetworkProto();
+    const networkJSON = networkToJSON(networkType);
+
+    const depositTx = await this.getDepositTransaction(depositTransactionId);
+
+    if (outputIndex === undefined) {
+      outputIndex = await this.getDepositTransactionVout(depositTransactionId);
+    }
+
+    const totalAmount = depositTx.getOutput(outputIndex).amount;
+    const creditAmountSats = Number(totalAmount) - fee;
+
+    if (creditAmountSats <= 0) {
+      throw new ValidationError(
+        "Fee too large. Credit amount must be greater than 0",
+        {
+          field: "creditAmountSats",
+          value: creditAmountSats,
+        },
+      );
+    }
+
+    const tx = new Transaction();
+
+    tx.addInput({
+      txid: depositTransactionId,
+      index: outputIndex,
+      witnessScript: new Uint8Array(),
+    });
+
+    // Decode the address and create output script
+    const addressDecoded = Address(getNetwork(network)).decode(
+      destinationAddress,
+    );
+    const outputScript = OutScript.encode(addressDecoded);
+
+    // Add the output to the transaction
+    tx.addOutput({
+      script: outputScript,
+      amount: BigInt(creditAmountSats),
+    });
+
+    const spendTxSighash = getSigHashFromTx(
+      tx,
+      0,
+      depositTx.getOutput(outputIndex),
+    );
+
+    // Used in the signing job and frost.
+    const signingNonceCommitment =
+      await this.config.signer.getRandomSigningCommitment();
+
+    const signingJob: SigningJob = {
+      rawTx: tx.toBytes(),
+      signingPublicKey: await this.config.signer.getStaticDepositSigningKey(0),
+      signingNonceCommitment: signingNonceCommitment,
+    };
+
+    const message = await this.getStaticDepositSigningPayload(
+      depositTransactionId,
+      outputIndex,
+      networkJSON.toLowerCase(),
+      UtxoSwapRequestType.Refund,
+      creditAmountSats,
+      bytesToHex(spendTxSighash),
+    );
+    const hashBuffer = sha256(message);
+    const swapResponseUserSignature =
+      await this.config.signer.signMessageWithIdentityKey(hashBuffer);
+
+    const sparkClient = await this.connectionManager.createSparkClient(
+      this.config.getCoordinatorAddress(),
+    );
+
+    const transferId = uuidv7();
+
+    // Initiate Utxo Swap
+    const swapResponse = await sparkClient.initiate_utxo_swap({
+      onChainUtxo: {
+        txid: hexToBytes(depositTransactionId),
+        vout: outputIndex,
+        network: networkType,
+      },
+      requestType: UtxoSwapRequestType.Refund,
+      amount: {
+        creditAmountSats: 0,
+        $case: "creditAmountSats",
+      },
+      userSignature: swapResponseUserSignature,
+      sspSignature: new Uint8Array(),
+      transfer: {
+        transferId: transferId,
+        ownerIdentityPublicKey: await this.config.signer.getIdentityPublicKey(),
+        receiverIdentityPublicKey:
+          await this.config.signer.getIdentityPublicKey(),
+      },
+      spendTxSigningJob: signingJob,
+    });
+
+    if (!swapResponse) {
+      throw new Error("Failed to initiate utxo swap");
+    }
+
+    // Sign the spend tx
+    const userSignature = await this.config.signer.signFrost({
+      message: spendTxSighash,
+      publicKey: swapResponse.depositAddress!.verifyingPublicKey,
+      privateAsPubKey: await this.config.signer.getStaticDepositSigningKey(0),
+      selfCommitment: signingNonceCommitment,
+      statechainCommitments:
+        swapResponse.spendTxSigningResult!.signingNonceCommitments,
+      verifyingKey: swapResponse.depositAddress!.verifyingPublicKey,
+    });
+
+    const signatureResult = await this.config.signer.aggregateFrost({
+      message: spendTxSighash,
+      statechainSignatures: swapResponse.spendTxSigningResult!.signatureShares,
+      statechainPublicKeys: swapResponse.spendTxSigningResult!.publicKeys,
+      verifyingKey: swapResponse.depositAddress!.verifyingPublicKey,
+      statechainCommitments:
+        swapResponse.spendTxSigningResult!.signingNonceCommitments,
+      selfCommitment: signingNonceCommitment,
+      publicKey: await this.config.signer.getStaticDepositSigningKey(0),
+      selfSignature: userSignature,
+    });
+
+    // Update the input with the signature
+    tx.updateInput(0, {
+      finalScriptWitness: [signatureResult],
+    });
+
+    return tx.hex;
+  }
+
   private async getStaticDepositSigningPayload(
     transactionID: string,
     outputIndex: number,
     network: string,
+    requestType: UtxoSwapRequestType,
     creditAmountSats: number,
     sspSignature: string,
   ): Promise<Uint8Array> {
@@ -1337,9 +1504,22 @@ export class SparkWallet extends EventEmitter {
     new DataView(outputIndexBuffer).setUint32(0, outputIndex, true); // true for little-endian
     parts.push(new Uint8Array(outputIndexBuffer));
 
-    // Request type fixed amount (0)
+    let requestTypeInt: number;
+    switch (requestType) {
+      case UtxoSwapRequestType.Fixed:
+        requestTypeInt = 0;
+        break;
+      case UtxoSwapRequestType.MaxFee:
+        requestTypeInt = 1;
+        break;
+      case UtxoSwapRequestType.Refund:
+        requestTypeInt = 2;
+        break;
+      default:
+        requestTypeInt = 0;
+    }
     const requestTypeBuffer = new ArrayBuffer(1);
-    new DataView(requestTypeBuffer).setUint8(0, 0);
+    new DataView(requestTypeBuffer).setUint8(0, requestTypeInt);
     parts.push(new Uint8Array(requestTypeBuffer));
 
     // Add credit amount as 8-byte unsigned integer (little-endian)
@@ -1371,6 +1551,37 @@ export class SparkWallet extends EventEmitter {
   }
 
   private async getDepositTransactionVout(txid: string): Promise<number> {
+    const depositTx = await this.getDepositTransaction(txid);
+
+    const staticDepositAddresses = new Set(
+      await this.queryStaticDepositAddresses(),
+    );
+
+    let vout = -1;
+
+    for (let i = 0; i < depositTx.outputsLength; i++) {
+      const output = depositTx.getOutput(i);
+      if (!output) {
+        continue;
+      }
+      const parsedScript = OutScript.decode(output.script!);
+      const address = Address(getNetwork(this.config.getNetwork())).encode(
+        parsedScript,
+      );
+      if (staticDepositAddresses.has(address)) {
+        vout = i;
+        break;
+      }
+    }
+
+    if (vout === -1) {
+      throw new Error("No static deposit address found");
+    }
+
+    return vout;
+  }
+
+  private async getDepositTransaction(txid: string): Promise<Transaction> {
     if (!txid) {
       throw new ValidationError("Transaction ID cannot be empty", {
         field: "txid",
@@ -1413,32 +1624,7 @@ export class SparkWallet extends EventEmitter {
     }
     const depositTx = getTxFromRawTxHex(txHex);
 
-    const staticDepositAddresses = new Set(
-      await this.queryStaticDepositAddresses(),
-    );
-
-    let vout = -1;
-
-    for (let i = 0; i < depositTx.outputsLength; i++) {
-      const output = depositTx.getOutput(i);
-      if (!output) {
-        continue;
-      }
-      const parsedScript = OutScript.decode(output.script!);
-      const address = Address(getNetwork(this.config.getNetwork())).encode(
-        parsedScript,
-      );
-      if (staticDepositAddresses.has(address)) {
-        vout = i;
-        break;
-      }
-    }
-
-    if (vout === -1) {
-      throw new Error("No static deposit address found");
-    }
-
-    return vout;
+    return depositTx;
   }
 
   /**
@@ -1963,7 +2149,10 @@ export class SparkWallet extends EventEmitter {
             const leafPubKey = leafPubKeyMap.get(leaf.leaf.id);
             if (leafPubKey) {
               leavesToClaim.push({
-                leaf: leaf.leaf,
+                leaf: {
+                  ...leaf.leaf,
+                  refundTx: leaf.intermediateRefundTx,
+                },
                 signingPubKey: leafPubKey,
                 newSigningPubKey: await this.config.signer.generatePublicKey(
                   sha256(leaf.leaf.id),
@@ -2094,10 +2283,11 @@ export class SparkWallet extends EventEmitter {
    *
    * @param {Object} params - Parameters for the lightning invoice
    * @param {number} params.amountSats - Amount in satoshis
-   * @param {string} params.memo - Description for the invoice
+   * @param {string} [params.memo] - Description for the invoice. Should not be provided if the descriptionHash is provided.
    * @param {number} [params.expirySeconds] - Optional expiry time in seconds
    * @param {boolean} [params.includeSparkAddress] - Optional boolean signalling whether or not to include the spark address in the invoice
    * @param {string} [params.receiverIdentityPubkey] - Optional public key of the wallet receiving the lightning invoice. If not present, the receiver will be the creator of this request.
+   * @param {string} [params.descriptionHash] - Optional h tag of the invoice. This is the hash of a longer description to include in the lightning invoice. It is used in LNURL and UMA as the hash of the metadata. This field is mutually exclusive with the memo field. Only one or the other should be provided.
    * @returns {Promise<LightningReceiveRequest>} BOLT11 encoded invoice
    */
   public async createLightningInvoice({
@@ -2106,6 +2296,7 @@ export class SparkWallet extends EventEmitter {
     expirySeconds = 60 * 60 * 24 * 30,
     includeSparkAddress = false,
     receiverIdentityPubkey,
+    descriptionHash,
   }: CreateLightningInvoiceParams): Promise<LightningReceiveRequest> {
     const sspClient = this.getSspClient();
 
@@ -2149,11 +2340,23 @@ export class SparkWallet extends EventEmitter {
       });
     }
 
+    if (memo && descriptionHash) {
+      throw new ValidationError(
+        "Memo and descriptionHash cannot be provided together. Please provide only one.",
+        {
+          field: "memo",
+          value: memo,
+          expected: "Memo or descriptionHash",
+        },
+      );
+    }
+
     const requestLightningInvoice = async (
       amountSats: number,
       paymentHash: Uint8Array,
       memo?: string,
       receiverIdentityPubkey?: string,
+      descriptionHash?: string,
     ) => {
       const network = this.config.getNetwork();
       let bitcoinNetwork: BitcoinNetwork = BitcoinNetwork.REGTEST;
@@ -2171,6 +2374,7 @@ export class SparkWallet extends EventEmitter {
         memo,
         includeSparkAddress: includeSparkAddress,
         receiverIdentityPubkey,
+        descriptionHash,
       });
 
       if (!invoice) {
@@ -2221,6 +2425,7 @@ export class SparkWallet extends EventEmitter {
       memo,
       invoiceCreator: requestLightningInvoice,
       receiverIdentityPubkey,
+      descriptionHash,
     });
 
     return invoice;

package/src/spark-wallet/types.ts

@@ -8,6 +8,7 @@ export type CreateLightningInvoiceParams = {
   expirySeconds?: number;
   includeSparkAddress?: boolean;
   receiverIdentityPubkey?: string;
+  descriptionHash?: string;
 };
 
 export type PayLightningInvoiceParams = {

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

@@ -5,6 +5,7 @@ import { getTxId } from "../../utils/bitcoin.js";
 import { getNetwork, Network } from "../../utils/network.js";
 import { SparkWalletTesting } from "../utils/spark-testing-wallet.js";
 import { BitcoinFaucet } from "../utils/test-faucet.js";
+
 describe("deposit", () => {
   it("should generate a deposit address", async () => {
     const { wallet: sdk } = await SparkWalletTesting.initialize({
@@ -209,3 +210,44 @@ describe("deposit", () => {
     expect(balance.balance).toEqual(sendAmount * 2n);
   }, 30000);
 });
+
+describe("refund static deposit", () => {
+  it("should refund a static deposit", async () => {
+    const faucet = BitcoinFaucet.getInstance();
+
+    await faucet.fund();
+
+    const { wallet: sdk } = await SparkWalletTesting.initialize({
+      options: {
+        network: "LOCAL",
+      },
+    });
+
+    const depositAddress = await sdk.getStaticDepositAddress();
+    if (!depositAddress) {
+      throw new Error("Failed to get deposit address");
+    }
+
+    const signedTx = await faucet.sendToAddress(depositAddress, 10_000n);
+
+    await faucet.mineBlocks(10);
+
+    const withdrawalAddress = await faucet.getNewAddress();
+
+    await faucet.generateToAddress(1, withdrawalAddress);
+
+    // Sleep to allow chain watcher to catch up
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    await faucet.mineBlocks(10);
+
+    const refundTx = await sdk.refundStaticDeposit({
+      depositTransactionId: signedTx.id,
+      destinationAddress: withdrawalAddress,
+      fee: 1000,
+    });
+
+    const broadcastResult = await faucet.broadcastTx(refundTx);
+    expect(broadcastResult).toBeDefined();
+  }, 30000);
+});

package/src/tests/integration/ssp/lightning.test.ts

@@ -20,46 +20,6 @@ const { wallet: walletStatic, ...rest } = await SparkWallet.initialize({
 
 describe("Lightning Network provider", () => {
   describe("should create lightning invoice", () => {
-    test.concurrent.each([
-      ["REGTEST", "lnbcrt"],
-      ["MAINNET", "lnbc"],
-    ])(
-      `.network(%s)`,
-      async (network, invoicePrefix) => {
-        const options: ConfigOptions = {
-          network: network as NetworkType,
-        };
-        const { wallet, ...rest } = await SparkWallet.initialize({
-          mnemonicOrSeed:
-            "logic ripple layer execute smart disease marine hero monster talent crucial unfair horror shadow maze abuse avoid story loop jaguar sphere trap decrease turn",
-          options,
-        });
-
-        let invoice = await wallet.createLightningInvoice({
-          amountSats: 1000,
-          memo: "test",
-        });
-
-        expect(invoice.invoice.encodedInvoice).toMatch(
-          new RegExp(`^${invoicePrefix}[0-9]*[a-zA-Z0-9]*$`),
-        );
-        expect(invoice.invoice.paymentHash.length).toEqual(64);
-        expect(invoice.invoice.amount.originalValue).toEqual(1000 * 1000);
-        expect(invoice.invoice.amount.originalUnit).toEqual(
-          CurrencyUnit.MILLISATOSHI,
-        );
-        expect(invoice.status).toEqual(
-          LightningReceiveRequestStatus.INVOICE_CREATED,
-        );
-        expect(invoice.transfer).toBeUndefined();
-        expect(invoice.invoice.bitcoinNetwork).toEqual(
-          network as BitcoinNetwork,
-        );
-        expect(invoice.network).toEqual(network as BitcoinNetwork);
-      },
-      30000,
-    );
-
     test.concurrent.each([
       [0],
       [1],