The Hypurrliquid Paper

1. Architecture Overview #

Hyperliquid L1 (HyperCore) is a purpose-built blockchain for perpetual futures, spot trading, lending (BOLE), prediction markets (HIP-4), and an integrated EVM (HyperEVM). It uses HyperBFT consensus with sub-second block times and processes ~200,000 operations/second.^[1]

1.1 System Stack

1.2 Crate Map

1.3 Confirmed Dependency Versions

Extracted from path strings in the 81MB binary.^[2]

/home/ubuntu/hl/code_Mainnet/        (mainnet build 105cb1dc)
+-- base/          -- Shared utilities (40+ files)
+-- db/            -- RocksDB backend
+-- evm_rpc/       -- EVM JSON-RPC
+-- l1/            -- Core logic
|   +-- abci/engine.rs, state.rs
|   +-- book/book/impl_insert_order.rs
|   +-- clearinghouse/
|   +-- exchange/impl_trading.rs, end_block.rs, exchange.rs, impl_outcome.rs
|   +-- evm/hyper_evm.rs, transactor.rs
|   +-- staking.rs, vault/, fees/compute.rs, bole/user_state.rs
+-- net_utils/     -- TCP + LZ4
+-- node/consensus/ -- state.rs, server.rs, types.rs, timer.rs, mempool.rs,
                      client_block.rs, heartbeat_tracker.rs, rpc.rs, network.rs

/home/ubuntu/hl/code_Testnet/        (testnet build 331bef9b, 2026-04-03)
+-- base/          -- Utilities (50+ files, expanded)
+-- db/            -- RocksDB backend
+-- evm_rpc/       -- EVM JSON-RPC
+-- l1/            -- Core logic (+ core_writer.rs in evm/)
+-- node/          -- Orchestration + Consensus

2. Consensus: HyperBFT #

HyperBFT is a two-chain HotStuff variant. CONFIRMED BIN: "CertifiedTwoChainCommit" in rodata^[3]

2.1 Parameters

2.2 Round Lifecycle

2.3 Core Structures

Block { round, parent_round, tx_hashes, qc, tc, block_hash, time, proposer }
ClientBlock { proof: { signed_block, commit_proof }, txs }
Qc { block_hash, round, signatures }
Tc { signed_timeouts, round }
CommitProof { child: Signed<Block>, grandchild_qc: Qc }
EpochTracker { epoch_states, active_epoch, cur_epoch_state, cur_epoch, epoch_duration_seconds }

2.4 Consensus Errors

CONFIRMED at VA 0x6600fa.^[4]

2.5 Validator Signing Gates (6 Checks)

3. Mempool #

Mempool {
    committed_tx_hashes:  HashSet,    // dedup
    uncommitted_txs:      HashMap,    // pending
    tx_hash_to_seq_num:   HashMap,    // ordering
    block_hash_to_block:  HashMap,    // block buffer
    broadcaster_nonces:   HashMap,    // per-broadcaster
}

No hard mempool size limit CONFIRMED. Eviction is time-based.^[5]

3.1 Admission Pipeline (7 Stages)

4. Block Execution Pipeline #

CONFIRMED from binary VA 0x01e748e0 and string at 0x539f8a. Pipeline: RecoverUsers → BeginBlock → DeliverSignedActions → ProcessFills → EVM Block → EndBlock → Commit → VoteAppHash.^[6]

4.1 RecoverUsers

Before any effects: parse block header, validate proposer is active validator, verify broadcaster authorization per bundle, recover EIP-712 signers, reject duplicate nonces.

4.2 BeginBlock — 9 Named Effects CONFIRMED

Binary-confirmed order from VA 0x01e748e0 (2026-04-02). Note: this ordering differs from older RE notes which placed BOLE after funding.

Supplementary per-book maintenance (after the 9 named effects):

4.3 DeliverSignedActions

Each bundle is processed sequentially. Per action: resolve actor (EIP-712 recovery), nonce check, try typed dispatch (HlAction enum, 90 variants), fall back to JSON string dispatch. Fills accumulate in BlockResult.

4.4 ProcessFills

After all actions: per-fill fee computation (compute_fee() with tiers + referral), debit fees, clearinghouse.process_fill() for position updates, volume tracking for tier progression, fill history (capped 1000/user), ExEx event emission.

4.5 EVM Block Phase

Dual-block architecture: small blocks (1s, 2M gas) for responsive UX + big blocks (60s, 30M gas) for heavy computation. Each block's receipts are scanned for CoreWriter RawAction(address,bytes) logs from 0x3333...3333. Decoded actions are enqueued in ActionDelayer with delay_scale × 3000ms delay and later fire through the named delayed-action lane in the next block's begin_block (slot 8 in the current widened testnet note).

In replay mode (no executor): raw tx calldata parsed via minimal RLP scanner to extract CoreWriter calls without EVM execution.

4.6 EndBlock

Update mark prices from order book mid-prices: for each book with orders, mark_prices[asset] = book.mid_price().

4.7 Commit + VoteAppHash

State hash: rmp_serde → blake3 XOF (2048B) → paddw u16 (LtHash16) → SHA-256 (32B). 11 L1 + 3 EVM accumulator categories. Final app_hash is first_16(SHA-256(L1_combined)) || first_16(SHA-256(EVM_combined)). Every 2000 blocks, validators submit VoteAppHash; quorum at 2/3+ stake agreement.

4.8 Timing Parameters

4.9 Action Dispatch — All 97 Variants

Main dispatcher at VA 0x0272a320 (>500KB). CONFIRMED: the current widened testnet note exposes 90 mainnet + 7 testnet-only variants. Use the dedicated Action Inventory for the authoritative family/sub-variant tables; local parity work on the full surface is still active.^[8]

Trading (9 types)

Margin & Leverage (3 types)

Transfers (6 types)

Sub-Accounts (3 types)

Vaults (6 types)

Staking (5 types)

Account (7 types)

