From fe42c6005d9611b338ed4a5e33d69e02bf96fae9 Mon Sep 17 00:00:00 2001
From: sourcebridge_42 <sourcebridge_42@agents.chunk.local>
Date: Sun, 19 Apr 2026 09:10:09 +0000
Subject: [PATCH] docs: add documentation for GovernanceContract.sol

---
 docs/GovernanceContract.md | 78 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/GovernanceContract.md

diff --git a/docs/GovernanceContract.md b/docs/GovernanceContract.md
new file mode 100644
index 0000000..617acf7
--- /dev/null
+++ b/docs/GovernanceContract.md
@@ -0,0 +1,78 @@
+## Overview
+The GovernanceContract is a decentralized governance mechanism for managing community proposals and voting processes on the ChunkNet blockchain. It provides a transparent, secure method for community members to create, vote on, and finalize governance proposals.
+
+## Interface
+
+| Function | Parameters | Returns | Description |
+|----------|------------|---------|-------------|
+| `createProposal` | `string _description` | `uint256` | Create a new governance proposal |
+| `vote` | `uint256 _proposalId, bool _support` | `void` | Cast a vote on an active proposal |
+| `finalizeProposal` | `uint256 _proposalId` | `void` | Conclude voting and determine proposal status |
+| `getProposalDetails` | `uint256 _proposalId` | `Proposal` | Retrieve detailed information about a specific proposal |
+
+## Events
+
+- `ProposalCreated`: Emitted when a new proposal is created
+- `ProposalVoted`: Triggered when a community member votes
+- `ProposalStatusChanged`: Signals changes in proposal status
+
+## Storage Layout
+
+- `proposals`: Mapping of proposal IDs to Proposal structs
+- `proposalCount`: Total number of proposals created
+- `votingContract`: Reference to the VotingContract for voting power calculations
+- Constant parameters:
+  - `VOTING_PERIOD`: 7 days
+  - `QUORUM_PERCENTAGE`: 30%
+  - `PASS_THRESHOLD_PERCENTAGE`: 50%
+
+## Access Control
+
+- Proposal creation: Open to all registered community members
+- Voting: Restricted to members with valid voting power
+- Proposal finalization: Can be called by any participant after voting period ends
+
+## Security Considerations
+
+- Prevents double voting through `hasVoted` mapping
+- Uses voting power from external VotingContract
+- Implements time-based voting restrictions
+- Requires quorum and pass threshold for proposal validation
+- Prevents proposal manipulation through cryptographic hashing
+
+## Deployment
+
+**Blockchain Environment**:
+- RPC URL: https://rpc.chunknet.org
+- Chain ID: 214562
+- Network: ChunkNet DevNet
+
+**Deployment Steps**:
+1. Deploy VotingContract first
+2. Pass VotingContract address to GovernanceContract constructor
+3. Verify contract parameters
+4. Set appropriate access controls
+
+**Recommended Deployment Configuration**:
+bash
+forge create GovernanceContract \
+  --rpc-url https://rpc.chunknet.org \
+  --private-key $DEPLOYER_PRIVATE_KEY \
+  --constructor-args $VOTING_CONTRACT_ADDRESS
+
+
+## Testing
+
+Test cases should cover:
+- Proposal creation validation
+- Voting mechanism
+- Quorum and threshold calculations
+- Proposal status transitions
+- Edge cases and potential attack vectors
+
+Recommended test scenarios:
+- Create proposal with empty description
+- Vote before and after voting period
+- Test voting power calculations
+- Validate proposal finalization logic
+- Check event emissions
\ No newline at end of file