v0.4 to v0.5

Migration guide from SDK v0.4 to v0.5 - update your integration with breaking changes

Introduction

In the SDK v0.5 release, we introduce some breaking changes. You can find the full 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.4 to v0.5

Let's migrate the v0.4 jetton to TON swap example code to the v0.5:

import TonWeb from 'tonweb';
import { Router, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

const WALLET_ADDRESS = ''; // ! replace with your address
const JETTON0 = 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO'; // STON
const PROXY_TON = 'EQCM3B12QK1e4yZSf8GtBRT0aLMNyEsBc_DhVfRRtOEffLez'; // ProxyTON

const provider = new TonWeb.HttpProvider();

const router = new Router(provider, {
  revision: ROUTER_REVISION.V1,
  address: ROUTER_REVISION_ADDRESS.V1,
});

const tonToJettonTxParams = await router.buildSwapJettonTxParams({
  userWalletAddress: WALLET_ADDRESS,
  offerJettonAddress: JETTON0,
  offerAmount: new TonWeb.utils.BN('1000000000'),
  askJettonAddress: PROXY_TON,
  minAskAmount: new TonWeb.utils.BN('1'),
  queryId: 12345,
});

Contracts export change

The first thing you will face after the SDK update is that Module '"@ston-fi/sdk"' has no exported member Router.

This is because contracts (such as Router, Pool, LpAccount, etc) now no longer exported by their names. We start to use the export of domain related objects that will contain all the contracts.

At the current state SDK exports 3 domain object DEX, FARM, pTON.

So the first required change to our code is to replace the import of Router contract with the DEX object.

- import { Router, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

+ import { DEX, ROUTER_REVISION, ROUTER_REVISION_ADDRESS } from '@ston-fi/sdk';

Contract revision drop

Because multiple versions of the contracts appeared with uncomparable interfaces, we were forced to drop the architecture with revisions and the root class that obtained multiple revisions.

before:

.
└── dex
    └── Router
        └── Router
            ├── RouterRevisionV1
            └── RouterRevisionV2

after:

.
└── dex
    └── Router
        ├── RouterV1
        └── RouterV2

If you use extends or overrides contract revisions from the SDK anywhere in your code, you will now need to override the contract class instead.

If you use the override of the revision to define custom gas constants, it's now possible to pass gas constants as constructor parameters.

Contract version

Since we dropped revisions but still need to be able to separate different contracts, every contract now provides the statice field version. And to math this, *_REVISION enums was renamed to *_VERSION.

Now you can use it like this:

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

DEX.v1.Router.version === DEX_VERSION.v1

*_VERSION enum values is in lover case (v1) to match the STON.fi API responses

Back to our code - you can just remove import and usage of the ROUTER_REVISION completely and instead, to determine witch version of the DEX contract you would like to use, use version key of the domain object (DEX in this case)

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

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

-  const router = new Router(provider, {
-   revision: ROUTER_REVISION.V1,
+  const router = new Dex.v1.Router(provider, {
    address: ROUTER_REVISION_ADDRESS.V1,
  });

Contract address constant drop

For contracts with known addresses (for example, a router), the address is available as a static field on the class and is no longer required to be specified in the constructor.

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

DEX.v1.Router.address; // EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt
pTON.v1.address; // EQCM3B12QK1e4yZSf8GtBRT0aLMNyEsBc_DhVfRRtOEffLez

The following changes need to be made on this step

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

  const router = new Dex.v1.Router(provider, {
-  address: ROUTER_REVISION_ADDRESS.V1,
  });

Contract constructor parameters

All contract constructors now require 1 object with tonApiClient field to be passed. tonApiClient is a name for what in TonWeb is named provider.

-   const provider = new TonWeb.HttpProvider();

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

Optionally, you can pass an instance of stonApiClient. This is a class from @ston-fi/api package. If it is passed, STON.fi public REST API will be used to fetch data instead of using direct on-chain methods called via TON API.

At the current state of the package development, this client is optional, but we expect it to be required in the future when it no longer is possible to get some data required for the SDK to work from on-chain and

Contracts method renaming

In v0.5, some of the contract methods were renamed:

v0.4	v0.5
buildSwapJettonTxParams	buildSwapJettonToJettonTxParams & buildSwapJettonToTonTxParams
buildSwapProxyTonTxParams	buildSwapTonToJettonTxParams
buildProvideLiquidityProxyTonTxParams	buildProvideLiquidityTonTxParams

Our code snippet using renamed fn buildSwapJettonTxParams that was split in two: buildSwapJettonToJettonTxParams & buildSwapJettonToTonTxParams. Since we are swapping a jetton to TON, we will use a new fn buildSwapJettonToTonTxParams

-   const tonToJettonTxParams = await router.buildSwapJettonTxParams({

+   const tonToJettonTxParams = await router.buildSwapJettonToTonTxParams({

buildSwapJettonToTonTxParams fn now explicitly requires us to pass the address of the pTON contract to be used in the swap. Previously, it required the same, but under the askJettonAddress name, that was confusing.

-  askJettonAddress: PROXY_TON,

+  proxyTonAddress: PROXY_TON,

pTON contract

Because pTON class is now exported from the SDK we can use address from the pTON contract instead of a hardcoded string value in our code

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

- const PROXY_TON = 'EQCM3B12QK1e4yZSf8GtBRT0aLMNyEsBc_DhVfRRtOEffLez'; // ProxyTON
+ const PROXY_TON = pTON.v1.address;

Conclusion

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

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,
});