> For the complete documentation index, see [llms.txt](https://andrewkimjoseph.gitbook.io/celina-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://andrewkimjoseph.gitbook.io/celina-sdk/guides/governance.md).

# Governance

Read governance proposals, lock/unlock CELO for voting power, and vote — all via unsigned transaction flows against Celo's core `Governance` and `LockedGold` contracts.

## Proposals

```ts
const { proposals, pagination } = await celina.governance.getGovernanceProposals({
  page: 1,
  pageSize: 10,
  includeMetadata: true, // fetches CGP frontmatter — slower; set false for faster list responses
});

const { proposal, content } = await celina.governance.getProposalDetails(42);
// content — CGP markdown body when the proposal links to a CGP
```

## Votable proposals

Only proposals in **Referendum** stage can be voted on. `getVotableProposals` resolves the on-chain dequeue and filters by stage, returning the `index` required for `prepareVote`:

```ts
const { proposals } = await celina.governance.getVotableProposals();
// proposals[].proposalId, proposals[].index, proposals[].stage === "Referendum"
```

`prepareVote` looks up the dequeue index internally — you only need `proposalId`.

## Locked CELO and voting power

```ts
const locked = await celina.governance.getLockedCeloBalance("0xYourAddress");
// locked.totalLockedFormatted, locked.nonvotingLockedFormatted, locked.governanceVotingPowerFormatted

const pending = await celina.governance.getPendingWithdrawals("0xYourAddress");
// pending.withdrawals[].isMature, pending.matureCount
```

## Prepare: lock, unlock, relock, withdraw, vote

All five are humanness-gated by convention (see [Humanness](/celina-sdk/guides/humanness.md)) — the SDK methods themselves do not call `checkHumanness`; celina-mcp's `execute_*` tools apply the gate before preparing.

```ts
// Lock — relocks matured pending withdrawals first, then locks the remainder as new CELO
const lockFlow = await celina.governance.prepareLockCelo(from, "100");

// Unlock — starts LockedGold's 3-day timelock
const unlockFlow = await celina.governance.prepareUnlockCelo(from, "50");

// Relock a specific pending withdrawal (cancels its timelock)
const relockFlow = await celina.governance.prepareRelockCelo(from, /* index */ 0, "50");

// Withdraw all matured pending withdrawals (throws if none are mature yet)
const withdrawFlow = await celina.governance.prepareWithdrawCelo(from);

// Vote — Abstain | No | Yes (VOTE_VALUES also includes "None", not votable)
const voteFlow = await celina.governance.prepareVote(from, /* proposalId */ 42, "Yes");
```

```ts
import { VOTE_VALUES, voteValueToInt, type VoteValueName } from "@andrewkimjoseph/celina-sdk";
// VOTE_VALUES === ["None", "Abstain", "No", "Yes"] — on-chain enum order
```

`prepareLockCelo`, `prepareUnlockCelo`, `prepareRelockCelo`, and `prepareWithdrawCelo` call `assertCeloAccountRegistered` first — the `from` address must have a registered Celo account (see [Send tokens](/celina-sdk/guides/send-tokens.md) for account registration).

Sign and broadcast like any other prepared flow:

```ts
for (const step of flow.steps) {
  await sendTransactionAsync({
    to: step.to,
    data: step.data,
    value: step.value ? BigInt(step.value) : undefined,
  });
}
```

## MCP tool mapping

| SDK method               | MCP tool (stdio, humanness-gated) | Browser prepare         |
| ------------------------ | --------------------------------- | ----------------------- |
| `getGovernanceProposals` | `get_governance_proposals`        | — (read, both surfaces) |
| `getProposalDetails`     | `get_proposal_details`            | — (read, both surfaces) |
| `getVotableProposals`    | `get_votable_proposals`           | — (read, both surfaces) |
| `getLockedCeloBalance`   | `get_locked_celo_balance`         | — (read, both surfaces) |
| `getPendingWithdrawals`  | `get_pending_withdrawals`         | — (read, both surfaces) |
| `prepareLockCelo`        | `execute_lock_celo`               | `prepare_lock_celo`     |
| `prepareUnlockCelo`      | `execute_unlock_celo`             | `prepare_unlock_celo`   |
| `prepareRelockCelo`      | `execute_relock_celo`             | `prepare_relock_celo`   |
| `prepareWithdrawCelo`    | `execute_withdraw_celo`           | `prepare_withdraw_celo` |
| `prepareVote`            | `execute_vote`                    | `prepare_vote`          |

`execute_*` tools accept an optional `signer: "celo" | "self_agent"` (defaults to CELO when both keys are configured) and apply the humanness gate before signing. Browser `prepare_*` tools return unsigned flows only — no humanness gate is applied at that layer; apply your own gate if your host needs one.

If you intend to sign with `self_agent`, fund and register that address **before** locking — see [Two wallets: CELO + Self agent](/celina-sdk/guides/mcp-session-wallet.md#two-wallets-celo--self-agent).

## Governance delegation

Delegating **governance voting power** on locked CELO is separate from voting on proposals — it routes through `LockedGold`, not `Governance`. See [Staking — Governance delegation](/celina-sdk/guides/staking.md#governance-delegation-lockedgold) for the full flow.

* **Discovery:** `getGovernanceDelegates` / MCP `get_governance_delegates` — curated [Celo Mondo](https://mondo.celo.org/delegate) directory (off-chain; not an on-chain registry). Any address can receive delegation.
* **Execution:** `prepareDelegatePower` / MCP `execute_delegate_power` with a chosen delegatee and percent (1–100).

## Related

* [Humanness](/celina-sdk/guides/humanness.md) — gating model for the `execute_*` writes above
* [Staking](/celina-sdk/guides/staking.md) — validator election staking, governance delegation, and Celo Mondo delegate directory
* [MCP session wallet](/celina-sdk/guides/mcp-session-wallet.md) — funding a Self agent from the main wallet
* [Prepared-step simulation](/celina-sdk/guides/prepared-step-simulation.md)
* [wagmi integration](/celina-sdk/guides/wagmi-integration.md)
* [Prepared flows](/celina-sdk/concepts/prepared-flows.md)
* [GovernanceService API](/celina-sdk/services/governanceservice.md)


---

# 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://andrewkimjoseph.gitbook.io/celina-sdk/guides/governance.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.