Smart Contract

HertzFlow is built on a modular smart contract architecture deployed on BNB Smart Chain.

Overview

Architecture

Design Principles

1. Modularity: Contracts are separated by function for upgradeability

2. Data Separation: State is stored in dedicated DataStore

3. Event-Driven: All actions emit events through EventEmitter

4. Two-Step Execution: Actions require request creation then keeper execution

Contract Categories

Bank Contracts

Hold funds for the protocol:

• DepositVault - Holds deposit collateral

• WithdrawalVault - Holds withdrawal tokens

• OrderVault - Holds order collateral

• HlvVault - Holds HLV vault tokens

• ShiftVault - Holds shift operation tokens

Data Storage

• DataStore - Primary key-value data storage

• RoleStore - Access control management

• OracleStore - Oracle signer management

Exchange Contracts

User-facing interaction points:

• ExchangeRouter - Create deposits, withdrawals, orders

• Router - Token approval management

• HlvRouter - HLV-specific operations

Handler Contracts

Execute user requests:

• DepositHandler - Execute deposits

• WithdrawalHandler - Execute withdrawals

• OrderHandler - Execute orders

• LiquidationHandler - Execute liquidations

• AdlHandler - Auto-deleverage positions

• HlvDepositHandler - Execute HLV deposits

• HlvWithdrawalHandler - Execute HLV withdrawals

Reader Contracts

Query protocol state:

• Reader - Market and position data

• HlvReader - HLV vault data

Factory Contracts

Create new protocol entities:

• MarketFactory - Create new markets

• HlvFactory - Create new HLV vaults

Oracle Contracts

Price feed management:

• Oracle - Price validation and caching

• ChainlinkPriceFeedProvider - Chainlink integration

Price Oracle Architecture

Accurate and tamper-resistant price discovery is a cornerstone of the Hertzflow protocol. Our oracle design balances decentralization, reliability, and latency requirements to serve both trading and risk management functions.

The Hertzflow oracle design ensures:

• Primary reliance on decentralized, manipulation-resistant feeds (Pyth).

• Automatic degradation to high-quality CEX index prices when needed.

• Liquidity-aware weighting for fallback aggregation.

• Multi-layer resiliency with redundancy at both the runtime and infrastructure levels.

Aggregator Strategy

• Primary Source – Pyth Network Hertzflow prioritizes high-frequency decentralized price streams from Pyth Network. Pyth aggregates prices and confidence intervals from multiple independent publishers, applying a PoS-weighted mechanism to produce manipulation-resistant reference prices.

• Fallback Source – CEX Index Prices If Pyth data is unavailable or stale beyond 3 seconds, the system degrades gracefully to an index price feed aggregated from leading centralized exchanges (Binance, OKX, Bybit).

Update Frequency

• Latency Guarantees p99 latency: ≤ 1–2 seconds, ensuring keepers' liquidation and settlement logic remains real-time. p999 latency: bounded by a stricter upper limit (configurable) to guarantee global stability under stress conditions.

Oracle Node Selection

• Decentralized Path (Preferred): Pyth Network for resilient, publisher-aggregated price feeds. To eliminate reliance on third-party APIs and avoid rate limits, we self-host Pyth's core infrastructure components including pythnet-rpc, wormhole-spy, and hermes.

• Centralized Path (Fallback): CEX feeds selected strictly from venues with top-tier depth and reputation (Binance, OKX, Bybit). Feeds are consumed via WebSocket subscriptions to minimize latency. Redundancy across exchanges ensures continuity even if individual feeds degrade.

Slippage Protection Mechanism

When fallback aggregation relies on CEX data, Hertzflow enforces a liquidity-weighted scoring system to prioritize healthier order books:

• Depth Score (a): Sum of bid/ask liquidity within ±1% of current price.

• Support Ratio (b): Ratio of near-book (top 3 levels) to mid-book liquidity, measuring order book resilience.

• Balance Score (c): Relative balance of total bids vs. asks, reflecting buy/sell symmetry.

The composite score is calculated as:

$$Score_{exchange} = w_1 × a + w_2 × b + w_3 × c$$

Scores are used as weights in the final aggregated index, ensuring high-liquidity venues contribute more heavily to the effective oracle price.

Exception Handling & Failover

To maintain uninterrupted pricing, the system implements multi-layered resiliency mechanisms:

• Real-Time Failover: Wait up to 3s for Pyth updates. If data remains stale, immediately switch to the fallback CEX index.

• Continuity Assurance:

  • Quick Fixer: Patches short-term gaps detected at runtime.

  • Gap Fixer: Scheduled process validating DB continuity and repairing missed intervals.

  • Lazy Filler: On-demand backfill during query time for external consumers.

• Architecture-Level Redundancy: Fetcher and Aggregator services run in active-active multi-instance mode, eliminating single points of failure.

Key Flows

Deposit Flow

User → ExchangeRouter.createDeposit → DepositVault
Keeper → DepositHandler.executeDeposit → MarketToken minted

Order Flow

User → ExchangeRouter.createOrder → OrderVault
Keeper → OrderHandler.executeOrder → Position updated

Withdrawal Flow

User → ExchangeRouter.createWithdrawal → WithdrawalVault
Keeper → WithdrawalHandler.executeWithdrawal → Tokens returned

Contract Addresses

Addresses below are taken from the BSC Testnet deployment artifacts. Always treat the deployed artifacts as the source of truth and verify the checksum casing of an address before using it.

BSC Testnet

Contract	Address	Purpose
ExchangeRouter	0x2e3E1079A1131a345A64c470456349344651CD04	Create deposits, withdrawals, orders
Reader	0xBeF101a258e73a73CC81c9Ca53688e445e479710	Market and position data
DataStore	0x07822C54B16fDE499b2451E88aeb0b4F2697Ee96	Primary key-value data storage
RoleStore	0x5BAFb2B0492b8DeD3aE2b0C8A20C5e3F25273eB9	Access control management
Oracle	0x7aad08e9cABa1A3b2D9d12bB143b6d259232C012	Price validation and caching
OracleStore	0xd1aA533A769e08EC2d3659ca77b26CaD4A590C7e	Oracle signer management
DepositVault	0x0d7f48214d3DC9E8062FA893F008b52C11953966	Holds deposit collateral
WithdrawalVault	0xc41c74f798aBE26Af3B77dfF4a1F8a02C576a2E2	Holds withdrawal tokens
OrderVault	0x423f977E2B752632De43E9a6d24dDbfE5395cAdc	Holds order collateral
SwapHandler	0xCa144Ac04AE8da71a528426BDFf2d682FF1AaeF4	Swap execution during order settlement

BSC Mainnet

To be published after mainnet deployment verification.