Skip to main content

Register users

On-chain registration is deprecated

Following an upgrade from StarkEx v3 to StarkEx v4, on-chain user registration is only required in the following scenarios where the L1-L2 wallet pair needs to be recorded on Ethereum (L1):

  • Withdrawals were initiated but not completed before the upgrade to StarkEx v4
  • Forced operations, such as full withdrawals.

User registration consists of two parts:

  1. Generating an Immutable X L2 user account for an Ethereum L1 account
  2. Registering the L1 <-> L2 wallet pair

This enables the following:

  • A user with an Ethereum L1 account now has an associated L2 account on Immutable X
  • L1 users can deposit L1 assets to their L2 account
  • An L2 user can transact on Immutable X (create orders, trade assets, transfer assets, etc.)
  • An L2 user can withdraw their assets on L2 to their L1 account

Off-chain, then on-chain registration​

By default, Immutable's registerUser endpoint first registers a user off-chain. This means that the L1-L2 wallet pair is recorded in an Immutable database. All transactions that the user performs on L2 are recorded against this registered L2 user, however, L1 is not yet aware of the wallet mapping.

Then, when the users performs a transaction that requires an update of the state of the corresponding L1 wallet (ie. withdrawing an NFT from the L2 wallet to the L1 wallet), the user is registered on-chain, which means recording the L1-L2 wallet pair on Ethereum (L1).

What's going on under the hood?​

  • A deterministic calculation according to EIP-2645 which uses the user's Ethereum key to sign a static string.
  • This signature is used as a cryptographic seed with generic path parameters defined by the proposal's derivation path for hierarchical keys: m / purpose' / layer' / application' / eth_address_1' / eth_address_2' / index (This is the step that binds the L2 key with the L1 key)
  • The generated private key is then passed through an efficient grinding method to enforce distribution within STARK's elliptic curve domain. The generated key pair is what you'll be using on a day-to-day basis to interact with any Immutable X functionality.

This is a high-level overview of the user registration process: User Registration

📝Guides

Core SDK​

1. Initialize the Core SDK​

In order to use the Core SDK, you need to initialize it.

2. Generate signers​

Registering a user requires the user's signature, so your application will need to create signers. See the guide on how to generate signers.

3. Register the user​

📚SDK reference
const walletConnection = { ethSigner, starkSigner };

client.registerOffchain(walletConnection);