Community & governance

Architecture and responsibilities

1. 01

   Proposal and voting interface

   Collect target, amount and dates and display a readable view of the execution data.

   Web UI / Wallet
2. 02

   Voting power and rules

   Configure voting tokens, delegation, thresholds and quorum.

   IVotes / Weight strategy
3. 03

   Proposal lifecycle

   Manage proposal IDs, voting windows, results and state.

   GenericGovernorHelper
4. 04

   Delayed execution

   Timelock calls the target contract after the delay.

   TimelockController / Target contract

Example data model

Map application records to the data managed by the chain or APIs. Field names and values below illustrate the application model for this architecture.

Processing flow

1. 1

   Prepare governance and the budget

   Connect Governor, Timelock, an IVotes token and a weight strategy. The executing Timelock must hold the budget tokens and any required permissions.

   GenericGovernor / TimelockController / IVotes
2. 2

   Include the exact action in the proposal

   Encode the recipient and 100 units as an ERC-20 transfer, then propose it with a voting window and description. Display the token, recipient and display amount, not only encoded bytes.

   Interface.encodeFunctionData → governor.propose
3. 3

   Collect votes

   Eligible members vote while the proposal is Active. For ERC20Votes configurations, check delegation and historical voting power; current holdings alone may not establish voting power.

   state(proposalId) / castVote(proposalId, 1)
4. 4

   Queue a successful proposal

   Queue after voting ends successfully. Approval, Queued and Executed are distinct states. Enable actions based on state, including defeated or canceled outcomes.

   queue(proposalId) → Timelock delay
5. 5

   Execute after the delay

   Once the Timelock operation is Ready, an authorized executor calls execute. After confirmation, check the recipient’s balance and execution event and update the proposal view.

   Timelock.isOperationReady / governor.execute(proposalId)

Before using the code

• Deploy Governor, Timelock, voting token and weight strategy, then configure roles for proposals, queueing and execution.
• Timelock must hold the budget tokens. Transfers must satisfy transferability, pause and allowlist conditions.
• Use UNIX seconds based on the target chain’s clock. The end must follow the start and respect the allowed voting window.

npm install --save-exact @hazbase/kit@0.9.0 ethers@6.16.0

The TypeScript functions below are called from your application with the appropriate connections, permissions and data. Integrate the UI, persistence and recovery using the architecture above.

Propose a 100-unit allocation

Pass units: "100" to encode the allocation using the budget token’s decimals. This function creates the proposal; voting, queueing and execution are separate operations at later states.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

import { GenericGovernorHelper, FlexibleTokenHelper } from '@hazbase/kit';
import { Interface, parseUnits } from 'ethers';
type Signer = Parameters<typeof GenericGovernorHelper.deploy>[1];

export async function proposeCommunityGrant(input: {
  governorAddress: string;
  budgetTokenAddress: string;
  recipient: string;
  units: string;
  description: string;
  startTs: bigint;
  endTs: bigint;
  proposer: Signer;
}) {
  const governor = GenericGovernorHelper.attach(input.governorAddress, input.proposer);
  const token = FlexibleTokenHelper.attach(input.budgetTokenAddress, input.proposer);
  const amount = parseUnits(input.units, await token.decimals());
  if (amount <= 0n) throw new Error('Grant must be positive.');
  const erc20 = new Interface(['function transfer(address to, uint256 amount)']);

  // At execution, Timelock must hold the budget tokens being transferred.
  const proposalId = await governor.propose({
    proposer: await input.proposer.getAddress(),
    targets: [input.budgetTokenAddress],
    values: [0n],
    calldatas: [erc20.encodeFunctionData('transfer', [input.recipient, amount])],
    description: input.description,
    startTs: input.startTs,
    endTs: input.endTs,
  });

  // Voting, queueing and execution are separate actions at later states.
  return { proposalId: proposalId.toString(), state: await governor.state(proposalId) };
}

Implementation considerations

Extending the architecture

Related API and SDK reference