Proporcionar liquidez (v2)

Proporciona liquidez en STON.fi v2: depósitos de un solo lado con gestión automática de vault

Más información

• Guía de inicio rápido: Consulte nuestro Inicio rápido de Liquidity para un ejemplo completo de aplicación React

• Blog: Pools de liquidez de STON.fi e integración con TON

Si está simulando una provisión de liquidez con el simular provisión de liquidez endpoint y su cuenta LP ya contiene algunos tokens (p. ej., "lp_account_token_a_balance": "más de 0" o "lp_account_token_b_balance": "más de 0"), establecer token_a_units o token_b_units en la solicitud podría llevar a un min_lp_units inexacto en el resultado de la simulación. Esto podría resultar en pérdida permanente de fondos. Le recomendamos encarecidamente reembolsar cualquier token antiguo de la cuenta LP antes de continuar.

El patrón listo para producción es basado en API. Simule primero la provisión, deje que la API de STON.fi le indique qué router usar y luego cree las instancias de contrato dinámicamente. Esto mantiene su integración compatible con futuras actualizaciones del router y evita codificar las direcciones de los contratos.

Flujo de trabajo primero para mainnet

La API REST de STON.fi (api.ston.fi) solo sirve datos de mainnet, por lo que toda provisión de liquidez en producción debe seguir este flujo:

1. Simule la provisión para obtener metadatos de enrutamiento (dirección del pool, cantidades de tokens y el objeto completo del router).

2. Pase simulationResult.router directamente a dexFactory() para crear contratos dinámicamente.

3. Genere los parámetros de la transacción de provisión de liquidez con los ayudantes del router.

import { Client, dexFactory, toUnits } from "@ston-fi/sdk";
import { StonApiClient } from "@ston-fi/api";

const tonClient = new Client({
  endpoint: "https://toncenter.com/api/v2/jsonRPC",
});

const apiClient = new StonApiClient();

const userWalletAddress = "<su dirección de billetera>";
const tokenA = { address: "<dirección del activo A o 'ton'>", decimals: 9 };
const tokenB = { address: "<dirección del activo B>", decimals: 9 };
const amountA = "10"; // cantidad legible por humanos (p. ej. "10")
const amountB = "5";  // cantidad legible por humanos para el segundo token
const slippageTolerance = "0.001";

// Descubra los pools existentes para el par. Si no se encuentra ninguno, estamos creando un nuevo pool.
const [poolInfo] = await apiClient.getPoolsByAssetPair({
  asset0Address: tokenA.address,
  asset1Address: tokenB.address,
});

const provisionType = poolInfo ? "Balanced" : "Initial"; // o "Arbitrary" para proporciones manuales

const simulationInput: Parameters<StonApiClient["simulateLiquidityProvision"]>[0] = {
  tokenA: tokenA.address,
  tokenB: tokenB.address,
  provisionType,
  slippageTolerance,
  walletAddress: userWalletAddress,
  ...(poolInfo ? { poolAddress: poolInfo.address } : {}),
};

if (provisionType === "Initial") {
  simulationInput.tokenAUnits = toUnits(amountA, tokenA.decimals).toString();
  simulationInput.tokenBUnits = toUnits(amountB, tokenB.decimals).toString();
} else if (provisionType === "Balanced") {
  // Aporte **solo** un lado; la API calcula la cantidad correspondiente para el otro token.
  simulationInput.tokenAUnits = toUnits(amountA, tokenA.decimals).toString();
} else {
  // "Arbitrary" – proporcione cualquier proporción. Para hacerlo de un solo lado, establezca una de las cantidades en "0".
  simulationInput.tokenAUnits = toUnits(amountA, tokenA.decimals).toString();
  simulationInput.tokenBUnits = toUnits(amountB, tokenB.decimals).toString();
}

const simulationResult = await apiClient.simulateLiquidityProvision(simulationInput);

// 2. Los metadatos del router vienen con el resultado de la simulación
const { router: routerInfo } = simulationResult;
const dexContracts = dexFactory(routerInfo);

// 3. Abra el contrato del router
const router = tonClient.open(
  dexContracts.Router.create(routerInfo.address)
);

// Ayudante opcional cuando TON forma parte de la provisión
const proxyTon = dexContracts.pTON.create(routerInfo.ptonMasterAddress);

El simulationResult el objeto contiene provisionType, tokenA, tokenB, tokenAUnits, tokenBUnits, minLpUnits, y router. Reutilice esos valores al construir la transacción real de provisión para garantizar que la carga útil firmada coincida con la ruta simulada.

Interpretación de los resultados de la simulación

