Spark Signer Interface

The Spark SDK provides the SparkSigner interface to enable flexible implementation of signing operations. This abstraction allows you to customize how cryptographic operations are performed, enabling support for secure enclaves, hardware wallets, remote signing services, and other specialized key management systems.

The SDK includes DefaultSparkSigner which handles standard single-signature operations and stores nonces internally for security. For server-side enclave integrations, UnsafeStatelessSparkSigner is available.

Core Concepts

Key Types

Spark wallets derive 5 key types from a master seed using BIP32:

Path	Key Type	Purpose
`m/8797555'/n'/0'`	Identity Key	Primary wallet identifier and authentication
`m/8797555'/n'/1'`	Signing HD Key	Base key for leaf key derivation
`m/8797555'/n'/2'`	Deposit Key	Receiving L1 Bitcoin deposits
`m/8797555'/n'/3'`	Static Deposit HD Key	Reusable deposit addresses
`m/8797555'/n'/4'`	HTLC Preimage HD Key	Lightning HTLC operations

The KeyDerivation System

The signer uses a discriminated union type to specify how to derive or retrieve a private key for signing operations:

enum KeyDerivationType {
  LEAF = "leaf",           // Derive from signing HD key using sha256(path)
  DEPOSIT = "deposit",     // Use the deposit key directly
  STATIC_DEPOSIT = "static_deposit",  // Use static deposit key at index
  ECIES = "ecies",         // Decrypt private key from ciphertext
  RANDOM = "random",       // Generate a random key (for adaptor signatures)
}

type KeyDerivation =
  | { type: KeyDerivationType.LEAF; path: string }
  | { type: KeyDerivationType.DEPOSIT }
  | { type: KeyDerivationType.RANDOM }
  | { type: KeyDerivationType.STATIC_DEPOSIT; path: number }
  | { type: KeyDerivationType.ECIES; path: Uint8Array };

This abstraction is used throughout the signer interface, particularly in signFrost() and getPublicKeyFromDerivation().

Security Model

All private keys are derived from a master seed using BIP32 hierarchical deterministic key derivation
Private keys never leave the signer. Only signatures and public keys are returned.
DefaultSparkSigner stores nonces internally to prevent reuse attacks
For enclave integrations, UnsafeStatelessSparkSigner exposes nonces externally

Implementations

DefaultSparkSigner

The recommended implementation for client-side applications. It stores signing nonces internally to prevent reuse attacks.

import { DefaultSparkSigner } from "@buildonspark/spark-sdk";

const signer = new DefaultSparkSigner();
const mnemonic = await signer.generateMnemonic();
const seed = await signer.mnemonicToSeed(mnemonic);
await signer.createSparkWalletFromSeed(seed, 0);

UnsafeStatelessSparkSigner

For server-side enclave integrations where nonces need to be managed externally. This signer returns nonces in getRandomSigningCommitment() instead of storing them internally.

import { UnsafeStatelessSparkSigner } from "@buildonspark/spark-sdk";

// Only use in secure server environments
const signer = new UnsafeStatelessSparkSigner();

UnsafeStatelessSparkSigner exposes nonces externally. Only use this in secure server environments where you can properly protect nonce data.

Custom Signer Implementation

You can extend DefaultSparkSigner to implement custom signing logic, such as forwarding requests to a secure enclave:

import { DefaultSparkSigner, SignFrostParams } from "@buildonspark/spark-sdk";

class EnclaveSigner extends DefaultSparkSigner {
  private enclave: EnclaveClient;

  constructor(enclave: EnclaveClient) {
    super();
    this.enclave = enclave;
  }

  async signFrost(params: SignFrostParams): Promise<Uint8Array> {
    // Forward signing request to secure enclave
    return this.enclave.signFrost(params);
  }

