> For the complete documentation index, see [llms.txt](https://docs.tonadocash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonadocash.com/protocol-reference/governance.md).

# Governance

The on-chain `Governance` contract is where authority lives after the bootstrap multisig hands off. It executes proposals weighted by veTONADO voting power behind a timelock.

## Lifecycle

```
   ┌──────────┐       Vote(yes/no)        ┌──────────┐       ┌──────────┐
   │ Propose  │ ───── (asks veTONADO ──→  │  Queue   │ ────→ │ Execute  │
   │ (ACTIVE) │       for vp; reply       │ (QUEUED) │       │ (EXECUTED│
   │          │       credits tally)      │          │       │  / queued│
   │          │                           │          │       │  msg     │
   │          │       Or never gets       │          │       │  sent)   │
   │          │       enough votes →      │          │       │          │
   │          │       Queue marks         │          │       │          │
   │          │       (REJECTED)          │          │       │          │
   └──────────┘                           └──────────┘       └──────────┘
        ↓                                       ↓                  ↓
   votingPeriod                             timelock-          target receives
   accepts votes                            Seconds delay      proposal.body
```

Concretely:

1. **`Propose(payload)`** - anyone with enough TON for gas. `payload` is a `Cell<ProposalPayload>` containing `(dest, value, body)` - the outbound message governance will fire if the proposal passes. New proposal enters `ACTIVE` with `votingEnd = now + votingPeriodSeconds`.
2. **`Vote(proposalId, support: 0|1)`** - anyone with vTONADO. The governance contract immediately sends a `QueryVotingPower` to the configured veTONADO contract. veTONADO replies asynchronously with `VotingPowerReply(requestId, voter, vp)`; governance credits `vp` to `forVotes` or `againstVotes`.
3. **`Queue(proposalId)`** - anyone, after `votingEnd`. If `forVotes >= quorum && forVotes > againstVotes` → status = `QUEUED`, `timelockEnd = now + timelockSeconds`. Else → `REJECTED`.
4. **`Execute(proposalId)`** - anyone, after `timelockEnd` on a `QUEUED` proposal. The queued outbound message fires; status → `EXECUTED`.

## Security: cross-contract vote-weight verification

Voting on TON differs from Compound-style block-snapshot voting because TON contracts can't synchronously read each other's state. The pattern:

* Voter sends `Vote(...)` → governance stores a `PendingVote` record (keyed by a per-vote `requestId`) and sends `QueryVotingPower(requestId, voter)` to veTONADO.
* veTONADO looks up the voter's current vp and sends `VotingPowerReply(requestId, voter, vp)` back to the governance contract.
* Governance receives the reply, **asserts `sender == veTonadoAddr`** (the security boundary), looks up the pending vote by `requestId`, and credits the vp.

The `sender == veTonadoAddr` check is the single critical invariant. Without it, anyone could forge a reply and inflate any proposal's tallies.

Vote-arrival ordering matters because vp is measured AT REPLY TIME, not at the moment the voter sent `Vote`. This means a voter who locks additional TONADO between their `Vote` and the reply lands gets the HIGHER vp credited. Acceptable trade-off: matches "voting power is current at vote time" semantics.

## Stale-reply handling

If a proposal transitions out of ACTIVE (e.g., voting period ended) before a vote reply lands, the late credit is **silently dropped**. The proposal's tallies stay as they were at the queue moment. This prevents late voters from gaming the system by deliberately delaying their reply.

## Owner and renunciation

`Governance` deploys with `owner = multisig` for fast iteration during bootstrap. The multisig can:

* `AdminSetParams` - tune `votingPeriod`, `timelockSeconds`, `quorum`
* `AdminSetVeTonado` - update the veTONADO contract address (e.g., after a veTONADO upgrade migration)
* `AdminPause` / `AdminUnpause` - emergency pause
* `AdminRenounce` - transfer `owner` to `BURN_ADDRESS`. After this, admin ops are permanently uncallable; the protocol becomes purely self-governing.

The intended path: ship with multisig for the first months; once parameters stabilize and veTONADO TVL is meaningful, the multisig calls `AdminRenounce` and the protocol runs on community governance alone.

## Parameter defaults

| Parameter             | Default        | Notes                                                                              |
| --------------------- | -------------- | ---------------------------------------------------------------------------------- |
| `votingPeriodSeconds` | 3 days         | Common Compound-style default                                                      |
| `timelockSeconds`     | 1 day          | Long enough for users to react if a malicious proposal queues                      |
| `quorum`              | TBD per launch | Set as a fraction of expected initial `totalVotingPower` after first ve locks land |

Adjust via `AdminSetParams` until renounce.

## See also

* [`governance.tolk`](https://github.com/tonadocash/monorepo/blob/main/apps/contracts/contracts/governance/governance.tolk) - full contract source
* [`governance.ts`](https://github.com/tonadocash/monorepo/blob/main/packages/core/src/governance.ts) - SDK wrapper
* [`governance.test.ts`](https://github.com/tonadocash/monorepo/blob/main/apps/contracts/tests/governance.test.ts) - 10 sandbox tests
* [tokenomics.md](/protocol-reference/tokenomics.md) - where governance fits in the broader token model
* [contracts-spec.md](/protocol-reference/contracts-spec.md) - surface area summary