DeFi & Abstraction (5 types)

Governance (3 types)

VoteGlobal Sub-Types (22 wired)

Validator (9 types)

HIP-3/HIP-4 (3 types + sub-types)

System (11 types)

Special (7 types)

Additional (8 types)

Total: the current widened testnet note exposes 97 action variants, expanding to 126 sub-types (+ 6 SetGlobal + 8 PerpDeploy + 22 VoteGlobal). Treat that as the current action-surface map, not as a blanket claim that parity is complete on every branch.^[9]

5. Exchange State (57 Keys) #

The Exchange struct: ALL L1 state. ~1.1GB as .rmp, saved every ~20 min.^[10]

CONFIRMED Serde struct chain discovered at .rodata offset 0x543428 in testnet binary (2026-04-03). This gives the complete ABCI state serialization layout -- every field name, order, and nesting depth for the full Exchange struct hierarchy. BIN: testnet 331bef9b .rodata 0x543428

5.1 Locus (15 Keys, 3-Char Serde Renames)

Locus is the compact core container inside the 57-field Exchange. The parent Exchange uses full field names in serde; Locus is the notable exception that still uses short 3-character keys.

5.2 Clearinghouse (18 Fields)

This is the perp risk and balance core that locus.cls[] stores for the main market and each HIP-3 perp universe.

5.3 CStaking (23 Fields)

CStaking is the on-chain validator, delegation, governance, and broadcaster-control surface. The raw binary inventory is easier to use when grouped by purpose.

5.4 Live State Size

6. Matching Engine #

6.1 Cancel Reasons (11)

CONFIRMED at offset 0x64f964.^[11]

6.2 Reject Reasons (17)

6.3 Fee Tiers

VIP Tiers (7 Levels) API: app.hyperliquid.xyz/fees^[12]

MM Tiers (3): MM1 0.5%/-0.1bps, MM2 1.5%/-0.2bps, MM3 3.0%/-0.3bps

Staking Discount Tiers (7)

6.3.1 FeeSchedule and FeeTracker Layouts

CONFIRMED from binary struct chain in testnet build 331bef9b (2026-04-03). BIN: serde field chain at .rodata 0x543428

FeeSchedule (9 fields)

tiers                          // VIP tier definitions
referral_discount              // Referral discount percentage
referrer_keep                  // Referrer keep percentage
extra_destination_fractions    // Extra fee destination routing
stake_discount_tiers           // Staking discount tier table
weigh_spot_volume_double       // Double-weight spot volume flag
aligned_quote_token_config     // Aligned quote token configuration
+2 unknown fields              // Under investigation

FeeTracker (10 fields)

fee_schedule                   // Active FeeSchedule(9)
unrewarded_users               // Users pending reward distribution
user_states                    // Per-user fee accounting state
referrer_states                // Per-referrer fee accounting state
code_to_referrer               // Referral code -> referrer mapping
referral_bucket_millis         // Referral bucket timing
total_fees_collected           // Cumulative fees collected
total_spot_fees_collected      // Cumulative spot fees collected
collected_builder_fees         // Builder fee accumulator
trials_disabled                // Fee trial disable flag

6.4 Wire Format

OrderWireSerde  { a: u32, b: bool, p: String, s: String, r: bool, t: OrderTypeWire, c: Option<Cloid> }
OrderAction     { orders: Vec, builder: Option<OrderBuilderInfo>, grouping: Grouping }
Cancel          { a: u32, o: u64 }
CancelByCloid   { asset: u32, cloid: Cloid }
ModifyWire      { oid: u64, order: OrderWireSerde }
TwapWireSerde   { a: u32, b: bool, s: String, r: bool, m: u64, t: bool }
// Tif: Alo | Ioc | Gtc    Tpsl: Na | NormalTpsl | PositionTpsl
// Grouping: Na | Default | DexAbstraction | UnifiedAccount | PortfolioMargin

6.5 Matching Algorithm CONFIRMED

Price-time priority CLOB with self-trade prevention and post-only enforcement. Each asset has an independent order book backed by BTreeMap<PriceKey, VecDeque<Order>>.

Data Structure Layout

OrderBook {
  bid_levels: BTreeMap<-price, PriceLevel>   // negative key = descending sort (best bid first)
  ask_levels: BTreeMap<+price, PriceLevel>   // positive key = ascending sort (best ask first)
  oid_index:  HashMap<u64, (Side, PriceKey)> // O(1) cancel by OID
}

PriceLevel {
  orders: VecDeque<Order>   // FIFO: front = oldest (first priority)
  total_size: f64           // aggregate size at this price
}

// BTreeMap guarantees: O(log n) insert/lookup, ordered iteration
// VecDeque guarantees: O(1) push_back (new orders), O(1) pop_front (best time priority)
// HashMap guarantees: O(1) cancel by OID

Key Properties

Post-Match Pipeline

For each fill in block:
  1. Compute fees via full fee pipeline (VIP tier, MM, staking, referral, builder)
  2. Debit fees from maker and taker balances
  3. Update positions via clearinghouse.process_fill()
  4. Increment fill nonce counter (znfn)
  5. Record fill in state hash (OrderStatusHash::Filled → Na accumulator)
  6. Track volume for VIP tier advancement
  7. Emit fill event for WebSocket subscribers

7. Funding Rate System #

7.1 Parameters

7.2 Algorithm

1. premium = (mark_px - oracle_px) / oracle_px
2. EMA: decay = exp(-dt * ln(2) / half_life)
   num   = num * decay + premium * (1 - decay)
   denom = denom * decay + (1 - decay)
   smoothed = num / denom
3. Clamp to [-max_slippage, +max_slippage]
4. rate = smoothed * perp_to_funding_multiplier[asset]
5. rate += perp_to_funding_interest_rate[asset]
6. Binance mode: premium_index + clamp(interest - premium_index, -0.0005, 0.0005)

7.3 FundingTracker (8 Fields)