  async createSparkWalletFromSeed(
    seed: Uint8Array | string,
    accountNumber?: number
  ): Promise<string> {
    // Initialize keys in enclave
    return this.enclave.initializeWallet(seed, accountNumber);
  }
}

// Use with SparkWallet
const { wallet } = await SparkWallet.initialize({
  signer: new EnclaveSigner(myEnclave),
  options: { network: "MAINNET" }
});

Custom Key Derivation Paths

If you need a non-standard derivation scheme, you can pass a custom sparkKeysGenerator to DefaultSparkSigner. This example shows a simple generator that replaces ? with the accountNumber and then derives the five Spark key roots under that account:

import { DefaultSparkSigner, SparkValidationError } from "@buildonspark/spark-sdk";
import { HDKey } from "@scure/bip32";

class DerivationPathKeysGenerator {
  constructor(private readonly basePathTemplate: string) {}

  async deriveKeysFromSeed(seed: Uint8Array, accountNumber: number) {
    const hdkey = HDKey.fromMasterSeed(seed);

    const basePath = this.basePathTemplate.replace("?", String(accountNumber));
    const identityKey = hdkey.derive(`${basePath}/0'`);
    const signingKey = hdkey.derive(`${basePath}/1'`);
    const depositKey = hdkey.derive(`${basePath}/2'`);
    const staticDepositKey = hdkey.derive(`${basePath}/3'`);
    const htlcPreimageKey = hdkey.derive(`${basePath}/4'`);

    if (
      !identityKey.privateKey ||
      !identityKey.publicKey ||
      !signingKey.privateKey ||
      !signingKey.publicKey ||
      !depositKey.privateKey ||
      !depositKey.publicKey ||
      !staticDepositKey.privateKey ||
      !staticDepositKey.publicKey ||
      !htlcPreimageKey.privateKey ||
      !htlcPreimageKey.publicKey
    ) {
      throw new SparkValidationError("Failed to derive all required keys from seed");
    }

    return {
      identityKey: {
        privateKey: identityKey.privateKey,
        publicKey: identityKey.publicKey,
      },
      signingHDKey: {
        hdKey: signingKey,
        privateKey: signingKey.privateKey,
        publicKey: signingKey.publicKey,
      },
      depositKey: {
        privateKey: depositKey.privateKey,
        publicKey: depositKey.publicKey,
      },
      staticDepositHDKey: {
        hdKey: staticDepositKey,
        privateKey: staticDepositKey.privateKey,
        publicKey: staticDepositKey.publicKey,
      },
      HTLCPreimageHDKey: {
        hdKey: htlcPreimageKey,
        privateKey: htlcPreimageKey.privateKey,
        publicKey: htlcPreimageKey.publicKey,
      },
    };
  }
}

// Use ? as placeholder for account number
const customGenerator = new DerivationPathKeysGenerator("m/44'/0'/?'");

const signer = new DefaultSparkSigner({
  sparkKeysGenerator: customGenerator
});

Wallet Initialization

Generate Mnemonic

Generates a new BIP39 mnemonic phrase for wallet creation.

const mnemonic = await signer.generateMnemonic();
console.log(mnemonic); // "abandon ability able about above absent..."

Show Returns

Promise<string>

required

A 12-word BIP39 mnemonic phrase

Convert Mnemonic to Seed

Converts a BIP39 mnemonic phrase to a cryptographic seed.

const seed = await signer.mnemonicToSeed(mnemonic);
console.log("Seed length:", seed.length); // 64 bytes

Show Parameters

string

required

Valid BIP39 mnemonic phrase

Show Returns

Promise<Uint8Array>

required

64-byte seed derived from the mnemonic

Initialize from Seed

Initializes the signer with a master seed and derives all necessary keys.

const seed = await signer.mnemonicToSeed(mnemonic);
const identityPubKey = await signer.createSparkWalletFromSeed(seed, 0);
console.log("Identity public key:", identityPubKey);

Show Parameters

Uint8Array | string

required

