@buildonspark/spark-sdk 0.1.40 → 0.1.41

package/src/services/config.ts

@@ -114,6 +114,10 @@ export class WalletConfigService
     return this.config.tokenSignatures;
   }
 
+  public getTokenTransactionVersion(): "V0" | "V1" {
+    return this.config.tokenTransactionVersion;
+  }
+
   public getElectrsUrl(): string {
     return this.config.electrsUrl;
   }

package/src/services/connection.ts

@@ -18,6 +18,10 @@ import {
 } from "../proto/spark_authn.js";
 import { RetryOptions, SparkCallOptions } from "../types/grpc.js";
 import { WalletConfigService } from "./config.js";
+import {
+  SparkTokenServiceClient,
+  SparkTokenServiceDefinition,
+} from "../proto/spark_token.js";
 
 export class ConnectionManager {
   private config: WalletConfigService;
@@ -28,6 +32,13 @@ export class ConnectionManager {
       authToken: string;
     }
   > = new Map();
+  private tokenClients: Map<
+    string,
+    {
+      client: SparkTokenServiceClient & { close?: () => void };
+      authToken: string;
+    }
+  > = new Map();
 
   // We are going to .unref() the underlying channels for stream clients
   // to prevent the stream from keeping the process alive
@@ -193,6 +204,28 @@ export class ConnectionManager {
     return client;
   }
 
+  async createSparkTokenClient(
+    address: string,
+    certPath?: string,
+  ): Promise<SparkTokenServiceClient & { close?: () => void }> {
+    if (this.tokenClients.has(address)) {
+      return this.tokenClients.get(address)!.client;
+    }
+    const authToken = await this.authenticate(address);
+    const channel = await this.createChannelWithTLS(address, certPath);
+
+    const middleware = this.createMiddleware(address, authToken);
+    const tokenClient = await this.createGrpcClient<SparkTokenServiceClient>(
+      SparkTokenServiceDefinition,
+      channel,
+      true,
+      middleware,
+    );
+
+    this.tokenClients.set(address, { client: tokenClient, authToken });
+    return tokenClient;
+  }
+
   async getStreamChannel(address: string) {
     return this.streamClients.get(address)?.channel;
   }
@@ -340,7 +373,10 @@ export class ConnectionManager {
   }
 
   private async createGrpcClient<T>(
-    defintion: SparkAuthnServiceDefinition | SparkServiceDefinition,
+    defintion:
+      | SparkAuthnServiceDefinition
+      | SparkServiceDefinition
+      | SparkTokenServiceDefinition,
     channel: Channel | ChannelWeb,
     withRetries: boolean,
     middleware?: any,

package/src/services/token-transactions.ts

@@ -3,27 +3,19 @@ import {
   bytesToNumberBE,
   numberToBytesBE,
 } from "@noble/curves/abstract/utils";
-import { secp256k1 } from "@noble/curves/secp256k1";
 import {
   OutputWithPreviousTransactionData,
   OperatorSpecificTokenTransactionSignablePayload,
-  OperatorSpecificOwnerSignature,
-  TokenTransaction,
-  StartTokenTransactionResponse,
   SignTokenTransactionResponse,
-  SignatureWithIndex,
+  OperatorSpecificOwnerSignature,
   RevocationSecretWithIndex,
 } from "../proto/spark.js";
+import { secp256k1 } from "@noble/curves/secp256k1";
 import { SparkCallOptions } from "../types/grpc.js";
-import { collectResponses } from "../utils/response-validation.js";
 import {
   hashOperatorSpecificTokenTransactionSignablePayload,
   hashTokenTransaction,
 } from "../utils/token-hashing.js";
-import {
-  KeyshareWithOperatorIndex,
-  recoverRevocationSecretFromKeyshares,
-} from "../utils/token-keyshares.js";
 import {
   calculateAvailableTokenAmount,
   checkIfSelectedOutputsAreAvailable,
@@ -39,6 +31,17 @@ import {
 import { SigningOperator } from "./wallet-config.js";
 import { hexToBytes } from "@noble/hashes/utils";
 import { decodeSparkAddress } from "../address/index.js";
+import {
+  TokenTransaction,
+  SignatureWithIndex,
+  InputTtxoSignaturesPerOperator,
+} from "../proto/spark_token.js";
+import { TokenTransaction as TokenTransactionV0 } from "../proto/spark.js";
+import { collectResponses } from "../utils/response-validation.js";
+import {
+  KeyshareWithOperatorIndex,
+  recoverRevocationSecretFromKeyshares,
+} from "../utils/token-keyshares.js";
 
 const MAX_TOKEN_OUTPUTS = 500;
 
@@ -135,16 +138,25 @@ export class TokenTransactionService {
         this.config.getNetworkType(),
       );
       return {
-        receiverSparkAddress: hexToBytes(receiverAddress),
+        receiverSparkAddress: hexToBytes(receiverAddress.identityPublicKey),
         tokenPublicKey: hexToBytes(transfer.tokenPublicKey),
         tokenAmount: transfer.tokenAmount,
       };
     });
 
-    const tokenTransaction = await this.constructTransferTokenTransaction(
-      outputsToUse,
-      tokenOutputData,
-    );
+    let tokenTransaction: TokenTransactionV0 | TokenTransaction;
+
+    if (this.config.getTokenTransactionVersion() === "V0") {
+      tokenTransaction = await this.constructTransferTokenTransactionV0(
+        outputsToUse,
+        tokenOutputData,
+      );
+    } else {
+      tokenTransaction = await this.constructTransferTokenTransaction(
+        outputsToUse,
+        tokenOutputData,
+      );
+    }
 
     const txId = await this.broadcastTokenTransaction(
       tokenTransaction,
@@ -155,6 +167,53 @@ export class TokenTransactionService {
     return txId;
   }
 
+  public async constructTransferTokenTransactionV0(
+    selectedOutputs: OutputWithPreviousTransactionData[],
+    tokenOutputData: Array<{
+      receiverSparkAddress: Uint8Array;
+      tokenPublicKey: Uint8Array;
+      tokenAmount: bigint;
+    }>,
+  ): Promise<TokenTransactionV0> {
+    const availableTokenAmount = calculateAvailableTokenAmount(selectedOutputs);
+    const totalRequestedAmount = tokenOutputData.reduce(
+      (sum, output) => sum + output.tokenAmount,
+      0n,
+    );
+
+    const tokenOutputs = tokenOutputData.map((output) => ({
+      ownerPublicKey: output.receiverSparkAddress,
+      tokenPublicKey: output.tokenPublicKey,
+      tokenAmount: numberToBytesBE(output.tokenAmount, 16),
+    }));
+
+    if (availableTokenAmount > totalRequestedAmount) {
+      const changeAmount = availableTokenAmount - totalRequestedAmount;
+      const firstTokenPublicKey = tokenOutputData[0]!!.tokenPublicKey;
+
+      tokenOutputs.push({
+        ownerPublicKey: await this.config.signer.getIdentityPublicKey(),
+        tokenPublicKey: firstTokenPublicKey,
+        tokenAmount: numberToBytesBE(changeAmount, 16),
+      });
+    }
+
+    return {
+      network: this.config.getNetworkProto(),
+      tokenInputs: {
+        $case: "transferInput",
+        transferInput: {
+          outputsToSpend: selectedOutputs.map((output) => ({
+            prevTokenTransactionHash: output.previousTransactionHash,
+            prevTokenTransactionVout: output.previousTransactionVout,
+          })),
+        },
+      },
+      tokenOutputs,
+      sparkOperatorIdentityPublicKeys: this.collectOperatorIdentityPublicKeys(),
+    };
+  }
+
   public async constructTransferTokenTransaction(
     selectedOutputs: OutputWithPreviousTransactionData[],
     tokenOutputData: Array<{
@@ -187,6 +246,7 @@ export class TokenTransactionService {
     }
 
     return {
+      version: 1,
       network: this.config.getNetworkProto(),
       tokenInputs: {
         $case: "transferInput",
@@ -199,6 +259,7 @@ export class TokenTransactionService {
       },
       tokenOutputs,
       sparkOperatorIdentityPublicKeys: this.collectOperatorIdentityPublicKeys(),
+      expiryTime: undefined,
     };
   }
 
@@ -214,21 +275,43 @@ export class TokenTransactionService {
   }
 
   public async broadcastTokenTransaction(
-    tokenTransaction: TokenTransaction,
+    tokenTransaction: TokenTransactionV0 | TokenTransaction,
     outputsToSpendSigningPublicKeys?: Uint8Array[],
     outputsToSpendCommitments?: Uint8Array[],
   ): Promise<string> {
     const signingOperators = this.config.getSigningOperators();
+    if (!isTokenTransaction(tokenTransaction)) {
+      return this.broadcastTokenTransactionV0(
+        tokenTransaction,
+        signingOperators,
+        outputsToSpendSigningPublicKeys,
+        outputsToSpendCommitments,
+      );
+    } else {
+      return this.broadcastTokenTransactionV1(
+        tokenTransaction as TokenTransaction,
+        signingOperators,
+        outputsToSpendSigningPublicKeys,
+        outputsToSpendCommitments,
+      );
+    }
+  }
 
+  private async broadcastTokenTransactionV0(
+    tokenTransaction: TokenTransactionV0,
+    signingOperators: Record<string, SigningOperator>,
+    outputsToSpendSigningPublicKeys?: Uint8Array[],
+    outputsToSpendCommitments?: Uint8Array[],
+  ): Promise<string> {
     const { finalTokenTransaction, finalTokenTransactionHash, threshold } =
-      await this.startTokenTransaction(
+      await this.startTokenTransactionV0(
         tokenTransaction,
         signingOperators,
         outputsToSpendSigningPublicKeys,
         outputsToSpendCommitments,
       );
 
-    const { successfulSignatures } = await this.signTokenTransaction(
+    const { successfulSignatures } = await this.signTokenTransactionV0(
       finalTokenTransaction,
       finalTokenTransactionHash,
       signingOperators,
@@ -336,13 +419,36 @@ export class TokenTransactionService {
     return bytesToHex(finalTokenTransactionHash);
   }
 
-  private async startTokenTransaction(
+  private async broadcastTokenTransactionV1(
     tokenTransaction: TokenTransaction,
     signingOperators: Record<string, SigningOperator>,
     outputsToSpendSigningPublicKeys?: Uint8Array[],
     outputsToSpendCommitments?: Uint8Array[],
+  ): Promise<string> {
+    const { finalTokenTransaction, finalTokenTransactionHash, threshold } =
+      await this.startTokenTransaction(
+        tokenTransaction,
+        signingOperators,
+        outputsToSpendSigningPublicKeys,
+        outputsToSpendCommitments,
+      );
+
+    await this.signTokenTransaction(
+      finalTokenTransaction,
+      finalTokenTransactionHash,
+      signingOperators,
+    );
+
+    return bytesToHex(finalTokenTransactionHash);
+  }
+
+  private async startTokenTransactionV0(
+    tokenTransaction: TokenTransactionV0,
+    signingOperators: Record<string, SigningOperator>,
+    outputsToSpendSigningPublicKeys?: Uint8Array[],
+    outputsToSpendCommitments?: Uint8Array[],
   ): Promise<{
-    finalTokenTransaction: TokenTransaction;
+    finalTokenTransaction: TokenTransactionV0;
     finalTokenTransactionHash: Uint8Array;
     threshold: number;
   }> {
@@ -407,7 +513,7 @@ export class TokenTransactionService {
         });
       }
     }
-    // Start the token transaction
+
     const startResponse = await sparkClient.start_token_transaction(
       {
         identityPublicKey: await this.config.signer.getIdentityPublicKey(),
@@ -453,8 +559,122 @@ export class TokenTransactionService {
     };
   }
 
-  private async signTokenTransaction(
-    finalTokenTransaction: TokenTransaction,
+  private async startTokenTransaction(
+    tokenTransaction: TokenTransaction,
+    signingOperators: Record<string, SigningOperator>,
+    outputsToSpendSigningPublicKeys?: Uint8Array[],
+    outputsToSpendCommitments?: Uint8Array[],
+  ): Promise<{
+    finalTokenTransaction: TokenTransaction;
+    finalTokenTransactionHash: Uint8Array;
+    threshold: number;
+  }> {
+    const sparkClient = await this.connectionManager.createSparkTokenClient(
+      this.config.getCoordinatorAddress(),
+    );
+
+    const partialTokenTransactionHash = hashTokenTransaction(
+      tokenTransaction,
+      true,
+    );
+
+    const ownerSignaturesWithIndex: SignatureWithIndex[] = [];
+    if (tokenTransaction.tokenInputs!.$case === "mintInput") {
+      const issuerPublicKey =
+        tokenTransaction.tokenInputs!.mintInput.issuerPublicKey;
+      if (!issuerPublicKey) {
+        throw new ValidationError("Invalid mint input", {
+          field: "issuerPublicKey",
+          value: null,
+          expected: "Non-null issuer public key",
+        });
+      }
+
+      const ownerSignature = await this.signMessageWithKey(
+        partialTokenTransactionHash,
+        issuerPublicKey,
+      );
+
+      ownerSignaturesWithIndex.push({
+        signature: ownerSignature,
+        inputIndex: 0,
+      });
+    } else if (tokenTransaction.tokenInputs!.$case === "transferInput") {
+      if (!outputsToSpendSigningPublicKeys || !outputsToSpendCommitments) {
+        throw new ValidationError("Invalid transfer input", {
+          field: "outputsToSpend",
+          value: {
+            signingPublicKeys: outputsToSpendSigningPublicKeys,
+            revocationPublicKeys: outputsToSpendCommitments,
+          },
+          expected: "Non-null signing and revocation public keys",
+        });
+      }
+
+      for (const [i, key] of outputsToSpendSigningPublicKeys.entries()) {
+        if (!key) {
+          throw new ValidationError("Invalid signing key", {
+            field: "outputsToSpendSigningPublicKeys",
+            value: i,
+            expected: "Non-null signing key",
+          });
+        }
+        const ownerSignature = await this.signMessageWithKey(
+          partialTokenTransactionHash,
+          key,
+        );
+
+        ownerSignaturesWithIndex.push({
+          signature: ownerSignature,
+          inputIndex: i,
+        });
+      }
+    }
+
+    const startResponse = await sparkClient.start_transaction(
+      {
+        identityPublicKey: await this.config.signer.getIdentityPublicKey(),
+        partialTokenTransaction: tokenTransaction,
+      },
+      {
+        retry: true,
+        retryableStatuses: ["UNKNOWN", "UNAVAILABLE", "CANCELLED", "INTERNAL"],
+        retryMaxAttempts: 3,
+      } as SparkCallOptions,
+    );
+
+    if (!startResponse.finalTokenTransaction) {
+      throw new Error("Final token transaction missing in start response");
+    }
+    if (!startResponse.keyshareInfo) {
+      throw new Error("Keyshare info missing in start response");
+    }
+
+    validateTokenTransaction(
+      startResponse.finalTokenTransaction,
+      tokenTransaction,
+      signingOperators,
+      startResponse.keyshareInfo,
+      this.config.getExpectedWithdrawBondSats(),
+      this.config.getExpectedWithdrawRelativeBlockLocktime(),
+      this.config.getThreshold(),
+    );
+
+    const finalTokenTransaction = startResponse.finalTokenTransaction;
+    const finalTokenTransactionHash = hashTokenTransaction(
+      finalTokenTransaction,
+      false,
+    );
+
+    return {
+      finalTokenTransaction,
+      finalTokenTransactionHash,
+      threshold: startResponse.keyshareInfo!.threshold,
+    };
+  }
+
+  private async signTokenTransactionV0(
+    finalTokenTransaction: TokenTransactionV0,
     finalTokenTransactionHash: Uint8Array,
     signingOperators: Record<string, SigningOperator>,
   ): Promise<{
@@ -581,60 +801,53 @@ export class TokenTransactionService {
     };
   }
 
-  public async finalizeTokenTransaction(
+  private async signTokenTransaction(
     finalTokenTransaction: TokenTransaction,
-    revocationSecrets: RevocationSecretWithIndex[],
-    threshold: number,
-  ): Promise<TokenTransaction> {
-    const signingOperators = this.config.getSigningOperators();
-    // Submit finalize_token_transaction to all SOs in parallel
-    const soResponses = await Promise.allSettled(
-      Object.entries(signingOperators).map(async ([identifier, operator]) => {
-        const internalSparkClient =
-          await this.connectionManager.createSparkClient(operator.address);
-        const identityPublicKey =
-          await this.config.signer.getIdentityPublicKey();
-
-        try {
-          const response = await internalSparkClient.finalize_token_transaction(
-            {
-              finalTokenTransaction,
-              revocationSecrets,
-              identityPublicKey,
-            },
-            {
-              retry: true,
-              retryableStatuses: [
-                "UNKNOWN",
-                "UNAVAILABLE",
-                "CANCELLED",
-                "INTERNAL",
-              ],
-              retryMaxAttempts: 3,
-            } as SparkCallOptions,
-          );
-
-          return {
-            identifier,
-            response,
-          };
-        } catch (error) {
-          throw new NetworkError(
-            "Failed to finalize token transaction",
-            {
-              operation: "finalize_token_transaction",
-              errorCount: 1,
-              errors: error instanceof Error ? error.message : String(error),
-            },
-            error as Error,
-          );
-        }
-      }),
-    );
+    finalTokenTransactionHash: Uint8Array,
+    signingOperators: Record<string, SigningOperator>,
+  ) {
+    const coordinatorClient =
+      await this.connectionManager.createSparkTokenClient(
+        this.config.getCoordinatorAddress(),
+      );
 
-    collectResponses(soResponses);
+    const inputTtxoSignaturesPerOperator =
+      await this.createSignaturesForOperators(
+        finalTokenTransaction,
+        finalTokenTransactionHash,
+        signingOperators,
+      );
 
-    return finalTokenTransaction;
+    try {
+      await coordinatorClient.commit_transaction(
+        {
+          finalTokenTransaction,
+          inputTtxoSignaturesPerOperator,
+          ownerIdentityPublicKey:
+            await this.config.signer.getIdentityPublicKey(),
+        },
+        {
+          retry: true,
+          retryableStatuses: [
+            "UNKNOWN",
+            "UNAVAILABLE",
+            "CANCELLED",
+            "INTERNAL",
+          ],
+          retryMaxAttempts: 3,
+        } as SparkCallOptions,
+      );
+    } catch (error) {
+      throw new NetworkError(
+        "Failed to sign token transaction",
+        {
+          operation: "sign_token_transaction",
+          errorCount: 1,
+          errors: error instanceof Error ? error.message : String(error),
+        },
+        error as Error,
+      );
+    }
   }
 
   public async fetchOwnedTokenOutputs(
@@ -780,4 +993,142 @@ export class TokenTransactionService {
       }
     }
   }
+
+  private async finalizeTokenTransaction(
+    finalTokenTransaction: TokenTransactionV0,
+    revocationSecrets: RevocationSecretWithIndex[],
+    threshold: number,
+  ): Promise<TokenTransactionV0> {
+    const signingOperators = this.config.getSigningOperators();
+    // Submit finalize_token_transaction to all SOs in parallel
+    const soResponses = await Promise.allSettled(
+      Object.entries(signingOperators).map(async ([identifier, operator]) => {
+        const internalSparkClient =
+          await this.connectionManager.createSparkClient(operator.address);
+        const identityPublicKey =
+          await this.config.signer.getIdentityPublicKey();
+
+        try {
+          const response = await internalSparkClient.finalize_token_transaction(
+            {
+              finalTokenTransaction,
+              revocationSecrets,
+              identityPublicKey,
+            },
+            {
+              retry: true,
+              retryableStatuses: [
+                "UNKNOWN",
+                "UNAVAILABLE",
+                "CANCELLED",
+                "INTERNAL",
+              ],
+              retryMaxAttempts: 3,
+            } as SparkCallOptions,
+          );
+
+          return {
+            identifier,
+            response,
+          };
+        } catch (error) {
+          throw new NetworkError(
+            "Failed to finalize token transaction",
+            {
+              operation: "finalize_token_transaction",
+              errorCount: 1,
+              errors: error instanceof Error ? error.message : String(error),
+            },
+            error as Error,
+          );
+        }
+      }),
+    );
+
+    collectResponses(soResponses);
+
+    return finalTokenTransaction;
+  }
+
+  private async createSignaturesForOperators(
+    finalTokenTransaction: TokenTransaction,
+    finalTokenTransactionHash: Uint8Array,
+    signingOperators: Record<string, SigningOperator>,
+  ) {
+    const inputTtxoSignaturesPerOperator: InputTtxoSignaturesPerOperator[] = [];
+
+    for (const [_, operator] of Object.entries(signingOperators)) {
+      let ttxoSignatures: SignatureWithIndex[] = [];
+
+      if (finalTokenTransaction.tokenInputs!.$case === "mintInput") {
+        const issuerPublicKey =
+          finalTokenTransaction.tokenInputs!.mintInput.issuerPublicKey;
+        if (!issuerPublicKey) {
+          throw new ValidationError("Invalid mint input", {
+            field: "issuerPublicKey",
+            value: null,
+            expected: "Non-null issuer public key",
+          });
+        }
+
+        const payload: OperatorSpecificTokenTransactionSignablePayload = {
+          finalTokenTransactionHash: finalTokenTransactionHash,
+          operatorIdentityPublicKey: hexToBytes(operator.identityPublicKey),
+        };
+
+        const payloadHash =
+          await hashOperatorSpecificTokenTransactionSignablePayload(payload);
+
+        const ownerSignature = await this.signMessageWithKey(
+          payloadHash,
+          issuerPublicKey,
+        );
+
+        ttxoSignatures.push({
+          signature: ownerSignature,
+          inputIndex: 0,
+        });
+      } else if (finalTokenTransaction.tokenInputs!.$case === "transferInput") {
+        const transferInput = finalTokenTransaction.tokenInputs!.transferInput;
+
+        // Create signatures for each input
+        for (let i = 0; i < transferInput.outputsToSpend.length; i++) {
+          const payload: OperatorSpecificTokenTransactionSignablePayload = {
+            finalTokenTransactionHash: finalTokenTransactionHash,
+            operatorIdentityPublicKey: hexToBytes(operator.identityPublicKey),
+          };
+
+          const payloadHash =
+            await hashOperatorSpecificTokenTransactionSignablePayload(payload);
+
+          let ownerSignature: Uint8Array;
+          if (this.config.getTokenSignatures() === "SCHNORR") {
+            ownerSignature =
+              await this.config.signer.signSchnorrWithIdentityKey(payloadHash);
+          } else {
+            ownerSignature =
+              await this.config.signer.signMessageWithIdentityKey(payloadHash);
+          }
+
+          ttxoSignatures.push({
+            signature: ownerSignature,
+            inputIndex: i,
+          });
+        }
+      }
+
+      inputTtxoSignaturesPerOperator.push({
+        ttxoSignatures: ttxoSignatures,
+        operatorIdentityPublicKey: hexToBytes(operator.identityPublicKey),
+      });
+    }
+
+    return inputTtxoSignaturesPerOperator;
+  }
+}
+
+function isTokenTransaction(
+  tokenTransaction: TokenTransactionV0 | TokenTransaction,
+): tokenTransaction is TokenTransaction {
+  return "version" in tokenTransaction && "expiryTime" in tokenTransaction;
 }

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 tokenTransactionVersion?: "V0" | "V1";
     readonly electrsUrl?: string;
     readonly lrc20ApiConfig?: LRC20WalletApiConfig;
     readonly sspClientOptions?: SspClientOptions;
@@ -173,6 +174,7 @@ const BASE_CONFIG: Required<ConfigOptions> = {
   threshold: 2,
   signingOperators: getLocalSigningOperators(),
   tokenSignatures: "SCHNORR",
+  tokenTransactionVersion: "V0",
   electrsUrl: getElectrsUrl("LOCAL"),
   expectedWithdrawBondSats: 10000,
   expectedWithdrawRelativeBlockLocktime: 1000,