v1 to v2

Migration guide from SDK v1 to v2 - upgrade to vault-based architecture and new features

This guide covers the migration from STON.fi SDK v1 to v2.

Overview

SDK v2 introduces architectural improvements and new contract types:

• Support for CPI (Constant Product with Concentrated Liquidity) pools

• Support for WStable (Weighted Stable) pools

• New routing architecture

• Enhanced utility functions for handling jetton amounts

• Factory helpers for contract instantiation

Breaking Changes

Router and Pool Method Calls

The base Router and Pool method calls are now deprecated. You must specify the pool type explicitly.

v1:

import { DEX } from '@ston-fi/sdk';

const router = new DEX.v1.Router(address);
const swapParams = await router.getSwapJettonToJettonTxParams({
  // parameters
});

v2:

import { DEX } from '@ston-fi/sdk';

// For Constant Product pools (most common)
const router = new DEX.v1.Router.CPI(address);
const swapParams = await router.getSwapJettonToJettonTxParams({
  // parameters
});

// For Weighted Stable pools
const router = new DEX.v1.Router.WStable(address);
const swapParams = await router.getSwapJettonToJettonTxParams({
  // parameters
});

New Contract Types

v2 adds support for different pool types:

// Constant Product with Concentrated Liquidity
const cpiRouter = new DEX.v1.Router.CPI(address);
const cpiPool = new DEX.v1.Pool.CPI(address);

// Weighted Stable pools
const wstableRouter = new DEX.v1.Router.WStable(address);
const wstablePool = new DEX.v1.Pool.WStable(address);

New Features

Utility Functions

New functions for handling jetton amounts with decimals:

import { toUnits, fromUnits } from '@ston-fi/sdk';

// Convert human-readable amount to blockchain units
const amountInUnits = toUnits(100, 9); // 100 tokens with 9 decimals
// Result: 100000000000n

// Convert blockchain units to human-readable amount
const humanAmount = fromUnits(100000000000n, 9);
// Result: "100"

Factory Functions

New factory helpers for creating contract instances:

import { dexFactory, routerFactory } from '@ston-fi/sdk';

// Create DEX instance with factory
const dex = dexFactory();

// Create router instance with factory
const router = routerFactory('CPI', address);

Migration Steps

1. Update Package

   npm install @ston-fi/sdk@^2.0.0

2. Update Router/Pool Calls

   Replace all direct Router and Pool calls with typed versions:

   // Old
   const router = new DEX.v1.Router(address);
   
   // New - specify pool type
   const router = new DEX.v1.Router.CPI(address);

3. Update Method Calls

   Most method signatures remain the same, just the class instantiation changes:

   // Methods work the same way
   const swapParams = await router.getSwapJettonToJettonTxParams({
     userWalletAddress: wallet,
     offerJettonAddress: tokenA,
     askJettonAddress: tokenB,
     offerAmount: amount,
     minAskAmount: minAmount
   });

4. Use New Utilities

   When working with token amounts, use the new utility functions:

   import { toUnits, fromUnits } from '@ston-fi/sdk';
   
   // Instead of manual calculations
   const amount = 100n * 10n ** 9n;
   
   // Use utility functions
   const amount = toUnits(100, 9);

Code Examples

Swap Migration

v1:

const router = new DEX.v1.Router(routerAddress);
const params = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: wallet,
  offerJettonAddress: tokenA,
  askJettonAddress: tokenB,
  offerAmount: 1000000000n,
  minAskAmount: 900000000n
});

v2:

// Specify pool type explicitly
const router = new DEX.v1.Router.CPI(routerAddress);
const params = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: wallet,
  offerJettonAddress: tokenA,
  askJettonAddress: tokenB,
  offerAmount: toUnits(1, 9), // Use utility function
  minAskAmount: toUnits(0.9, 9)
});

Pool Operations Migration

v1:

const pool = new DEX.v1.Pool(poolAddress);
const poolData = await pool.getPoolData();

v2:

// Specify pool type
const pool = new DEX.v1.Pool.CPI(poolAddress);
const poolData = await pool.getPoolData();

// For stable pools
const stablePool = new DEX.v1.Pool.WStable(poolAddress);
const stablePoolData = await stablePool.getPoolData();

Working with Different Pool Types

// Determine pool type and create appropriate instance
function createPoolInstance(poolType: 'CPI' | 'WStable', address: string) {
  switch(poolType) {
    case 'CPI':
      return new DEX.v1.Pool.CPI(address);
    case 'WStable':
      return new DEX.v1.Pool.WStable(address);
    default:
      throw new Error(`Unknown pool type: ${poolType}`);
  }
}

Backwards Compatibility

• The SDK v2 maintains compatibility with existing smart contracts

• Method signatures remain largely unchanged

• The main change is in how you instantiate Router and Pool classes

Common Issues

TypeScript Errors

If you see TypeScript errors about missing CPI or WStable properties, ensure you're using the correct import:

// Correct
import { DEX } from '@ston-fi/sdk';
const router = new DEX.v1.Router.CPI(address);

// Incorrect - will cause TypeScript errors
const router = new DEX.v1.Router(address);

Runtime Errors

If you encounter "method not found" errors, verify you're using the correct pool type for your target pool.

Need Help?

• Review the SDK documentation

• Check the CHANGELOG for detailed changes

• Ask in Telegram