Hypurrliquid Yellow Paper

The protocol-truth reference for the Hyperliquid L1 reimplementation. Every claim here is tagged with its evidence level.

Evidence levels: CONFIRMED = verified from binary RE or official docs. OBSERVED = seen in runtime/snapshots. IMPLEMENTED = coded in hlx. INFERRED = deduced from behavior.

Use the White Paper for narrative architecture. Use the Hypurrliquid Paper for the full RE reference with Mermaid diagrams. Use the Action Inventory for the current action-family and sub-variant tables. Use the Truth Register when you want the compact fact ledger instead of the full chapter narrative. For the denser subsystem splits, use Hashing, Staking & Validators, Bridge2, and Outcomes.

0. Truth Surfaces#

This paper is the technical narrative, not the only truth surface. Read it together with:

• Truth Register for the compact confirmed/active fact ledger
• Open Claims for unresolved work
• Protocol Scope Matrix for protocol vs testnet_impl vs local_impl
• Action Inventory for action-family and sub-variant tables

1. Block Lifecycle (46 Hook Points)#

CONFIRMED from binary VA 0x01e748e0 and string at 0x539f8a.

1.1 Pipeline#

RecoverUsers → BeginBlock (9+5 effects) → DeliverSignedActions (97 types)
→ ProcessFills → EVM Block → EndBlock → Commit → VoteAppHash

1.2 BeginBlock — 9 Named Effects#

1.3 Supplementary Effects#

Current local main matches the widened 9-effect note on this ordering. What remains open on ActionDelayer is control semantics (enabled, delayer_mode, status_guard, vty_trackers), not the named drain slot.

1.4 EndBlock#

Mark prices updated from book mid-prices: mark_prices[asset] = book.mid_price().

1.5 VoteAppHash#

Every 2000 blocks. Quorum at 2/3+ stake. Final app_hash is first_16(SHA-256(L1_combined)) || first_16(SHA-256(EVM_combined)), where each half comes from the rmp_serde → blake3 XOF (2048B) → paddw u16 LtHash pipeline rather than one flat 14-category digest.

1.6 Consensus / Topology Surface#

Current confirmed testnet-facing networking and consensus facts:

• ingress is concentrated through a broadcaster layer
• proposer rotation uses stake-weighted RoundRobinTtl
• QC and TC certificates drive the two-chain commit rule
• validator/sentry admission checks gate the transport layer
• ports 4001 and 4002 split block-streaming and peer/RPC verification traffic

Treat the exact operator deployment shape as still chain-scoped, but keep these surfaces aligned across lifecycle, gossip, and consensus notes.

1.7 Validator Lifecycle / Jail Surface#

Current confirmed validator-control facts:

• epochs are time-based via epoch_duration_seconds
• active validators are recomputed at epoch boundaries
• signer admission checks search epoch_states[cur_epoch]
• jailed signers are excluded from normal proposer / signing flow
• CSignerAction currently has unjailSelf, jailSelf, and jailSelfIsolated
• manual unjail is rate-limited by signer_to_last_manual_unjail_time

What remains open on this lane is threshold/trigger detail, not the existence of the lifecycle surface.

2. Exchange State (57 Fields)#

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

57/57 fields declared. 55/57 deeply parsed from snapshots. 2 skipped (user_to_evm_state, validator_power_updates).

3. Action Surface (97 Variants, 126 Sub-Types)#

CONFIRMED from binary dispatcher at VA 0x0272a320. 90 mainnet + 7 testnet.

Current testnet notes widen the action surface to 97 variants. The local engine has broad typed coverage, but parity work remains active and this page should not be read as a blanket “zero gaps” claim.

4. Funding Rate#

CONFIRMED from binary assertions.

• EMA: DeterministicEma with fraction-based accumulation (num/denom). assert!(decay <= 1.), assert!(self.denom > 0.).
• Funding payment: payment = szi × oracle_px × (cum_funding_global - pos.cum_funding_entry)
• Direction: Positive rate = longs pay shorts.
• Guard interval: 8000ms for both distribute and update.
• Per-asset multiplier: Set via SetFundingMultiplier VoteGlobal.

