optimizeLeaves

Manually optimize leaf structure for faster transfers.

Manually optimizes wallet leaf structure by consolidating or splitting leaves into power-of-2 denominations. This is an async generator that yields progress updates and can be interrupted between steps.

For background on leaf optimization concepts, multiplicity levels, and tradeoffs, see Leaf Optimization in the initialize docs.

When to Use

Use this method when you’ve configured manual mode (auto: false) in your initialization options. In manual mode, the SDK won’t optimize automatically—you control exactly when optimization runs.

// Initialize with manual mode
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET",
    optimizationOptions: {
      auto: false,
      multiplicity: 5
    }
  }
});

// Then call optimizeLeaves() explicitly
for await (const progress of wallet.optimizeLeaves()) {
  console.log(`Optimizing: ${progress.step}/${progress.total}`);
}

In auto mode (default), the SDK handles optimization automatically. You typically don’t need to call this method directly.

Method Signature

async *optimizeLeaves(
  multiplicity?: number
): AsyncGenerator<{
  step: number;
  total: number;
  controller: AbortController;
}>

Parameters

multiplicity · number

Optimization multiplicity (0-5). Defaults to the value set in optimizationOptions during initialization.

Yields

progress · object · required

Progress object containing:

• step: Current step number
• total: Total number of steps
• controller: AbortController to cancel optimization between steps

Interrupting Optimization

The abort controller lets you pause optimization between steps—useful when the user wants to send a payment mid-optimization.

let optimizeGenerator = wallet.optimizeLeaves();

async function runOptimization() {
  for await (const progress of optimizeGenerator) {
    console.log(`Step ${progress.step} of ${progress.total}`);

    // User wants to send payment - abort optimization
    if (userWantsToSend) {
      progress.controller.abort();
      break;
    }
  }
}

// Start optimization
runOptimization();

// Later: user triggers a send
userWantsToSend = true;
await wallet.transfer({ ... });

// Resume optimization after the transfer
runOptimization();

Optimization runs multiple swap operations with the SSP. If you abort mid-optimization, the wallet remains in a valid state but may not be fully optimized. You can resume optimization later.

Example: Basic Usage

for await (const progress of wallet.optimizeLeaves()) {
  console.log(`Step ${progress.step} of ${progress.total}`);
}
console.log("Optimization complete");

Example: With Progress UI

async function optimizeWithProgress() {
  const progressBar = showProgressBar();

  try {
    for await (const { step, total } of wallet.optimizeLeaves(5)) {
      progressBar.update(step / total * 100);
    }
    progressBar.complete();
  } catch (error) {
    progressBar.error("Optimization failed");
    throw error;
  }
}