Add comprehensive governance system implementation

- Create bitcell-governance crate with full implementation
- Implement proposal system (parameter changes, treasury, upgrades)
- Implement token-weighted voting (linear and quadratic)
- Implement delegation system
- Implement type-specific timelock delays
- Implement multi-sig guardian controls
- Add 20+ comprehensive unit tests
- Add integration tests
- Add benchmarks
- Create documentation (GOVERNANCE.md and README.md)

Co-authored-by: Steake <530040+Steake@users.noreply.github.com>

Author: Copilot

Cargo.toml

@@ -16,6 +16,7 @@ members = [
     "crates/bitcell-wallet-gui",
     "crates/bitcell-compiler",
     "crates/bitcell-light-client",
+    "crates/bitcell-governance",
 ]
 resolver = "2"
 

crates/bitcell-governance/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "bitcell-governance"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+bitcell-crypto = { path = "../bitcell-crypto" }
+bitcell-state = { path = "../bitcell-state" }
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+bincode.workspace = true
+tracing.workspace = true
+hex.workspace = true
+sha2.workspace = true
+
+[dev-dependencies]
+proptest.workspace = true
+criterion.workspace = true
+tempfile = "3.23.0"
+
+[[bench]]
+name = "governance_bench"
+harness = false

crates/bitcell-governance/README.md

@@ -0,0 +1,152 @@
+# BitCell Governance
+
+On-chain governance system for the BitCell blockchain.
+
+## Overview
+
+The governance system enables decentralized decision-making for protocol parameters, treasury spending, and protocol upgrades. It implements token-weighted voting with delegation support and guardian emergency controls.
+
+## Features
+
+- **Proposal System**: Submit and vote on three types of proposals:
+  - Parameter changes (e.g., max block size, minimum stake)
+  - Treasury spending (allocate funds from protocol treasury)
+  - Protocol upgrades (deploy new protocol versions)
+
+- **Voting Methods**:
+  - Linear voting: 1 CELL = 1 vote
+  - Quadratic voting: sqrt(CELL) = votes (Sybil-resistant)
+
+- **Delegation**: Delegate your voting power to trusted representatives
+
+- **Timelock Protection**:
+  - Parameter changes: 2-day delay
+  - Protocol upgrades: 2-day delay
+  - Treasury spending: 6-hour delay
+
+- **Guardian Controls**: 2-of-3 multi-sig for emergency actions
+  - Cancel malicious proposals
+  - Execute critical upgrades immediately
+
+## Quick Start
+
+```rust
+use bitcell_governance::{GovernanceManager, ProposalType, VotingMethod, GuardianSet};
+
+// Create governance manager
+let mut gov = GovernanceManager::new();
+
+// Submit a proposal
+let proposer = [1u8; 33];
+let proposal_id = gov.submit_proposal(
+    proposer,
+    ProposalType::ParameterChange {
+        parameter: "max_block_size".to_string(),
+        new_value: "2000000".to_string(),
+    },
+    "Increase max block size to 2MB".to_string(),
+    current_timestamp,
+)?;
+
+// Vote on the proposal
+let voter = [2u8; 33];
+let voting_power = 10000 * 100_000_000; // 10,000 CELL
+gov.vote(proposal_id, voter, true, voting_power, current_timestamp)?;
+
+// Finalize after timelock expires
+let passed = gov.finalize_proposal(proposal_id, current_timestamp + (2 * 24 * 60 * 60))?;
+
+if passed {
+    println!("Proposal passed!");
+}
+```
+
+## Delegation
+
+```rust
+// Delegate voting power
+let delegator = [1u8; 33];
+let delegatee = [2u8; 33];
+let amount = 5000 * 100_000_000; // 5,000 CELL
+
+gov.delegate(delegator, delegatee, amount)?;
+
+// Delegatee now has additional voting power
+let total_power = gov.get_voting_power(&delegatee, base_power);
+```
+
+## Guardian Override
+
+```rust
+use bitcell_governance::{Guardian, GuardianAction};
+
+// Setup guardians
+let guardians = GuardianSet::with_guardians(vec![
+    Guardian {
+        pubkey: [1u8; 33],
+        name: "Guardian 1".to_string(),
+        added_at: timestamp,
+    },
+    Guardian {
+        pubkey: [2u8; 33],
+        name: "Guardian 2".to_string(),
+        added_at: timestamp,
+    },
+    Guardian {
+        pubkey: [3u8; 33],
+        name: "Guardian 3".to_string(),
+        added_at: timestamp,
+    },
+]);
+
+// Emergency cancel (requires 2/3 signatures)
+let signatures = vec![signature1, signature2]; // 64-byte signatures
+gov.guardian_override(proposal_id, GuardianAction::Cancel, signatures)?;
+```
+
+## Configuration
+
+```rust
+use bitcell_governance::{GovernanceConfig, VotingMethod, GuardianThreshold, TimelockConfig};
+
+let config = GovernanceConfig {
+    quorum: 10_000 * 100_000_000, // 10,000 CELL minimum
+    voting_method: VotingMethod::Quadratic,
+    guardian_threshold: GuardianThreshold {
+        required: 2,
+        total: 3,
+    },
+    timelock: TimelockConfig {
+        parameter_change_delay: 2 * 24 * 60 * 60,  // 2 days
+        treasury_spending_delay: 6 * 60 * 60,       // 6 hours
+        protocol_upgrade_delay: 2 * 24 * 60 * 60,   // 2 days
+    },
+};
+
+let gov = GovernanceManager::with_config(config, guardians);
+```
+
+## Security Features
+
+- **Overflow Protection**: All arithmetic uses saturating operations
+- **Collision Resistance**: Proposal IDs use SHA-256 hashing
+- **Double-Vote Prevention**: Each address can only vote once per proposal
+- **Quadratic Voting**: Reduces influence of large token holders
+- **Timelock Delays**: Prevent hasty or malicious changes
+- **Guardian Multi-sig**: Emergency response capability
+
+## Testing
+
+```bash
+cargo test -p bitcell-governance
+```
+
+## Benchmarks
+
+```bash
+cargo bench -p bitcell-governance
+```
+
+## License
+
+MIT OR Apache-2.0