Master seed as bytes or hex string

number

default:"0"

Account index for key derivation. Defaults to 0 on REGTEST, 1 on MAINNET for backwards compatibility.

Show Returns

Promise<string>

required

Hex-encoded identity public key

Key Management

Get Identity Public Key

Retrieves the wallet’s identity public key.

const identityKey = await signer.getIdentityPublicKey();
console.log("Identity key:", identityKey);

Show Returns

Promise<Uint8Array>

required

The identity public key (33 bytes, compressed)

Get Deposit Signing Key

Retrieves the deposit signing public key used for L1 Bitcoin deposits.

const depositKey = await signer.getDepositSigningKey();
console.log("Deposit signing key:", depositKey);

Show Returns

Promise<Uint8Array>

required

The deposit signing public key

Get Static Deposit Signing Key

Retrieves a static deposit signing public key by index.

const signingKey = await signer.getStaticDepositSigningKey(0);
console.log("Static deposit signing key:", signingKey);

Show Parameters

number

required

Index for the static deposit key

Show Returns

Promise<Uint8Array>

required

The static deposit signing public key

Get Static Deposit Secret Key

Retrieves a static deposit private key by index. Used when the private key needs to be shared with the deposit service during static deposit flows.

const secretKey = await signer.getStaticDepositSecretKey(0);

Show Parameters

number

required

Index for the static deposit key

Show Returns

Promise<Uint8Array>

required

The static deposit private key

Get Public Key from Derivation

Derives a public key based on a KeyDerivation specification.

import { KeyDerivationType } from "@buildonspark/spark-sdk";

// Get public key for a leaf
const leafPubKey = await signer.getPublicKeyFromDerivation({
  type: KeyDerivationType.LEAF,
  path: "leaf-123"
});

// Get deposit public key
const depositPubKey = await signer.getPublicKeyFromDerivation({
  type: KeyDerivationType.DEPOSIT
});

Show Parameters

KeyDerivation

required

Specifies how to derive the key (LEAF, DEPOSIT, STATIC_DEPOSIT, ECIES, or RANDOM)

Show Returns

Promise<Uint8Array>

required

The derived public key

Digital Signatures

Sign with Identity Key

Signs a message using the wallet’s identity key with ECDSA.

const message = new TextEncoder().encode("Hello, Spark!");
const signature = await signer.signMessageWithIdentityKey(message);
console.log("Signature:", signature);

// With compact format
const compactSignature = await signer.signMessageWithIdentityKey(message, true);

Show Parameters

Uint8Array

required

Message to sign

boolean

default:"false"

Use compact signature format instead of DER

Show Returns

Promise<Uint8Array>

required

ECDSA signature (DER or compact format)

Validate Signature

Validates an ECDSA signature against the identity key.

const message = new TextEncoder().encode("Hello, Spark!");
const signature = await signer.signMessageWithIdentityKey(message);
const isValid = await signer.validateMessageWithIdentityKey(message, signature);
console.log("Signature valid:", isValid);

Show Parameters

Uint8Array

required

Original message

Uint8Array

required

Signature to validate

Show Returns

Promise<boolean>

required

True if signature is valid

Sign with Schnorr (Identity Key)

Creates a Schnorr signature using the identity key.

const message = new TextEncoder().encode("Hello, Spark!");
const schnorrSignature = await signer.signSchnorrWithIdentityKey(message);
console.log("Schnorr signature:", schnorrSignature);

Show Parameters

Uint8Array

required

Message to sign

Show Returns

Promise<Uint8Array>

required

Schnorr signature (64 bytes)

Sign Transaction Index

Signs a specific input of a Bitcoin transaction. The method looks up the private key based on the provided public key (must be either identity or deposit key).

import { Transaction } from "@scure/btc-signer";

const tx = new Transaction();
// ... build transaction ...

const identityKey = await signer.getIdentityPublicKey();
signer.signTransactionIndex(tx, 0, identityKey);

