Skip to main content

Core SDK to Unified TypeScript SDK Migration Guide

This guide is intended to help you migrate from the deprecated Core Typescript SDK to the Typescript SDK.

The Typescript SDK (@imtbl/sdk) provides access to all of the functionality of the imx-core-sdk (@imtbl/core-sdk), as well as additional features and improvements.

The migration process is straightforward and should not require significant changes to your application code.

Installation​

Remove imx-core-sdk:

# npm
npm uninstall imx-core-sdk
# or yarn
yarn remove imx-core-sdk

Install ts-immutable-sdk:

# npm
npm install @imtbl/sdk
# or yarn
yarn add @imtbl/sdk

Code Changes​

The IMXClient class from the ts-immutable-sdk is a mostly drop-in replacement for the ImmutableX class from imx-core-sdk.

The previous ImmutableX and Config import and initialization from imx-core-sdk:

// old imx-core-sdk initialization
import { ImmutableX, Config } from 'imx-core-sdk';

const config = Config.SANDBOX;
const client = new ImmutableX(config);

Update to:

// new ts-immutable-sdk initialization
import { config, x } from '@imtbl/sdk';

const { Environment } = config;
const {
  IMXClient,
  imxClientConfig, // helper method to create a client config
  ImmutableX,      // alias for IMXClient
} = x;

const imxClient = new IMXClient(imxClientConfig({ environment: Environment.SANDBOX }));

Basic Usage​

Once you have the new IMXClient instance, you can use it like the previous ImmutableX instance.

// follows the same pattern as the previous ImmutableX instance
// https://www.npmjs.com/package/@imtbl/core-sdk#get-all-collections-and-get-assets-from-a-particular-collection
const collections = await imxClient.listCollections({
  pageSize: 2,
});

Code Splitting​

An alternative to the example above is importing the whole SDK and destructuring the SDK modules; importing only the required modules is possible to reduce the bundle size.

Check the Typescript SDK - Code Splitting documentation for more details.

Browser Bundle​

The ts-immutable-sdk also provides browser bundles hosted on unpkg.com and jsdelivr.com. These can be used to include the SDK in a web application without needing to install it as a dependency.

See the Typescript SDK - Browser Bundle documentation for more details.

Major Differences​

As mentioned, the IMXClient class is a mostly drop-in replacement for the ImmutableX class. Some methods that were previously available on the ImmutableX class are no longer available on the IMXClient class.

Instead, they are now available on the GenericIMXProvider class.

The following methods have been moved from IMXClient to GenericIMXProvider:

  • getAddress
  • registerOffchain
  • isRegisteredOffchain
  • isRegisteredOnchain
  • createOrder
  • cancelOrder
  • createTrade
  • transfer
  • batchNftTransfer
  • exchangeTransfer
  • deposit
  • prepareWithdrawal
  • completeWithdrawal

GenericIMXProvider Usage​

The GenericIMXProvider class is used to access the methods that were previously available on the ImmutableX class.

import { config, x } from '@imtbl/sdk';
import { AlchemyProvider } from '@ethersproject/providers';

const { Environment } = config;
const {
  createStarkSigner,
  GenericIMXProvider,
  IMXClient,
  imxClientConfig,
  ProviderConfiguration,
  generateLegacyStarkPrivateKey,
} = x;

// assuming network and alchemyKey are defined
// alternatively, you could use JsonRpcProvider from @ethersproject/providers
const provider = new AlchemyProvider(network, alchemyKey);

const environment = Environment.SANDBOX;
const ethSigner = new Wallet(privateKey /** from env.var or elsewhere */).connect(provider);
const starkPrivateKey = await generateLegacyStarkPrivateKey(ethSigner);
const starkSigner = createStarkSigner(starkPrivateKey);

const imxProviderConfig = new ProviderConfiguration({
  baseConfig: {
    environment,
  },
});
const imxProvider = new GenericIMXProvider(
  imxProviderConfig,
  ethSigner,
  starkSigner,
);
const userAddress = await imxProvider.getAddress();

Testing​

Test your application thoroughly to ensure that the migration has been successful and that all functionality is working as expected.