v1 a v2

Guía de migración del SDK v1 a v2: actualiza a la arquitectura basada en vault y nuevas funciones

Esta guía cubre la migración de STON.fi SDK v1 a v2.

Resumen

SDK v2 introduce mejoras arquitectónicas y nuevos tipos de contratos:

• Compatibilidad con pools CPI (Producto Constante con Liquidez Concentrada)

• Compatibilidad con pools WStable (Estable Ponderado)

• Nueva arquitectura de enrutamiento

• Funciones de utilidad mejoradas para manejar cantidades de jetton

• Ayudantes de fábrica para instanciar contratos

Cambios incompatibles

Llamadas a métodos de Router y Pool

El método base Enrutador y Pool las llamadas a métodos ahora están obsoletas. Debe especificar explícitamente el tipo de pool.

v1:

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

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

v2:

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

// Para pools de Producto Constante (los más comunes)
const router = new DEX.v1.Router.CPI(address);
const swapParams = await router.getSwapJettonToJettonTxParams({
  // parámetros
});

// Para pools Estables Ponderados
const router = new DEX.v1.Router.WStable(address);
const swapParams = await router.getSwapJettonToJettonTxParams({
  // parámetros
});

Nuevos tipos de contratos

v2 añade compatibilidad con diferentes tipos de pools:

// Producto Constante con Liquidez Concentrada
const cpiRouter = new DEX.v1.Router.CPI(address);
const cpiPool = new DEX.v1.Pool.CPI(address);

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

Nuevas funciones

Funciones de utilidad

Nuevas funciones para manejar cantidades de jetton con decimales:

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

// Convertir una cantidad legible por humanos a unidades de blockchain
const amountInUnits = toUnits(100, 9); // 100 tokens con 9 decimales
// Resultado: 100000000000n

// Convertir unidades de blockchain a una cantidad legible por humanos
const humanAmount = fromUnits(100000000000n, 9);
// Resultado: "100"

Funciones de fábrica

Nuevos ayudantes de fábrica para crear instancias de contratos:

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

// Crear instancia de DEX con fábrica
const dex = dexFactory();

// Crear instancia de router con fábrica
const router = routerFactory('CPI', address);

Pasos de migración

1. Actualizar paquete

   npm install @ston-fi/sdk@^2.0.0

2. Actualizar llamadas a Router/Pool

   Reemplace todas las llamadas directas Enrutador y Pool con versiones tipadas:

   // Antiguo
   const router = new DEX.v1.Router(address);
   
   // Nuevo - especificar el tipo de pool
   const router = new DEX.v1.Router.CPI(address);

3. Actualizar llamadas a métodos

   La mayoría de las firmas de métodos siguen igual; solo cambia la instanciación de la clase:

   // Los métodos funcionan igual
   const swapParams = await router.getSwapJettonToJettonTxParams({
     userWalletAddress: wallet,
     offerJettonAddress: tokenA,
     askJettonAddress: tokenB,
     offerAmount: amount,
     minAskAmount: minAmount
   });

4. Usar nuevas utilidades

   Al trabajar con cantidades de tokens, use las nuevas funciones de utilidad:

   import { toUnits, fromUnits } from '@ston-fi/sdk';
   
   // En lugar de cálculos manuales
   const amount = 100n * 10n ** 9n;
   
   // Usar funciones de utilidad
   const amount = toUnits(100, 9);

Ejemplos de código

Migración de intercambio

v1:

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

v2:

// Especificar explícitamente el tipo de pool
const router = new DEX.v1.Router.CPI(routerAddress);
const params = await router.getSwapJettonToJettonTxParams({
  userWalletAddress: wallet,
  offerJettonAddress: tokenA,
  askJettonAddress: tokenB,
  offerAmount: toUnits(1, 9), // Usar función de utilidad
  minAskAmount: toUnits(0.9, 9)
});

Migración de operaciones de Pool

v1:

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

v2:

// Especificar tipo de pool
const pool = new DEX.v1.Pool.CPI(poolAddress);
const poolData = await pool.getPoolData();

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

Trabajar con diferentes tipos de pool

// Determinar el tipo de pool y crear la instancia apropiada
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(`Tipo de pool desconocido: ${poolType}`);
  }
}

Compatibilidad con versiones anteriores

• SDK v2 mantiene compatibilidad con los contratos inteligentes existentes

• Las firmas de los métodos permanecen en gran medida sin cambios

• El cambio principal está en cómo se instancian las clases Router y Pool

Problemas comunes

Errores de TypeScript

Si ve errores de TypeScript sobre propiedades faltantes CPI o WStable asegúrese de estar usando la importación correcta:

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

// Incorrecto - causará errores de TypeScript
const router = new DEX.v1.Router(address);

Errores en tiempo de ejecución

Si encuentra errores de "method not found", verifique que esté usando el tipo de pool correcto para su pool de destino.

¿Necesitas ayuda?

• Revisa la documentación del SDK

• Consulte el CHANGELOG para ver los cambios detallados

• Pregunte en Telegram