Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt

Use this file to discover all available pages before exploring further.

HyperLiquid runs a custom BFT consensus protocol called HyperBFT, derived from HotStuff. It achieves sub-second block times with deterministic finality through a two-chain commit rule.

​
Block production

HyperLiquid produces blocks approximately every 0.07 seconds (70ms). Each block is proposed by a single validator selected through proposer rotation. The block production pipeline:
  1. Transaction submission — users submit signed actions through the API
  2. Forwarding — non-leader validators forward transactions to the current leader
  3. Block proposal — the leader batches pending transactions into a BlockPropose message and broadcasts it to all validators
  4. Voting — validators verify and vote on the proposed block
  5. Commitment — after two consecutive rounds of quorum votes, the block is committed
  6. Distribution — committed blocks are forwarded to non-validator nodes for state application
Transactions that are not included in a block remain pending for the next proposal cycle. Transactions that expire without being committed are dropped.

​
Two-chain commit rule

HyperBFT uses a two-chain commit rule derived from HotStuff BFT: 
Round N:   Validators vote on Block A --> Quorum Certificate QC(A) formed
Round N+1: Validators vote on Block B --> Quorum Certificate QC(B) formed
           --> Block A is now COMMITTED (CertifiedTwoChainCommit)
A block is only finalized after two consecutive rounds of quorum votes succeed. This provides:
  • Byzantine fault tolerance — the system tolerates up to f Byzantine validators out of 3f+1 total
  • O(n) communication complexity — linear message complexity per round, significantly better than classical PBFT
  • Deterministic finality — once committed, a block cannot be reverted
  • Fast confirmation — two rounds at ~70ms each means finality in roughly 140ms under normal conditions
The CertifiedTwoChainCommit is the cryptographic proof that a block has been finalized through this process.

​
Consensus message types

The consensus layer uses several message types to coordinate block production:
MessagePurpose
BlockProposeLeader proposes a new block containing batched transactions
BlockVoteValidators vote on a proposed block
TxVoteIndividual transaction voting (enables partial block acceptance)
TimeoutValidator signals that the current round has timed out
TcTimeout certificate — proof that enough validators timed out
HeartbeatLiveness signal from a validator
HeartbeatAckAcknowledgment of a heartbeat
QcQuorum certificate with next proposer designation

​
TxVote

Individual transaction voting is a newer addition to the consensus protocol. It enables several capabilities:
  • Partial block acceptance — validators can reject specific transactions while accepting the rest of the block
  • Priority enforcement — validators verify that priority fee bids are honored correctly
  • Censorship resistance — validators can flag transactions that were improperly excluded
  • Ordering verification — ensures transaction ordering matches auction results

​
Proposer rotation

Validators take turns proposing blocks in a deterministic rotation. The Qc (quorum certificate) message includes a next_proposer field that designates which validator proposes the next block, along with a suspect field that can flag misbehaving proposers. Under normal operation, the rotation cycles through the active validator set. If a proposer fails to produce a block within the timeout window, a Timeout message triggers a view change and the next validator in rotation takes over.

​
Validator roles

Leader (proposer)

Receives forwarded transactions, batches them into blocks, and broadcasts proposals. Rotates every round.

Voter

Validates proposed blocks, casts votes, and participates in quorum formation. All validators vote on every block they don’t propose.

Sentry

Non-validator nodes that connect to validators. Provides DDoS protection for the validator set by proxying connections.

Non-validator

Receives committed blocks and state updates after consensus. Serves read-only data to clients and applications.

​
Heartbeat system

Validators must continuously prove liveness through a heartbeat mechanism. The system tracks several metrics per validator: 
since_last_success    -- time since last successful heartbeat
last_ack_duration     -- round-trip latency of most recent heartbeat
latency               -- current latency measurement
latency_ema           -- exponential moving average of latency over time
Heartbeats serve two purposes:
  1. Liveness detection — identifying validators that have gone offline or become unresponsive
  2. Performance monitoring — tracking latency trends to enforce quality-of-service standards
The consensus layer maintains a snapshot of heartbeat state:
FieldDescription
validators_missing_heartbeatValidators that have not sent a heartbeat within the expected window
disconnected_validatorsValidators with broken network connections
heartbeat_statusesPer-validator heartbeat state and latency metrics
jailed_validatorsValidators currently removed from the active set

​
Heartbeat jailing configuration

The heartbeat system enforces both liveness AND performance standards through configurable thresholds: 
HeartbeatJailingConfig:
  dry_run                       — test mode (monitor without actual jailing)
  latency_ema_jail_threshold    — EMA latency threshold that triggers jailing
Per-validator heartbeat tracking:
FieldPurpose
since_last_successTime elapsed since last successful heartbeat
last_ack_durationLatency of the most recent heartbeat acknowledgment
latencyCurrent measured latency
latency_emaExponential moving average of latency over time
The HeartbeatSnapshot captures the full liveness picture at any point: 
HeartbeatSnapshot:
  validators_missing_heartbeat   — validators that have not sent a heartbeat
  disconnected_validators        — validators with broken connections
  heartbeat_statuses             — per-validator heartbeat state
  jailed_validators              — currently jailed validators
Validators with consistently high latency (latency_ema exceeding the threshold) can be jailed even if they are technically producing heartbeats. This enforces performance standards, not just liveness.

​
Jailing

Validators that fail to maintain liveness or performance standards are jailed — temporarily removed from the active validator set. Jailed validators cannot propose blocks or participate in voting until they are unjailed.

​
Jailing triggers

Validators can be jailed not only for going offline, but also for sustained high latency. The protocol enforces performance standards, not just liveness.
There are two paths to jailing:
  1. Missing heartbeats — a validator that stops sending heartbeat messages will be flagged and eventually jailed
  2. Latency threshold — if a validator’s exponential moving average (EMA) latency exceeds the latency_ema_jail_threshold, it is jailed for poor performance

​
Jailing configuration

HeartbeatJailingConfig {
  dry_run                        -- test mode (logs but does not jail)
  latency_ema_jail_threshold     -- EMA latency ceiling before jailing
}
The dry_run mode allows the network to tune jailing parameters without risking validator set instability.

​
Jail voting

Validators can also vote to jail other validators through the VoteJail action. This requires consensus — multiple validators must agree before a validator is forcibly jailed. This mechanism provides a social layer of accountability beyond automated heartbeat checks.

​
Jail state

The staking module tracks comprehensive jail state:
FieldDescription
jailed_signersSet of currently jailed validator signing keys
jail_vote_trackerTracks active jail votes and their progress
jail_untilEarliest timestamp when a jailed validator can request unjail
signer_to_last_manual_unjail_timeCooldown tracking for manual unjail requests
disabled_validatorsPermanently disabled validators (beyond temporary jailing)
disabled_node_ipsIP addresses blocked at the application level

​
Unjailing

Jailed validators can request to be unjailed after the jail_until timestamp passes. The system tracks the last manual unjail time per signer to prevent rapid jail/unjail cycling. Validators that are placed in the disabled_validators set are permanently removed and cannot unjail through the standard process.

​
Validator revenue

Validators earn revenue through block production and transaction processing. The ValidatorBroadcasterShare system distributes broadcaster revenue among validators, potentially weighted by their latency performance — creating an economic incentive to maintain low-latency infrastructure.