5. Liquidation & ADL#

CONFIRMED from binary constants and docs.

• Margin check: margin_available = account_value - initial_margin_required. Liquidatable when < 0.
• Isolated: Per-position check with allocated margin.
• BOLE liquidation threshold: Health factor < 0.8.
• BOLE cooldown: 30 seconds for partial liquidations.
• BOLE types: Partial (50% seize), Market (full repay), Backstop (default liquidator).
• ADL: Triggered when shortfall persists after liquidation. Counterparties ranked by ROE (highest first). Position reduced proportionally.
• ADL priority: ROE = unrealized_pnl / margin_allocated.

6. State Hashing#

CONFIRMED algorithm: rmp_serde → blake3 XOF (2048B) → paddw u16 (LtHash16) → SHA-256 (32B).

• 11 L1 categories + 3 EVM categories = 14 accumulators.
• L1 accumulators: Running sums from genesis maintained in live state, not the stale BSS cache that earlier notes treated as canonical.
• EVM accumulators: accounts_hash, contracts_hash, storage_hash.
• Heartbeat concise_lt_hashes: EVM only. The traced heartbeat surface does not carry the full L1 accumulator state.

6.1 AppHash Split#

Current repo truth is that the final app_hash is first_16(SHA-256(L1_combined)) || first_16(SHA-256(EVM_combined)), not a single SHA-256 over one merged 14-accumulator buffer.

6.2 RespHash Backend Split#

Current repo truth is intentionally narrower than "hashing is solved":

• the code explicitly tracks Mainnet versus Testnet RespHash backends
• the backend split is real and should remain chain-scoped in docs and replay work
• the local implementation does not yet claim full mainnet serializer parity across all response families

Treat RespHashMode::Mainnet as backend selection, not as proof that every mainnet response serializer is already closed.

6.3 Current Serializer Facts#

Treat the following as closed facts, not loose hypotheses:

• G-family success/error split: hybrid actions do not hash a 3-field payload on success. Success is the same 1-field {status:"success"} map used by the H-family status serializer. The 3-field {status:"err", success:false, error:<msg>} payload is error-only.
• Response-family map: the current user-facing response surface closes four practical serializer families: F (TWAP), G (error branch for hybrid actions), H (status-only success), and J (order-status fill family).
• Fill hash payload: fills hash through a separate 18-field payload: px, sz, startPosition, dir, closedPnl, oid, crossed, fee, builderFee, tid, cloid, liquidation, feeTrialEscrow, builder, twapId, deployerFee, liquidatedUser, markPx.
• API wrapper fields: coin and feeToken belong to API/user-fill wrapper surfaces, not to the hashed fill payload itself.

Current open lane:

• exact local derivation of fill economics and flags (startPosition, closedPnl, tid, liquidation membership, maker/taker routing)
• remaining mainnet-specific serializer families that are still not fully wired locally

7. CoreWriter (EVM → L1)#

CONFIRMED from binary and official docs.

• Precompile address: 0x3333333333333333333333333333333333333333
• Function: sendRawAction(bytes) selector 0x17938e13
• Encoding: abi.encodePacked(uint8(1), uint24(actionId), abi.encode(params...))
• 15 action types: LimitOrder, VaultTransfer, TokenDelegate, StakingDeposit, StakingWithdraw, SpotSend, UsdClassTransfer, FinalizeEvmContract, AddApiWallet, CancelByOid, CancelByCloid, ApproveBuilderFee, SendAsset, ReflectEvmSupplyChange, BorrowLend.
• Delay: delay_scale × 3000ms (configurable). Actions fire in next block's begin_block Effect 8.
• In replay mode: Raw tx calldata scanned via RLP parser without EVM execution.

8. Bridge Finalization and Validator-Set Updates#

