L1 Data Schemas
The node writes data to ~/hl/data
. With default settings, the network will generate around 100 GB of logs per day, so it is recommended to archive or delete old files.
The command line flags to generate the auxiliary data below can be found at https://github.com/hyperliquid-dex/node
Transaction Blocks
Blocks parsed as transactions are streamed to
~/hl/data/replica_cmds/{start_time}/{date}/{height}
State Snapshots
State snapshots are saved every 10,000 blocks to
~/hl/data/periodic_abci_states/{date}/{height}.rmp
Trades
Trades data is saved to
~/hl/data/node_trades/hourly/{date}/{hour}
// Example trade
{
"coin": "COMP",
"side": "B",
"time": "2024-07-26T08:26:25.899",
"px": "51.367",
"sz": "0.31",
"hash": "0xad8e0566e813bdf98176040e6d51bd011100efa789e89430cdf17964235f55d8",
"trade_dir_override":"Na",
// side_info always has length 2
// side_info[0] is the buyer
// side_info[1] is the seller
"side_info": [
{
"user": "0xc64cc00b46101bd40aa1c3121195e85c0b0918d8",
"start_pos": "996.67",
"oid": 12212201265,
"twap_id": null,
"cloid": null
},
{
"user": "0x768484f7e2ebb675c57838366c02ae99ba2a9b08",
"start_pos": "-996.7",
"oid": 12212198275,
"twap_id": null,
"cloid": null
}
]
}
Order Statuses
Order status data is saved to
~/hl/data/node_order_statuses/hourly/{date}/{hour}
// Example order status
{
"time": "2024-07-26T08:31:48.717",
"user": "0xc64cc00b46101bd40aa1c3121195e85c0b0918d8",
"status": "canceled",
"order": {
"coin": "INJ",
"side": "A",
"limitPx": "25.381",
// filled size
"sz": "257.0",
"oid": 12212359592,
"timestamp": 1721982700270,
"triggerCondition": "N/A",
"isTrigger": false,
"triggerPx": "0.0",
"children": [],
"isPositionTpsl": false,
"reduceOnly": false,
"orderType": "Limit",
// original order size
"origSz": "257.0",
"tif": "Alo",
"cloid": null
}
}
Miscellaneous Events
Miscellaneous event data is saved to
~/hl/data/misc_events/hourly/{date}/{hour}
Miscellaneous events currently include the following
Staking deposits
Staking delegations
Staking withdrawals
Validator rewards
Ledger updates (funding distributions, spot transfers, etc)
type MiscEvent = {
time: string;
hash: string;
inner: MiscEventInner;
}
type MiscEventInner = CDeposit | Delegation | CWithdrawal | ValidatorRewards | Funding | LedgerUpdate;
type CDeposit = {
user: string;
amount: number;
}
type Delegation = {
user: string;
validator: string;
amount: number;
is_undelegate: boolean;
}
type CWithdrawal = {
user: string;
amount: number;
is_finalized: boolean;
}
type ValidatorRewards = {
validator_to_reward: Array<[string, number]>;
}
type Funding {
coin: string;
usdc: number;
szi: number;
fundingRate: number;
nSamples: number;
}
type LedgerUpdate = {
users: Array<string>;
delta: LedgerDelta;
}
// InternalTransfer means Perp USDC transfer
// RewardsClaim is for builder and referrer fees
// Deposit/Withdraw refer to Arbitrum USDC bridge
type LedgerDelta = Withdraw
| Deposit
| VaultCreate
| VaultDeposit
| VaultWithdraw
| VaultDistribution
| VaultLeaderCommission
| Liquidation
| InternalTransfer
| SubAccountTransfer
| SpotTransfer
| SpotGenesis
| RewardsClaim
| AccountActivationGas
| PerpDexClassTransfer
| DeployGasAuction;
type Withdraw = {
usdc: number;
nonce: number;
fee: number;
}
type Deposit = {
usdc: number;
}
type VaultCreate {
vault: string;
usdc: number;
fee: number;
}
type VaultWithdraw {
vault: string;
user: string;
requestedUsd: number;
commission: number;
closingCost: number;
basis: number;
}
type VaultDistribution {
vault: string;
usdc: number;
}
type Liquidation {
liquidatedNtlPos: number;
accountValue: number;
leverageType: string;
liquidatedPositions: Array<LiquidatedPosition>;
}
type LiquidatedPosition {
coin: string;
szi: number;
}
type InternalTransfer {
usdc: number;
user: string;
destination: string;
fee: number;
}
type AccountClassTransfer {
usdc: number;
toPerp: boolean;
}
type SubAccountTransfer {
usdc: number;
user: string;
destination: string;
}
type SpotTransfer {
token: string;
amount: number;
usdcValue: number;
user: string;
destination: string;
fee: number;
nativeTokenFee: number;
}
type SpotGenesis {
token: string;
amount: number;
}
type RewardsClaim {
amount: number;
}
type AccountActivationGas {
amount: number;
token: string;
}
type PerpDexClassTransfer {
amount: number;
token: string;
dex: string;
toPerp: boolean;
}
type DeployGasAuction {
token: string;
amount: number;
}
L4 Snapshots
Given an abci state, the node can compute an L4 book snapshot, which is the entire order book with full information about the orders for each level. This can be used as a checkpoint upon which the order statuses stream may be applied, allowing users to stream an L4 book in realtime.
Orders in the snapshot are sorted in time-order at the same price level. Trigger orders come at the end and be differentiated with isTrigger
.
[
[
"BTC", // coin
[
[ // bids
{
"coin": "BTC",
"side": "B",
"limitPx": "103988.0",
"sz": "0.2782",
"oid": 30112287571,
"timestamp": 1747157301016,
"triggerCondition": "N/A",
"isTrigger": false,
"triggerPx": "0.0",
"children": [],
"isPositionTpsl": false,
"reduceOnly": false,
"orderType": "Limit",
"origSz": "0.2782",
"tif": "Alo",
"cloid": null
},
..
],
[ // asks
{
"coin": "BTC",
"side": "A",
"limitPx": "93708.0",
"sz": "0.00047",
"oid": 30073539988,
"timestamp": 1747128626867,
"triggerCondition": "Price below 101856",
"isTrigger": true,
"triggerPx": "101856.0",
"children": [],
"isPositionTpsl": false,
"reduceOnly": true,
"orderType": "Stop Market",
"origSz": "0.00047",
"tif": null,
"cloid": null
},
..
]
]
],
[
"ETH",
..
],
[
"SOL",
..
]
]
Last updated