Skip to content

Governance

This document explains how governance works in Sage Protocol from a contributor's perspective — what the different governance models mean operationally, how they affect code paths, and why the design looks the way it does.

For the full governance narrative and user-facing documentation, see Home and the Governance Models concept page.

Why Governance Matters for Contributors

Governance isn't just a user-facing feature — it fundamentally shapes how every other system in the protocol behaves. The CLI, the worker, the subgraph, and the discovery stack all need to understand who can change what, and how.

The key insight: governance determines what "latest" means. In an operator/personal DAO, "latest" changes immediately when the operator executes. In a community DAO, "latest" changes only after a proposal passes voting, survives the timelock delay, and is executed on-chain. Every system that reads "the current state" must account for this difference.

The Two Governance Shapes

Operator / Personal

A single operator (or multisig) can update library pointers directly. The CLI can "publish" and execute without community voting.

What this means in code: - CLI paths that skip voting but still validate roles/addresses - The worker and subgraph see on-chain updates the same way regardless of governance mode — they index events, not decision processes - "Latest" changes immediately after the operator's transaction is mined

Community / Token Voting

Proposals go through voting periods and timelock gates before updates take effect. Users need delegated voting power to propose and vote.

What this means in code: - sage doctor --registry must accurately reflect the proposer's eligibility (token balance, delegation status, cooldown) - The full proposal lifecycle matters: propose → vote → queue → execute. Each step is a separate transaction. - "Latest" changes only after the execute transaction is mined — which can be days or weeks after the initial proposal

This distinction creates a design constraint: any system that needs to know "what is current" should treat on-chain execution as the source of truth, not proposal submission or vote completion.

Key Governance Tooling Surfaces

The governance system touches multiple packages:

CLI: packages/sage/crates/cli/src/commands/proposals.rs and related command modules under packages/sage/crates/cli/src/commands/ implement the human/agent interface for governance operations.

Contracts: Governors, timelocks, and registries under contracts/ define the on-chain rules.

Worker + Discovery: The worker and discovery stack should treat on-chain execution as the source of truth for what is "active" or "latest." They don't need to understand governance modes — they just index events from executed transactions.

Indexing Implications

The subgraph indexes governance events (proposals created, votes cast, proposals executed) and these drive the governance UX in the web app. But for content freshness — which manifest CID is current — the relevant event is the LibraryRegistry update, which only fires after execution.

This means there's an inherent delay between "a proposal passed" and "the new content is live in discovery." The delay is the timelock period plus indexing propagation. For community DAOs, this can be days. Systems should communicate this to users rather than trying to shortcut around it.

Boosts and the Merkle Leaf Format

GovernanceBoostManagerMerkle verifies boost claims against a Merkle root where each leaf binds to a specific chain, contract, governor, and proposal:

keccak256(abi.encode(chainid, address(this), governor, proposalId, account, amount))

This encoding exists because boosts are governor+proposal specific. A voter rebate for governor A proposal #42 should not be claimable for governor B proposal #42. The chain ID and contract address prevent cross-chain and cross-contract replay.

Any off-chain Merkle root or proof generator must use this exact encoding, otherwise on-chain claim(...) will revert with bad proof. This is a common integration gotcha — the encoding must be byte-identical.

Why Multiple Governance Models

We provide operator, council, and community governance because different communities have different trust profiles and iteration speeds. A solo creator needs instant control; a large community needs formal voting with safeguards. Rather than forcing everyone through the same process, we provide playbooks that pre-configure the three governance axes (governance kind, proposal access, execution access).

The tradeoff is complexity. Multiple governance models mean more code paths, more testing surface, and more ways for users to misunderstand who has authority over what. We accept this tradeoff because the alternative — one-size-fits-all governance — would make the protocol unusable for either solo creators or large communities.

For a detailed explanation of the governance models and when to use each, see Governance Models.

How This Connects