Skip to content

What's New in v3.0.0

With version 3.0.0 there are breaking changes. This page will guide you through the migration and explain what you need to know.

A Quick Summary

  • Symphony contract address has changed to a proxy contract lies at 0xC340F8C5C58f4f99B4e43673eba07Cf378047DD2. From now on frequent contract address changes are not expected. Sdk handles contract address change internally.
  • Usage of getTotalAmountOut(), getTotalAmountIn(), getRouteDetails(), Route.getTotalAmountOut(),Route.getTotalAmountIn(), Route.getRouteDetails() will break your application on v3.0.0 update. If you haven't used them, your application will not break but highly advise migrating from deprecated functions.
  • With v3.0.0 you can have dynamic token list. After v3.0.0 newly added tokens by Symphony will reflect to your token list.
  • You can still opt out of following Symphony list and provide your own curated list while using Symphony SDK.
  • All the configurations are still functional with or without new token list mechanism. See Configuration Page
  • feeParams now operate on a 10000 basis point (bps) scale instead of 1000. Please update your feeParams configuration to preserve your existing fee structure. Using the old configuration with v3.0.0 will result in only one-tenth of the intended fees being applied.
  • NEW: giveApproval() now supports custom amount override, allowing you to approve any amount regardless of the route's swap amount across all implementations (viem, ethersV5, ethers).

Breaking Changes

Breaking changes include updates to helper function usage and the feeParams configuration. If your project does not rely on these functions or a custom fee configuration, upgrading to v3.0.0 will not affect your application. Most helper methods are primarily used internally.

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 Class 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();

If you were using helper functions on your project, consider using Route object directly. If you have a resolved Route, you can reach amountIn, amountOut or details provided by getRouteDetails() function directly from Route object. See Route.

For feeParams Configuration

// 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
  },
});

Deprecated Methods and Migration to Live Token List

Those methods are widely used methods that are subjected to change. They are flagged '@deprecated' but will continue to work. Highly suggest migrating them to newer methods.

For Live Token Data

If you have following implementations in your code:

  • symphony.getTokenList()
  • symphony.getConfig().tokens
  • symphony.isTokenListed()

please migrate them to;

// 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 staticTokensAlternative = symphony.getConfig().tokens;
const isListedStatic = symphony.isTokenListed("0x...");

New Custom Approval Functionality

Version 3.0.0 introduces enhanced approval functionality that allows you to override the default approval amount when working with routes. This feature is available across all implementations (viem, ethersV5, and ethers).

Custom Amount Override

// Use route's default amount (existing behavior - no changes needed)
await route.giveApproval();
 
// NEW: Override with custom raw amount (wei)
await route.giveApproval({
  amount: "2000000000000000000", // 2 tokens in wei
  options: { isRaw: true },
});
 
// NEW: Override with custom formatted amount
await route.giveApproval({
  amount: "1.05", // 1.05 tokens (automatically converted to wei)
  options: { isRaw: false },
});

Use Cases

This functionality is particularly useful for:

  • Batch approvals: Approve larger amounts to reduce future transaction costs, give users to give infinite approval.
  • Precise control: Set exact approval amounts for security or compliance reasons
  • Custom strategies: Implement your own approval management logic

Performance

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