Governance
Proposal Lifecycle
Pre-launch
Section
Governance
Documentation category
Type
Guide
Technical reference
Summary
The eight proposal states, what moves a proposal between them, and why passing is not the same as executing.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

A proposal moves through discrete on-chain states. Each transition emits an event, so the full history of any proposal is reconstructible from the chain without trusting an interface.

The States

StateMeaning
PENDINGSubmitted, voting not yet open
ACTIVEOpen for voting by addresses holding rights at the proposal's tier
PASSEDQuorum reached at finalisation. Not yet executed
FAILEDFinalised without reaching quorum
VETOEDVetoed by the Foundation inside the veto window
ESCALATEDRaised to a higher tier for decision
CANCELLEDWithdrawn by the Foundation at any stage before execution
EXECUTEDApplied on chain. Terminal

The Path

  1. Submit. The proposal records its type, tier, proposer and title, and carries the execution data its type expects. A validator rotation, for example, carries the outgoing address, the incoming address and the new BLS public key.
  2. Vote. Only addresses granted rights at the proposal's tier may vote, and each may vote once. The voting window is a block count, not a wall-clock duration: see Governance Parameters.
  3. Finalise. When the window closes, quorum is evaluated as yesVotes × 100 ≥ threshold × totalValidators. Reaching it moves the proposal to PASSED; not reaching it moves it to FAILED.
  4. Veto window. A passed proposal waits. The Foundation may veto during this period; executing before it closes is rejected by the contract, not by convention.
  5. Execute. Once the window has closed and no veto was cast, the proposal executes and becomes EXECUTED.
Passing is not executing

A proposal reads PASSED for the whole veto window and the whole timelock. An integration that treats PASSED as "this change is live" will act on a decision that can still be vetoed. Wait for EXECUTED.

Quorum Is Against the Validator Count, Not the Turnout

The denominator is totalValidators, the recorded size of the validator set, not the number of validators who voted. Abstention therefore counts against a proposal rather than being excluded from the maths. This is deliberate: a settlement-layer change should require positive assent from a majority of the set, not from a majority of whoever happened to be online.

Reading Governance Programmatically

Every status transition emits an event, and the governance ledger mirrors them. Index the events rather than polling state if you need a history: state tells you where a proposal is now, events tell you how it got there and when.

Next Steps

Frequently Asked Questions
6 questions
A proposal says PASSED. Is the change live?

No. PASSED holds through the whole Foundation veto window and the timelock, and the proposal can still be vetoed. Wait for EXECUTED.

Who can vote?

Addresses granted rights at the proposal's tier. Holding stake does not confer them and neither does running a node.

Can I vote twice or change my vote?

No. Each eligible address votes once per proposal.

What is the difference between VETOED and CANCELLED?

VETOED is the Foundation stopping a proposal that passed, inside the veto window. CANCELLED is withdrawal at any stage before execution.

How do I build a reliable history of a proposal?

Index the events. State tells you where a proposal is now; events tell you how it got there and when.

What does ESCALATED mean?

The proposal has been raised to a higher tier for decision, so the quorum that applies to it changes.