> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankarachain.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pool Vault Governance

> Optional token-weighted governance mode for pool-vault — proposals, share-weighted voting and timelocked execution on Stellar.

By default, a `pool-vault` is run by whoever holds its Manager role: fee, oracle and
accepted-token changes are single-key decisions. That suits most operator-run funds.
For **cooperative- or community-owned** pools, such as a farming cooperative's fund or a
community investment group, the vault can instead be run by its share holders.
Governance mode is Stellar-only.

## Opting in

Governance mode is chosen at deployment and is **one-way**:

```ts theme={null}
const { contractAddress } = await factory.deployPoolVault({
  name: "Kaduna Farmers Coop Fund", symbol: "KFCF", assetId: "KFCF-2026", countryCode: "NG",
  governance: {
    votingPeriod: 3n * 86400n,   // voting open for 3 days
    timelock: 2n * 86400n,       // then 2 days before it can execute
    quorumBps: 2_000,            // ≥ 20% of shares must vote
    proposalThresholdBps: 100,   // ≥ 1% of shares to propose
  },
});
```

On-chain this calls `multi-token-factory::deploy_governed_pool_vault`, which uses
`pool-vault::initialize_governed`. An existing vault's Manager can also call
`enable_governance(config)` once. **Vaults that never opt in behave exactly as before.**

## What changes in governance mode

These actions can then **only** happen through a passed proposal:

| Action | Proposal |
| - | - |
| Change the management fee | `SetManagementFeeBps(bps)` |
| Change the price oracle | `SetOracle(address)` |
| Add / remove an accepted token | `AddAcceptedToken(token, weight_bps)` / `RemoveAcceptedToken(token)` |
| Change a minimum deposit | `SetMinDeposit(token, amount)` |
| Upgrade the contract | `Upgrade(wasm_hash)` |

Calling the direct Manager setters, or `upgrade`, reverts. Direct `mint` of pool shares
is disabled too, so no single key can create voting power.

## Lifecycle

1. **Propose**: `propose(proposer, action)`. The proposer must hold at least
   `proposal_threshold_bps` of supply. The quorum is fixed at creation from the total
   supply at that moment.
2. **Vote**: `vote(voter, id, support)`. Each vote is weighted by the voter's share
   balance. Those shares are **locked** until voting ends: they can't be transferred,
   burned or withdrawn, so the same shares can't vote twice from another address. A voter
   can vote once per proposal.
3. **Outcome**: after `voting_period`, a proposal passes if `for > against` and
   `for + against ≥ quorum`.
4. **Timelock**: a passed proposal is `Queued` for `timelock` seconds. Holders who
   disagree can withdraw during this window.
5. **Execute**: anyone calls `execute(id)`.

The proposer can `cancel_proposal` while voting is open. `proposal_state(id)` returns
`Active | Defeated | Queued | Executable | Executed | Cancelled`.

```ts theme={null}
import { PoolGovernance } from "@ankarachain/sdk";

const gov = new PoolGovernance(memberAdapter, VAULT);
const { proposalId } = await gov.propose({ kind: "set-management-fee-bps", feeBps: 25 });
await gov.vote(proposalId, true);
// …3 days of voting + 2 days of timelock later, anyone:
if ((await gov.getState(proposalId)) === "executable") await gov.execute(proposalId);
```

<Note>
  Operational roles stay with their holders in governance mode: pausing (`Pauser`), asset
  status and the identity verifier (`Manager`). If your community wants those governed too,
  assign the roles to a multisig held by elected stewards.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.