Reading Core from EVM

EVM contracts can read Core state synchronously through the READ_CORE precompile. Each read completes within the calling transaction and returns its result directly.

For each EVM block, the sequencer selects one sealed Core block (called the parent Core block) and pins its post-execution state for all Core reads in that EVM block. This keeps read results consistent throughout the EVM block, even if the selected snapshot lags the Core tip.

The READ_CORE precompile charges 20,000 gas per call, plus any memory expansion costs.

Execution

An EVM contract reads Core state by calling the READ_CORE precompile with an encoded query. The read completes synchronously and returns its result within the same call. Reads can also be evaluated off-chain through eth_call.

📘

Note

eth_calls that perform READ_CORE only succeed with the latest block tag. Support for earlier blocks is planned for an upcoming update.

Reads have no request ID, do not enter a queue, and require no destination transaction. They neither modify Core state nor record a request on Core.

Reads use the pinned snapshot rather than the latest Core state. Consequently:

• The same read in a later EVM block can return a different result if that block uses a newer Core snapshot.
• Reads do not reflect writes submitted earlier in the same EVM block, including within the same transaction.
• A transaction-status read returns status 0 if the request was unprocessed in this Core snapshot, even if the Core tip has processed it since.

Failures

A failed read consumes all gas forwarded to READ_CORE and returns no data. In Solidity, call and staticcall report the failure by returning false.

Reads fail for unsupported selectors, malformed input, insufficient gas, or unmet query requirements—for example, a requested account, asset, or market that does not exist.

Supported reads

Reads that take a controlling address resolve to its master account, so subaccounts cannot be read.

Transaction status

Returns the processing status and result of an EVM-initiated Core write, identified by its request ID (reqId).

Input

abi.encodePacked(uint16(0x0000), reqId)

Output

abi.encode(status, data)

Status 0 indicates that the request is either pending or has never been issued. Status 1 means the request has been successfully processed and status 2 indicates a failure.

Decode the response as (uint8 status, bytes data).

• For status 0, data is empty.
• For status 1, the write type determines whether data contains a return value or is empty.
• For status 2, data contains abi.encode(uint32(errorCode)).

Account info

Returns information about a Core account identified by its controlling address and whether it is L1-controlled or EVM-controlled.

Input

abi.encodePacked(uint16(0x0001), accountAddress, isL1Account)

Output

abi.encode(
    accountType,
    accountIndex,
    masterAccountIndex,
    l1Address,
    evmAddress,
    collateralBaseAmount
)

The call fails if the account does not exist in Core state. A system address's presence in the L1 bridge mapping does not make its Core system account accessible through this read.

Core asset decimals

Returns the number of decimal places Core uses for the asset.

Input

abi.encodePacked(uint16(0x0002), assetId)

Output

abi.encode(decimals)

The call fails if the asset does not exist.

L1 token address

Returns the L1 token address associated with the Core asset.

Input

abi.encodePacked(uint16(0x0003), assetId)

Output

abi.encode(l1Token)

The call fails if the asset does not exist.

EVM token address

Returns the EVM token address associated with the Core asset.

Input

abi.encodePacked(uint16(0x0004), assetId)

Output

abi.encode(evmToken)

The call fails if the asset does not exist.

Market info

Returns configuration, fees, and prices for the selected market.

Input

abi.encodePacked(uint16(0x0005), marketId)

Output

abi.encode(
    marketType,
    baseAssetId,
    quoteAssetId,
    takerFee,
    makerFee,
    minBaseAmount,
    minQuoteAmount,
    liquidationFee,
    indexPrice,
    markPrice
)

Amounts and prices use the same market-specific scales as createOrder's amount and price. READ_CORE does not return the decimals; read them from GET /api/v1/orderBookDetails.

The fee actually charged is at the sequencer's discretion. It depends on the account's fee tier and is always at most than takerFee and makerFee. Most of the time, it is substantially lower.

The call fails if the market does not exist.

Spot balance

Returns the account's available and locked spot balances for the selected asset.

Input

abi.encodePacked(uint16(0x0006), accountAddress, isL1Account, assetId)

Output

abi.encode(availableBalance, lockedBalance)

Both balances are expressed in Core base units, the units used by baseAmount. One base unit equals tickSize of the EVM token's smallest units. Divide the corresponding amount in EVM token units by tickSize and round down to obtain the Core balance. See Amounts for the definition of tickSize and how to look it up.

The call fails if the account or asset does not exist.

Position

Returns the account's position in the selected market.

Input

abi.encodePacked(uint16(0x0007), accountAddress, isL1Account, marketId)

Output

abi.encode(
    lastFundingRatePrefixSum,
    position,
    entryQuote,
    initialMarginFraction,
    totalOrderCount,
    totalPositionTiedOrderCount,
    marginMode,
    allocatedMargin
)

The call fails if the account or market does not exist.

L1 account index

Resolves an L1 controlling address to its Core master account index.

Input

abi.encodePacked(uint16(0x0008), l1Address)

Output

abi.encode(accountIndex)

The call fails if the account does not exist in Core state. A system address's presence in the L1 bridge mapping does not make its Core system account accessible through this read or the account-info read.

EVM account index

Resolves an EVM controlling address to its Core master account index.

Input

abi.encodePacked(uint16(0x0009), accountAddress)

Output

abi.encode(accountIndex)

The call fails if the account does not exist in Core state.

Example: reading a spot balance

The following contract reads a Core spot balance.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract CoreReader {
    address constant READ_CORE = 0x6600000000000000000000000000000000000000;

    function spotBalance(
        address accountAddress,
        bool isL1Account,
        uint32 assetId
    ) external view returns (int128 availableBalance, int128 lockedBalance) {
        (bool success, bytes memory result) = READ_CORE.staticcall(
            abi.encodePacked(uint16(0x0006), accountAddress, isL1Account, assetId)
        );
        require(success, "Core balance read failed");
        return abi.decode(result, (int128, int128));
    }
}