> For the complete documentation index, see [llms.txt](https://docs.onyx.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onyx.org/governance/onyx-chain/proposal-lifecycle.md). # Proposal Lifecycle Every proposal on Onyx Chain — every **OIP** — moves through the same on-chain state machine. This page walks through each stage, the exact timing, and what it means for you as a voter. ## The state machine ```mermaid graph TD P["Pending
voting delay — 1 day"] --> A["Active
voting open — 2 days"] A --> S["Succeeded
quorum reached, For above Against"] A --> D["Defeated
quorum missed or majority failed"] S --> Q["Queued
timelock delay — 2 days"] Q --> E["Executed
actions performed on-chain"] P --> C["Canceled"] A --> C Q --> C ``` | State | Meaning | Duration | | ------------- | -------------------------------------------------------------------------------------------------------- | ----------------------- | | **Pending** | The proposal exists on-chain but voting has not opened yet. | 1 day (voting delay) | | **Active** | Voting is open. Eligible stakers cast For, Against, or Abstain. | 2 days (voting period) | | **Succeeded** | Voting closed; the proposal passed. | Until queued | | **Defeated** | Voting closed; the proposal failed. Terminal state. | — | | **Queued** | The proposal's actions are locked into the Timelock and wait out the safety delay. | 2 days (timelock delay) | | **Executed** | The Timelock has performed the proposal's actions. Terminal state. | — | | **Canceled** | The proposal was withdrawn or blocked by the guardian safety mechanism before execution. Terminal state. | — | ## Stage by stage ### 1. Drafting and the proposal snapshot Before a proposal can be created, its voting snapshot is prepared: the eligible stXCN voting weight of every staker is measured at a specific finalized block, published on-chain to the [Snapshot Registry](/governance/onyx-chain/contracts.md#stxcn-snapshot-registry), and held open to public challenge for **1 day** before it is finalized. This finalized snapshot fixes *who can vote on this proposal and with how much weight* — nothing that happens to balances afterwards changes it. A proposal contains the **exact on-chain actions** it will perform — the target contracts, values, and encoded calls — plus a human-readable description. What you vote on is precisely what gets executed; there is no "interpretation" step between an approved vote and execution. ### 2. Creation (proposing) The proposer submits the proposal on-chain, attaching a cryptographic proof of their own snapshot weight. The Governor contract checks the proof against the latest finalized eligibility snapshot and requires: > **Proposal threshold:** the proposer's snapshot weight must be at least `max(100,000,000, 0.10% of eligible staked supply)` — currently **100,000,000** staked XCN. This threshold prevents spam while keeping proposing open to any sufficiently committed staker — no whitelist, no committee approval. Once the transaction confirms, the proposal has a permanent on-chain ID, is assigned its **OIP number**, and enters **Pending**. ### 3. Voting delay (1 day) For one day after creation, the proposal is visible but voting is closed. This window gives every voter time to: * read the proposal description and inspect the raw actions on the [explorer](https://explorer.onyx.org), * discuss it with the community, * decide how to vote. Your voting weight is already fixed at the snapshot — buying or staking during the delay does **not** add voting power for this proposal. ### 4. Voting period (2 days) Voting opens for two days. Every eligible staker casts one of three options: | Option | Effect | | ----------- | -------------------------------------------------------------------------------------- | | **For** | Supports the proposal. Counts toward quorum **and** the majority. | | **Against** | Opposes the proposal. Counts toward the majority only. | | **Abstain** | Participates without taking a side. Counts toward **neither** quorum nor the majority. | Votes are weighted by snapshot stXCN balance and each address can vote once per proposal. When you vote through the Onyx App, the app automatically attaches the cryptographic proof of your snapshot weight — you just choose For, Against, or Abstain and sign. ### 5. Tallying — how a proposal passes When the voting period ends, the proposal **succeeds** only if **both** conditions hold: 1. **Quorum (For-only):** For votes alone total at least `max(200,000,000, 2.00% of eligible staked supply)` — currently **200,000,000** XCN of staked weight. Against and Abstain votes never count toward quorum. 2. **Majority:** For votes strictly exceed Against votes. {% hint style="info" %} **Why For-only quorum matters:** a proposal cannot reach quorum through opposition or abstention. A heavily contested proposal with 190M For and 500M Against fails quorum *and* the majority — it needs genuine, affirmative support to pass. {% endhint %} If either condition fails, the proposal is **Defeated** — a terminal state. A defeated proposal can only be tried again as a brand-new proposal with a new vote. ### 6. Queue and Timelock (2 days) A succeeded proposal does not execute immediately. It is first **queued** into the [Timelock](/governance/onyx-chain/contracts.md#onyx-chain-timelock), which enforces a mandatory **2-day delay** before the actions can run. This delay is the community's final safety net: * everyone can review exactly what is about to execute, * integrators and users can prepare for the change, * if the proposal turns out to be malicious or defective, the **guardian** — an emergency safety role — can cancel it before execution. ### 7. Execution After the timelock delay expires, **anyone** can trigger execution. The Timelock performs the proposal's actions exactly as approved — for example, transferring a grant from the [Grant Treasury](/governance/onyx-chain/contracts.md#grant-treasury), or updating a protocol parameter. The result is permanently recorded on-chain and the proposal reaches **Executed**. ## Timeline at a glance ```mermaid graph LR T0["Day 0
Proposal created"] --> T1["Day 1
Voting opens"] T1 --> T3["Day 3
Voting closes"] T3 --> T3q["Day 3
Queued in Timelock"] T3q --> T5["Day 5
Earliest execution"] ``` From creation to execution is a **minimum of about 5 days**: 1-day voting delay + 2-day voting period + 2-day timelock delay (plus the 1-day snapshot challenge window that runs before creation). ## Voter checklist * ✅ **Stake early.** Only stXCN held at the snapshot counts — stake before a proposal you care about reaches its snapshot. See [Voting Power and Snapshots](/governance/onyx-chain/voting-power.md). * ✅ **Use the voting delay.** Read the description *and* glance at the raw actions — the actions are what actually executes. * ✅ **Vote within the 2-day window.** There are no late votes and no vote changes after the period closes. * ✅ **Abstain is not "quiet support."** Abstain never helps a proposal reach quorum. * ✅ **Watch the queue.** The 2-day timelock is your last chance to react to an approved change before it goes live. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.onyx.org/governance/onyx-chain/proposal-lifecycle.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.