crates/bitcell-governance/benches/governance_bench.rs

@@ -0,0 +1,179 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use bitcell_governance::*;
+
+const CELL: u64 = 100_000_000;
+
+fn bench_submit_proposal(c: &mut Criterion) {
+    c.bench_function("submit_proposal", |b| {
+        let mut gov = GovernanceManager::new();
+        let mut counter = 0u64;
+        
+        b.iter(|| {
+            counter += 1;
+            gov.submit_proposal(
+                black_box([1u8; 33]),
+                black_box(ProposalType::ParameterChange {
+                    parameter: format!("param_{}", counter),
+                    new_value: "value".to_string(),
+                }),
+                black_box(format!("Proposal {}", counter)),
+                black_box(counter),
+            ).unwrap()
+        });
+    });
+}
+
+fn bench_vote_linear(c: &mut Criterion) {
+    c.bench_function("vote_linear", |b| {
+        let mut gov = GovernanceManager::new();
+        let proposal_id = gov.submit_proposal(
+            [1u8; 33],
+            ProposalType::ParameterChange {
+                parameter: "test".to_string(),
+                new_value: "value".to_string(),
+            },
+            "Test".to_string(),
+            1000,
+        ).unwrap();
+        
+        let mut voter_counter = 2u8;
+        
+        b.iter(|| {
+            voter_counter = voter_counter.wrapping_add(1);
+            let voter = [voter_counter; 33];
+            gov.vote(
+                black_box(proposal_id),
+                black_box(voter),
+                black_box(true),
+                black_box(1000 * CELL),
+                black_box(1100),
+            ).unwrap()
+        });
+    });
+}
+
+fn bench_vote_quadratic(c: &mut Criterion) {
+    c.bench_function("vote_quadratic", |b| {
+        let config = GovernanceConfig {
+            voting_method: VotingMethod::Quadratic,
+            ..Default::default()
+        };
+        let mut gov = GovernanceManager::with_config(config, GuardianSet::new());
+        
+        let proposal_id = gov.submit_proposal(
+            [1u8; 33],
+            ProposalType::ParameterChange {
+                parameter: "test".to_string(),
+                new_value: "value".to_string(),
+            },
+            "Test".to_string(),
+            1000,
+        ).unwrap();
+        
+        let mut voter_counter = 2u8;
+        
+        b.iter(|| {
+            voter_counter = voter_counter.wrapping_add(1);
+            let voter = [voter_counter; 33];
+            gov.vote(
+                black_box(proposal_id),
+                black_box(voter),
+                black_box(true),
+                black_box(10000 * CELL),
+                black_box(1100),
+            ).unwrap()
+        });
+    });
+}
+
+fn bench_delegation(c: &mut Criterion) {
+    c.bench_function("delegate", |b| {
+        let mut gov = GovernanceManager::new();
+        let delegatee = [2u8; 33];
+        let mut delegator_counter = 3u8;
+        
+        b.iter(|| {
+            delegator_counter = delegator_counter.wrapping_add(1);
+            let delegator = [delegator_counter; 33];
+            gov.delegate(
+                black_box(delegator),
+                black_box(delegatee),
+                black_box(1000 * CELL),
+            ).unwrap()
+        });
+    });
+}
+
+fn bench_get_voting_power(c: &mut Criterion) {
+    c.bench_function("get_voting_power", |b| {
+        let mut gov = GovernanceManager::new();
+        let delegatee = [2u8; 33];
+        
+        // Add some delegations
+        for i in 0..10 {
+            gov.delegate([i; 33], delegatee, 1000 * CELL).unwrap();
+        }
+        
+        b.iter(|| {
+            gov.get_voting_power(
+                black_box(&delegatee),
+                black_box(5000 * CELL),
+            )
+        });
+    });
+}
+
+fn bench_finalize_proposal(c: &mut Criterion) {
+    c.bench_function("finalize_proposal", |b| {
+        b.iter_batched(
+            || {
+                let mut gov = GovernanceManager::new();
+                let proposal_id = gov.submit_proposal(
+                    [1u8; 33],
+                    ProposalType::TreasurySpending {
+                        recipient: [2u8; 33],
+                        amount: 1000 * CELL,
+                        reason: "Test".to_string(),
+                    },
+                    "Test".to_string(),
+                    1000,
+                ).unwrap();
+                
+                // Vote with quorum
+                gov.vote(proposal_id, [2u8; 33], true, 15000 * CELL, 1100).unwrap();
+                
+                (gov, proposal_id)
+            },
+            |(mut gov, proposal_id)| {
+                gov.finalize_proposal(
+                    black_box(proposal_id),
+                    black_box(1000 + 6 * 60 * 60 + 1),
+                ).unwrap()
+            },
+            criterion::BatchSize::SmallInput,
+        );
+    });
+}
+
+fn bench_integer_sqrt(c: &mut Criterion) {
+    c.bench_function("integer_sqrt", |b| {
+        b.iter(|| {
+            // Test with various values
+            for n in [100, 10000, 1000000, 100000000u64] {
+                black_box(bitcell_governance::integer_sqrt(n));
+            }
+        });
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_submit_proposal,
+    bench_vote_linear,
+    bench_vote_quadratic,
+    bench_delegation,
+    bench_get_voting_power,
+    bench_finalize_proposal,
+    bench_integer_sqrt,
+);
+criterion_main!(benches);