Cutover Process and Timeline

August 10, 2026 · View on GitHub

Overview

As part of the evolution of the Hiero ledger to support block streams, improved network signatures, and future use cases; we must provide a mechanism for the existing public networks to transition from record streams and individual node signature to Block Streams, Block Nodes, and HinTS/TSS signatures.

Goals

  • Establish new WRAPS keys and Groth parameters via a "Powers of Tau" ceremony executed on existing trusted network nodes to produce publicly verifiable files.
  • Provide a clear structure to migrate an existing public network to the HinTS TSS signature process and WRAPS address book proofs.
  • Provide a clear structure to migrate an existing public network from retrieving record stream data via centralized S3 services to subscribing to the block stream via block nodes.
  • Provide a clear structure to migrate an existing public network's full block chain history record streams to wrapped record file blocks integrated in block stream history with integrated validity proofs for each block.

Timeline Diagram

timeline
    title Cutover Timeline
    section Releases
        Before Release N
                  : Release N
                  : Release N+1
                  : Release N+2
    section Wrapped Record Block(WRB) Hashes
        .
                 : Consensus Node begins generating WRB partial hash data
                 : Consensus Node reads Jumpstart Data
                 : .
        .
                 : WRB partial hash data stored on disk.
                 : CN Catches up WRB root hash during post-upgrade processing
                 : .
        .
                 : .
                 : CN begins using WRB hash as previous block hash
                 : .
        .
                 : .
                 : CN stores WRB hash in BlockInfo
                 : CN removes `BlockInfo` entirely during migration and only uses `BlockStreamInfo`.
    section TSS Enablement
        TSS Ceremony Runs
                 : WRAPS proving key and parameters loaded from a local file or network content storage.
                 : TSS enabled but not used
                 : TSS enabled and signs blocks
        TSS proving key, verification key, and parameters produced
                 : .
                 : WRAPS proving key hash loaded during upgrade migration
                 : .
        .
                 : .
                 : LedgerID set and published with WRAPS verification key and initial TSS Roster
                 : .
        .
                 : .
                 : First WRAPS proof created
                 : .
    section Offline Record Wrapping (ORW)
        .
                 : "Live" WRB download and wrap from S3
                 : Jumpstart Data included in CN release package
                 : .
        .
                 : Deliver WRB files into "Record Backfill History" (RBH) Block Node
                 : .
                 : .
        .
                 : Continuously produce the Jumpstart Data with hash data for the most recent WRB
                 : .
                 : .
    section Block Nodes
        Block Nodes are running in "preview" mode
                 : Test continuous backfill from "Record Block History" (RBH) block node
                 : All "final" tier 1 block nodes are reset at the beginning of this release
                 : All block nodes receive the authoritative blocks and store them permanently.
        .
                 : Continue to receive "preview" block streams
                 : All "final" tier 1 block nodes are backfilling from the RBH Block Node.
                 : .
    section Block Streams
        Preview Block Streams with incomplete hashes
                 : Preview Block Streams with incomplete hashes continue
                 : Preview Block Streams with incomplete hashes continue
                 : Block Streams replace record streams with the first block after upgrade, with full TSS and WRAPS.

Process and Sequence

  • Release K (<= N) — Completed
    • The "Powers of Tau" ceremony executed during this release to produce the WRAPS keys and Groth parameters. As of TSS library v3.8.0 the ceremony-created artifacts ship with the release, and the WRAPS proving key tar is published at wraps-v1.0.0.tar.gz.
    • Block Nodes run in Preview mode.
    • Preview Block Streams produced with incomplete hash data.
  • Release N
    • Consensus Node generates WRB subtree hashes.
    • Consensus Node stores WRB subtree hash data on disk.
    • "Offline" process downloading record files from S3.
      • Generate WRB blocks from record files.
      • WRB files added to "RBH" block node.
      • Produce Jumpstart Data occasionally (configurable, perhaps 1/hour).
    • Block Nodes may test backfill from RBH, but do not store backfilled WRBs.
      • Preview blocks are accepted and stored.
    • Preview block streams continue with incomplete hashes.
  • Release N+1
    • Jumpstart Data is included in the Consensus Node release package, and is from approximately 8-10 days before the release date.
    • Consensus Node reads Jumpstart Data.
      • WRB data is combined with the Jumpstart Data to complete "WRB Catch Up".
      • Consensus Node begins creating WRB block root hash with all necessary correct inputs.
      • Consensus Node stores the correct WRB hash in BlockInfo in state at the end of each block.
      • Consensus Node stores the correct WRB streaming hash tree data in state in BlockInfo at the end of each block.
    • WRAPS proving key and parameters downloaded by Consensus Node.
    • WRAPS proving key hash read from configuration.
      • This data is stored in state as part of post-upgrade migration.
      • The hash is used to validate the downloaded WRAPS data.
    • TSS is enabled in Consensus Node but does not sign blocks.
      • TSS creates the Ledger ID and publishes LedgerID, Initial Roster, and WRAPS verification key in record stream via TSS adoption transaction.
      • Consensus Node creates WRAPS proofs for each new Roster.
    • Offline process continues to generate WRB files for backfill via RBH Block Node.
    • Block Nodes are prepared for cutover.
      • All "production" Tier 1 block nodes are reset to clear preview blocks.
      • All "production" Tier 1 block nodes begin rapid backfill from RBH to preload all history prior to cutover.
    • Preview block streams continue to "testing" block nodes and are written to "preview" buckets for testing and qualification.
      • Preview block hashes continue to be entirely incomplete (to reduce complexity).
  • Release N+2 (Cutover Release)
    • Consensus Node performs cutover tasks during post upgrade processing.
      • Consensus Node signs each block with TSS and WRAPS.
      • Consensus Node ceases producing Record Streams.
      • Consensus Node removes BlockInfo from state. BlockStreamInfo is used after cutover and is optimized for block streams rather than record streams.
      • Consensus Node begins producing Block Streams and publishing to Block Nodes.
    • Block Nodes complete final backfill and begin receiving Block Streams.
      • Block Nodes verify TSS signature for each block.
    • RBH node is shut down once all block nodes finish backfill.
    • Block Streams become authoritative.

