Module cfxcore::consensus::pivot_hint

source ·
Expand description

Pivot hint provides validation support during blockchain synchronization and historical data execution by leveraging trusted pivot chain information from authoritative sources.

During the synchronization process of archive nodes, when processing historical data, pivot hints help prevent execution on forked branches and protect against problematic historical states that occurred on mainnet/testnet chains.

§File Structure

The pivot hint file consists of three main parts:

  • Header Part (28 bytes): Contains configuration parameters
  • Page Digests Part: A list of keccak hashes for each page
  • Pages Part: Sequential storage of all pages

§Page Organization

Blocks are organized into pages based on several configurable parameters:

  • range_max: Upper bound (exclusive) of block heights for stored hashes
  • page_interval: Number of consecutive blocks in each page
  • Each page contains:
    • Major section: Full hashes for blocks every major_interval heights
    • Minor section: Hash prefixes (in length of minor_hash_length``) for blocks every minor_interval` heights

§Parameter Constraints

The following parameters must maintain integer multiple relationships:

  • range_max must be a multiple of page_interval
  • page_interval must be a multiple of major_interval
  • major_interval must be a multiple of minor_interval

§Fork Validation

During fork validation, when the consensus layer attempts to switch the pivot chain from branch A to branch B, it must provide:

  • fork_at: The first block height where branch A and B diverge
  • me_height: The last block height of branch B
  • A query interface to retrieve block hashes on branch B within range [fork_at, me_height]

The validation process follows these rules:

  • If [fork_at, me_height] covers with major section records, validation uses the last recorded full hash
  • If no major section records covered but minor section overlap exists, validation uses minor section records (note: this may allow switching to branches that aren’t on the final main chain)
  • If neither major nor minor section overlap exists, the switch is allowed

When fork_at exceeds range_max, it indicates the fork point is beyond the static file records, and the switch is automatically allowed.

§Loading Process

  1. Load and validate Header Part parameters
  2. Load Page Digests Part and verify against predetermined Pivot Hint Checksum
  3. Keep Page Digests in memory
  4. Verify each page against Page Digests when loading to prevent corruption

Structs§

  • PivotHint
    Manages pivot block hash records for chain fork validation during sync process.
  • PivotHintConfig
    Configuration for initializing PivotHint.