> For the complete documentation index, see [llms.txt](https://ston-fi.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ston-fi.gitbook.io/docs/developer-section/dex/sdk/migration/v1-to-v2.md).

# v1 to v2

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:**

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

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

**v2:**

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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**

   ```bash
   npm install @ston-fi/sdk@^2.0.0
   ```
2. **Update Router/Pool Calls**

   Replace all direct `Router` and `Pool` calls with typed versions:

   ```typescript
   // 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:

   ```typescript
   // 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:

   ```typescript
   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:**

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

**v2:**

```typescript
// 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:**

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

**v2:**

```typescript
// 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

```typescript
// 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:

```typescript
// 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](https://github.com/ston-fi/sdk)
* Check the [CHANGELOG](https://github.com/ston-fi/sdk/blob/main/CHANGELOG.md) for detailed changes
* Ask in [Telegram](https://t.me/stonfidex)