Skip to main content

Generate signers

User signatures are required for certain types of operations on Immutable X. These are:

  1. Transactions that update blockchain state
  2. Operations that update Immutable X's databases that require user authorization for

Examples:

✅ Require user signatures❌ Do not require user signatures
Transactions that update
blockchain state
Operations requiring user
authorization
Read-only operations
  • Creating an order
  • Filling an order (creating a trade)
  • Transferring assets between users
  • Depositing assets on L2 (Immutable X)
  • Withdrawing assets to L1 (Layer 1 Ethereum)
  • Creating a project
  • Registering a user off-chain
  • Getting a list of all assets on Immutable X
  • Getting the details (ie. metadata) of a particular asset
  • Getting a list of all open orders
  • Getting a list of historical trades

Using "signers" to get user signatures

In order to get user signatures, applications can use "signers". These are abstractions of user accounts that can be used to sign transactions. A user's private key is required to generate them.

Ethereum (L1) signers are required to sign transactions on L1 (ie. depositing assets from the L1 wallet to the L2 one) and Stark (L2) signers are required to sign transactions on L2 (ie. creating an order on an L2 marketplace, transferring an asset to another user on L2).

How do applications generate and use signers?

There are two ways to get signers in your application:

  1. Generate your own by obtaining and using the user's private keys
  2. Connect to a user's wallet application

The first option, where an application obtains a user's private key directly, is risky because these keys allow anyone in possession of them full control of an account.

The second option provides an application with an interface to the user's account by prompting the user to connect with their wallet application (ie. mobile or browser wallet). Once connected the app can begin asking the user to sign transactions and messages without having to reveal their private key.

1. Generate your own signers

💡Available with:

Below are instructions on how to generate:

  • Ethereum (L1) signers
  • Stark (L2) private keys and signers using the Typescript SDK
caution

If you generate your own Stark private key, you will have to persist it. The key is randomly generated so cannot be deterministically re-generated.

The SDK provides functionality for applications to generate Stark (L2) generateStarkPrivateKey and createStarkSigner

import { AlchemyProvider } from '@ethersproject/providers';
import { Wallet } from "@ethersproject/wallet";
import { x } from "@imtbl/sdk";

const {
generateStarkPrivateKey,
createStarkSigner
} = x;

const apiKey = '<YOUR_ALCHEMY_API_KEY>';
const ethPrivateKey = '<YOUR ETH PRIVATE KEY>';

// Create Ethereum signer
const ethNetwork = 'sepolia'; // Or 'mainnet'
const provider = new AlchemyProvider(ethNetwork, apiKey);
const ethSigner = new Wallet(ethPrivateKey).connect(provider);

// Create Stark signer
const starkPrivateKey = generateStarkPrivateKey(); // Or retrieve previously generated key
const starkSigner = createStarkSigner(starkPrivateKey);

2. Connect to users' wallets

Your application can facilitate signing of user transactions by connecting to users' wallet applications. This ensures that you do not have to handle private keys.

💡Available with:
  1. Install the npm package:
npm install @imtbl/imx-sdk --save
# or
yarn add @imtbl/imx-sdk
  1. Import the Link package:
import { Link } from '@imtbl/imx-sdk';
  1. Set the correct network URL

Choose from the following:

NetworkDescriptionURL
SandboxThe default test network (currently, it is Sepoliahttps://link.sandbox.x.immutable.com/v1
ProductionEthereum networkhttps://link.x.immutable.com/v1
const linkAddress = 'https://link.x.immutable.com/v1'; // Or "https://link.sandbox.x.immutable.com/v1"
  1. Initialize the client
const link = new Link(linkAddress);

Operations like registering a user (see guide) can be executed by the Link client, which uses the JS SDK under the hood.