@imtbl/imx-wallet-sdk-web

Immutable Wallet SDK Web

Overview

Warning IMMUTABLE WALLET SDK WEB IS UNSTABLE
Since it has not hit the version 1.0 yet, its public interface should not be considered final. Future releases may include breaking changes without further notice. We will do our best to keep this documentation updated providing visibility on breaking changes planned.

The Immutable Wallet SDK Web (Wallet SDK) connects with users' L1 and L2 wallets and returns "signers". Signers are abstractions of blockchain user accounts (also known as "wallets") that can be used to sign messages and transactions that execute blockchain state-changing operations. The Wallet SDK is used in conjunction with the Immutable Core SDK Typescript (Core SDK), to which the Wallet SDK passes the signers to the Core SDK to execute its functionality.

Documentation

• Wallet SDK reference
• Core SDK reference
• Immutable X developer docs

Installation

The Wallet SDK package can be downloaded via NPM command line:

npm install @imtbl/imx-wallet-sdk-web --save

Quickstart

It is easy to set up and start using the Wallet SDK:

import {
  ENVIRONMENTS,
  L1_PROVIDERS,
  WalletSDK,
} from '@imtbl/imx-wallet-sdk-web';

(async () => {
  // Builds the Wallet SDK object
  const sdk = await WalletSDK.build({
    env: ENVIRONMENTS.STAGING,
    /*
      RPC config is only required if the WalletConnect provider (L1_PROVIDERS.WALLET_CONNECT)
      is being used. Follow this reference for the RPC config:
      https://docs.walletconnect.com/quick-start/dapps/web3-provider#provider-options
    */
    rpc: {
      3: 'https://ropsten.mycustomnode.com',
    },
  });

  // Connects on the chosen provider - WalletConnect
  const walletConnection = await sdk.connect({ provider: L1_PROVIDERS.WALLET_CONNECT });
  // For Metamask:
  // const walletConnection = await sdk.connect({ provider: L1_PROVIDERS.METAMASK });

  // Register the user using the Core SDK
  await coreSdkWorkflows.registerOffchain(walletConnection);
})();

Note
The coreSdkWorkflows object setup was omitted for brevity.
Check out the Workflows examples to get examples of how to set up the Core SDK workflows.

Note
The object WalletConnection can also be retrieved in the following ways:

// By calling the method `getWalletConnection`
const walletConnection = sdk.getWalletConnection();

// By listening to the event `WALLET_SDK_EVENTS.CONNECTION_UPDATED`
walletSdkEvents.on(
  WALLET_SDK_EVENTS.CONNECTION_UPDATED,
  (updatedWalletConnection: WalletConnection) =>
    { const walletConnection = updatedWalletConnection; },
);

Reference

Supported environments

To facilitate the environment changes, there is a provided list of enums that helps to control the environments/networks used.

• ENVIRONMENTS.DEVELOPMENT For local development infrastructure. Usually combined with the Ropsten/Goerli Ethereum network.
• ENVIRONMENTS.STAGING For testing and validation infrastructure. Usually combined with the Ropsten/Goerli Ethereum network.
• ENVIRONMENTS.PRODUCTION For the live and fresh daily basis infrastructure. Usually combined with the Mainnet Ethereum network.

Warning ROPSTEN DEPRECATION
Ropsten network is set to be deprecated in the near future.

Supported L1 wallets

• L1_PROVIDERS.WALLET_CONNECT To connect using WalletConnect.
• L1_PROVIDERS.METAMASK To connect using MetaMask.

Supported events

To help keep the application up to date with possible wallet changes externally triggered by the user, the Wallet SDK uses the event system to provide meaningful indications of its current state through the emitter walletSdkEvents and the enum WALLET_SDK_EVENTS. Check out below the current list of events.

• WALLET_SDK_EVENTS.CONNECTION_UPDATED When the user connects a fresh wallet or opens the application with a wallet already connected before.
• WALLET_SDK_EVENTS.WALLET_DISCONNECTED When the user disconnects the wallet on purpose, changes the wallet itself or changes the network.

Note
Check out the Events examples for code examples.

Compatibility matrix

Core SDK version	Wallet SDK version
0.7.0	0.1.2
0.7.0	0.1.3
0.7.0	0.1.4
0.7.0	0.1.5
0.7.0	0.1.6
0.7.0	0.1.7

Examples

Events

Events are a really powerful tool that can be used for a sort of different scenarios. Find below some different examples on how to control the application flow using the events provided by the Wallet SDK.

Note
Check out the Supported events reference to get the complete list of events.

Ensuring an up-to-date connection

It is important that applications have the most recent wallet connected for each user, to ensure that functions behave as expected. There may be instances where users change wallets or have two wallets connected, so the below code ensures the connection is up to date.

import {
  WALLET_SDK_EVENTS,
  WalletConnection,
  walletSdkEvents,
} from '@imtbl/imx-wallet-sdk-web';
import { Workflows } from '@imtbl/core-sdk';

// Defines a simple state interface
type UserWallet = {
  connection: WalletConnection | null,
}

// Creates the state
let userWallet: UserWallet = {
  connection: null,
};

