> 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/contracts.md).

# Governance Contracts

Onyx Chain governance is implemented by a small set of purpose-built smart contracts deployed on Onyx Mainnet (chain ID 327). Each contract has one job, and no single party — including the team — can bypass the chain of checks they enforce together.

## Architecture

```mermaid
graph TD
    subgraph "Proposal plane"
        U["Staker / Voter<br/>(Onyx App or direct call)"] -->|"propose / vote<br/>with Merkle proof"| GOV["Governor<br/>OnyxGovernorV2"]
        GOV -->|"queue approved<br/>proposal"| TL["Timelock<br/>OnyxTimelockV2"]
        TL -->|"execute after<br/>2 days"| TR["Grant Treasury<br/>and other governed contracts"]
    end
    subgraph "Snapshot plane"
        ST["stXCN<br/>StakedXCNDirect"] -.->|"balances read at<br/>snapshot block"| REG["Snapshot Registry<br/>StXCNSnapshotRegistryV2"]
        PUB["Snapshot publisher"] -->|"post root"| REG
        CHA["Independent challenger"] -->|"challenge bad roots<br/>1-day window"| REG
    end
    GOV -->|"verify proofs"| REG
    GRD["Guardian"] -->|"veto bad root"| REG
    GRD -->|"cancel malicious<br/>queued proposal"| TL
```

The flow of authority is one-directional: stakers' balances feed snapshots, snapshots authorize proposals and votes in the Governor, the Governor commands the Timelock, and only the Timelock touches governed contracts.

## Contract addresses (Onyx Mainnet, chain ID 327)

| Contract                                      | Address                                                                                                                      |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Governor (`OnyxGovernorV2`)                   | [`0xd6fA6779224deD996D8a7d04ba51Dc4769b08280`](https://explorer.onyx.org/address/0xd6fA6779224deD996D8a7d04ba51Dc4769b08280) |
| Timelock (`OnyxTimelockV2`)                   | [`0xFC6a91f52dF6e3a8E0bB547de4265D71BD3feCA4`](https://explorer.onyx.org/address/0xFC6a91f52dF6e3a8E0bB547de4265D71BD3feCA4) |
| Snapshot Registry (`StXCNSnapshotRegistryV2`) | [`0xB14461828f3b55edf1B82020724dF7560117dB88`](https://explorer.onyx.org/address/0xB14461828f3b55edf1B82020724dF7560117dB88) |
| stXCN (`StakedXCNDirect`)                     | [`0xA553a603e2f84fEa6c1fc225E0945FE176C72F74`](https://explorer.onyx.org/address/0xA553a603e2f84fEa6c1fc225E0945FE176C72F74) |
| Grant Treasury                                | [`0xB592E16d6A7EF093Aa77843E1cB7BB287584f17a`](https://explorer.onyx.org/address/0xB592E16d6A7EF093Aa77843E1cB7BB287584f17a) |
| Wrapped XCN (WXCN, Treasury grant asset)      | [`0x1a0Da75ADf091a69E7285e596bB27218D77E17a9`](https://explorer.onyx.org/address/0x1a0Da75ADf091a69E7285e596bB27218D77E17a9) |

## The contracts

### Governor

The **Governor** (`OnyxGovernorV2`) is the heart of the system — it is where proposals are created, voted on, and driven through their [lifecycle](/governance/onyx-chain/proposal-lifecycle.md). It is built on the industry-standard OpenZeppelin Governor framework, extended with proof-based eligibility:

* **Proof-bound proposing.** `proposeWithProof` requires the proposer to attach a Merkle proof of their snapshot weight; the Governor checks it against the latest finalized eligibility snapshot in the Registry and enforces the proposal threshold (currently 100,000,000 staked XCN).
* **Proof-bound voting.** The only accepted vote path carries the voter's weight and Merkle proof; the Governor verifies every vote against the proposal's finalized snapshot root. A vote without a valid proof counts as zero.
* **For-only quorum.** Quorum (currently 200,000,000) is satisfied by For votes alone; passage additionally requires For > Against.
* **Fixed timing.** Voting delay (1 day) and voting period (2 days) are compiled into the contract — they cannot be quietly changed by an operator. The threshold and quorum *rates* can be adjusted only within hard-coded bounds, and only by governance itself.

### Onyx Chain Timelock

The **Timelock** (`OnyxTimelockV2`) is the executor and the safety buffer. When a proposal succeeds, the Governor queues its actions here, where they must wait a mandatory **2 days** before execution:

* The Timelock — not the Governor, not any admin — is the **owner of governed contracts**. A governed contract only changes when the Timelock executes an approved proposal.
* The Governor is the only address allowed to queue operations (proposer role).
* The guardian holds a **cancel** right on the Timelock, so a malicious proposal that slipped through a vote can still be stopped during the 2-day delay — but the guardian can never *create* or *fast-track* anything.

### stXCN Snapshot Registry

The **Snapshot Registry** (`StXCNSnapshotRegistryV2`) is the on-chain home of [voting-power snapshots](/governance/onyx-chain/voting-power.md). It stores each published Merkle root with its full metadata (snapshot block, eligible supply, policy version) and enforces the root lifecycle:

* **Post → challenge (1 day) → finalize.** Only roots that survive the challenge window become usable for governance.
* **Strict role separation.** The publisher, challenger, and guardian are required to be distinct parties — the contract itself rejects a configuration where one address holds two of these roles.
* **Fail-closed verification.** The Governor's proof checks revert on an unfinalized root, a wrong-purpose root, a mismatched policy, or a paused registry. There is no fallback path that skips verification.

### stXCN (StakedXCNDirect)

**stXCN** is the liquid staking token you receive for staking XCN — and the sole source of voting power on Onyx Chain. It is a rebasing token: your balance grows as staking rewards accrue, and governance snapshots measure that grown balance. stXCN itself is documented in [Staking and stXCN](/onyx-defi/onyx-app/staking.md).

### Grant Treasury

The **Grant Treasury** is the first contract governed end-to-end by Onyx Chain governance. It holds WXCN and exposes exactly one privileged function — paying out a grant to a recipient — callable **only by its owner, the Timelock**. In other words:

> The only way funds leave the Grant Treasury is a full OIP: proposal → vote → quorum → 2-day timelock → execution.

This makes community grant funding a pure governance decision, with every step publicly visible and verifiable on the [explorer](https://explorer.onyx.org).

## Operational roles

| Role                    | What it can do                                                         | What it cannot do                                      |
| ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
| **Publisher**           | Post new snapshot roots to the Registry                                | Finalize its own root early, vote, or execute anything |
| **Challenger**          | Dispute an incorrect root during the 1-day window                      | Post roots or interfere with correct ones              |
| **Guardian**            | Veto a bad root; cancel a malicious proposal during the timelock delay | Create, fast-track, or execute proposals; move funds   |
| **Governor (contract)** | Queue approved proposals into the Timelock                             | Execute anything without the 2-day delay               |
| **Timelock (contract)** | Execute approved proposals after the delay                             | Act without an approved, queued proposal               |

{% hint style="info" %}
**Verify, don't trust.** All the contracts above are deployed on Onyx Mainnet and every proposal, snapshot root, vote, queue, and execution is a public transaction. You can independently verify any governance action on the [explorer](https://explorer.onyx.org) using the addresses in the table above.
{% endhint %}


---

# 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/contracts.md?ask=<question>&goal=<endgoal>
```

`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.