/hardfork-activation-and-protocol-upgrade

name: "hardfork-activation-and-protocol-upgrade"
description: "L1 trigger - audits bugs that surface only at fork boundaries / protocol upgrade points: activation logic, dormant code paths, upgrade epoch correctness, version gating."

Injectable Skill: Hardfork Activation and Protocol Upgrade

> **L1 trigger**: `L1_PATTERN=true` AND (`fork_rules` OR `chain_config` OR `hardfork` OR `upgrade_handler` OR `x/upgrade` OR `ActivationHeight` OR `ActivationEpoch` detected in recon subsystem map) > **Inject Into**: `depth-state-trace` or `depth-consensus-invariant` > **Language**: Go and Rust > **Finding prefix**: `[HF-N]` > **Status**: v0.1 draft (added from Round 4 gap analysis)

Orchestrator Decomposition Guide

• Sections 1, 2: depth-state-trace (activation logic, version gating)
• Section 3: depth-consensus-invariant (dormant code paths)
• Section 4: depth-edge-case (boundary epoch + upgrade races)

When This Skill Activates

Recon identifies fork-activation, chain-config, or upgrade-handler code. This skill addresses a distinct bug class surfaced by Round 4: **bugs that are invisible until an upgrade epoch arrives**. The Prysm Fusaka bug (Dec 2025) is the canonical example — perfectly working code in v7.0.0, Critical-severity bug the moment Fusaka activated.

The defining feature: these bugs cannot be found by analyzing "current behavior" alone. They live in code paths that are dormant until a specific block height, epoch, or version condition fires.

1. Activation Logic

Every hardfork has an activation condition: a block height, timestamp, epoch, or version number. Verify:

1a. Activation condition is deterministic

• The condition must not depend on non-deterministic inputs (no wall clock, no node-local config that differs across peers)
• The condition must be a single canonical value per chain, not derived from a header field an attacker can influence

1b. Activation is atomic across all affected rules

If a hardfork activates multiple rule changes (new opcode, new gas cost, new pricing), ALL must activate at the same height. Partial activation = consensus split.

1c. Activation code is reachable

Check: the code gated by `if block.Number >= ForkBlock` actually runs. Dead code that was meant to activate but never does is a finding (late activation = missed hardfork).

1d. Test network vs mainnet

Testnet activation heights are different from mainnet. Verify: the code does not have a hardcoded mainnet block number that breaks on testnet, or vice versa. Every activation condition should be config-driven.

Tag: `[HF-ACTIVATE:{fork}:{issue}]`

2. Dormant Code Paths

The hardest class: code that exists for a future fork but has never run in production. Prysm Fusaka is the exemplar — v7.0.0 shipped with the Fusaka code path, but that path was dormant until the upgrade epoch. When it activated, bugs surfaced that no amount of testing on the pre-Fusaka chain would have caught.

Check

• List every `if chainConfig.IsXxx(blockNumber)` gate in the codebase
• For each, identify what code runs when the gate becomes true
• Apply full L1 skill pack to that dormant code (it's effectively a new codebase that just hasn't executed yet)
• **Cross-check against the spec**: does the code match the spec document for that fork?
• **Cross-check against other clients**: has another client already implemented the fork? Run a differential against their implementation (this is the strongest check)

Tag: `[HF-DORMANT:{fork}:{gated-code}]`

**Critical methodology nuance**: dormant code is under-tested by definition. Any finding in dormant code should be flagged **High or Critical** because the production blast radius is the entire upgrade.

3. Version Gating

For protocols with multiple client implementations, version gating must agree:

• Client A version X says "Fusaka activates at epoch 411392"
• Client B version Y must say the same

Check:

• Activation constants are consistent across clients (spec document is the source of truth)
• If the activation is spec-defined, the spec must be referenced in the code (grep for EIP number, Cosmos ADR, etc.)
• Client-specific feature flags must not alter the activation height

Tag: `[HF-VERSION:{client}:{divergence}]`

4. Upgrade Epoch Boundary

At the upgrade epoch itself, two rule sets coexist: pre-upgrade rules apply to blocks at epoch N-1, post-upgrade rules apply to N. At the boundary:

4a. Transition state

• What state must be migrated? (New struct fields, storage layout changes, validator set format changes)
• Is the migration idempotent? (Can be re-run safely)
• Is the migration atomic with the activation? (Can the chain halt mid-migration?)

4b. Transition reorgs

• If a reorg happens across the upgrade epoch boundary, do both old and new rules apply correctly?
• Specifically: a block at epoch N (post-upgrade) that gets reorged back to epoch N-1 (pre-upgrade) — is the state consistently reverted to pre-upgrade rules?

4c. Consuming contracts

• If the upgrade changes opcode behavior (gas prices, semantics), do existing deployed contracts still work? This is a consensus concern because a contract that suddenly fails at the upgrade height can cause chain divergence if one client handles the failure differently from another.

Tag: `[HF-BOUNDARY:{issue}]`

5. Rollback and Upgrade Cancellation

If an upgrade fails post-deployment, the protocol may need to be rolled back.

• Is rollback supported? (Usually not — it requires a coordinated reorg)
• If the upgrade handler panics, does it halt the chain (Cosmos x/upgrade pattern) or revert? Halting is usually intentional; reverting silently is a bug.
• Emergency-pause switches: exist? Guarded by governance? Tested?

Tag: `[HF-ROLLBACK:{state}]`

6. Boundary Conditions

| State | Test | Expected | |---|---|---| | Genesis = fork block | chain starts at upgrade | handled | | Reorg across fork | reorg to block before fork activation | state rolled back to pre-fork rules | |