Skip to content

Changelog

All notable changes to this project will be documented in this file.

[3.0.0] - 2025-08-03

Added

  • Contract Address Change - Symphony's contract address is now 0xC340F8C5C58f4f99B4e43673eba07Cf378047DD2. It is a proxy contract. From now on, contract address changes will not take place frequently
  • New tokenService - Centralized async token management service for fetching live token data from Symphony Assetlist API
  • Async token methods - getTokenListAsync() and isTokenListedAsync() methods to Symphony class across all implementations
  • Proactive cache warming - Background token fetching during SDK initialization for improved performance
  • Live token data - Real-time token information provided by Symphony
  • Intelligent fallback - Automatic fallback to static tokens when API is unavailable
  • Race condition protection - Promise caching prevents duplicate API calls
  • Enhanced error handling - Comprehensive logging and graceful degradation
  • Cross-implementation parity - Identical functionality across viem, ethersV5, and ethers v6+ implementations
  • Custom amount approval override - giveApproval() now supports custom amount parameter to override route's default amount across all implementations
  • Flexible approval amounts - Support for both raw (wei) and formatted amounts in custom approvals with automatic decimal conversion

Changed

  • BREAKING: getTotalAmountOut() is now async and requires await across all implementations
  • BREAKING: getTotalAmountIn() is now async and requires await across all implementations
  • BREAKING: getRouteDetails() is now async and requires await across all implementations
  • BREAKING: Route.getTotalAmountOut() is now async and requires await across all implementations
  • BREAKING: Route.getTotalAmountIn() is now async and requires await across all implementations
  • BREAKING: Route.getRouteDetails() is now async and requires await across all implementations
  • BREAKING: feeParams is now based on 10000 instead of 1000
  • Improved performance - Token list access is ~90% faster after initial cache warming, near zero delay for end users/frontend applications, zero delay on subsequent calls
  • Enhanced configuration - additionalTokens and overrideDefaultTokens now work with both static and async token methods
  • Better token validation - Centralized token structure validation and address normalization

Fixed

  • Decimal parsing bug - Fixed incorrect usage of .decimals instead of .address in approval functions on 'isRaw=true' configuration

Deprecated

  • Sync token methods (getTokenList(), isTokenListed()) are still supported but async methods are recommended for live data

Technical Details

Core Functions Migrated

  • checkApproval.js - Now uses async tokenService with user configuration
  • getRoute.js - Migrated to async tokenService with await getRouteDetails()
  • giveApproval.js - Updated to use async tokenService with await getTotalAmountIn()

Helper Functions Made Async

  • getTotalAmountOut.js - Function signature changed to async getTotalAmountOut(route)
  • getTotalAmountIn.js - Function signature changed to async getTotalAmountIn(route)
  • getRouteDetails.js - Function signature changed to async getRouteDetails(route)

Dependent Functions Updated

  • calculateAmountOutMin.js - Updated to await getTotalAmountOut()
  • swap.js - Updated to await getTotalAmountIn() for token amount calculations
  • generateCalldata.js - Updated to await getTotalAmountIn() for token values
  • Route entity methods - Made async where they call async helpers

Configuration Changes

  • config.js - Refactored to delegate token operations to tokenService
  • Token validation and merging logic moved to centralized tokenService
  • Native address handling improved across all implementations
  • feeParams configuration has changed increments from 1000 to 10000 for granular control over fees

Migration Guide

For Direct Helper Function Usage

// Before v3.0.0
const amountOut = getTotalAmountOut(route);
const amountIn = getTotalAmountIn(route);
const details = getRouteDetails(route);
 
// v3.0.0 and later
const amountOut = await getTotalAmountOut(route);
const amountIn = await getTotalAmountIn(route);
const details = await getRouteDetails(route);

For Route Entity Usage

// Before v3.0.0
const amountOut = route.getTotalAmountOut();
const amountIn = route.getTotalAmountIn();
const details = route.getRouteDetails();
 
// v3.0.0 and later
const amountOut = await route.getTotalAmountOut();
const amountIn = await route.getTotalAmountIn();
const details = await route.getRouteDetails();

For Live Token Data

// New in v3.0.0 - Live token data
const liveTokens = await symphony.getTokenListAsync();
const isListed = await symphony.isTokenListedAsync("0x...");
 
// Still supported - Static token data
const staticTokens = symphony.getTokenList();
const isListedStatic = symphony.isTokenListed("0x...");

For Fee Parameters

// Before v3.0.0
SymphonySDK.setConfig({
  feeParams: {
    paramFee: "100", // =10% fees cut from out amount
    feeAddress: "your-fee-receiver-address",
    feeSharePercentage: "800", // = 80% of fees cut sent to your fee receiver address
  },
});
 
// After v3.0.0
SymphonySDK.setConfig({
  feeParams: {
    paramFee: "1000", // =10% fees cut from out amount
    feeAddress: "your-fee-receiver-address",
    feeSharePercentage: "8000", // = 80% of fees cut sent to your fee receiver address
  },
});

For Fee Parameters

// Before v3.0.0
SymphonySDK.setConfig({
  feeParams: {
    paramFee: "100", // =10% fees cut from out amount
    feeAddress: "your-fee-receiver-address",
    feeSharePercentage: "800", // = 80% of fees cut sent to your fee receiver address
  },
});
 
// After v3.0.0
SymphonySDK.setConfig({
  feeParams: {
    paramFee: "1000", // =10% fees cut from out amount
    feeAddress: "your-fee-receiver-address",
    feeSharePercentage: "8000", // = 80% of fees cut sent to your fee receiver address
  },
});

For Custom Approval Amounts

// New in v3.0.0 - Custom amount override
// Use route's default amount (existing behavior)
await route.giveApproval();
 
// Override with custom raw amount (wei)
await route.giveApproval({
  amount: "1000000000000000000", // 1 token in wei
  options: { isRaw: true },
});
 
// Override with custom formatted amount
await route.giveApproval({
  amount: "1.05", // 1.05 tokens
  options: { isRaw: false },
});
 
// Works across all implementations (viem, ethersV5, ethers)

Performance Improvements

  • First async call: ~50-300ms (API fetch + cache)
  • Subsequent calls: ~0ms (served from cache for each session)
  • Background warming: No impact on SDK initialization time
  • Memory usage: Optimized caching with efficient cleanup

Backward Compatibility

  • All existing sync methods continue to work without changes
  • No breaking changes for users who don't directly call helper functions
  • Fee parameters should be updated to fit more granular fee controls
  • Gradual migration path available
  • Full configuration parity maintained