// Defines the function to update the state
function updateUserWallet(newUserWallet: UserWallet) {
  userWallet = newUserWallet;
}

// Listens for connection update notifications and when triggered, updates the state
walletSdkEvents.on(
  WALLET_SDK_EVENTS.CONNECTION_UPDATED,
  (updatedWalletConnection: WalletConnection) =>
    updateUserWallet({ connection: updatedWalletConnection }),
);

// Listens for disconnection notifications and when triggered, cleans the state up
walletSdkEvents.on(
  WALLET_SDK_EVENTS.WALLET_DISCONNECTED,
  () => updateUserWallet({ connection: null }),
);

// Provides a function to register a user with the up-to-date connection
async function registerUser(coreSdkWorkflows: Workflows) {
  const { connection } = userWallet;

  if (!connection) throw new Error('There is still no wallet connection available.');

  await coreSdkWorkflows.registerOffchain(connection);
}

Handling screen statuses

It is useful for users to understand the status of their wallet (e.g Connected/disconnected). The below code allows developers to return the wallet status:

import {
  WALLET_SDK_EVENTS,
  walletSdkEvents,
} from '@imtbl/imx-wallet-sdk-web';

// Defines possible wallet statuses
enum WalletStatus {
  CONNECTED = 'Connected',
  DISCONNECTED = 'Disconnected'
}

// Creates the state
let walletStatus = WalletStatus.DISCONNECTED;

// Listens for connection update notifications and when triggered, updates the state
walletSdkEvents.on(
  WALLET_SDK_EVENTS.CONNECTION_UPDATED,
  (_) => { walletStatus = WalletStatus.CONNECTED; },
);

// Listens for disconnection notifications and when triggered, updates the state
walletSdkEvents.on(
  WALLET_SDK_EVENTS.WALLET_DISCONNECTED,
  () => { walletStatus = WalletStatus.DISCONNECTED; },
);

// Provides a function to get the current status
function getWalletStatus(): WalletStatus {
  return walletStatus;
}

Workflows

The Wallet SDK was designed to work in tandem with Core SDK and, as such, you can use the signers provided by the Wallet SDK to perform the workflows available in the Core SDK. Below you can find some examples of how to use the Wallet SDK to perform some of the workflows.

Note
The following examples use a Core SDK package version compatible with Wallet SDK integration. Check out the Compatibility matrix to get versions of the Core SDK which currently accepts Wallet SDK integration.

Buy (Create Trade)

import {
  ENVIRONMENTS,
  L1_PROVIDERS,
  WALLET_SDK_EVENTS,
  WalletConnection,
  walletSdkEvents,
  WalletSDK,
} from '@imtbl/imx-wallet-sdk-web';
import {
  getConfig,
  Workflows,
  GetSignableTradeRequest,
} from '@imtbl/core-sdk';

// Creates the state
const state : { walletConnection: WalletConnection | null; } =
  { walletConnection: null };

// Listens for connection update notifications and when triggered, updates the state
walletSdkEvents.on(
  WALLET_SDK_EVENTS.CONNECTION_UPDATED,
  (updatedWalletConnection: WalletConnection) =>
    { state.walletConnection = updatedWalletConnection; },
);

// Listens for disconnection notifications and when triggered, cleans the state up
walletSdkEvents.on(
  WALLET_SDK_EVENTS.WALLET_DISCONNECTED,
  () => { state.walletConnection = null; },
);

// Provides a function to build the Wallet SDK and connect on the chosen provider
async function setupWalletSDK(): Promise<WalletConnection> {
  const sdk = await WalletSDK.build({ env: ENVIRONMENTS.STAGING });

  return await sdk.connect({ provider: L1_PROVIDERS.METAMASK });
}

// Provides a function to build the Core SDK workflows
function setupCoreSDKWorkflows(): Workflows {
  const coreSdkConfig = getConfig({
    coreContractAddress: '0x4527BE8f31E2ebFbEF4fCADDb5a17447B27d2aef',
    registrationContractAddress: '0x6C21EC8DE44AE44D0992ec3e2d9f1aBb6207D864',
    chainID: 3, // Ropsten
    basePath: 'https://api.ropsten.x.immutable.com',
  });

  return new Workflows(coreSdkConfig);
}

// Provides a function to execute the Create Trade workflow
async function createTrade(
  walletConnection: WalletConnection,
  coreSdkWorkflows: Workflows,
  tradeRequest: GetSignableTradeRequest,
) {
  if (!walletConnection) throw new Error('There is still no wallet connection available.');

  await coreSdkWorkflows.registerOffchain(walletConnection);

  const createTradeResponse =
    await coreSdkWorkflows.createTrade(
      walletConnection,
      tradeRequest,
    );

  console.log(createTradeResponse);
}

(async () => {
  state.walletConnection = await setupWalletSDK();

  const coreSdkWorkflows = setupCoreSDKWorkflows();

  const fakeTradeRequest = {
    user: '0x00', // Ethereum address of the submitting user
    order_id: 1000, // The ID of the maker order involved
  };

  const { walletConnection } = state;

  await createTrade(walletConnection, coreSdkWorkflows, fakeTradeRequest);
})();