Show Parameters

Transaction

required

The Bitcoin transaction to sign (from @scure/btc-signer)

number

required

Input index to sign

Uint8Array

required

Public key identifying which private key to use

FROST Protocol (Threshold Signatures)

Spark uses FROST (Flexible Round-Optimized Schnorr Threshold) signatures for collaborative signing between users and Signing Operators.

Get Random Signing Commitment

Generates a random signing commitment for FROST protocol. In DefaultSparkSigner, the nonce is stored internally. In UnsafeStatelessSparkSigner, the nonce is returned in the response.

const commitment = await signer.getRandomSigningCommitment();
console.log("Commitment:", commitment.commitment);
// commitment.nonce is only present in UnsafeStatelessSparkSigner

Show Returns

Promise<SigningCommitmentWithOptionalNonce>

required

Object containing the signing commitment, and optionally the nonce (for stateless signers)

Get Nonce for Commitment

Retrieves the nonce associated with a previously generated commitment. In DefaultSparkSigner, this looks up the internally stored nonce. In UnsafeStatelessSparkSigner, this returns the nonce from the commitment object.

const commitment = await signer.getRandomSigningCommitment();
const nonce = signer.getNonceForSelfCommitment(commitment);

Show Parameters

SigningCommitmentWithOptionalNonce

required

The commitment returned from getRandomSigningCommitment()

Show Returns

SigningNonce | undefined

The signing nonce, or undefined if not found

FROST Signing

Performs FROST signing operation. This produces the user’s signature share that will be combined with Signing Operator shares.

import { KeyDerivationType } from "@buildonspark/spark-sdk";

const commitment = await signer.getRandomSigningCommitment();

const params = {
  message: sighash,  // Transaction sighash to sign
  keyDerivation: { type: KeyDerivationType.LEAF, path: leafId },
  publicKey: leafPublicKey,
  verifyingKey: leaf.verifyingPublicKey,
  selfCommitment: commitment,
  statechainCommitments: soCommitments,  // From Signing Operators
  adaptorPubKey: undefined  // Optional adaptor for atomic swaps
};

const signatureShare = await signer.signFrost(params);

Show Parameters

SignFrostParams

required

FROST signing parameters:

message: The message (sighash) to sign
keyDerivation: How to derive the signing key
publicKey: The user’s public key for this leaf
verifyingKey: The aggregated public key (user + SOs)
selfCommitment: User’s signing commitment
statechainCommitments: Signing Operators’ commitments
adaptorPubKey: Optional adaptor public key

Show Returns

FROST signature share

Aggregate FROST Signatures

Aggregates FROST signature shares (user’s + Signing Operators’) into a final Schnorr signature.

const params = {
  message: sighash,
  publicKey: leafPublicKey,
  verifyingKey: leaf.verifyingPublicKey,
  selfCommitment: commitment,
  selfSignature: userSignatureShare,
  statechainCommitments: soCommitments,
  statechainSignatures: soSignatures,
  statechainPublicKeys: soPublicKeys
};

const finalSignature = await signer.aggregateFrost(params);

Show Parameters

AggregateFrostParams

required

FROST aggregation parameters including all signature shares and public keys

Show Returns

Promise<Uint8Array>

required

Final aggregated Schnorr signature (64 bytes)

These methods implement Shamir’s Secret Sharing with verifiable proofs, used internally for key splitting operations.

Split Secret with Proofs

Splits a secret into shares using Shamir’s Secret Sharing with verifiable proofs.

const params = {
  secret: privateKey,
  curveOrder: secp256k1.CURVE.n,
  threshold: 3,
  numShares: 5
};

const shares = await signer.splitSecretWithProofs(params);

Show Parameters

SplitSecretWithProofsParams

required

secret: The secret to split (as Uint8Array)
curveOrder: The curve order (bigint)
threshold: Minimum shares needed to reconstruct
numShares: Total number of shares to generate

