Skip to content

What's New in v3.1.0

With version 3.1.0 we've made significant improvements to type safety, API consistency, and transaction handling. This page will guide you through the migration and explain what you need to know.

A Quick Summary

  • Full TypeScript support is now available for all three implementations (viem, ethersV5, ethers v6) with complete type definitions.
  • Transaction receipts are now returned by default from swap() functions - no more need to call .wait() manually.
  • API consistency improved by moving isRaw and outTokenDecimals from slippage to options parameter.
  • Slippage BPS scale standardized to 10,000 (from 1,000,000) to match industry standards and fee calculations.
  • Error handling improved across all implementations for better debugging experience.

Breaking Changes

Breaking changes include updates to parameter locations, transaction handling, and slippage BPS calculations. Review each section below to understand how these changes might affect your application.

Parameter Location Changes

The isRaw and outTokenDecimals fields have moved from the slippage object to the options object for better semantic clarity:

// Before v3.1.0
await swap({
  slippage: {
    slippageAmount: "100",
    isBps: true,
    isRaw: false, // Was in slippage
    outTokenDecimals: 18, // Was in slippage
  },
});
 
// v3.1.0 and later
await swap({
  options: {
    isRaw: false, // Now in options
    outTokenDecimals: 18, // Now in options
    skipApproval: true,
    wait: 1,
  },
  slippage: {
    slippageAmount: "100",
    isBps: true, // Only slippage-related fields remain
  },
});

Transaction Wait Behavior

For ethers and ethersV5 implementations, swap() now waits for transaction confirmation by default:

// Before v3.1.0 - Manual wait required
const result = await swap(...);
const receipt = await result.swapReceipt.wait(); // Extra step needed
 
// v3.1.0 and later - Automatic wait
const result = await swap(...);
const receipt = result.swapReceipt; // Already a TransactionReceipt!

Slippage BPS Scale Standardization

The basis points (BPS) scale for slippage has been standardized to 10,000 (matching feeParams calculations):

// Before v3.1.0 - 1,000,000 BPS = 100%
const result = await route.swap({
  slippage: {
    slippageAmount: 10000, // 1% slippage (10,000 / 1,000,000)
    isBps: true,
  },
});
 
// v3.1.0 and later - 10,000 BPS = 100%
const result = await route.swap({
  slippage: {
    slippageAmount: 100, // 1% slippage (100 / 10,000)
    isBps: true,
  },
});

New Features

Complete TypeScript Support

All three implementations now have full TypeScript definitions with proper type exports:

// Viem implementation
import { Route, swap, SwapResult } from "symphony-sdk/viem";
import type {
  TokenList,
  TokenMetadata,
  Address,
  FeeParams,
  SymphonyConfig,
  SwapResult,
  //..
} from "symphony-sdk/viem";
..
// EthersV5 implementation
import { Route, swap } from "symphony-sdk/ethersV5";
import type {
  TokenList,
  TokenMetadata,
  Address,
  FeeParams,
  SymphonyConfig,
  SwapResult,
  //..
} from "symphony-sdk/ethersV5";
..
// Ethers v6 implementation
import { Route, swap } from "symphony-sdk/ethers";
import type {
  TokenList,
  TokenMetadata,
  Address,
  FeeParams,
  SymphonyConfig,
  SwapResult,
  //..
} from "symphony-sdk/ethers";
..

Configurable Transaction Confirmations

Control how many confirmations to wait for with the options.wait parameter:

// Wait for 3 confirmations
await swap({
  route,
  options: {
    wait: 3, // Wait for 3 block confirmations
  },
});
 
// Default behavior (1 confirmation)
await swap({
  route,
  options: {
    wait: 1, // Default - wait for 1 confirmation
  },
});

Migration Guide

Quick Migration Checklist

  1. Move isRaw and outTokenDecimals from slippage to options parameter
  2. Remove .wait() calls on swap results (ethers/ethersV5 users)
  3. Update BPS values - divide by 100 if using isBps: true
  4. Add TypeScript types (optional) - import from symphony-sdk/types/*

Detailed Migration Examples

For Slippage with BPS

If you're using basis points for slippage:

// Before v3.1.0
slippage: {
  slippageAmount: 50000,   // 5% slippage - 1_000_000 = 100%
  isBps: true
}
 
// v3.1.0 and later
slippage: {
  slippageAmount: 500,      // 5% slippage (50000 / 100) - 10_000 = 100%
  isBps: true
}

For Transaction Handling

If you're manually waiting for transactions:

// Before v3.1.0
const result = await swap(...);
const receipt = await result.swapReceipt.wait();
console.log("Transaction hash:", receipt.transactionHash);
 
// v3.1.0 and later
const result = await swap(...);
const receipt = result.swapReceipt; // Already waited!
console.log("Transaction hash:", receipt.transactionHash);

For Raw Amount Handling

If you're using isRaw to handle wei values:

// Before v3.1.0
await swap({
  slippage: {
    slippageAmount: "100",
    isBps: false,
    isRaw: true, // Was here
    outTokenDecimals: 18,
  },
});
 
// v3.1.0 and later
await swap({
  options: {
    isRaw: true, // Now here
    outTokenDecimals: 18,
  },
  slippage: {
    slippageAmount: "100",
    isBps: false,
  },
});

Understanding isRaw and isBps

isRaw - For Amount Formatting

  • isRaw: true - Amounts are in wei units (e.g., "1000000000000000000" for 1 token with 18 decimals)
  • isRaw: false - Amounts are user-friendly strings (e.g., "1.5" for 1.5 tokens)
  • Location: Always in the options parameter
  • Use case: Determines how to interpret amount inputs

isBps - For Slippage Format

  • isBps: true - Slippage in basis points (100 = 1%, 10000 = 100%)
  • isBps: false - Slippage as percentage (1 = 1%, 100 = 100%)
  • Location: Always in the slippage parameter
  • Use case: Determines how to interpret slippage values

Backward Compatibility

Who Needs to Update?

  • ✅ All users using BPS slippage - Must update values (divide by 100)
  • ✅ Ethers/EthersV5 users calling .wait() - Can remove the wait call
  • ✅ Users with isRaw or outTokenDecimals in slippage - Must move to options
  • ❌ Viem users not using BPS or isRaw - No changes needed
  • ❌ JavaScript users - TypeScript support is optional

Minimal Impact Users

If you're using the SDK with:

  • Percentage-based slippage (not BPS)
  • Default options (no isRaw or outTokenDecimals)
  • Viem implementation

You likely don't need to make any changes!

Performance Improvements

  • Type safety - Full TypeScript support catches errors at compile time
  • Consistent behavior - All three implementations now behave identically
  • Better debugging - Standardized error handling with stack traces
  • Reduced code - No more manual .wait() calls needed

Need Help?

If you encounter issues during migration:

  1. Check that all isRaw and outTokenDecimals are in options
  2. Verify your BPS values are divided by 100
  3. Remove any .wait() calls on swap results
  4. Review the full changelog for complete details