Accounts

Lighter EVM and Lighter Core use separate account models. This page explains both models and how an EVM address can control a Core account.

Lighter EVM accounts

Lighter EVM uses the same account model and address format as Ethereum L1: accounts are either externally owned accounts (EOAs) or smart contracts, identified by a 20-byte address. Account state is independent between L1 and Lighter EVM.

Core accounts

Core has master accounts and subaccounts. Each subaccount belongs to, and is controlled by, exactly one master account. Every Core account maintains its own state, including balances, orders, positions, and API keys.

Every Core account is uniquely identified by a uint48 accountIndex assigned when the account is created. Master account indices are in [0, 2^47 - 1], while subaccount indices are in [2^47, 2^48 - 2].

A master account is created when the protocol processes the first deposit for a previously unregistered address. Once the master account exists, subaccounts can be created under it.

Master accounts are also well-indexed by the tuple (domain, address), where domain is either Ethereum L1 or Lighter EVM. Each tuple identifies at most one Core master account, and each master account has exactly one controlling tuple. Core therefore treats the same 20-byte address on Ethereum L1 and Lighter EVM as two distinct controllers.

EVM-controlled accounts

An EVM-controlled master account is indexed by (Lighter EVM, address), where address may identify an EOA or a smart contract.

Core creates the master account when it processes the first deposit from Lighter EVM to the controlling EVM address.

Once the account is created, you can retrieve its accountIndex from Lighter EVM using the EVM account index read.

The controlling address operates the master account and its subaccounts through the EvmToCoreEntrypoint and EvmInteropManager predeploys; see EVM and Core.

L1-controlled accounts

An L1-controlled master account is indexed by (Ethereum L1, address).

Core creates the master account when it processes the first deposit from Ethereum L1 to the controlling L1 address. The controlling address operates the master account and its subaccounts from L1 and cannot operate them from Lighter EVM.

These accounts can only be created by deposits from L1.

Account authorization

Core recognizes two forms of authorization: API-key authorization and master authorization.

API-key authorization

An API key authorizes its holder to submit routine Core transactions, such as placing and cancelling orders, without obtaining separate approval from the master account’s controller for each transaction.

The key holder signs these transactions and submits them directly to Core, without sending an Ethereum L1 or Lighter EVM transaction. The controller may hold the API key itself or allow a separate operator to hold it. For example, a smart contract can register a key held by an off-chain operator, allowing that operator to trade on the contract’s behalf.

Accounts created through deposits initially have no API keys. The master account’s controller must authorize registering the first key and can later update or revoke it.

For what an API key can do, including on subaccounts, see Lighter's API keys guide. GET /api/v1/accountsByEvmAddress?evm_address=... lists an EVM-controlled account's subaccounts.

To generate an API-key pair locally, see generate an API-key pair in the Signing Core transactions guide.

An API key can be registered in three ways.

• From Core. An EOA controller of an L1-controlled or EVM-controlled account can submit a signed ChangePubKey transaction (txType = 8). It requires a signature from the new API key and the controller's ECDSA signature, so no previously registered key is needed. See Lighter's API-key registration guide.
• From EVM. The controller of an EVM-controlled account calls EvmToCoreEntrypoint.changePubKey(...).
• From L1. The controller of an L1-controlled account calls L1CoreMessaging.changePubKey(...).

See Signing Core transactions for setting up the WASM signer and submitting transactions directly to Core.

Master authorization

Master authorization is explicit approval from the master account’s controller. It is required to manage API keys and to perform certain sensitive operations, such as withdrawals to L1. A directly submitted Core transaction may require API-key authorization, master authorization, or both, depending on the operation.

The controller can provide master authorization in either of two ways:

• By signature. If the controlling address is an EOA, it can provide an ECDSA signature authorizing the operation.
• From its controlling domain. The controller can call the corresponding method on Ethereum L1 or Lighter EVM. The authenticated caller provides master authorization, so a separate ECDSA signature is unnecessary.

A smart contract cannot produce an ECDSA signature. A contract-controlled account must therefore use the appropriate L1-initiated or EVM-initiated method when master authorization is required. It can still register an API key that an off-chain operator uses for routine transactions requiring only API-key authorization.