Show Returns

Promise<VerifiableSecretShare[]>

required

Array of verifiable secret shares

Subtract and Split with Proofs

Subtracts two derived private keys and splits the result into verifiable shares. Used in transfer flows.

import { KeyDerivationType } from "@buildonspark/spark-sdk";

const shares = await signer.subtractAndSplitSecretWithProofsGivenDerivations({
  first: { type: KeyDerivationType.LEAF, path: "old-leaf" },
  second: { type: KeyDerivationType.LEAF, path: "new-leaf" },
  curveOrder: secp256k1.CURVE.n,
  threshold: 3,
  numShares: 5
});

Subtract, Split, and Encrypt

Subtracts keys, splits into shares, and encrypts the second key for the receiver. Used in transfer operations.

const result = await signer.subtractSplitAndEncrypt({
  first: { type: KeyDerivationType.LEAF, path: oldLeafId },
  second: { type: KeyDerivationType.LEAF, path: newLeafId },
  curveOrder: secp256k1.CURVE.n,
  threshold: 3,
  numShares: 5,
  receiverPublicKey: receiverIdentityKey
});

console.log(result.shares);       // Verifiable secret shares
console.log(result.secretCipher); // Encrypted key for receiver

Encryption

Decrypt ECIES

Decrypts ECIES-encrypted data using the identity key. Returns the public key corresponding to the decrypted private key.

const ciphertext = encryptedKeyFromSender;
const publicKey = await signer.decryptEcies(ciphertext);

Show Parameters

Uint8Array

required

ECIES-encrypted private key

Show Returns

Promise<Uint8Array>

required

Public key corresponding to the decrypted private key

HTLC Operations

Generate HTLC HMAC

Generates an HMAC for HTLC (Hash Time-Locked Contract) operations using the HTLC preimage key.

const hmac = await signer.htlcHMAC(transferId);

Show Parameters

string

required

The transfer ID to generate HMAC for

Show Returns

Promise<Uint8Array>

required

HMAC output (32 bytes)

Complete Example

import { 
  SparkWallet, 
  DefaultSparkSigner,
  KeyDerivationType 
} from "@buildonspark/spark-sdk";

async function demonstrateSparkSigner() {
  // 1. Create and initialize signer
  const signer = new DefaultSparkSigner();
  
  const mnemonic = await signer.generateMnemonic();
  console.log("Generated mnemonic:", mnemonic);

  const seed = await signer.mnemonicToSeed(mnemonic);
  const identityKeyHex = await signer.createSparkWalletFromSeed(seed, 0);
  console.log("Identity key:", identityKeyHex);

  // 2. Get keys
  const identityKey = await signer.getIdentityPublicKey();
  const depositKey = await signer.getDepositSigningKey();
  const staticDepositKey = await signer.getStaticDepositSigningKey(0);

  console.log("Keys initialized");

  // 3. Sign and validate a message
  const message = new TextEncoder().encode("Hello, Spark!");
  
  const signature = await signer.signMessageWithIdentityKey(message);
  const isValid = await signer.validateMessageWithIdentityKey(message, signature);
  console.log("Signature valid:", isValid);

  // 4. Schnorr signature
  const schnorrSig = await signer.signSchnorrWithIdentityKey(message);
  console.log("Schnorr signature length:", schnorrSig.length);

  // 5. Get public key from derivation
  const leafPubKey = await signer.getPublicKeyFromDerivation({
    type: KeyDerivationType.LEAF,
    path: "my-leaf-id"
  });
  console.log("Leaf public key:", leafPubKey);

  // 6. Use with SparkWallet
  const { wallet } = await SparkWallet.initialize({
    mnemonicOrSeed: mnemonic,
    accountNumber: 0,
    options: { network: "REGTEST" }
  });

  const address = await wallet.getSparkAddress();
  console.log("Spark address:", address);
}

