This project implements a decentralized kindness pool system using Hardhat and Solidity smart contracts. Users can contribute to or receive from a daily pool of Ether, promoting a culture of giving and receiving kindness.

For detailed business logic, please refer to BUSINESS_LOGIC.md.

Key features:

• 24-hour cycles for contributions and distributions
• User can contribute between 0.001 and 1 ETH
• Users can enter a receiver pool to potentially receive funds
• Automatic distribution at the end of each cycle
• Daily contribution and receiver limits
• Rate limiting and DoS protection
• Failed transfer handling and retry mechanisms
• Comprehensive security features

• Node.js (v14.0.0 or later)
• npm (v6.0.0 or later)
• Git

1. Clone the repository:

   git clone https://github.com/your-repo/kindness-pool.git
   cd kindness-pool

2. Install dependencies:

   npm install

npm run compile

npm test

npm test -- test/Pool.test.ts
npm test -- test/DoSAttacks.test.ts
npm test -- test/DailyTracking.test.ts

npm run format
npm run format:check

npm run clean

1. Pool.sol - Main contract managing contributions, receivers, and distributions
2. UserRegistry.sol - Manages user statistics and receiver pool status
3. TimeBasedDistributor.sol - Handles time-based distribution logic
4. Errors.sol - Custom error definitions for gas-efficient error handling

• Reentrancy Protection: Uses checks-effects-interactions pattern
• Rate Limiting: Action cooldowns and transaction limits
• DoS Protection: Gas limit protections and receiver limits
• Failed Transfer Handling: Robust retry mechanisms with exponential backoff
• Access Control: Role-based permissions for admin functions

• Contribution Limits: 5 ETH maximum per user per day
• Receiver Pool Limits: 1 entry/exit per user per day
• Transaction Limits: 10 transactions per user per day (Note: Currently has a reset bug)
• Action Cooldowns: 1 hour between general actions, 30 minutes between receiver pool actions

• Uses custom errors for gas efficiency
• Comprehensive error messages for debugging
• Failed transfer tracking and retry mechanisms

• Description: Contribute ETH to the daily pool
• Parameters:
  • amount: Amount to contribute (0.001 to 1 ETH)
• Requirements:
  • Amount must be between MIN_KINDNESS_AMOUNT and MAX_KINDNESS_AMOUNT
  • User must not exceed daily contribution limit (5 ETH)
  • Respects transaction limits and cooldowns

• Description: Enter the receiver pool to potentially receive funds
• Requirements:
  • User must not have contributed today
  • User must not already be in receiver pool
  • Respects daily entry limits and cooldowns

• Description: Exit the receiver pool
• Requirements:
  • User must be in receiver pool
  • Respects daily exit limits and cooldowns

• Description: Distribute the daily pool to receivers (admin only)
• Requirements:
  • Must be within distribution window
  • Must not have distributed today
  • Pool must have minimum balance

• Returns: bool - Whether current time is within distribution window

• Returns: bool - Whether distribution has occurred today

• Returns: uint256 - Current number of receivers

• Returns: uint256 - Amount of unclaimed funds from failed transfers

• MIN_KINDNESS_AMOUNT: 0.001 ETH
• MAX_KINDNESS_AMOUNT: 1 ETH
• MAX_DAILY_CONTRIBUTION: 5 ETH
• MAX_DAILY_RECEIVER_ENTRIES: 1
• MAX_DAILY_RECEIVER_EXITS: 1
• MAX_TRANSACTIONS_PER_DAY: 10
• ACTION_COOLDOWN: 1 hour
• RECEIVER_POOL_COOLDOWN: 30 minutes
• MAX_RECEIVERS: 100

• KindnessGiven(address indexed giver, uint256 amount)
• KindnessReceived(address indexed receiver, uint256 amount)
• PoolDistributed(uint256 totalAmount, uint256 receiverCount)
• EnteredReceiverPool(address indexed receiver)
• LeftReceiverPool(address indexed receiver)
• TransferFailed(address indexed receiver, uint256 amount)
• TransferRetried(address indexed receiver, uint256 amount, bool success)

• UserStatsUpdated(address indexed user, bool isGiving, uint256 amount, uint256 totalGiven, uint256 totalReceived, int256 netAmount)
• UserNameUpdated(address indexed user, string name)
• ReceiverPoolStatusUpdated(address indexed user, bool isInReceiverPool)

1. Start a local Hardhat node:

   npx hardhat node

2. Deploy contracts to local network:

   npx hardhat run scripts/deploy.ts --network localhost

1. Configure your environment variables in .env:

   PRIVATE_KEY=your_private_key
   INFURA_API_KEY=your_infura_key
   ETHERSCAN_API_KEY=your_etherscan_key
   

2. Deploy to testnet (e.g., Sepolia):

   npx hardhat run scripts/deploy.ts --network sepolia

3. Verify contracts:

   npx hardhat verify --network sepolia DEPLOYED_ADDRESS

⚠️ Warning: Ensure thorough testing before mainnet deployment

1. Use the same process as testnet but with mainnet network configuration
2. Consider using a multisig wallet for admin functions
3. Implement timelocks for critical parameter changes

1. Transaction Count Reset Bug: The transactionCount mapping is not reset in the daily reset mechanism, causing permanent lockout after 10 transactions
2. Gas Limit Considerations: Large receiver pools may approach gas limits during distribution
3. Failed Transfer Handling: Failed transfers are tracked but require manual intervention for resolution

1. Admin Role Management: Use multisig wallets for admin roles
2. Emergency Procedures: Implement emergency pause mechanisms
3. Monitoring: Monitor failed transfers and retry attempts
4. Gas Price Management: Consider gas price fluctuations for distribution operations

The project includes comprehensive test suites:

• Pool.test.ts: Core functionality tests
• DoSAttacks.test.ts: Denial of service attack resistance tests
• DailyTracking.test.ts: Daily reset and limit tests
• UserRegistry.test.ts: User statistics and registry tests
• ReceiverPoolExit.test.ts: Receiver pool exit functionality tests

# Run all tests
npm test

# Run with gas reporting
npx hardhat test --gas-report

# Run specific test file
npm test -- test/DoSAttacks.test.ts

# Run tests with coverage
npx hardhat coverage

1. Fork the repository
2. Create a feature branch
3. Implement your changes with tests
4. Ensure all tests pass
5. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

For questions and support, please open an issue on the GitHub repository.