v0.5 to v1

Migration guide from SDK v0.5 to v1.0 - transition to stable API with enhanced features

Introduction

In the SDK v1.0.0 release, we introduce some breaking changes. You can find the complete list of the release changes in the CHANGELOG.md file, but in this docs section, we will be focused on some real code snippet migration from the SDK v0.5.* to v1.0.0

Let's migrate the v0.5.* jetton to TON swap example code to the v1.0.0:

import TonWeb from "tonweb";
import { DEX, pTON } from "@ston-fi/sdk";

const router = new DEX.v1.Router({
  tonApiClient: new TonWeb.HttpProvider(),
});

const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({
  userWalletAddress: "", // ! replace with your address
  offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  offerAmount: new TonWeb.utils.BN("1000000000"),
  proxyTonAddress: pTON.v1.address,
  minAskAmount: new TonWeb.utils.BN("1"),
  queryId: 12345,
});

TonWeb package replacement with @ton/ton

The main source of this release's breaking changes is the migration from the tonweb to the @ton/ton package. So, the first step is to add the @ton/ton package to your project. To do that, follow the installation step from their docs.

As a result of this step, we need to be able to create an instance of TonClient that @ton-ton package uses to make on-chain requests.

import { TonClient } from "@ton/ton";

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

Contract constructor interface change

Since the @ton package makes an on-chain request by injecting the provider into open contract methods, SDK contracts no longer need to require a tonApiClient in constructor parameters. So, the contract's constructor interface has been changed to accept the address as a first parameter and the configuration object as a second parameter.

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

type ContractsConstructorParameters = ConstructorParameters<
  typeof DEX.v1.Router
>;
// ^: [address: Address | string, (RouterV1Options | undefined)?]

That means router contract creation in the code we are migrating needed to be changed to the following:

- import TonWeb from 'tonweb';

const router = new DEX.v1.Router(
-  {
-    tonApiClient: new TonWeb.HttpProvider(),
-  }
);

Router.v1 has a known default address, so the first constructor parameter, in this case, is optional. For other contracts, there is no default address, so it should be specified

const pool = new DEX.v1.Pool(
  "EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U" // STON/GEMSTON pool
);

If you specified custom gasConstants for a contract, it is still possible to do so. Only instead of passing them as part of the first constructor parameter object, you need to pass them in a second object

const pool = new DEX.v1.Pool(
+ 'EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U',
  {
-    address: 'EQCl-ax-5QC06ub096s2bqTbhYZWigZ1-FkJm2IVIMSazp7U',
    gasConstants: {
        burn: DEX.v1.Pool.gasConstants.burn,
    }
  }
);

"Opening" of the contracts

The @ton/ton package needs to be opened for use in making on-chain requests from the contract.

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

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

- const router = new DEX.v1.Router();
+ const router = client.open(new DEX.v1.Router());

build*TxParams methods renaming

All contracts build*TxParams methods were renamed to get*TxParams. This was needed to math @ton/ton package convention for methods that could make on-chain request

- const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({

+ const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({

BN.js replacement with native BigInt

In the previous version of the SDK package, to represent the amount, we used BN.js, which came as a part of the TonWeb package and was accessible via TonWeb.utils.BN. @ton/ton package uses native javascript BigInt instead of BN.js.

And the migration is peaty easy - since the constructors of BN and BigInt are comparable. We only need to replace Class that represents the amount

-  offerAmount: new TonWeb.utils.BN('1000000000'),
+  offerAmount: BigInt('1000000000'),
-  minAskAmount: new TonWeb.utils.BN('1'),
+  minAskAmount: BigInt('1'),

Operations with pTON

Previously, every operation that worked with a native TON requested a proxyTonAddress. But since we are developing the next version of the proxyTon contract with some differences in the ton sending transaction instead of only the address, we need to know more about the proxyTon.

So now operations with native ton require the instance of pTON contracts.

const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
-  proxyTonAddress: pTON.v1.address,
+  proxyTon: new pTON.v1(),
});

txParams shape change and MessageData type drop

To better match @ton/ton package interfaces, we slightly changed the object's shape that returns from the get*TxParams methods. The change is only in names; the purpose of this field stayed unchanged. It describes the transaction that, if sent, will cause the requested action on the DEX.

This change lets us use the get*TxParams methods output directly in the @ton/ton send functionality.

Before

type TxParams = typeof tonToJettonTxParams;
// ^: { to: Address, gasAmount: BN, payload: Cell }

After

type TxParams = typeof tonToJettonTxParams;
// ^: { to: Address, value: BigInt, body?: Cell | null }

Because we switched from our MessageData interface to @ton/ton SenderArguments type, MessageData export from the SDK package was removed

Contracts method renaming

In v1.0.0, some of the contract methods were renamed:

v0.5.*	v1.0.0
RouterV1.getData	RouterV1.getRouterData
PoolV1.getData	PoolV1.getPoolData
LpAccountV1.getData	LpAccountV1.getLpAccountData

Conclusion

And in the end this is a code we have migrated to

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

const client = new TonClient({
  endpoint: "https://ton-api.ston.fi/jsonRPC",
});

const router = client.open(new DEX.v1.Router());

const tonToJettonTxParams = await router.getSwapJettonToTonTxParams({
    userWalletAddress: "", // ! replace with your address
    offerJettonAddress: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    offerAmount: BigInt("1000000000"),
    proxyTon: new pTON.v1(),
    minAskAmount: BigInt("1"),
    queryId: 12345,
  });