How does the consensus node "catch up" with the last Wrapped Record Block hash?

This is a roughly three part process.

  • The first part requires offline processing to do the following.
    1. Download every record file from the beginning.
    2. Process each file to extract the record data, wrap that data in a block.
    3. Record the block hash, block number, and state of the historical block subtree.
      • Update the current Jumpstart Data with this data after each 1000 blocks.
  • The second part requires that the Consensus Node Software record the following values for each record file produced for the Record Stream.
    1. Calculate the subtree hashes for the current record file data according to the structure documented below.
    2. For each new record, store the Consensus Time, block number, and subtree hash for subtrees 3, 4, 5, 6, 7, and 8 in a hash-data file. Only the "output" subtree is expected to have a non-zero value.
  • The Consensus Node Software will store the hash data for each record for a single release.
  • The third part requires the following tasks.
    1. The Jumpstart Data from part one must be included in the upgrade package for the consensus node.
    2. The Consensus Node Software will read the Jumpstart Data, and find the matching block in the hash-data file.
    3. The Consensus Node Software will use the values in the Jumpstart Data to calculate the Block Root for the matching wrapped record file block.
      • The Consensus Node Software will use the calculated Block Root and the data from the hash-data file to continue calculating the Block Root for each record file block in order.
      • The Consensus Node Software will complete all Block Root calculations forward until reaching the current wrapped record block.
    4. The Consensus Node Software will, thereafter, maintain the previous Block Root hash and the state of the historical block subtree in state.

Block Root Tree Structure (16 fixed leaves)

                                    Block Root
                                         │
                           ┌─────────────┴────────────┐
                   Consensus Time              Fixed Root Tree
                    (Timestamp)                  (16 leaves)
                                                      │
                                         ┌────────────┴──────────────┐
                                    Left Subtree                  Reserved
                                         │                      (future use)
                    ┌────────────────────┴───────────────────┐
                Left-Left                                Left-Right
                    │                                        │
          ┌─────────┴─────────┐                     ┌────────┴────────┐
    left-left-left      left-left-right      left-right-left   left-right-right
          │                   │                     │                 │
    ┌─────┴────┐       ┌──────┴──────┐           ┌──┴──┐       ┌──────┴──────┐
PrevBlock  AllBlocks  State  ConsensusHeaders  Input Output  StateChanges  Trace

Fixed Leaf Positions (from design doc)

PositionItemDescription
1Previous Block Root HashLinks to previous block, forming the blockchain.
2All Block Hashes Tree RootStreaming merkle tree of all previous block hashes.
3State Root HashState merkle tree root at block start.
4Consensus HeadersEventHeader, RoundHeader items.
5Input ItemsSignedTransaction.
6Output ItemsBlockHeader, RecordFile items, TransactionResult, TransactionOutput items.
7State ChangesStateChanges items.
8Trace DataTraceData items.
9–16ReservedFor future expansion.

Subtree Item Types

  • Consensus Headers: EVENT_HEADER, ROUND_HEADER
  • Input Items: SIGNED_TRANSACTION
  • Output Items: BLOCK_HEADER, RECORD_FILE, TRANSACTION_RESULT, TRANSACTION_OUTPUT
  • State Changes: STATE_CHANGES
  • Trace Data: TRACE_DATA

Additional Items (Not Hashed)

  • BLOCK_FOOTER - Contains hashes already included elsewhere in the tree.
  • BLOCK_PROOF - Proves the hash, so cannot be part of it.