--- name: architecture description: HyperCore vs HyperEVM — what lives where, how they interact, the complete system model. Essential reading before building anything on Hyperliquid. Use when planning architecture, understanding state, or deciding where logic belongs. --- # Hyperliquid Architecture ## What You Probably Got Wrong **"Hyperliquid is an EVM chain."** HyperEVM is ONE component of Hyperliquid. The other component — HyperCore — is a custom exchange engine that runs alongside the EVM. They share finality but are distinct execution environments. **"Everything is a contract."** HyperCore has no contracts. Its logic (orderbook matching, liquidations, funding rate calculation) is built into the L1 protocol. You can't deploy to HyperCore — you integrate with it via API. **"The EVM and exchange are on separate chains."** They share the same validator set and consensus round. An EVM transaction and a HyperCore order placed in the same block are final at the same time. This atomic finality is what makes Hyperliquid unique. --- ## System Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ HyperBFT Consensus │ │ (All validators agree on HyperCore + HyperEVM state) │ │ │ │ ┌──────────────────────┐ ┌──────────────────────────┐ │ │ │ HyperCore │ │ HyperEVM │ │ │ │ │ │ │ │ │ │ • Perp orderbook │ │ • EVM contracts │ │ │ │ • Spot orderbook │◄──┤ • ERC-20 tokens │ │ │ │ • Positions │ │ • DeFi protocols │ │ │ │ • Funding rates │ │ • Chain ID 999 │ │ │ │ • HLP vault │ │ • HYPE gas token │ │ │ │ • HIP-1/2/3 tokens │ │ │ │ │ │ • Cross-margin │ │ │ │ │ └──────────────────────┘ └──────────────────────────┘ │ │ │ │ Access: Access: │ │ POST /info Standard EVM RPC │ │ POST /exchange https://rpc.hyperliquid.xyz/ │ │ WSS /ws evm │ └─────────────────────────────────────────────────────────────┘ ``` --- ## HyperCore HyperCore is the native exchange engine. It is NOT EVM — it's a purpose-built exchange running at L1 consensus speed. ### What Lives in HyperCore **Perpetual Futures:** - All open perp positions (long/short, size, entry price, margin) - Funding rates and payments (every 8 hours, can be instantaneous) - Cross-margin pool (USDC collateral shared across all perp positions) - Isolated margin positions - Liquidation engine **Spot Orderbook:** - HIP-1 native spot tokens - Full CLOB (central limit orderbook) for each spot pair - HIP-2 hyperliquidity — protocol-level AMM for spot tokens **Vaults:** - HLP (Hyperliquid Liquidity Provider) — the main protocol vault - User-created vaults - Vault deposits and withdrawals **Token Standards:** - HIP-1: native spot token definition - HIP-2: automated hyperliquidity seeding - HIP-3: permissioned spot DEX (builder-controlled listing) **User Accounts:** - Balances (USDC, HYPE, HIP-1 tokens) - Positions - Open orders ### How to Read HyperCore State All via `POST /info` to `https://api.hyperliquid.xyz/info`: ```json // Get perp market metadata { "type": "meta" } // Get spot market metadata { "type": "spotMeta" } // Get user state (all positions, balances) { "type": "clearinghouseState", "user": "0x..." } // Get open orders { "type": "openOrders", "user": "0x..." } // Get orderbook { "type": "l2Book", "coin": "ETH" } // Get all perp markets ticker data { "type": "allMids" } ``` ### How to Write to HyperCore All via `POST /exchange` to `https://api.hyperliquid.xyz/exchange`: ```json { "action": { "type": "order", ... }, "nonce": 1234567890123, "signature": { "r": "0x...", "s": "0x...", "v": 27 } } ``` Every write requires an EIP-712 signature. No unsigned writes. --- ## HyperEVM HyperEVM is a standard EVM environment running alongside HyperCore. ### What Lives in HyperEVM - Smart contracts (Solidity, Vyper) - ERC-20 tokens, ERC-721 NFTs - HyperSwap V2 (deployed AMM DEX) - Any contract you deploy - HYPE as native currency (Chain ID 999) ### Key Differences from Ethereum Mainnet | Feature | Ethereum Mainnet | HyperEVM | |---------|-----------------|----------| | Chain ID | 1 | 999 (mainnet) / 998 (testnet) | | Native currency | ETH | HYPE | | Block time | ~12s | ~1-2s | | Priority fees | → validators | Burned | | Blob transactions | Yes (Cancun) | No (Cancun opcodes, no blobs) | | MEV | Significant | Minimal | | Testnet | Sepolia (11155111) | 998 | ### Connecting to HyperEVM ```typescript // viem import { defineChain } from 'viem'; export const hyperliquid = defineChain({ id: 999, name: 'HyperEVM', nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 }, rpcUrls: { default: { http: ['https://rpc.hyperliquid.xyz/evm'] }, }, blockExplorers: { default: { name: 'HyperEVM Explorer', url: 'https://explorer.hyperliquid.xyz' }, }, }); export const hyperliquidTestnet = defineChain({ id: 998, name: 'HyperEVM Testnet', nativeCurrency: { name: 'HYPE', symbol: 'HYPE', decimals: 18 }, rpcUrls: { default: { http: ['https://rpc.hyperliquid-testnet.xyz/evm'] }, }, blockExplorers: { default: { name: 'HyperEVM Testnet Explorer', url: 'https://explorer-testnet.hyperliquid.xyz' }, }, }); ``` --- ## The Bridge: 0x2222...2222 The system address `0x2222222222222222222222222222222222222222` is the HyperCore ↔ HyperEVM bridge. **Moving HYPE from HyperCore to HyperEVM:** - Method 1: On HyperEVM, send a transaction to `0x2222...2222` with HYPE value. This is counterintuitive — you're sending FROM HyperEVM TO the bridge address, and HYPE appears on HyperEVM. - Wait, actually: sending HYPE to `0x2222...2222` on HyperEVM **withdraws** it TO HyperCore. Let me clarify the bridge mechanics: **HyperEVM → HyperCore (withdraw from EVM):** - Send HYPE to `0x2222222222222222222222222222222222222222` on HyperEVM - HYPE appears in your HyperCore spot balance **HyperCore → HyperEVM (deposit to EVM):** - Use the `/exchange` API with action type `"spotSend"` or use the `"evmUserModify"` action - HYPE appears as HYPE token on HyperEVM **In practice:** - The Hyperliquid app UI handles bridging for users - For programmatic bridging, use the SDK - HYPE decimals: 18 on HyperEVM, float representation in HyperCore API --- ## HyperCore State Reading from HyperEVM HyperEVM contracts can read HyperCore state via a system precompile at address `0x0000000000000000000000000000000000000800` (verify current address in official docs — may change). This enables HyperEVM contracts to: - Read open positions - Read orderbook state - Trigger HyperCore actions based on onchain conditions This is advanced functionality — most builders use the REST API instead of the precompile. --- ## State Sync and Finality Both HyperCore and HyperEVM reach finality in the same HyperBFT round. This means: - A HyperCore order and a HyperEVM transaction in the same block are BOTH final at the same time - There's no "cross-chain" risk between HyperCore and HyperEVM — they share consensus - Bridge operations (via 0x2222...2222) have the same finality guarantee **No waiting for "safe" confirmations.** 1 block = final. Plan your UX accordingly. --- ## Decision Framework: Where Does Logic Go? ``` Does it involve trading, positions, or native token markets? ├─ YES → HyperCore API (/exchange) │ Use SDK, EIP-712 signing │ └─ NO → Does it need custom contract logic? ├─ YES → HyperEVM (Solidity contract) │ Chain ID 999, HYPE gas │ └─ NO → Is it a read query? ├─ HyperCore state → POST /info └─ EVM state → standard eth_call via RPC ``` --- ## Asset IDs Understanding asset IDs is critical for HyperCore API calls: - **Perp asset IDs:** 0-indexed position in `meta.universe` array (e.g., ETH-perp might be asset 1) - **Spot asset IDs:** 10000 + spot index (e.g., if PURR is spot index 0, its asset ID is 10000) - **HIP-3 builder assets:** 100000 + (perp_dex_index * 10000) + index Always fetch current asset IDs via `POST /info` with `{ "type": "meta" }` — never hardcode them. ```python # Get current asset IDs import requests meta = requests.post('https://api.hyperliquid.xyz/info', json={'type': 'meta'}).json() # Perp assets for i, asset in enumerate(meta['universe']): print(f"Perp {i}: {asset['name']}") # Spot assets spot_meta = requests.post('https://api.hyperliquid.xyz/info', json={'type': 'spotMeta'}).json() for i, token in enumerate(spot_meta['tokens']): print(f"Spot {i} (ID: {10000+i}): {token['name']}") ```