gru_emoney_token-factory/CONTRIBUTING.md

Contributing to eMoney Token Factory

Thank you for your interest in contributing to the eMoney Token Factory project! This document provides guidelines and instructions for contributing.

Development Setup

Prerequisites

• Foundry (latest version)
• Git
• A code editor (VS Code recommended with Solidity extension)

Initial Setup

1. Clone the repository:

git clone <repository-url>
cd gru_emoney_token-factory

2. Install dependencies:

forge install

3. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Compile the contracts:

forge build

5. Run tests:

forge test

Code Style Guidelines

Solidity

• Follow Solidity Style Guide
• Use Solidity 0.8.20 or higher
• Maximum line length: 120 characters
• Use 4 spaces for indentation (no tabs)

Naming Conventions

• Contracts: PascalCase (e.g., ComplianceRegistry)
• Functions: camelCase (e.g., setCompliance)
• Variables: camelCase (e.g., activeLienAmount)
• Constants: UPPER_SNAKE_CASE (e.g., COMPLIANCE_ROLE)
• Events: PascalCase (e.g., ComplianceUpdated)
• Errors: PascalCase (e.g., TransferBlocked)

Documentation

• All public/external functions must have NatSpec documentation
• Include @notice, @dev, @param, and @return tags where applicable
• Contract-level documentation should describe the contract's purpose and key features

Example

/**
 * @notice Sets compliance status for an account
 * @dev Requires COMPLIANCE_ROLE
 * @param account Address to update
 * @param allowed Whether the account is allowed (compliant)
 * @param tier Risk tier (0-255)
 * @param jurHash Jurisdiction hash (e.g., keccak256("US"))
 */
function setCompliance(
    address account,
    bool allowed,
    uint8 tier,
    bytes32 jurHash
) external override onlyRole(COMPLIANCE_ROLE) {
    // Implementation
}

Testing Requirements

Test Coverage

• Maintain >90% test coverage
• All new features must have corresponding tests
• Edge cases and error conditions must be tested

Test Structure

• Unit tests: test/unit/
• Integration tests: test/integration/
• Fuzz tests: test/fuzz/
• Invariant tests: test/invariants/

Running Tests

# Run all tests
forge test

# Run specific test file
forge test --match-path test/unit/ComplianceRegistryTest.t.sol

# Run with verbosity
forge test -vvv

# Run coverage
forge coverage --ir-minimum

Writing Tests

• Use descriptive test function names: test_setCompliance_updatesStatus()
• Follow Arrange-Act-Assert pattern
• Test both success and failure cases
• Use vm.expectRevert() for expected failures
• Use vm.prank() and vm.startPrank() for access control testing

Example

function test_setCompliance_updatesStatus() public {
    // Arrange
    address user = address(0x123);
    
    // Act
    vm.prank(complianceOperator);
    complianceRegistry.setCompliance(user, true, 1, bytes32(0));
    
    // Assert
    assertTrue(complianceRegistry.isAllowed(user));
}

Pull Request Process

1. Create a branch:

git checkout -b feature/your-feature-name

2. Make your changes:

   • Write code following the style guidelines
   • Add tests for new functionality
   • Update documentation as needed
   • Ensure all tests pass

3. Commit your changes:

git add .
git commit -m "feat: add your feature description"

Use conventional commit messages:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• test: for test additions/changes
• refactor: for code refactoring
• chore: for maintenance tasks

4. Push and create PR:

git push origin feature/your-feature-name

5. Create Pull Request:
   • Provide a clear description of changes
   • Reference any related issues
   • Ensure CI checks pass
   • Request review from maintainers

PR Checklist

• Code follows style guidelines
• All tests pass
• Test coverage maintained (>90%)
• NatSpec documentation added
• README/docs updated if needed
• No linter errors
• Security considerations addressed

Code Review Guidelines

For Authors

• Respond to all review comments
• Make requested changes or explain why not
• Keep PRs focused and reasonably sized
• Update PR description if scope changes

For Reviewers

• Be constructive and respectful
• Focus on code quality and correctness
• Check for security issues
• Verify tests are adequate
• Ensure documentation is clear

Security Considerations

• Never commit private keys or sensitive data
• Review all external calls and dependencies
• Consider edge cases and attack vectors
• Follow secure coding practices
• Report security issues to security@example.com (see SECURITY.md)

Project Structure

gru_emoney_token-factory/
├── src/                    # Source contracts
│   ├── interfaces/         # Interface definitions
│   ├── libraries/          # Library contracts
│   ├── errors/             # Custom errors
│   └── *.sol              # Core contracts
├── test/                   # Test files
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── fuzz/              # Fuzz tests
│   └── invariants/        # Invariant tests
├── script/                # Deployment scripts
│   └── helpers/           # Helper libraries
├── docs/                  # Documentation
└── lib/                   # Dependencies

Getting Help

• Check existing documentation (README.md, RUNBOOK.md)
• Search existing issues and PRs
• Ask questions in discussions
• Contact maintainers for guidance

License

By contributing, you agree that your contributions will be licensed under the MIT License.