Interacting with HyperCore
Read precompiles
The testnet EVM provides read precompiles that allows querying HyperCore information. The precompile addresses start at 0x0000000000000000000000000000000000000800 and have methods for querying information such as perps positions, spot balances, vault equity, staking delegations, oracle prices, and the L1 block number.
The values are guaranteed to match the latest HyperCore state at the time the EVM block is constructed.
Attached is a Solidity file L1Read.sol
describing the read precompiles. As an example, this call queries the third perp oracle price on testnet:
To convert to floating point numbers, divide the returned price by 10^(6 - szDecimals)
for perps and 10^(8 - base asset szDecimals)
for spot.
Precompiles called on invalid inputs such as invalid assets or vault address will return an error and consume all gas passed into the precompile call frame. Precompiles have a gas cost of 2000 + 65 * output_len
.
CoreWriter contract (testnet only)
A system contract is available at 0x3333333333333333333333333333333333333333 for sending transactions from the HyperEVM to HyperCore. It burns ~25,000 gas before emitting a log to be processed by HyperCore as an action. In practice the gas usage for a basic call will be ~47000. A solidity file CoreWriter.sol
for the write system contract is attached.
Action encoding details
Byte 1: Encoding version
Currently, only version
1
is supported, but enables future upgrades while maintaining backward compatibility.
Bytes 2-4: Action ID
These three bytes, when decoded as a big-endian unsigned integer, represent the unique identifier for the action.
Remaining bytes: Action encoding
The rest of the bytes constitue the action-specific data. It is always the raw ABI encoding of a sequence of Solidity types
1
Limit order
(asset, isBuy, limitPx, sz, reduceOnly, encodedTif, cloid)
(uint32, bool, uint64, uint64, bool, uint8, uint128)
Tif encoding: 1
for Alo
, 2
for Gtc
, 3
for Ioc
. Cloid encoding: 0 means no cloid, otherwise uses the number as the cloid.
2
Vault transfer
(vault, isDeposit, usd)
(address, bool, uint64)
3
Token delegate
(validator, wei, isUndelegate)
(address, uint64, bool)
4
Staking deposit
wei
uint64
5
Staking withdraw
wei
uint64
6
Spot send
(destination, token, wei)
(address, uint64, uint64)
7
USD class transfer
(ntl, toPerp)
(uint64, bool)
Happy building. Any feedback is appreciated.
Last updated