1. asset_to_premiums    2. override_impact_usd    3. clamp
4. default_impact_usd   5. hl_only_perps          6. use_binance_formula
7. perp_to_funding_multiplier    8. perp_to_funding_interest_rate

DeterministicEma(5): num, denom, decay_duration, n_samples, [last_update_time]
DeterministicVty(7): desc, samples, emas, val, n_updates, n_bucket_updates, alert_bucket_guard

8. Oracle and Mark Price #

The oracle pipeline transforms external price feeds into consensus oracle prices, mark prices, and ultimately funding rates and liquidation triggers. Every step has been confirmed from binary RE.^[13]

8.1 Full Oracle Pipeline

8.2 SetGlobalAction (4 Fields) CONFIRMED

The broadcaster submits consensus oracle prices via SetGlobalAction (variant 1 of SetGlobal sub-types). The 4th field is nativePx -- the native token (HYPE) price. BIN: confirmed 2026-04-02

SetGlobalAction {
    pxs: Vec<Option<String>>,              // oracle prices, indexed by asset
    externalPerpPxs: Vec<Option<String>>,   // external perp prices (Binance, etc.)
    usdtUsdcPx: Option<String>,            // USDT/USDC exchange rate
    nativePx: Option<String>,              // CONFIRMED: HYPE price
}

Governance sub-actions (variant index 0..14): registerAsset, setOracle, insertMarginTable, setFeeRecipient, haltTrading, setMarginTableIds, setOpenInterestCaps, setFundingMultipliers, setMarginModes, setFeeScale, setGrowthModes, setFundingInterestRates, disableDex, setPerpAnnotation.

8.3 Oracle Struct (4 Fields) CONFIRMED

Oracle {
    pxs: HashMap<u32, f64>,               // consensus oracle prices per asset
    external_perp_pxs: HashMap<u32, f64>,  // external perp prices
    err_dur_guard: BucketGuard,            // error duration tracking
    lpxk: OracleKindMap,                   // last price kind map
}

OracleKindMap  // Maps assets to oracle kind: Reserved, NO_ERROR, universe, oraclePx, disabled

8.4 Oracle History Ring Buffer CONFIRMED

Exchange field [55] oh is a ring buffer of 100 oracle snapshots, each containing a full copy of the oracle state at that point in time. SNAP: confirmed from ABCI state at h=942770000

Exchange.oh: Vec<(DateTime, OracleSnapshot)>  // 100 entries
OracleSnapshot {
    pxs: HashMap<u32, f64>,
    external_perp_pxs: HashMap<u32, f64>,
    err_dur_guard: BucketGuard,
    l: ???,   // abbreviated field, purpose TBD
}

This ring buffer provides recent oracle price history for mark price smoothing, stale detection, and error duration tracking.

8.5 Validator Voting Pipeline

Validators submit price votes via ValidatorL1VoteAction. Votes are tracked per action type with expiry-based rounds. CONFIRMED: stake-weighted median.

ValidatorL1VoteTracker(3) {
    prune_bucket_guard: BucketGuard,
    action_to_tracker: HashMap<ActionType, ActionTracker>,
    active: bool,
}
ActionTracker(3) { active: bool, expire_time: u64, vote_tracker: VoteTracker }
VoteTracker(7) { version, round, initial_round, round_to_val, order_ntl, max_px, ema }

StreamTracker(3) {
    validator_to_value: HashMap<Address, ValidatorValue>,
    median_value: f64,                    // CONFIRMED: stake-weighted median
    update_median_bucket_guard: BucketGuard,
}

8.6 Mark Price Formula CONFIRMED

Mark price is derived from the oracle price and order book impact prices. The impact price simulates a trade of impact_usd notional against the book to determine a fair market price.

Impact price configuration:
    default_impact_usd: f64,                   // typically 200 USD
    override_impact_usd: HashMap<u32, f64>,    // per-asset override
    clamp: bool,                                // whether to clamp impact price

Mark price computation:
    impact_bid = simulate_buy(book, impact_usd_notional)
    impact_ask = simulate_sell(book, impact_usd_notional)
    mark_px = f(oracle_px, impact_bid, impact_ask, ema)

Three parallel price maps in exchange state:
    coin_to_mark_px: HashMap<u32, f64>          // mark prices
    coin_to_oracle_px: HashMap<u32, f64>        // oracle prices
    coin_to_external_perp_px: HashMap<u32, f64> // external perp prices

API response per asset (PerpAssetCtx): markPx, funding, openInterest, prevDayPx, dayNtlVlm, premium, midPx, impactPxs (array of [bid_impact, ask_impact]), dayBaseVlm, circulatingSupply, totalSupply.

8.7 HIP-3 Stale Mark Price CONFIRMED

