initialize

Creates and initializes a new SparkWallet instance.

Method Signature

interface SparkWalletProps {
  mnemonicOrSeed?: Uint8Array | string;
  accountNumber?: number;
  signer?: SparkSigner;
  options?: ConfigOptions;
}

static async initialize(props: SparkWalletProps): Promise<{
  wallet: SparkWallet;
  mnemonic?: string;
}>

Parameters

Uint8Array | string

BIP-39 mnemonic phrase or raw seed

number

Number used to generate multiple identity keys from the same mnemonic

SparkSigner

Custom signer implementation for advanced use cases

ConfigOptions

Wallet configuration options including network selection

Show ConfigOptions Details

interface ConfigOptions {
  // e.g. "MAINNET" | "TESTNET" | "SIGNET" | "REGTEST" | "LOCAL"
  network?: NetworkType; // Required for most use cases

  // Advanced options (rarely needed):
  signingOperators?: Readonly<Record<string, SigningOperator>>;
  coordinatorIdentifier?: string;
  frostSignerAddress?: string;
  threshold?: number;

  tokenSignatures?: "ECDSA" | "SCHNORR";
  tokenValidityDurationSeconds?: number;
  tokenOutputLockExpiryMs?: number;
  tokenTransactionVersion?: "V2" | "V3";

  electrsUrl?: string;
  sspClientOptions?: SspClientOptions;
  expectedWithdrawBondSats?: number;
  expectedWithdrawRelativeBlockLocktime?: number;
  signerWithPreExistingKeys?: boolean;
  console?: { otel?: boolean };

  optimizationOptions?: {
    auto?: boolean;        // Auto-optimize leaves on sync (default: true)
    multiplicity?: number; // Optimization level 0-5 (default: 1)
  };
  tokenOptimizationOptions?: {
    enabled?: boolean;           // Enable token output consolidation (default: true)
    intervalMs?: number;         // Optimization interval (default: 300000 = 5 min)
    minOutputsThreshold?: number; // Min outputs before optimizing (default: 50)
  };
  events?: Partial<SparkWalletEvents>; // Pre-register event handlers at init
}

type NetworkType = "MAINNET" | "TESTNET" | "SIGNET" | "REGTEST" | "LOCAL";

type SigningOperator = {
  id: number;
  identifier: string;
  address: string;
  identityPublicKey: string;
};

type SspClientOptions = {
  baseUrl: string;
  identityPublicKey: string;
  schemaEndpoint?: string;
};

Leaf Optimization

Leaf optimization pre-arranges your wallet’s internal structure to enable faster transfers. Without optimization, transfers may require a swap with the SSP (Spark Service Provider), adding latency. With optimization, transfers complete in ~5 seconds.

How It Works

Spark creates power-of-2 denomination leaves (1, 2, 4, 8, 16… sats). With one leaf of each denomination, you can transfer any amount without needing an SSP swap. With multiple leaves of each denomination, you can make multiple transfers without swapping.

Multiplicity Levels

The multiplicity setting controls how aggressively to optimize:

Level	Behavior	Use Case
0	No optimization	Testing only
1	1 leaf per denomination	Likely 1 fast transfer before needing a swap
2-4	Multiple leaves per denomination	Multiple fast transfers
5	Maximum optimization	Likely 5+ fast transfers without any swaps

The Tradeoff

Higher multiplicity = faster transfers, but smaller individual leaves. Leaves under 16,348 sats cannot be unilaterally exited (fees would exceed value). If unilateral exit capability is critical for your users, use a lower multiplicity or larger balances.

For most consumer wallets, fast transfer speeds for 100% of users outweighs unilateral exit costs for a small fraction of users.

Auto vs Manual Mode

Auto mode (auto: true, default):

Optimization runs automatically in the background after sync
Swaps with SSP when leaves are too far from optimal
Transfers wait for optimization to complete before sending
Best for most applications

Manual mode (auto: false):

You control exactly when optimization runs via optimizeLeaves()
More aggressive optimization (skips the “is it needed?” check)
Use when you want maximum optimization regardless of current state

Configuration Examples

// Default behavior - auto optimization with multiplicity 1
const { wallet } = await SparkWallet.initialize({
  options: { network: "MAINNET" }
});

// Fast transfers for consumer wallet
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET",
    optimizationOptions: {
      auto: true,
      multiplicity: 5
    }
  }
});

// Manual control for maximum optimization
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET",
    optimizationOptions: {
      auto: false,
      multiplicity: 5
    }
  }
});
// Then call wallet.optimizeLeaves() explicitly when needed

Safe to pass on every init. Pass optimizationOptions every time you initialize (e.g., on app reopen). The SDK only runs optimization if needed and does nothing on wallets with no balance.

Returns

SparkWallet

required

The initialized SparkWallet instance

string

The mnemonic if one was generated (undefined for raw seed)

Example

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

// Create a new wallet
const { wallet, mnemonic } = await SparkWallet.initialize({
  options: { network: "REGTEST" } // or "MAINNET"
});

console.log("Wallet initialized:", wallet);
console.log("Generated mnemonic:", mnemonic);

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

// Import wallet from existing mnemonic
const { wallet } = await SparkWallet.initialize({
  mnemonicOrSeed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
  accountNumber: 0, // Optional: specify account index
  options: { network: "REGTEST" }
});

console.log("Wallet restored from mnemonic");

Multiple SDK Instances

When running multiple wallet instances (e.g., service worker + popup in a browser extension):

Multiple instances are safe but may cause temporary claim failures. The SDK handles this automatically—failed claims retry and succeed on subsequent attempts.

Best practices:

Avoid calling getStaticDepositAddress() concurrently—this can create duplicate addresses
Let one instance handle background claiming if possible
Failed claims due to concurrent access are automatically recoverable

System Time Requirements

The SDK uses your device’s system time for expiry calculations.

Your device clock must be within 2 minutes of actual time, or operations will fail with “invalid expiry_time” errors. If users report this error, ask them to sync their device clock.

Introduction

Wallets

Wallet Viewer

Utilities

Issuance

Method Signature

Parameters

Leaf Optimization

How It Works

Multiplicity Levels

The Tradeoff

Auto vs Manual Mode

Configuration Examples

Returns

Example

Multiple SDK Instances

System Time Requirements

​Method Signature

​Parameters

​Leaf Optimization

​How It Works

​Multiplicity Levels

​The Tradeoff

​Auto vs Manual Mode

​Configuration Examples

​Returns

​Example

​Multiple SDK Instances

​System Time Requirements

Method Signature

Parameters

Leaf Optimization

How It Works

Multiplicity Levels

The Tradeoff

Auto vs Manual Mode

Configuration Examples

Returns

Example

Multiple SDK Instances

System Time Requirements