Core SDK to Typescript SDK Migration Guide
This guide is intended to help you migrate from the deprecated Core 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.