HIP-3 stale mark price detection uses a 10-second window. Mark prices older than 10 seconds are considered stale and refreshed during begin_block (effect #7 of 9). BIN: hip3_stale_mark_px_guard, refresh_hip3_stale_mark_pxs

Exchange fields:
    hip3_stale_mark_px_guard: BucketGuard,   // guards stale mark detection
    hip3_no_cross: bool,                      // disable crossing

Function: refresh_hip3_stale_mark_pxs() -- called in begin_block effect #7
Companion: prune_book_empty_user_states() -- cleanup (begin_block effect #4)

8.8 Oracle Price Bounds

9. Liquidation Engine #

See the dedicated Liquidation and ADL reference for the execution split across perps, portfolio margin, BOLE, spot, and outcomes, plus the current call-graph links and open-gap table.

Perp liquidation condition: margin_available < 0, equivalently account_value < maintenance_margin. Maintenance is tiered by notional bracket using lower_bound, max_leverage, and maintenance_deduction. Cross positions share account equity; isolated positions use per-position allocated margin.

9.0 begin_block Liquidation Trigger Flow CONFIRMED

BOLE liquidations run as effect #3 of the 9-step begin_block pipeline. Perp liquidations are user-initiated via the Liquidate action during action processing.

9.1 Margin And Trigger Logic

9.2 Auto-Deleveraging (ADL)

ADL is the shortfall path, not the first path. Standard liquidation runs first. If liquidation still leaves residual bad debt, Hyperliquid flips on perform_auto_deleveraging and tracks the unresolved amount in adl_shortfall_remaining. There are no socialized losses in the current model; loss is pushed into opposing profitable positions.

Ranking rule: counter-parties are selected from the opposing profitable side and ranked by ROE / PnL%, i.e. unrealized_pnl / margin_allocated. Higher ROE means higher ADL priority. In practical terms: a liquidated long pushes into profitable shorts first; a liquidated short pushes into profitable longs first.

1. Detect liquidatable account
2. Execute ordinary liquidation
3. Compute residual shortfall
4. If residual shortfall > 0:
   - set perform_auto_deleveraging = true
   - update adl_shortfall_remaining
   - bucket by (asset, opposing side)
   - rank profitable counterparties by ROE descending
   - delever until shortfall is exhausted or no eligible size remains

9.3 BOLE Liquidation

BOLE is a separate lending liquidation system with its own three LtHash categories. The strongest confirmed trigger is a 0.8 health-factor threshold. When a BOLE user falls below that boundary, the system can route through one of three liquidation modes:

The current best state model for BOLE risk is: supplied_value, borrowed_value, ltv, and healthFactor. The begin-block pass apply_bole_liquidations is the confirmed entrypoint for that lane.

9.4 Safeguards And Safety Controls

Operational rule set: liquidator margin is checked before liquidation, some assets require the liquidator to use cross margin, and BOLE backstop routing sits beside the ordinary liquidation path rather than replacing it. The current implementation effort mirrors that separation: planner first, then exact state transitions once the remaining edge semantics are proved.

9.5 Formula Sheet

Cross account value
  = balance + sum(unrealized_pnl_cross_positions)

Cross margin available
  = account_value - cross_maintenance_margin_used

Cross liquidation trigger
  = (margin_available < 0)

Isolated margin available
  = allocated_margin + unrealized_pnl - maintenance_margin

Isolated liquidation trigger
  = (isolated_margin_available < 0)

Initial margin
  = sum_over_tiers(notional_in_tier / max_leverage)

Maintenance margin
  = sum_over_tiers(notional_in_tier / max_leverage - maintenance_deduction)

ADL ranking score
  = return_on_equity
  = unrealized_pnl / margin_allocated

BOLE utilization
  = total_borrows / total_deposits

BOLE local health factor
  = supplied_value / borrowed_value

BOLE liquidation trigger
  = (health_factor < 0.8)

Confirmed for the trigger shapes and tier structure. Inferred / local model for parts that still depend on exact binary-side execution semantics, especially final BOLE transfer sizing and full portfolio-margin netting.

9.6 Product Surfaces

9.7 Trigger Call Graph

10. State Hashing: LtHash16 #

10.1 Algorithm CONFIRMED

Action Response (per action)
  -> rmp_serde::to_vec_named(response)     // rmp-serde 1.3.0, named/map mode
  -> blake3::Hasher (streaming Write)      // blake3 1.7.0 at VA 0x04e03010
  -> blake3 XOF (2048 bytes)
  -> 1024 x u16 LE
  -> SSE2 paddw wrapping-add               // VA 0x04e05786
  -> Per-category LtHash16 accumulator (11 L1 + 3 EVM = 14 total)

Final app_hash (32 bytes):
  L1_combined  = paddw(all 11 L1 accumulators)
  EVM_combined = paddw(all 3 EVM accumulators)
  app_hash     = first_16(SHA-256(L1_combined)) || first_16(SHA-256(EVM_combined))
  // NOT a single SHA-256 of all 14 combined! Confirmed from node log at h=536290000

10.2 All 11 L1 Hash Categories

CONFIRMED at rodata 0x65fb61.^[15]

10.3 RespHash Dispatch

VA 0x205a300. 20-entry jump table at 0x37fe2c. 14 accumulators at 0x800-byte intervals (0x50066c8..0x500cec8). Hashes response structs (not raw mutations).^[15]

10.4 EVM Element Formats

10.5 VoteAppHash

Every 2000 blocks, 3 validators, ~150 blocks after checkpoint. Mismatch: /tmp/abci_state_with_quorum_app_hash_mismatch.rmp.

10.6 Hash Accumulator Naming Pattern CONFIRMED

Binary strings reveal a systematic naming convention for hash accumulators, partitioned per clearinghouse (DEX) instance. BIN: rodata string search

Pattern: {category}_{dex_prefix}
Where dex_prefix:
    H   = main clearinghouse (clearinghouse index 0)
    H3  = HIP-3 clearinghouses

Examples from binary strings:
    AllBoleTH3        -- all BOLE state for HIP-3 clearinghouse
    borrowLeH3        -- borrow ledger entries, HIP-3
    funding_H3        -- funding state, HIP-3
    1emasH            -- EMAs for main clearinghouse

Per-clearinghouse hash partitioning confirmed:
    Each clearinghouse (main + HIP-3 instances) maintains
    separate LtHash16 accumulators for its own state.
    The suffix distinguishes which clearinghouse owns the
    accumulator. This enables incremental hashing per-DEX
    without cross-contamination between clearinghouse instances.

The 14 total accumulators (11 L1 + 3 EVM) cover: validator state changes, liquidation events (cross, isolated, BOLE), settlement, vault netting, spot dust conversion, and EVM state (accounts, contracts, storage).

11. Gossip Protocol (FULLY CRACKED) #

11.1 Wire Frame

[u32 BE body_len][u8 kind][body]   kind=0x01: LZ4 bincode-fork

11.2 Handshake

Out: [00 00 00 02][00][00][00]  (7B)    In: [00 00 00 01][00][chain]  (6B, chain=0x04=Mainnet)

11.3 MsgConcise (Tag 27, 8 variants)

11.4 OutMsgConcise (Tag 28, 9+ variants)

11.5 Mid Field

CONFIRMED: jump table VA 0x65f47c.^[20]

11.6 Heartbeat Wire Layout

Heartbeat { validator(20B), round(u64),
  snapshot: HeartbeatSnapshot {
    validator_set_snapshot: { stakes, jailed_validators },
    evm_block_number: u64,
    concise_lt_hashes: {
      accounts_hash:  ConciseLtHash { hash_concise: [u8;32], n_elements, n_bytes },
      contracts_hash: ConciseLtHash,
      storage_hash:   ConciseLtHash
    }
  },
  validator_to_last_msg_round, random_id
}
// hash_concise = 32B SHA-256 digest (NOT 2048B LtHash16)

11.7 Send Path (6 Layers)

12. HyperEVM #

12.1 Dual-Block Architecture CONFIRMED

HyperEVM runs two parallel block streams with different parameters:

Users opt into large blocks via the evmUserModify action with usingBigBlocks: true. Both block types share the same state -- they are sequential, not parallel execution environments.

12.2 CoreWriter (0x3333...3333) CONFIRMED

CoreWriter is the EVM-to-L1 bridge contract at address 0x3333333333333333333333333333333333333333. It is a system precompile, not a deployed contract.

Interface

interface ICoreWriter {
    event RawAction(address indexed user, bytes data);
    function sendRawAction(bytes calldata data) external;
}

Packed Encoding

abi.encodePacked(uint8(1), uint24(actionId), abi.encode(params...))

The version byte is always 1. The uint24 action ID selects the L1 action type. Parameters are standard ABI-encoded after the 4-byte prefix.

CoreWriter Action Types (15)

All CoreWriter actions go through the ActionDelayer -- they are NOT executed immediately. CONFIRMED

12.3 L1 to EVM Flow (sendToEvmWithData) CONFIRMED

The sendToEvmWithData action transfers funds from L1 (HyperCore) to HyperEVM, with optional calldata execution on arrival. 11 fields confirmed for the action.

12.4 EVM to L1 Flow (CoreWriter Scan Loop) CONFIRMED

After each EVM block is executed, the L1 state machine scans transaction receipts for CoreWriter log events and enqueues them as delayed L1 actions.

12.5 Action Delayer (9 Fields) CONFIRMED

delayed_actions, user_to_n_delayed_actions, n_total_delayed_actions,
max_n_delayed_actions, vty_trackers, status_guard, enabled,
delayer_mode(Alternating), delay_scale

Capacity behavior: When the delayer is at capacity (n_total_delayed_actions >= max_n_delayed_actions), new actions are silently rejected. There is no eviction of existing actions and no error returned to the caller. CONFIRMED

Placement note: the widened execution note and current local engine now align on update_action_delayer as the named delayed-action lane at slot 8. What remains open is the ActionDelayer control logic around enabled, delayer_mode, status_guard, and vty_trackers.

ActionDelayerStatus

enum ActionDelayerStatus {
    On,                           // Always active
    Alternating { seconds: u64 }, // Active in alternating windows
}

DelayedActionSerde

DelayedActionSerde {
    action,          // The L1 action to execute
    id,              // Unique action identifier
    is_frontend,     // Whether submitted via frontend
    expires_after,   // Expiry timestamp
    evm_tx_hash,     // Source EVM transaction hash
    broadcaster,     // Broadcasting validator
}

12.6 Security Model

13. Bridge #

The ETH-Hyperliquid bridge (version 2, "Bridge2") enables deposits and withdrawals between Ethereum L1 (Arbitrum) and HyperCore. Bridge operations use the same validator signer keys as consensus -- there are NOT separate EOA signing keys for bridge operations. CONFIRMED^[22]

13.1 Bridge2 Struct (10 Fields) CONFIRMED

Exchange field [8] bridge2. SNAP: confirmed from ABCI state

Bridge2(10) {
    eth_id_to_deposit_votes,           // deposit confirmation tracking
    finished_deposits_data,            // completed deposits
    withdrawal_signatures,             // withdrawal signature collection
    withdrawal_finalized_votes,        // finalization vote tracking
    finished_withdrawal_to_time,       // withdrawal completion timestamps
    validator_set_signatures,          // validator set update signatures
    validator_set_finalized_votes,     // validator set finalization votes
    bal,                               // bridge balance as UsdcNtl [usdc, ntl]
    last_pruned_deposit_block_number,  // deposit pruning watermark
    oaw,                               // only-allow-withdrawals flag
}

13.2 Signing Model CONFIRMED

Bridge signing = consensus signing. The consensus signer key (the key used for HyperBFT voting) is the same key that signs bridge withdrawal messages and validator set updates. There are NOT separate EOAs.

13.3 Deposit Flow

VoteEthDepositAction (3 fields): deposit_id, chain, validator. Each validator independently observes the Ethereum deposit and submits a vote. When 2/3+ of stake weight has voted, the deposit is confirmed and funds are credited.

13.4 Withdrawal Flow

ValidatorSignWithdrawalAction (5 fields): signature, chain, nonce, withdrawal_hash, validator. Validators sign the withdrawal using their consensus signer keys. After 2/3+ signatures are collected, the withdrawal enters a dispute period on Ethereum before funds can be claimed.

13.5 Validator Set Update Flow

When the active validator set changes (due to staking changes, jailing, or epoch transitions), the bridge's Ethereum-side contract must be updated to reflect the new signer set.

1. Validator set changes on HyperCore (epoch transition, delegation change)
2. Validators sign the new validator set: SignValidatorSetUpdateAction
3. validator_set_signatures accumulates signatures
4. 2/3+ stake-weighted signatures collected
5. validator_set_finalized_votes confirms finalization
6. New validator set submitted to Bridge2.sol on Ethereum
7. Bridge2.sol updates hot/cold signer sets

13.6 Bridge Action Types

13.7 Security Model

14. HIP-4: Outcomes #

Native L1 prediction markets (event contracts). Binary instruments that settle between 0 and 1 (or fractionally via settleFraction). Deployed through the HIP-3 (builder-deployed perps) pipeline but with fundamentally different mechanics: 1x isolated margin only, no leverage, no liquidation, no continuous oracle feed. Price discovery is purely CLOB-based. Settlement by deployer-designated oracleUpdater. Requires 1M HYPE stake (slashable for oracle manipulation).^[23]

14.1 OutcomeTracker (11 Fields) CONFIRMED

The OutcomeTracker is stored in the Exchange state and manages all live/active outcomes. BIN: struct OutcomeTracker with 11 elements

State structures:
    OutcomeTracker(11)     -- manages all outcome state in Exchange
    OutcomeSpec(4)         -- tuple struct: settleFraction, details, questions, outcome
    OutcomeSideSpec(3)     -- one side (YES or NO)
    QuestionSpec(5)        -- question grouping related outcomes
    SettledOutcome         -- resolved state
    SettledOutcomeSpec(3)  -- settlement parameters
    SettledOutcomeHistory(3) -- historical record
    SettledQuestionSpec(4) -- question-level settlement

14.2 Outcome Lifecycle

14.3 OutcomeDeploy Enum (8 Variants) CONFIRMED

Nested inside Hip3DeployAction. BIN: impl_outcome.rs

14.4 UserOutcomeAction Enum (4 Variants) CONFIRMED

14.5 Settlement Flow

The oracleUpdater address is set at deployment time in Hip3SchemaInput. It is the deployer-designated settlement authority -- the deployer IS the oracle. There is no Chainlink, Pyth, or continuous feed for outcome prices.

Settlement flow:
    1. oracleUpdater submits SettleOutcome(3) via Hip3DeployAction
    2. Trading halts immediately
    3. All open orders auto-cancelled (outcomeSettledCanceled)
    4. New orders rejected (outcomeSettledRejected)
    5. Positions auto-settle at posted outcome value (0, 1, or settleFraction)
    6. Collateral released to winners in collateralToken
    7. Slot recycled -- 1M HYPE stake available for new markets

Price bounds during trading: 0.001 to 0.999
Settlement values: 0 or 1 (binary), or fractional via settleFraction
Collateral: configurable per deployment (any aligned quote token, NOT restricted to USDH)

14.6 Price Discovery Model

14.7 HIP-3 Shared Infrastructure

Outcomes share deployment and orderbook infrastructure with HIP-3 perps:

Hip3SchemaInput(3): collateralToken, oracleUpdater, OutcomeDeploy
Hip3Schema(9): full_name, oracle_updater, fee_recipient, asset_to_oi_cap,
    sub_deployers, deployer_fee_scale, last_deployer_fee_scale_change_time, +2
Hip3Limits(6): total_oi_cap2, oi_sz_cap_per_perp, max_transfer_ntl2,
    max_under_initial_margin_transfer_ntl2, daily_px_range, max_n_users_with_positions

LtHash category: Settlement (index 5 of 11 L1 categories)

15. BOLE Lending #

Protocol-controlled lending system built into HyperCore L1. Not an EVM contract. BOLE is NOT deployer-configurable -- pool parameters (reserves, rate limits, ADL, backstop liquidation) are set at protocol level by validator governance via SystemBole (action 46, broadcaster-only).^[24]

15.1 BolePool (19 Fields) CONFIRMED

Per-token lending pool state. Stored in locus.blp (Exchange Locus field [8]). SNAP: confirmed from ABCI state

BolePool(19) {
    dp, du, o, pmmt, e, pmv, r, p, n, b,
    bog, pmdl, pml, uobc, ubgl, ubul, bwo, mbs, u
}
// Abbreviated serde names. Maps to:
//   totalSupplied, totalBorrowed, utilization, rates,
//   reserve config, user states, backstop params, etc.

Key API state per token:
    totalSupplied        // total supplied to pool
    totalBorrowed        // total borrowed from pool
    utilization          // totalBorrowed / totalSupplied
    healthFactor         // per-user health metric
    ltv                  // loan-to-value ratio
    predictedRate        // predicted interest rate
    borrowYearlyRate     // annualized borrow rate
    interestAmount       // accrued interest
    portfolioMarginEnabled // portfolio margin flag

15.2 User Operations CONFIRMED

BoleAction(3): operation, token, amount. Wire name: borrowLend.

15.3 Rate Curve (Aave-Style Kink Model) CONFIRMED

Interest rates follow a standard two-slope kink model, similar to Aave/Compound.

RawRateCurve {
    kink_rate: f64,          // interest rate at kink utilization point
    kink_utilization: f64,   // utilization threshold where slope changes
    base_rate: f64,          // base interest rate (at 0% utilization)
    slope1: f64,             // slope below kink (gentle)
    slope2: f64,             // slope above kink (steep)
}

Rate computation:
    if utilization <= kink_utilization:
        rate = base_rate + (utilization / kink_utilization) * slope1
    else:
        excess = (utilization - kink_utilization) / (1 - kink_utilization)
        rate = base_rate + slope1 + excess * slope2

15.4 SetBole Governance Variants (6) CONFIRMED

Protocol-level configuration via SystemBole (broadcaster-only). BIN: SetBole variants from Ghidra

15.5 BOLE Liquidation Flow CONFIRMED

BOLE liquidation is triggered in begin_block effect #3 (apply_bole_liquidations). Health factor threshold: 0.8. Three liquidation modes with distinct LtHash categories.

BOLE health computation:
    healthFactor = supplied_value / borrowed_value
    Liquidation trigger: healthFactor < 0.8

Order type: borrowLendLiquidation (display: "Borrow Liquidation")
Cooldown: partial_liquidation_cooldown = 30.0 seconds

Error messages:
    "Insufficient collateral for operation"
    "Insufficient balance"
    "Exceeded cap for asset"
    "Only supplying is enabled"
    "Too many operations"
    "borrow_cap > supply_cap"

15.6 Hash Accumulator Naming CONFIRMED

BOLE state is tracked in per-clearinghouse hash accumulators following the naming pattern from Section 10.6.

AllBoleTH3      -- all BOLE state for HIP-3 clearinghouse
borrowLeH3      -- borrow ledger entries, HIP-3

LtHash categories for BOLE liquidation events:
    BoleMarketLiquidation    (index 8 of 11 L1 categories)
    BoleBackstopLiquidation  (index 9, paired with [9,10])
    BolePartialLiquidation   (index 10, paired with [9,10])

Exchange field: reserve_accumulators -- Vec of (token_id, accumulator) pairs
    Mainnet keys: 107, 207, 232, 255 (4 tokens with BOLE reserves)

16. Guards (16 BucketGuards) #

Volume-Gated: Sub-accounts, scheduled cancels, portfolio margin, extra agents, referral codes.

17. Validator Operations #

Hyperliquid uses a two-key model per validator: a cold validator key that holds funds, receives rewards, and manages the validator profile, and a hot signer key stored in node_config.json that signs consensus messages and bridge operations.

17.1 CStaking (23 Fields) CONFIRMED

Exchange field [10] c_staking. Full consensus staking state. SNAP: confirmed from ABCI state

CStaking(23) {
    stakes,                                // validator stakes
    allowed_validators,                    // validator allowlist
    allow_all_validators,                  // permissionless mode flag
    broadcasters,                          // whitelisted broadcasters
    validator_to_profile,                  // CValidatorProfile per validator
    validator_to_last_signer_change_time,  // signer rotation tracking
    delegations,                           // delegation state per user
    proposals,                             // governance proposals
    stakes_decay_bucket_guard,             // stake decay timing
    jailed_signers,                        // currently jailed signers
    jail_vote_tracker,                     // jail vote accumulation
    jail_until,                            // jail expiry per validator
    signer_to_last_manual_unjail_time,     // unjail cooldown tracking
    native_token_reserve,                  // HYPE reserve for rewards
    stage_reward_bucket_guard,             // reward staging timing
    validator_to_staged_rewards,           // staged (pending) rewards
    distribute_reward_bucket_guard,        // reward distribution timing
    user_states,                           // per-user staking state
    pending_withdrawals,                   // pending stake withdrawals
    self_delegation_requirement,           // minimum self-delegation
    disabled_validators,                   // disabled validator set
    disabled_node_ips,                     // disabled node IPs
    validator_to_state,                    // per-validator state tracking
}

17.2 CValidatorProfile and CValidatorAction CONFIRMED

CValidatorProfile (6 Fields)

CValidatorProfile {
    node_ip: String,                // validator node IP address
    delegations_disabled: bool,     // whether delegations are accepted
    commission_bps: u32,            // commission in basis points
    signer: Address,                // hot signer key address
    register_time: u64,             // registration timestamp
    last_signer_change_time: u64,   // last signer rotation time
}

CValidatorAction (16 Variants) CONFIRMED

Requires cold validator key. BIN: variant index 0 <= i < 16

CSignerAction (3 Variants)

Requires hot signer key. BIN: CSignerAction dispatch at VA 0x3352310

17.3 Epoch Lifecycle CONFIRMED

Validator set transitions are epoch-based. The active set is determined by total delegation at epoch boundaries.

Staking(6) {
    epoch_states,             // historical epoch state snapshots
    active_epoch,             // currently active epoch index
    cur_epoch_state,          // current epoch validator set
    cur_epoch,                // current epoch number
    epoch_duration_seconds,   // epoch length (e.g. ~90 min for 100K rounds)
    allowed_validators,       // validator whitelist
}

EpochTracker {
    epoch_states,             // Vec of epoch snapshots
    active_epoch,             // active epoch index
    cur_epoch_state,          // current state
    cur_epoch,                // epoch counter
    epoch_duration_seconds,   // duration
}

Epoch transition:
    1. ForceIncreaseEpoch action triggers epoch boundary
    2. Rank validators by total delegation (self + delegated)
    3. Top N validators become the active set (24 mainnet, 50 testnet)
    4. New proposer rotation computed from new active set
    5. Bridge validator set updated (same signer keys)
    6. validator_power_updates applied to consensus

17.4 Delegation Flow CONFIRMED

Users delegate HYPE to validators via tokenDelegate. Rewards are distributed per epoch based on commission rates.

Delegation flow:
    1. User submits tokenDelegate action (validator, amount)
    2. Delegation recorded in c_staking.delegations
    3. Takes effect at next epoch boundary
    4. Rewards staged: stage_reward_bucket_guard fires periodically
    5. Rewards distributed: distribute_reward_bucket_guard fires
    6. User claims via claimRewards action

Reward distribution:
    validator_reward = block_reward * validator_stake_fraction
    validator_commission = validator_reward * commission_bps / 10000
    delegator_share = (validator_reward - commission) * delegator_fraction

Constraints:
    self_delegation_requirement enforced (minimum self-stake)
    pending_withdrawals tracked for unbonding period
    stakes_decay_bucket_guard handles stake decay over time

17.5 Jailing CONFIRMED

Validators are jailed for poor performance (latency) or manual self-jailing for maintenance.

Jailing fields:
    validator_latency_ema            // EMA of response latency
    latency_ema_jail_threshold       // threshold for jailing
    validators_missing_heartbeat     // set of non-responsive validators
    disconnected_validators          // detected network partitions
    jailed_signers                   // currently jailed signer set
    jail_until                       // jail expiry timestamp per validator
    signer_to_last_manual_unjail_time // unjail cooldown tracking
    jail_vote_tracker                // vote accumulation for jailing

Unjail requirements:
    1. Jail cooldown period must have elapsed (jail_until)
    2. Validator must be in active epoch set
    3. Submit CSignerAction::unjailSelf with hot signer key
    4. "Signer invalid or inactive for current epoch" if not in active set

17.6 RPC Backfill (9 Validation Checks)

18. Key Function Addresses #

19. Binary Structure #

Source module map from testnet binary 331bef9b (2026-04-03). CONFIRMED from panic paths and debug strings in the stripped ELF.

19.1 Source Module Map

/home/ubuntu/hl/code_Testnet/
+-- base/src/      -- Utilities (50+ files)
|   +-- types.rs, config.rs, serialize.rs, ...
+-- db/src/        -- RocksDB backend
|   +-- db.rs, compaction.rs
+-- evm_rpc/src/   -- EVM JSON-RPC
|   +-- server.rs, handlers.rs
+-- l1/src/        -- Core L1 logic
|   +-- abci/engine.rs, state.rs
|   +-- book/book/impl_insert_order.rs
|   +-- clearinghouse/
|   +-- exchange/impl_trading.rs, end_block.rs, exchange.rs, impl_outcome.rs
|   +-- evm/hyper_evm.rs, transactor.rs, core_writer.rs
|   +-- staking.rs, vault/, fees/compute.rs, bole/user_state.rs
+-- node/src/      -- Orchestration + Consensus
|   +-- consensus/state.rs, server.rs, types.rs, timer.rs, mempool.rs
|   +-- client_block.rs, heartbeat_tracker.rs, rpc.rs, network.rs

Compared to mainnet build 105cb1dc (40+ files in base/), the testnet binary shows 50+ files in base/ and additional modules in the evm/ subtree.

Changelog & Corrections #

Reverse engineering is iterative. This section documents wrong assumptions, corrections, and when findings were updated. Entries are newest-first.

2026-04-05

2026-04-04

2026-04-03

2026-04-02

References #

1. OBS Live mainnet: peak 7,746 actions/second, 2,451 in one 70ms block.
2. BIN Crate versions from path strings in rodata. Binary: 81MB ELF, build 105cb1dc.
3. BIN "CertifiedTwoChainCommit" in rodata. Domain separator at VA 0x76db94.
4. BIN Consensus errors at VA 0x6600fa. Field names from serde at VA 0x660467.
5. BIN No capacity string. "dropping txs/blocks" confirmed. Source: mempool.rs.
6. BIN Pipeline at offset 0x539f8a.
7. BIN begin_block_logic_guard. 5-step order from end_block.rs.
8. BIN variant index 0..90. Dispatcher at VA 0x0272a320.
9. RE Testnet: RestingOrder 12 fields, Fill 21 fields, 92 action variants.
10. SNAP Exchange state at h=535280000. 57 keys. 2.1M users, $3.01B.
11. BIN Cancel reasons at 0x64f964, index 0..10. Rejects at adjacent offsets.
12. API Fee tiers from app.hyperliquid.xyz/fees.
13. API fundingHistory 3600s apart. BTC 0.0000125 in 314/500 samples.
14. BIN blake3 at 0x04e03010, paddw at 0x04e05786, SHA-256 final.
15. BIN 11 categories at 0x65fb61. RespHash at 0x205a300. 14 accumulators.
16. BIN compute_resps_hash at 0x2355860, table at 0x3aa3f8.
17. SNAP EVM sizes from lt_hashes.json: 92B accounts, 84B storage.
18. BIN Wire: bswap at 0x1cc9f59, kind at 0x1cc9f5b.
19. BIN MsgConcise table 0x65f418, OutMsgConcise 0x65f458. Type: RpcUpdate.
20. BIN Mid table at 0x65f47c. 5 LEA: "in", "execution state", "out", "status", "round advance".
21. BIN hash_concise hex loop at 0x449e0f0, 32 bytes. ValidatorSetSnapshot 2 fields at 0x42b9b80.
22. RE ModifyBroadcaster no timelock. invalidateWithdrawals confirmed.
23. RE impl_outcome.rs confirmed. OutcomeDeploy(8), UserOutcomeAction(4).
24. BIN BolePool(19), SetBole variants, BoleAction(3). Source: bole/user_state.rs.
25. BIN Testnet binary 331bef9b (2026-04-03, 87MB). 97 action variants, 9 BeginBlock steps.
26. BIN Serde struct chain at .rodata 0x543428 -- complete ABCI state serialization layout.
27. BIN FeeSchedule(9) and FeeTracker(10) field layouts from struct chain.
28. BIN CoreWriter scan loop, ActionDelayer silent reject at capacity, DelayedActionSerde(6).
29. BIN 7 new action variants: GossipPriorityBidAction, ReserveRequestWeightAction, SystemAlignedQuoteSupplyDeltaAction, DeployerSendToEvmForFrozenUserAction, SystemUsdClassTransferAction, FinalizeEvmContractAction, SubAccountSpotTransferAction.
30. BIN SetGlobalAction 4th field confirmed as nativePx (HYPE price). Oracle(4) struct fields confirmed. Oracle history ring buffer (100 entries) at Exchange field [55] oh.
31. RE Bridge2(10) full field layout from ABCI state. Bridge signing = consensus signing confirmed. Deposit/withdrawal flows from binary action handlers.
32. BIN OutcomeTracker(11), OutcomeDeploy(8 variants), UserOutcomeAction(4 variants). Source: l1/src/exchange/impl_outcome.rs.
33. BIN CStaking(23) full field layout. CValidatorProfile(6), CValidatorAction(16 variants). Staking(6) epoch lifecycle. Jailing: latency_ema_jail, VoteJailBundle.
34. BIN Hash accumulator naming: AllBoleTH3, borrowLeH3, funding_H3, 1emasH. Per-clearinghouse partitioning confirmed from binary strings.
35. BIN RawRateCurve kink model fields: kink_rate, kink_utilization. BOLE health factor threshold 0.8. apply_bole_liquidations in begin_block effect #3.