CONFIRMED from Bridge2 state naming, bridge action inventory, and the current control-plane notes.

• Bridge2 state includes withdrawal_signatures, withdrawal_finalized_votes, finished_withdrawal_to_time, validator_set_signatures, validator_set_finalized_votes, bal, last_pruned_deposit_block_number, and oaw (bool).
• Withdrawal entrypoint: withdraw3.
• Bridge signing action: ValidatorSignWithdrawal.
• Finalize actions: VoteEthFinalizedWithdrawal and VoteEthFinalizedValidatorSetUpdate.
• Validator-set update signing: SignValidatorSetUpdate.
• Signer model: current repo truth keeps bridge signing on validator signer keys, not an unrelated bridge-only signer family.

What remains open is exact dispute-period closure and some Ethereum-side operational details, not whether bridge finalization is a first-class staged state machine.

9. Aligned Quote Token (HPT)#

DISCOVERED from Hyperliquid docs + API.

• Exchange field [56] hpt = AlignedQuoteTokenTracker.
• Per-token state: isAligned, firstAlignedTime, evmMintedSupply, dailyAmountOwed, predictedRate.
• Validator sidecar: aqa-publisher (github.com/native-markets/aqa-publisher).
• Rate source: 30-day SOFR average from NY Fed, FRED, OFR (median of 3 sources).
• Submission: validatorL1Stream action with riskFreeRate field, daily at 22:00 UTC.
• Protocol rate: Stake-weighted median of all active validator votes.
• Fee benefits: 20% lower taker, 50% better maker rebate for aligned stablecoins.

This is also a begin-block surface: update_aligned_quote_token is the current effect-9 lane in the widened testnet note.

10. Outcomes and Settlement Surface#

CONFIRMED for the baseline market model; HYPOTHESIS for the leading solvency-risk lane.

• Risk mode: 1x isolated-only, no leverage, no funding.
• Settlement authority: oracleUpdater posts final outcome via SettleOutcome.
• Post-settlement behavior: open orders auto-cancel via outcomeSettledCanceled; new orders reject via outcomeSettledRejected.
• Question metadata: fallbackOutcome, namedOutcomes, settledNamedOutcomes.
• User token operations: SplitOutcome, MergeOutcome, MergeQuestion, NegateOutcome.

Current open risk lane:

• MergeQuestion / fallback reconciliation is still the leading higher-order solvency hypothesis.
• The repo should treat question-level accounting as riskier than the simpler YES/NO pair mechanics until the binary path is closed.

11. Gossip Protocol#

CONFIRMED from binary RE.

• Frame format: [u32 BE len][u8 kind][body]. Traced data frames often use LZ4 with kind=0x01, while greetings use kind=0x00.
• Port 4001 greeting: bincode-fork TcpGreeting with chain-based variant index. Current live observations are testnet variant 3 (8 bytes total) and mainnet variant 2 (7 bytes total).
• Broader chain enum: the ABCI-stream chain mapping still tracks Local=0, Sandbox=1, Testnet=2, Mainnet=3; do not conflate that with the observed 4001 TcpGreeting variant index.
• Port 4003 authenticated greeting: keccak256("Hyperliquid Consensus Payload" + 0x00 + bincode(content)); content is bincode, not msgpack.
• Port 4003 signed content: the greeting is variable-sized, not a tiny fixed blob. Captured content closes a 20-byte validator address, varint round, 1-byte variant flag, optional 32-byte ABCI extra, several additional counters plus a 32-byte hash, a sorted heartbeat_statuses map, and a trailing empty-mempool varint. A few middle counters still lack semantic labels.
• Connection: Server-side connection_checks — unknown peers rejected after 5s timeout.
• Loopback: Dominated by MsgConcise/OutMsgConcise (tag 27/28).

12. Guard System#

All rate-limited effects use BucketGuard:

struct BucketGuard {
    last_time: Option<u64>,   // ms
    interval_ms: u64,
}

13. Implementation Status#