• Initial – aún no existe ningún pool. Proporcione cantidades positivas para ambos activos; el router desplegará el pool y acuñará los primeros tokens LP.

• Balanced – se añade liquidez a un pool existente al ratio actual. Proporcione una token amount (la otra es calculada por la API). El resultado siempre contiene dos valores positivos token*Units .

• Arbitrary – añada liquidez a un pool existente usando cualquier ratio. Proporcione cantidades explícitas para ambos tokens. Para realizar un depósito de un solo lado, establezca una de las cantidades en "0"; el SDK producirá un único mensaje que se apoya en la mecánica del vault.

Generación de mensajes de transacción

Defina la dirección TON canónica y mapee el resultado de la simulación a "piernas" del mensaje. Filtre las cantidades vacías para que las provisiones de un solo lado Arbitrary se reduzcan naturalmente a un solo mensaje.

const TON_ADDRESS = "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c";

const legs = [
  {
    userWalletAddress,
    minLpOut: simulationResult.minLpUnits,
    sendTokenAddress: simulationResult.tokenA,
    sendAmount: simulationResult.tokenAUnits,
    otherTokenAddress: simulationResult.tokenB,
  },
  {
    userWalletAddress,
    minLpOut: simulationResult.minLpUnits,
    sendTokenAddress: simulationResult.tokenB,
    sendAmount: simulationResult.tokenBUnits,
    otherTokenAddress: simulationResult.tokenA,
  },
].filter(({ sendAmount }) => BigInt(sendAmount) > 0n);

const isSingleSide =
  simulationResult.provisionType === "Arbitrary" && legs.length === 1;

const txParams = await Promise.all(
  legs.map((leg) => {
    if (leg.sendTokenAddress === TON_ADDRESS) {
      const tonLeg = {
        ...leg,
        proxyTon,
      };

      return isSingleSide
        ? router.getSingleSideProvideLiquidityTonTxParams(tonLeg)
        : router.getProvideLiquidityTonTxParams(tonLeg);
    }

    const jettonLeg = {
      ...leg,
      otherTokenAddress:
        leg.otherTokenAddress === TON_ADDRESS
          ? proxyTon.address.toString()
          : leg.otherTokenAddress,
    };

    return isSingleSide
      ? router.getSingleSideProvideLiquidityJettonTxParams(jettonLeg)
      : router.getProvideLiquidityJettonTxParams(jettonLeg);
  }),
);

Envíe el txParams array resultante en una sola transacción. Consulte nuestro guía para enviar transacciones para ejemplos específicos de billeteras.

Ejecute la transacción usando la integración de billetera que prefiera. TonConnect, Tonkeeper SDK, firmantes custodiales y otras bibliotecas aceptan todos los txParams generados arriba.

Provisiones en testnet (configuración manual)

Si realmente necesita realizar provisiones de liquidez en la testnet de TON, debe recurrir a contratos codificados manualmente porque api.ston.fi solo sirve para mainnet. La liquidez es escasa, así que planifique obtener o acuñar usted mismo los jettons, crear y financiar los pools necesarios y solo entonces intentar la provisión.

Para replicar los ejemplos anteriores en testnet, los probadores suelen usar TesREED/TestBlue y ejecutar depósitos tanto de un solo lado como equilibrados.

import { TonClient, toNano } from "@ton/ton";
import { DEX, pTON } from "@ston-fi/sdk";

const client = new TonClient({
  endpoint: "https://testnet.toncenter.com/api/v2/jsonRPC",
});

const router = client.open(
  DEX.v2_1.Router.CPI.create("kQALh-JBBIKK7gr0o4AVf9JZnEsFndqO0qTCyT-D-yBsWk0v") // Router CPI v2.1.0 (testnet)
);

const proxyTon = pTON.v2_1.create("kQACS30DNoUQ7NfApPvzh7eBmSZ9L4ygJ-lkNWtba8TQT-Px"); // pTON v2.1.0 (testnet)

const txParams = await router.getProvideLiquidityJettonTxParams({
  userWalletAddress: "<su billetera de testnet>",
  sendTokenAddress: "kQDLvsZol3juZyOAVG8tWsJntOxeEZWEaWCbbSjYakQpuYN5", // jetton TesREED (testnet)
  sendAmount: toNano("1"),
  otherTokenAddress: "kQB_TOJSB7q3-Jm1O8s0jKFtqLElZDPjATs5uJGsujcjznq3", // jetton TestBlue (testnet)
  minLpOut: "1",
  queryId: 12345,
});

Este enfoque manual es estrictamente para pruebas. Vuelva al flujo de trabajo impulsado por la API para cualquier cosa orientada a mainnet.