HyperEVM Development · DeFi on HyperEVM · 8/8
Composing with L1 Trading
The Composability Vision
The promise of HyperEVM is that smart contracts can compose with the native order book. Contracts read HyperCore through precompiles and write to it through the CoreWriter system contract at 0x3333333333333333333333333333333333333333, so strategies can run fully on-chain or split work between a contract and an off-chain keeper.
Architecture Patterns
Pattern 1: Smart Contract Vault + Keeper
HyperEVM (On-Chain) L1 (Order Book)
┌─────────────────┐ ┌──────────────┐
│ Vault Contract │ │ Positions │
│ - Deposits │ │ - BTC Long │
│ - Shares │◄────────►│ - ETH Short │
│ - Accounting │ Keeper │ - Funding │
└─────────────────┘ └──────────────┘
The vault contract manages deposits and share accounting on HyperEVM, while a keeper bot handles the actual trading on the L1. The keeper reads the vault's equity and adjusts positions proportionally.
Pattern 2: On-Chain Price Checks
// A contract that flags when a market's mark price drifts away from its oracle.
// PriceReader is the contract from the "Reading L1 State" lesson.
contract DeviationWatch is PriceReader {
event Deviation(uint32 perpIndex, uint64 markPx, uint64 oraclePx);
function check(uint32 perpIndex) external {
uint64 mark = markPx(perpIndex);
uint64 oracle = oraclePx(perpIndex);
// Flag a gap of more than 0.5% of the oracle price, in either direction
// (an oracle of 0 means the market has no price yet: flag it too)
uint256 gap = mark > oracle ? uint256(mark - oracle) : uint256(oracle - mark);
if (oracle == 0 || gap * 1000 > uint256(oracle) * 5) {
emit Deviation(perpIndex, mark, oracle);
}
}
}
A keeper watches for Deviation events and acts off-chain, for example by pausing its own quotes or alerting whoever runs the market.
Pattern 3: Trading Directly via CoreWriter
A contract can place orders for its own HyperCore account by calling sendRawAction on CoreWriter. The payload is a version byte (0x01), a 3-byte action ID, then the ABI-encoded fields. Action 1 is a limit order (action table):
// Testnet only — sketch, no access control
interface ICoreWriter {
function sendRawAction(bytes calldata data) external;
}
contract CoreTrader {
ICoreWriter constant CORE_WRITER =
ICoreWriter(0x3333333333333333333333333333333333333333);
// limitPx and sz are 10^8 * the human-readable value
function placeLimitOrder(uint32 asset, bool isBuy, uint64 limitPx, uint64 sz) external {
bytes memory fields = abi.encode(
asset, isBuy, limitPx, sz,
false, // reduceOnly
uint8(3), // tif: 1 = Alo, 2 = Gtc, 3 = Ioc
uint128(0) // cloid: 0 = none
);
// version 1, action ID 1 (limit order)
CORE_WRITER.sendRawAction(abi.encodePacked(uint8(1), uint24(1), fields));
}
}
Things to know:
- The contract's address must already exist as a HyperCore user (and hold margin there) before the EVM block is built, or the action is rejected
- Order actions and vault transfers from CoreWriter are delayed onchain for a few seconds
sendRawActionsucceeding on the EVM does not mean the order filled — check the result by reading HyperCore state later- A basic call uses about 47,000 gas
Cross-Environment Workflows
Deposit Flow
- User deposits a linked token (e.g. USDC) into the HyperEVM vault contract
- Contract mints shares to user
- Contract (or a keeper calling it) transfers the tokens to the token's system address, crediting the contract's HyperCore spot balance
- Positions are opened via CoreWriter (contract-driven) or via the API by an agent wallet the contract approved with CoreWriter action 9
Withdrawal Flow
- User requests withdrawal on HyperEVM
- Contract burns shares, emits event
- Proportional HyperCore positions are closed
- Funds are moved back to HyperEVM with a CoreWriter spot send (action 6) to the token's system address
- Once they arrive in a later EVM block, USDC is sent to the user
Because Core → EVM transfers land in a later block, withdrawals are asynchronous: design them as request-then-claim.
Building a Complete System
// Keeper that connects a HyperEVM vault to HyperCore trading (ethers v6)
import { ethers, EventLog } from "ethers";
class HybridVaultKeeper {
constructor(
private vaultContract: ethers.Contract,
// plus a HyperCore API client of your choice, signing with an agent wallet
) {}
async processDeposit(event: EventLog) {
const amount = event.args.amount;
// Move funds to the vault's HyperCore account (system address transfer)
// Open positions proportional to deposit
}
async processWithdrawal(event: EventLog) {
const shares = event.args.shares;
// Calculate proportional position to close
// Close HyperCore positions
// Move USDC back to HyperEVM, then let the user claim
}
}
The Future
Directions builders are exploring:
- Fully on-chain vaults — The docs now point to HyperEVM vaults using CoreWriter and precompiles as the successor to legacy HyperCore vaults, with access to spot and HIP-3 markets (Vaults)
- Composable vaults — Vault-of-vaults strategies built on ERC-4626 shares
- Cross-chain DeFi — Messaging and bridges such as LayerZero and Wormhole already list HyperEVM
Note that flash-loan-style atomic arbitrage between HyperEVM and HyperCore is not possible: CoreWriter actions execute after the EVM block, with an onchain delay for orders.