HSP-012: Two-Phase Model for Consensus Protocol Upgrades

House of Stake
1

HSP-012: Two-Phase Model for Consensus Protocol Upgrades

Status: Draft

Authors: Blaze

Created: October 22, 2025

Discussion:

Abstract

NEAR’s consensus upgrades like 2.9.0 (inflation reduction to 2.5% from 5%, vote started Oct 21) use stake-weighted signaling via binary runs (CODE_YELLOW), risking ejection for dissenters if <80% threshold met after 1 epoch grace. Propose two-phase with existing process: (1) Signaling via stable CODE_GREEN binary (yes/no/abstain vote via header flags, no penalties), (2) CODE_YELLOW release post-approval, using standard 1-epoch grace and reward taper after 80% upgrade (no hard ejection). Ensures full vote inclusion (including abstentions), avoids disruptions. Apply to impactful consensus changes (e.g., inflation, sharding, breaking versions) where dissent >10% projected.

Motivation

Current process signals via block headers when running candidate binaries—dissenters risk ejection post-80% threshold (nearcore docs). For 2.9.0 (~15% projected dissent per forums), small validators (bottom 50% stake) could exit, concentrating power (top 10 hold ~60%). Past upgrades (e.g., 1.28.0’s 92% pass) had laggard delays over 1 epoch. Two-phase uses GREEN for safe signaling (informational, no breaking changes), YELLOW for execution—aligns with Nightshade thresholds and color tiers. Abstentions allow neutral stake (e.g., testing concerns) to count without coercion, boosting quorum accuracy. Limit to high-impact cases: Consensus-altering (inflation/economics), structural (sharding/validation rules), or breaking (DB migrations affecting >20% nodes)—skipping minor patches (GREEN-only) to avoid overhead.

Specification

For impactful consensus upgrades (e.g., 2.9.0, where projected dissent >10% or stake at risk):

Phase 1: Signaling (7 Days)

  • CODE_GREEN binary with yes/no/abstain vote flag in headers (stake-weighted via producer participation; abstain for neutrals/testing).
  • Threshold: 2/3 quorum pass (abstentions excluded from yes/no ratio but count toward total quorum).
  • No ejection—GREEN is stable/informational.

Phase 2: Execution (Post-Pass)

  • CODE_YELLOW binary release; use normal migration: 80% threshold triggers 1-epoch grace, then standard reward taper (no hard ejection for laggards).
  • Retrofit 2.9.0: Add GREEN signaling before final threshold.

Non-applicable cases (e.g., GREEN perf tweaks): Standard single-phase.

Rationale

Leverages existing GREEN/YELLOW signaling—no new tech. Preserves 100% votes (incl. abstentions) vs. 5-10% dissent loss risk. Keeps 80% activation and 1-epoch grace; improves retention without overhauls. Scoped to impactful changes minimizes process creep (e.g., 80% of releases stay single-phase).

Backwards Compatibility

Parallel GREEN run; standard protocol-version flag.

Test Cases

  • 70% yes (20% abstain): Threshold met, full rewards during GREEN.
  • 40% no (30% abstain): Archive, no penalties.
  • Migration: 80% triggers 1-epoch grace; taper post-grace.
  • Low Dissent (<10% projected): Skip to single-phase YELLOW.

Reference Implementation

Add vote_flag (yes/no/abstain) to BlockHeaderInnerRest.version.

Security Considerations

Standard nearcore audits; no new vectors—uses existing header signaling.

Copyright

CC0 1.0.

Feedback welcome—fairer upgrades via standard process.

1 Like
2

I don’t like having to download 2 different binaries for each upgrade, would make it twice as complicated to manage validator / rpc node, requiring twice as much maintenance (which is not much, but still time). But maybe there could be a simpler approach - for example, after successful voting, delay the actual protocol upgrade by X epochs to give people who voted “against” additional time to update their binary. Also, I think this feels like it should be a NEP, not HSP

3

it would not be every proposal just high-impact ones.

good point maybe a NEP is best. some other validators mentioned an HSP for the change. will submit both ways.