VSC-88: Protocol Governance

VSC-88 adds on-chain protocol governance to Vexidus, enabling validators to propose and vote on protocol parameter changes, treasury spending, and community signal votes. It extends the existing VexVisor upgrade governance into a general-purpose system.

How It Works

1. Propose -- An active validator submits a proposal (parameter change, treasury spend, text, contract safety, or collection safety)
2. Vote -- Validators vote with stake-weighted power (same model as VexVisor upgrade voting)
3. Approve -- Quorum met + majority yes = Approved
4. Execute -- Anyone calls execute to apply the approved change on-chain

In seed-authority mode (early testnet), proposals are auto-approved. In full mode, real stake-weighted voting is required.

Proposal Types

Parameter Change

Adjusts on-chain protocol parameters. Auto-executed on approval -- the new value takes effect immediately.

Governable parameters:

Parameter	Description	Default	Bounds
gas_price	Base gas price (nanoVXS/gas)	10	1 -- 1,000
max_txs_per_block	Max transactions per block	10,000	100 -- 100,000
min_stake	Minimum VXS to become a validator	1,000 VXS	100 -- 100,000 VXS
max_commission_bps	Max validator commission (basis points)	5,000 (50%)	100 -- 10,000
voting_period_blocks	Governance voting duration	500 blocks	100 -- 50,400
quorum_percent	Required approval quorum	67%	51 -- 100%

Not governable (require binary upgrade via VexVisor):

• Block time (consensus-level coordination)
• Total VXS supply (fixed at 1.618B, unburnable)
• Block reward schedule

Treasury Spend

Transfers VXS from a governance-controlled treasury account to a specified recipient. Auto-executed on approval.

Treasury accounts (governance-controlled):

• Foundation Treasury -- 161.8M VXS (Vexidus Corp operations)
• Ecosystem & DeFi -- 242.7M VXS (grants, LP incentives)

Not governance-controlled: Public Distribution, Team (vesting), Marketing, SAFT, Testnet Rewards, Staking Reserve.

Text Proposal

Signal vote with no on-chain effect. Used for community sentiment ("should we prioritize feature X?"). Recorded on-chain for transparency.

Contract Safety (VSC-SAFE)

Reclassify a bridge contract's safety level. Used to upgrade legitimate projects to Verified status, or block known scam contracts. Auto-executed on approval -- the safety registry is updated immediately.

Required fields: --safety-chain, --safety-contract, --safety-level (Verified/Standard/Warning/Blocked)

See VexBridge Contract Safety for details on the scoring system.

Collection Safety (VSC-SAFE)

Flag or freeze a bridged NFT collection. Used to protect users from malicious collections with phishing metadata or impersonation attempts. Auto-executed on approval.

Required fields: --safety-collection (collection mint address)

---

Proposal Lifecycle

Created (Voting)
    |
    +-- Validators vote (stake-weighted)
    |       |
    |       +-- Quorum met + majority yes --> Approved
    |       |       |
    |       |       +-- ExecuteProposal called --> Executed
    |       |
    |       +-- Quorum met + majority no --> Rejected
    |
    +-- Voting period expires without quorum --> Expired
    |
    +-- Proposer cancels --> Cancelled

In seed-authority mode, proposals skip directly to Approved (auto-approved by the upgrade authority).

---

CLI Usage

Create a Proposal

# Parameter change: reduce gas price to 5
vexidus governance create-proposal \
  --type param \
  --title "Reduce gas price" \
  --description "Lower base gas price from 10 to 5 nanoVXS" \
  --param-key gas_price \
  --param-value 5

# Treasury spend: fund a grant
vexidus governance create-proposal \
  --type treasury \
  --title "Ecosystem Grant" \
  --description "Fund the VexSwap liquidity program" \
  --recipient Vx0RecipientAddress... \
  --amount 50000000000000

