```
chore: refactor logging module, update genesis timestamp, remove model relationships, and reorganize routers - Rename logging.py to logger.py and update import paths in poa.py and main.py - Update devnet genesis timestamp to 1766828620 - Remove SQLModel Relationship declarations from Block, Transaction, and Receipt models - Add SessionDep type alias and get_session dependency in coordinator-api deps - Reorganize coordinator-api routers: replace explorer/registry with exchange, users, marketplace
This commit is contained in:
oib
333
docs/governance.md
Normal file
333
docs/governance.md
Normal file
@ -0,0 +1,333 @@
|
||||
# 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.
|
||||
|
||||
```http
|
||||
GET /api/v1/governance/parameters
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```http
|
||||
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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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.
|
||||
|
||||
```http
|
||||
POST /api/v1/governance/proposals
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```http
|
||||
GET /api/v1/governance/proposals/{proposal_id}
|
||||
```
|
||||
|
||||
### Submit Vote
|
||||
|
||||
Submit a vote on a proposal.
|
||||
|
||||
```http
|
||||
POST /api/v1/governance/vote
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```http
|
||||
GET /api/v1/governance/voting-power/{user_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"user_id": "user-address",
|
||||
"voting_power": 10000
|
||||
}
|
||||
```
|
||||
|
||||
### Execute Proposal
|
||||
|
||||
Execute an approved proposal.
|
||||
|
||||
```http
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"transaction_fee": "0.05",
|
||||
"min_stake_amount": "1000",
|
||||
"max_block_size": "2000"
|
||||
}
|
||||
```
|
||||
|
||||
### Protocol Upgrade
|
||||
Initiate a protocol upgrade with version changes.
|
||||
|
||||
**Example Target:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
Reference in New Issue
Block a user