Integration Patterns

Remote Signer (Enclave Pattern)

For wallet providers that need to keep keys in a secure enclave:

class RemoteSigner extends DefaultSparkSigner {
  private apiClient: EnclaveAPIClient;
  private userId: string;

  constructor(apiClient: EnclaveAPIClient, userId: string) {
    super();
    this.apiClient = apiClient;
    this.userId = userId;
  }

  async signFrost(params: SignFrostParams): Promise<Uint8Array> {
    // Forward to enclave
    return this.apiClient.signFrost(this.userId, params);
  }

  async aggregateFrost(params: AggregateFrostParams): Promise<Uint8Array> {
    return this.apiClient.aggregateFrost(this.userId, params);
  }

  async createSparkWalletFromSeed(
    seed: Uint8Array | string, 
    accountNumber?: number
  ): Promise<string> {
    // Keys are managed in the enclave
    return this.apiClient.initializeWallet(this.userId, seed, accountNumber);
  }
}

Multi-User Wallet Pattern

For services managing wallets for multiple users:

class MultiUserSigner extends UnsafeStatelessSparkSigner {
  private keyStore: KeyStore;

  async signFrost(params: SignFrostParams): Promise<Uint8Array> {
    // Look up user's key material from secure storage
    const userKeys = await this.keyStore.getKeys(params.publicKey);
    
    // Perform signing with user's keys
    return super.signFrost({
      ...params,
      // Additional context if needed
    });
  }
}

For multi-user wallets, consider the trust model carefully. See the Alby architecture blog post for a trust-minimized approach using NWC.

​Core Concepts

​Key Types

​The KeyDerivation System

​Security Model

​Implementations

​DefaultSparkSigner

​UnsafeStatelessSparkSigner

​Custom Signer Implementation

​Custom Key Derivation Paths

​Wallet Initialization

​Generate Mnemonic

​Convert Mnemonic to Seed

​Initialize from Seed

​Key Management

​Get Identity Public Key

​Get Deposit Signing Key

​Get Static Deposit Signing Key

​Get Static Deposit Secret Key

​Get Public Key from Derivation

​Digital Signatures

​Sign with Identity Key

​Validate Signature

​Sign with Schnorr (Identity Key)

​Sign Transaction Index

​FROST Protocol (Threshold Signatures)

​Get Random Signing Commitment

​Get Nonce for Commitment

​FROST Signing

​Aggregate FROST Signatures

​Secret Sharing

​Split Secret with Proofs

​Subtract and Split with Proofs

​Subtract, Split, and Encrypt

​Encryption

​Decrypt ECIES

​HTLC Operations

​Generate HTLC HMAC

​Complete Example

​Integration Patterns

​Remote Signer (Enclave Pattern)

​Multi-User Wallet Pattern

Core Concepts

Key Types

The KeyDerivation System

Security Model

Implementations

DefaultSparkSigner

UnsafeStatelessSparkSigner

Custom Signer Implementation

Custom Key Derivation Paths

Wallet Initialization

Generate Mnemonic

Convert Mnemonic to Seed

Initialize from Seed

Key Management

Get Identity Public Key

Get Deposit Signing Key

Get Static Deposit Signing Key

Get Static Deposit Secret Key

Get Public Key from Derivation

Digital Signatures

Sign with Identity Key

Validate Signature

Sign with Schnorr (Identity Key)

Sign Transaction Index

FROST Protocol (Threshold Signatures)

Get Random Signing Commitment

Get Nonce for Commitment

FROST Signing

Aggregate FROST Signatures

Secret Sharing

Split Secret with Proofs

Subtract and Split with Proofs

Subtract, Split, and Encrypt

Encryption

Decrypt ECIES

HTLC Operations

Generate HTLC HMAC

Complete Example

Integration Patterns

Remote Signer (Enclave Pattern)

Multi-User Wallet Pattern