From 717672c11d57125eb2bb00b87203fb8470efb009 Mon Sep 17 00:00:00 2001 From: ybtuti Date: Sun, 11 May 2025 13:19:37 +0300 Subject: [PATCH 1/2] Initialize ChamaDAO protocol documentation Transforms basic Foundry template into comprehensive documentation for ChamaDAO protocol. Includes: - Detailed architecture overview and contract relationships - Implementation details for Chama, Contributions, and Loans contracts - Development setup and workflow guides - Security considerations and governance structure - Mermaid diagrams for key protocol workflows - Testing and deployment instructions Documents core functionality for decentralized community savings groups --- README.md | 315 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 279 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index a98f554..c5f25a9 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,309 @@ -## Foundry +# ChamaDAO Contracts -**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.** +A decentralized protocol that implements traditional community-based "Chama" savings groups on-chain. -Foundry consists of: +## Overview -- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools). -- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data. -- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network. -- **Chisel**: Fast, utilitarian, and verbose solidity REPL. +ChamaDAO is a blockchain protocol that digitizes traditional Chama savings groups – community-based financing systems common in Africa where members regularly contribute funds to a collective pool and take turns receiving the pooled amount. The protocol extends this concept with additional DeFi capabilities including decentralized governance, transparent fund management, and on-chain lending. -## Documentation +## 📋 Table of Contents -https://book.getfoundry.sh/ +- Architecture +- Contract Relationships +- Key Features +- Development Setup +- Contract Documentation + - Chama Factory + - Contributions + - Loans +- Function Workflows +- Development Guide +- Testing +- Deployment -## Usage +## Architecture -### Build +The ChamaDAO protocol is built with a modular architecture: -```shell -$ forge build ``` + ┌───────────────┐ + │ Chama.sol │ + │ (Factory) │ + └───────┬───────┘ + │ creates + ▼ +┌───────────────────────────────┐ +│ Contributions.sol │ +│ (Member & Round Management) │ +├───────────────────────────────┤ +│ Loans.sol │ +│ (Lending Functions) │ +└───────────────────────────────┘ +``` + +## Contract Relationships + +The ChamaDAO system consists of three main contracts: + +1. **Chama Contract** (Chama.sol): Factory contract that creates and manages Chama groups. +2. **Contributions Contract** (Contributions.sol): Manages member contributions, round processing, and inherits lending functionality. +3. **Loans Contract** (`Loans.sol`): Base contract that provides lending capabilities, inherited by Contributions. + +## Key Features + +- **Chama Group Creation**: Create named Chama groups with admin designation +- **Member Management**: Add or remove members from a Chama +- **Contribution Management**: Members can contribute funds to the Chama pool +- **Round Processing**: Automatic round management with epoch-based distribution +- **Lending Capabilities**: Members can request loans from the Chama pool +- **Role-Based Access**: Granular permissions using OpenZeppelin's AccessControl +- **Token Integration**: Support for ERC20 tokens as the contribution medium + +## Development Setup + +This project uses Foundry for Ethereum development. + +### Prerequisites + +- [Foundry](https://book.getfoundry.sh/getting-started/installation) + +### Installation + +1. Clone the repository + +```bash +git clone https://github.com/yourusername/chamadao-contracts.git +cd chamadao-contracts +``` + +2. Install dependencies + +```bash +forge install +``` + +3. Build the contracts + +```bash +forge build +``` + +## Contract Documentation -### Test +### Chama Factory -```shell -$ forge test +`Chama.sol` - Factory contract for creating and managing Chama groups. + +#### Key Functions + +```solidity +function createChama(address _admin, string memory _name, uint256 _interestRate) external returns (address) ``` -### Format +Creates a new Chama group with the specified admin, name, and interest rate. Returns the address of the deployed Contributions contract. -```shell -$ forge fmt +```solidity +function addMemberToChama(address _member, string memory _name) external onlyChamaAdmin(_name) ``` -### Gas Snapshots +Adds a member to an existing Chama group. Can only be called by the Chama admin. -```shell -$ forge snapshot +```solidity +function getChamaAddress(string memory _name) external view returns (address) ``` -### Anvil +Returns the contract address for a given Chama name. + +### Contributions + +`Contributions.sol` - Manages member contributions, round claiming, and member management. + +#### State Variables + +- `address public factoryContract`: The factory contract that created this Contributions instance +- `address private chamaAdmin`: The admin of this Chama group +- `uint256 public epochPeriod`: Time period of each contribution round (default: 30 days) +- `uint256 public currentRound`: Current round number +- `EnumerableSet.AddressSet private members`: Set of members in this Chama -```shell -$ anvil +#### Key Functions + +```solidity +function addContribution(uint256 _amount) external onlyRole(MEMBER_ROLE) ``` -### Deploy +Allows a member to add a contribution to the Chama pool. -```shell -$ forge script script/Counter.s.sol:CounterScript --rpc-url --private-key +```solidity +function claimRound() external nonReentrant onlyRole(MEMBER_ROLE) ``` -### Cast +Allows a member to claim the current round for all members, distributing funds according to the Chama model. Can only be called after the epoch period has ended. + +```solidity +function addMemberToChama(address _address) external onlyRole(CHAMA_ADMIN_ROLE) +``` + +Admin function to add a new member to the Chama. + +```solidity +function removeMemberFromChama(address _member) external onlyRole(CHAMA_ADMIN_ROLE) +``` + +Admin function to remove a member from the Chama. Member must have zero balance. + +```solidity +function changeContributionToken(address _token) external onlyRole(CHAMA_ADMIN_ROLE) +``` + +Changes the token used for contributions. The contract balance must be zero. + +### Loans + +`Loans.sol` - Base contract that provides lending functionality. + +This contract (not fully visible in the provided code snippets) appears to handle loan creation, approval, and repayment within the Chama ecosystem. It tracks frozen contribution amounts for outstanding loans. + +## Function Workflows + +### Creating a New Chama Group -```shell -$ cast +```mermaid +sequenceDiagram + Actor User + User->>Chama: createChama(admin, name, interestRate) + Chama->>Contributions: new Contributions(admin, token, interestRate) + Contributions->>Loans: initialize Loans + Contributions->>Contributions: Add admin as a member + Contributions->>Contributions: Grant admin roles + Chama->>Chama: Store Chama details + Chama-->>User: Return Contributions contract address ``` -### Help +### Adding a Member to Chama -```shell -$ forge --help -$ anvil --help -$ cast --help +```mermaid +sequenceDiagram + Actor Admin + Admin->>Chama: addMemberToChama(memberAddress, chamaName) + Chama->>Chama: Check if caller is chamaAdmin + Chama->>Contributions: addMemberToChama(memberAddress) + Contributions->>Contributions: Check if member already exists + Contributions->>Contributions: Add member to members set + Contributions->>Contributions: Create Member struct for tracking ``` + +### Member Contribution Flow + +```mermaid +sequenceDiagram + Actor Member + Member->>Contributions: addContribution(amount) + Contributions->>Contributions: Check if caller is a member + Contributions->>Contributions: Update member contribution amount + Contributions->>ERC20: safeTransferFrom(member, contract, amount) + Contributions-->>Member: Emit MemberHasContributed event +``` + +### Round Claiming Flow + +```mermaid +sequenceDiagram + Actor Member + Member->>Contributions: claimRound() + Contributions->>Contributions: Check if epoch period has ended + loop For each member + Contributions->>Contributions: Check member contributions + Contributions->>Contributions: Calculate available amount + Contributions->>ERC20: Transfer funds to the claiming member + end + Contributions->>Contributions: Update epoch end time + Contributions->>Contributions: Increment current round +``` + +## Development Guide + +### Adding a New Feature + +1. Identify which contract should implement the feature +2. Implement the new functionality with proper access controls +3. Add relevant tests to verify functionality +4. Update documentation to reflect changes + +### Best Practices + +- Always include events for important state changes +- Use OpenZeppelin's SafeERC20 for token transfers +- Check for zero addresses in public functions +- Implement nonReentrant modifiers for external calls +- Keep functions simple and follow the checks-effects-interactions pattern + +## Testing + +ChamaDAO uses Foundry's testing framework. Tests are located in test directory. + +Run all tests: + +```bash +forge test +``` + +Run specific test: + +```bash +forge test --match-contract ChamaTest -vvv +``` + +Run with gas reporting: + +```bash +forge test --gas-report +``` + +### Test Structure + +- unit: Unit tests for individual contracts +- mocks: Mock contracts for testing + +## Deployment + +The project includes deployment scripts for various networks. To deploy to a network: + +```bash +forge script script/DeployChama.s.sol:DeployChamaScript --rpc-url --private-key +``` + +### Contract Verification + +After deployment, you can verify contracts on Etherscan: + +```bash +forge verify-contract src/Chama.sol:Chama --etherscan-api-key --chain +``` + +## DAO Governance + +According to the ChamaDAO Whitepaper, governance is structured with the following components: + +1. **DAO Treasury** - Managed collectively by the community +2. **Membership Tiers** - Different levels of participation and voting rights +3. **Proposal System** - Formal mechanism for suggesting and approving changes +4. **Voting Mechanism** - Token-weighted or quadratic voting for decision making + +## Security Considerations + +- The protocol uses role-based access control to enforce permissions +- Funds cannot be withdrawn without proper round processing +- SafeERC20 is used to prevent common token handling vulnerabilities +- Members cannot be removed if they have a non-zero balance +- Token changes require zero balance to prevent fund loss + +## Additional Resources + +- [Foundry Documentation](https://book.getfoundry.sh/) +- ChamaDAO Whitepaper +- [OpenZeppelin Documentation](https://docs.openzeppelin.com/) + +## License + +This project is licensed under the MIT License. From c58e88df421d9ad95d31fc58a2c32db305a9651c Mon Sep 17 00:00:00 2001 From: ybtuti Date: Sun, 11 May 2025 13:26:23 +0300 Subject: [PATCH 2/2] Add member limit parameter to Chama creation Extends createChama function to include a numeric parameter for setting member limits during chama group creation. This allows for better control over group sizes and helps manage participation restrictions. --- test/unit/ChamaTest.t.sol | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/unit/ChamaTest.t.sol b/test/unit/ChamaTest.t.sol index 8651f74..888c8c6 100644 --- a/test/unit/ChamaTest.t.sol +++ b/test/unit/ChamaTest.t.sol @@ -15,12 +15,12 @@ contract ChamaTest is Test { function setUp() external { chama = new Chama(); - contributions = chama.createChama(chamaAdmin, "Chama1"); + contributions = chama.createChama(chamaAdmin, "Chama1", 10); } function testCreateChama() external { vm.prank(chamaAdmin); - address _contributions = chama.createChama(chamaAdmin, "Chama1"); + address _contributions = chama.createChama(chamaAdmin, "Chama1", 10); console.log("Chama admin is: ", IContributions(_contributions).getAdmin());