VexVisor -- Upgrade Governance Module

VexVisor is the on-chain upgrade governance module (discriminants 46-48) that enables coordinated binary upgrades across the validator set without manual intervention.

How It Works

1. Schedule -- Authority proposes upgrade: name, target height, binary URL, SHA256 checksum
2. Vote -- Validators vote to approve/reject (stake-weighted, 67% quorum in full mode)
3. Halt -- At target height, node writes data/upgrade-info.json and exits with code 42
4. VexVisor wrapper -- tools/vexvisor.sh detects exit(42), downloads new binary, verifies SHA256, restarts. Auto-rollback if crash within 60s.

Governance Modes

Mode	Behavior	Use Case
seed-authority (default)	Upgrade authority auto-approves, no voting needed	Early testnet
full	Stake-weighted voting with configurable quorum (default 67%)	Public beta / mainnet

Configure with --governance-mode <seed-authority|full>.

Operations

Schedule an Upgrade

Proposes a new upgrade to the network.

vexidus upgrade schedule \
  --name "v0.2.0" \
  --height 100000 \
  --url "https://releases.vexidus.io/v0.2.0/vexidus-node" \
  --checksum "abc123..." \
  --info-url "https://vexidus.io/releases/v0.2.0"

Requirements:

• Target height must be at least 100 blocks in the future
• Only one active upgrade plan at a time
• In seed-authority mode, must be signed by the upgrade authority
• Gas: 80,000

Vote on an Upgrade

Validators vote to approve or reject a proposed upgrade (only in full mode).

vexidus upgrade vote --name "v0.2.0" --approve

• Stake-weighted voting
• Double-vote prevention (each validator votes once)
• Quorum: 67% by default (configurable via --upgrade-quorum)
• Gas: 40,000

Cancel an Upgrade

Cancel a scheduled upgrade before it executes.

vexidus upgrade cancel --name "v0.2.0"

• Only the upgrade authority can cancel
• Gas: 60,000

View Active Plan

vexidus upgrade plan

Emergency Rollback

vexidus upgrade rollback

RPC Methods

Method	Description
vex_scheduleUpgrade	Schedule a network upgrade
vex_cancelUpgrade	Cancel a scheduled upgrade
vex_voteUpgrade	Vote on a scheduled upgrade
vex_getUpgradePlan	View the active upgrade plan

The VexVisor Wrapper

In production, all validators run via the tools/vexvisor.sh wrapper script. This script:

1. Monitors exit codes -- exit(42) means "upgrade required"
2. Downloads the new binary from the URL specified in the upgrade plan
3. Verifies SHA256 checksum -- rejects tampered binaries
4. Restarts with new binary -- automatic, no manual intervention
5. Auto-rollback -- if the new binary crashes within 60 seconds, rolls back to the previous version
6. Exponential backoff -- retries with increasing delays on repeated failures

Upgrade Lifecycle

Schedule Upgrade (RPC/CLI)
    |
    v
Voting Period (full mode only)
    |  67% stake-weighted quorum required
    v
Approved -> Target Height Reached
    |
    v
Node writes upgrade-info.json + exits(42)
    |
    v
VexVisor downloads binary + SHA256 verify
    |
    v
Restart with new binary
    |
    v
Grace Period (100 blocks) -- no jailing during upgrade

Upgrade Grace Period

After an upgrade halt, a grace period of 100 blocks (~200 seconds) suppresses missed-block tracking. This prevents validators from being jailed simply for performing an upgrade.

Expiry

Upgrade proposals that are not approved before voting_ends_at_height are automatically cancelled via expire_upgrade_voting().

CLI Flags

Flag	Default	Description
--governance-mode	seed-authority	Governance mode (seed-authority or full)
--upgrade-authority	none	Hex pubkey of the upgrade authority
--voting-period	500	Voting period in blocks
--upgrade-quorum	67	Required approval quorum (percent)
--auto-vote-seed	none	Auto-vote seed for deterministic voting

Evolution Plan

1. Phase 1 (Current): Seed-authority mode -- upgrade authority auto-approves
2. Phase 2: Full mode with auto-vote from seed -- automated governance
3. Phase 3: Real stake-weighted voting with manual validator decisions
4. Phase 4: VSC-88 protocol governance (parameter changes, treasury, multi-sig) -- LIVE + VSC-99 DAO program (token-weighted community governance) -- Coming Soon

SDK

use vexidus_sdk::BundleBuilder;

// Schedule an upgrade
let bundle = BundleBuilder::new(&sender)?
    .schedule_upgrade(name, height, url, checksum, info_url)
    .sign(&wallet);

// Cancel an upgrade
let bundle = BundleBuilder::new(&sender)?
    .cancel_upgrade(name)
    .sign(&wallet);

// Vote on an upgrade
let bundle = BundleBuilder::new(&sender)?
    .vote_upgrade(name, approve)
    .sign(&wallet);