governance 0.1.0

Governance and voting system for Neural Trader - proposal management, voting mechanisms, and consensus protocols
Documentation 
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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# Governance Crate

A comprehensive governance system for decentralized decision-making in the Neural Trader platform.

## Features

### 🗳️ Proposal Management
- **Multiple Proposal Types**:
  - Parameter Changes
  - Strategy Approvals
  - Risk Limit Adjustments
  - Emergency Actions
  - Treasury Allocations
  - Member Management

- **Proposal States**: Draft, Active, Passed, Rejected, Executed, Expired, Vetoed
- **Metadata Tracking**: Title, description, proposer, timestamps

### 👥 Member Management
- **Role-Based Access Control**:
  - **Admin**: Full proposal, voting, and execution rights
  - **Guardian**: Can veto proposals, full voting rights
  - **Member**: Can propose and vote
  - **Observer**: Read-only access

- **Voting Power**: Stake-based or role-based weighting
- **Reputation System**: Automatic reputation tracking based on participation
- **Delegation**: Members can delegate voting power to others

### 🗳️ Voting Mechanisms
- **Vote Types**: For, Against, Abstain
- **Weighted Voting**: Voting power based on stake/shares/reputation
- **Quorum Requirements**: Minimum participation threshold
- **Passing Threshold**: Configurable approval percentage (e.g., 66%)
- **Vote Delegation**: Transfer voting power to trusted members

### ⚙️ Execution System
- **Automatic Execution**: Execute proposals after passing
- **Time-Locked Execution**: Delay period before execution
- **Veto Mechanism**: Guardian/admin override capability
- **Execution Validation**: Verify proposal state and permissions

### 💰 Treasury Integration
- **Budget Allocation**: Governance-controlled fund allocation
- **Fund Withdrawal**: Multi-signature treasury access
- **Emergency Fund**: Reserved funds for critical situations
- **Transaction History**: Complete audit trail

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
governance = { path = "../governance" }
rust_decimal = "1.33"
```

## Quick Start

```rust
use governance::{GovernanceSystem, types::*};
use rust_decimal::Decimal;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create governance system with configuration
    let mut config = GovernanceConfig::default();
    config.quorum_percentage = Decimal::from(50);  // 50% participation
    config.passing_threshold = Decimal::from(66);  // 66% approval
    config.voting_period_seconds = 604800;         // 7 days

    let governance = GovernanceSystem::new(config);

    // 2. Register members
    governance.register_member(
        "alice".to_string(),
        Role::Admin,
        Decimal::from(100)
    )?;

    governance.register_member(
        "bob".to_string(),
        Role::Member,
        Decimal::from(150)
    )?;

    // 3. Create a proposal
    let proposal_id = governance.create_proposal(
        "Increase Risk Limit".to_string(),
        "Proposal to increase daily VaR limit from $50k to $75k".to_string(),
        ProposalType::RiskLimitAdjustment {
            limit_type: "daily_var".to_string(),
            old_limit: Decimal::from(50000),
            new_limit: Decimal::from(75000),
        },
        "alice".to_string(),
    )?;

    // 4. Cast votes
    governance.vote(&proposal_id, "alice", VoteType::For, None)?;
    governance.vote(&proposal_id, "bob", VoteType::For, None)?;

    // 5. Wait for voting period to end...

    // 6. Finalize voting
    governance.finalize_voting(&proposal_id)?;

    // 7. Execute if passed
    let result = governance.execute_proposal(&proposal_id, "alice")?;
    println!("Executed: {}", result.message);

    Ok(())
}
```

## Examples

Run the comprehensive demo:

```bash
cargo run --example governance_demo
```

## Testing

Run the test suite:

```bash
# All tests (20+ tests)
cargo test -p governance

# Specific test files
cargo test -p governance --test proposal_tests
cargo test -p governance --test voting_tests
cargo test -p governance --test integration_tests
```

## Documentation

For complete API documentation and advanced usage, see the inline documentation:

```bash
cargo doc -p governance --open
```

## License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.