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
• UI guide for implementing user wallet interactions

Installation

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

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

Quickstart

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

import {
  ENVIRONMENTS,
  L1_PROVIDERS,
  WalletSDK,
} from '@imtbl/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: {
      5: 'https://goerli.mycustomnode.com',
    },
    /*
      Will switch the chain based on this configured chainID when connecting to the wallet.(Optional)
      Following the table below to get the chainID and name mapping. 
      Consult https://chainlist.org/ for more.
      ChainId	| Network
      --- --- | --- --- 
      1	      | Ethereum Main Network (Mainnet)
      5	      | Goerli Test Network
    */
    chainID: 5,
  });

  // 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 Goerli Ethereum network.
• ENVIRONMENTS.STAGING For testing and validation infrastructure. Usually combined with the Goerli Ethereum network.
• ENVIRONMENTS.PRODUCTION For the live and fresh daily basis infrastructure. Usually combined with the Mainnet Ethereum network.

Supported L1 wallets

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

Note Immutable X does not recommend the use of hardware wallets, as some of them have non-deterministic signing. Please inform your users to select a soft wallet when connecting.

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.

Errors

Refer to the following list for the most common errors raised by the Wallet SDK and to get a guidance on how to solve them.

| Error message | Scenario | Solution | | ------------- | -------- | -------- | | The L1 provider {L1Provider} is not a valid option. | When an invalid L1 provider option was informed when calling connect(). | Provide a valid L1 provider option based on the Supported L1 wallets. | | The MetaMask provider was not found. | When a connect() using MetaMask was attempted but most likely the MetaMask extension was not installed. | Install the MetaMask extension or provide another valid L1 provider option based on the Supported L1 wallets. | | You cannot connect to WalletConnect Provider because RPC is not defined. | When a connect() using WalletConnect was attemped but the RPC was not provided. | Provide the RPC based on the Quickstart example. | | The L2 IMX Wallet connection has failed. | When a connect() was attempted on the L2 but was not succeeded. | Retry a connection, and if the error persists, contact the support team. |

Compatibility matrix

| Core SDK version | Wallet SDK version | | :--------------: | :----------------: | | 0.7.0 | 0.1.8 | | 0.7.0 | 0.1.9 |

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/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/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/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: 5, // goerli
    basePath: 'https://api.sandbox.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);
})();