Skip to main content
FlowGuard governance uses token-locked voting. Voters lock CashTokens into a vote-lock covenant for the duration of the voting period. After voting ends, they unlock and reclaim their tokens.

​
List Vault Proposals

GET /api/vaults/:vaultId/governance?status=ACTIVE
Returns all governance proposals for the vault. Optionally filter by status.

​
Create Proposal

POST /api/vaults/:vaultId/governance
x-user-address: bchtest:q...

{
  "title": "Increase executor reward to 0.01 BCH",
  "description": "Full rationale here",
  "quorum": 1000,
  "votingDurationDays": 7
}
Creates a proposal with status: ACTIVE. Voting opens immediately and closes after votingDurationDays. Response — 201 
{
  "id": "...",
  "vaultId": "hex32",
  "title": "...",
  "status": "ACTIVE",
  "votesFor": 0,
  "votesAgainst": 0,
  "votesAbstain": 0,
  "quorum": 1000,
  "votingEndsAt": "2026-03-03T00:00:00Z"
}

​
Get Proposal

GET /api/governance/:proposalId
Returns the proposal with full vote breakdown (all governance_votes rows).

​
Cast Off-chain Vote

POST /api/governance/:proposalId/vote
x-user-address: bchtest:q...

{
  "vote": "FOR",
  "weight": 500
}
Records a lightweight off-chain vote and updates the tally. Valid values: FOR, AGAINST, ABSTAIN.
For the full on-chain token-lock flow, use /lock and /confirm-lock instead.

​
Lock Tokens (On-chain Vote)

POST /api/governance/:proposalId/lock

{
  "voterAddress": "bchtest:qr...",
  "voteChoice": "FOR",
  "stakeAmount": 1000,
  "tokenCategory": "hex32"
}
Deploys a VoteLockCovenant and returns a wcTransaction for the voter to sign and fund with their CashTokens. Response 
{
  "success": true,
  "deployment": {
    "contractAddress": "bchtest:p...",
    "voteId": "hex32",
    "constructorParams": [...],
    "initialCommitment": "hex..."
  },
  "wcTransaction": { ... }
}

​
Confirm Lock

POST /api/governance/:proposalId/confirm-lock

{
  "voterAddress": "bchtest:q...",
  "voteChoice": "FOR",
  "weight": 1000,
  "txHash": "hex64",
  "contractAddress": "bchtest:p...",
  "voteId": "hex32",
  "constructorParams": [...],
  "nftCommitment": "hex..."
}
Verifies the vote-lock covenant output on-chain, records the vote in the database, and updates the tally.

​
Unlock Tokens

POST /api/governance/:proposalId/unlock

{
  "voterAddress": "bchtest:q...",
  "tokenCategory": "hex32"
}
Builds the unlock wcTransaction after the voting period ends. Uses the stored contract_address and constructor_params from the voter’s lock record. Response 
{
  "success": true,
  "unlockTransaction": {
    "unlockedAmount": 1000,
    "wcTransaction": { ... }
  }
}

​
Confirm Unlock

POST /api/governance/:proposalId/confirm-unlock

{
  "voterAddress": "bchtest:q...",
  "txHash": "hex64"
}
Verifies the voter received their tokens back and marks the unlock complete.