# Text proposal: signal vote
vexidus governance create-proposal \
  --type text \
  --title "Reduce block time?" \
  --description "Community sentiment check on reducing block time from 12s to 6s"

# Contract safety: verify a bridge contract
vexidus governance create-proposal \
  --type contract-safety \
  --title "Verify USDC on Base" \
  --description "Circle's official USDC deployment on Base" \
  --safety-chain base \
  --safety-contract 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 \
  --safety-level Verified

# Collection safety: flag a malicious NFT collection
vexidus governance create-proposal \
  --type collection-safety \
  --title "Freeze phishing collection" \
  --description "Collection metadata contains XSS payloads" \
  --safety-collection Vx0CollectionMintAddress...

Vote

vexidus governance vote --id 1 --approve
vexidus governance vote --id 1 --reject

Execute an Approved Proposal

vexidus governance execute --id 1

Cancel (Proposer Only)

vexidus governance cancel --id 1

View Proposals

vexidus governance list
vexidus governance list --status voting
vexidus governance show --id 1

---

RPC Methods

Method	Type	Description
vex_createProposal	Write	Submit a governance proposal
vex_voteProposal	Write	Vote on an active proposal
vex_executeProposal	Write	Execute an approved proposal
vex_cancelProposal	Write	Cancel a proposal (proposer only)
vex_getProposal	Read	Get proposal details by ID
vex_listProposals	Read	List proposals (filter by status)

Example: Create a Proposal

curl -s https://testnet.vexidus.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_createProposal",
    "params": [
      "VALIDATOR_ADDRESS",
      "ParameterChange",
      "Reduce gas price",
      "Lower base gas price from 10 to 5 nanoVXS",
      "gas_price",
      "5",
      null,
      null
    ],
    "id": 1
  }' | jq .

Example: List Active Proposals

curl -s https://testnet.vexidus.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "vex_listProposals",
    "params": ["voting"],
    "id": 1
  }' | jq .

---

SDK Usage

use vexidus_sdk::BundleBuilder;

// Create a parameter change proposal
let bundle = BundleBuilder::new(&validator_addr)?
    .create_proposal(
        "ParameterChange",
        "Reduce gas price",
        "Lower from 10 to 5 nanoVXS",
        Some("gas_price".to_string()),
        Some("5".to_string()),
        None, None,
    )
    .nonce(nonce)
    .sign(&wallet);

// Vote on a proposal
let bundle = BundleBuilder::new(&validator_addr)?
    .vote_proposal(1, true)  // proposal_id=1, approve=true
    .nonce(nonce)
    .sign(&wallet);

// Execute an approved proposal
let bundle = BundleBuilder::new(&any_addr)?
    .execute_proposal(1)
    .nonce(nonce)
    .sign(&wallet);

---

Constraints

Constraint	Value
Max active proposals	5
Title length	1 -- 128 characters
Description length	1 -- 1,024 characters
Who can propose	Active, non-jailed validators (full mode) or upgrade authority (seed-authority)
Who can vote	Active, non-jailed validators
Vote weight	Validator total stake (own + delegated)
Who can execute	Anyone (approval is the authorization)
Who can cancel	Original proposer only (unless already Executed)
Gas: CreateProposal	80,000
Gas: VoteProposal	40,000
Gas: ExecuteProposal	60,000
Gas: CancelProposal	40,000

Relationship to VexVisor

VexVisor (disc 46-48) handles binary upgrades -- scheduling, voting, halt-at-height, and auto-restart via the VexVisor wrapper script.

VSC-88 (disc 60-63) handles protocol governance -- parameter changes, treasury spending, and signal votes.

Both use the same governance mode (seed-authority or full), stake-weighted voting, quorum logic, and double-vote prevention. They are complementary systems.

Evolution

VSC-88 protocol governance is the foundation for the upcoming VSC-99 DAO Program, which extends the same voting engine to token-weighted community governance for user-created DAOs.