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

• GlvVault - 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

• GlvRouter - HLV-specific operations

Handler Contracts

Execute user requests:

• DepositHandler - Execute deposits

• WithdrawalHandler - Execute withdrawals

• OrderHandler - Execute orders

• LiquidationHandler - Execute liquidations

• AdlHandler - Auto-deleverage positions

• GlvDepositHandler - Execute HLV deposits

• GlvWithdrawalHandler - Execute HLV withdrawals

Reader Contracts

Query protocol state:

• Reader - Market and position data

• GlvReader - HLV vault data

Factory Contracts

Create new protocol entities:

• MarketFactory - Create new markets

• GlvFactory - 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

Security Model

Roles

Role	Permissions
ROLE_ADMIN	Grant/revoke roles
CONTROLLER	Execute protocol actions
ORDER_KEEPER	Execute orders
CONFIG_KEEPER	Update configuration

Access Control

• All state-changing functions require appropriate roles

• Timelock for sensitive configuration changes

• Multi-sig for critical operations