aitbc/docs/governance.md

Governance Module

The AITBC governance module enables decentralized decision-making through proposal voting and parameter changes.

Overview

The governance system allows AITBC token holders to:

• Create proposals for protocol changes
• Vote on active proposals
• Execute approved proposals
• Track governance history

API Endpoints

Get Governance Parameters

Retrieve current governance system parameters.

GET /api/v1/governance/parameters

Response:

{
  "min_proposal_voting_power": 1000,
  "max_proposal_title_length": 200,
  "max_proposal_description_length": 5000,
  "default_voting_period_days": 7,
  "max_voting_period_days": 30,
  "min_quorum_threshold": 0.01,
  "max_quorum_threshold": 1.0,
  "min_approval_threshold": 0.01,
  "max_approval_threshold": 1.0,
  "execution_delay_hours": 24
}

List Proposals

Get a list of governance proposals.

GET /api/v1/governance/proposals?status={status}&limit={limit}&offset={offset}

Query Parameters:

• status (optional): Filter by proposal status (active, passed, rejected, executed)
• limit (optional): Number of proposals to return (default: 20)
• offset (optional): Number of proposals to skip (default: 0)

Response:

[
  {
    "id": "proposal-uuid",
    "title": "Proposal Title",
    "description": "Description of the proposal",
    "type": "parameter_change",
    "target": {},
    "proposer": "user-address",
    "status": "active",
    "created_at": "2025-12-28T18:00:00Z",
    "voting_deadline": "2025-12-28T18:00:00Z",
    "quorum_threshold": 0.1,
    "approval_threshold": 0.5,
    "current_quorum": 0.15,
    "current_approval": 0.75,
    "votes_for": 150,
    "votes_against": 50,
    "votes_abstain": 10,
    "total_voting_power": 1000000
  }
]

Create Proposal

Create a new governance proposal.

POST /api/v1/governance/proposals

Request Body:

{
  "title": "Reduce Transaction Fees",
  "description": "This proposal suggests reducing transaction fees...",
  "type": "parameter_change",
  "target": {
    "fee_percentage": "0.05"
  },
  "voting_period": 7,
  "quorum_threshold": 0.1,
  "approval_threshold": 0.5
}

Fields:

• title: Proposal title (10-200 characters)
• description: Detailed description (50-5000 characters)
• type: Proposal type (parameter_change, protocol_upgrade, fund_allocation, policy_change)
• target: Target configuration for the proposal
• voting_period: Voting period in days (1-30)
• quorum_threshold: Minimum participation percentage (0.01-1.0)
• approval_threshold: Minimum approval percentage (0.01-1.0)

Get Proposal

Get details of a specific proposal.

GET /api/v1/governance/proposals/{proposal_id}

Submit Vote

Submit a vote on a proposal.

POST /api/v1/governance/vote

Request Body:

{
  "proposal_id": "proposal-uuid",
  "vote": "for",
  "reason": "I support this change because..."
}

Fields:

• proposal_id: ID of the proposal to vote on
• vote: Vote option (for, against, abstain)
• reason (optional): Reason for the vote (max 500 characters)

Get Voting Power

Check a user's voting power.

GET /api/v1/governance/voting-power/{user_id}

Response:

{
  "user_id": "user-address",
  "voting_power": 10000
}

Execute Proposal

Execute an approved proposal.

POST /api/v1/governance/execute/{proposal_id}

Note: Proposals can only be executed after:

1. Voting period has ended
2. Quorum threshold is met
3. Approval threshold is met
4. 24-hour execution delay has passed

Proposal Types

Parameter Change

Modify system parameters like fees, limits, or thresholds.

Example Target:

{
  "transaction_fee": "0.05",
  "min_stake_amount": "1000",
  "max_block_size": "2000"
}

Protocol Upgrade

Initiate a protocol upgrade with version changes.

Example Target:

{
  "version": "1.2.0",
  "upgrade_type": "hard_fork",
  "activation_block": 1000000,
  "changes": {
    "new_features": ["feature1", "feature2"],
    "breaking_changes": ["change1"]
  }
}

Fund Allocation

Allocate funds from the treasury.

Example Target:

{
  "amount": "1000000",
  "recipient": "0x123...",
  "purpose": "Ecosystem development fund",
  "milestones": [
    {
      "description": "Phase 1 development",
      "amount": "500000",
      "deadline": "2025-06-30"
    }
  ]
}

Policy Change

Update governance or operational policies.

Example Target:

{
  "policy_name": "voting_period",
  "new_value": "14 days",
  "rationale": "Longer voting period for better participation"
}

Voting Process

1. Proposal Creation: Any user with sufficient voting power can create a proposal
2. Voting Period: Token holders vote during the specified voting period
3. Quorum Check: Minimum participation must be met
4. Approval Check: Minimum approval ratio must be met
5. Execution Delay: 24-hour delay before execution
6. Execution: Approved changes are implemented

Database Schema

GovernanceProposal

• id: Unique proposal identifier
• title: Proposal title
• description: Detailed description
• type: Proposal type
• target: Target configuration (JSON)
• proposer: Address of the proposer
• status: Current status
• created_at: Creation timestamp
• voting_deadline: End of voting period
• quorum_threshold: Minimum participation required
• approval_threshold: Minimum approval required
• executed_at: Execution timestamp
• rejection_reason: Reason for rejection

ProposalVote

• id: Unique vote identifier
• proposal_id: Reference to proposal
• voter_id: Address of the voter
• vote: Vote choice (for/against/abstain)
• voting_power: Power at time of vote
• reason: Vote reason
• voted_at: Vote timestamp

TreasuryTransaction

• id: Unique transaction identifier
• proposal_id: Reference to proposal
• from_address: Source address
• to_address: Destination address
• amount: Transfer amount
• status: Transaction status
• transaction_hash: Blockchain hash

Security Considerations

1. Voting Power: Based on AITBC token holdings
2. Double Voting: Prevented by tracking voter addresses
3. Execution Delay: Prevents rush decisions
4. Quorum Requirements: Ensures sufficient participation
5. Proposal Thresholds: Prevents spam proposals

Integration Guide

Frontend Integration

// Fetch proposals
const response = await fetch('/api/v1/governance/proposals');
const proposals = await response.json();

// Submit vote
await fetch('/api/v1/governance/vote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    proposal_id: 'uuid',
    vote: 'for',
    reason: 'Support this proposal'
  })
});

Smart Contract Integration

The governance system can be integrated with smart contracts for:

• On-chain voting
• Automatic execution
• Treasury management
• Parameter enforcement

Best Practices

1. Clear Proposals: Provide detailed descriptions and rationales
2. Reasonable Thresholds: Set achievable quorum and approval thresholds
3. Community Discussion: Use forums for proposal discussion
4. Gradual Changes: Implement major changes in phases
5. Monitoring: Track proposal outcomes and system impact

Future Enhancements

1. Delegated Voting: Allow users to delegate voting power
2. Quadratic Voting: Implement more sophisticated voting mechanisms
3. Time-locked Voting: Lock tokens for voting power boosts
4. Multi-sig Execution: Require multiple signatures for execution
5. Proposal Templates: Standardize proposal formats

Support

For governance-related questions:

• Check the API documentation
• Review proposal history
• Contact the governance team
• Participate in community discussions