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](https://book.getfoundry.sh/getting-started/installation) (latest version)
- Git
- A code editor (VS Code recommended with Solidity extension)

### Initial Setup

1. **Clone the repository**:
```bash
git clone <repository-url>
cd gru_emoney_token-factory
```

2. **Install dependencies**:
```bash
forge install
```

3. **Set up environment variables**:
```bash
cp .env.example .env
# Edit .env with your configuration
```

4. **Compile the contracts**:
```bash
forge build
```

5. **Run tests**:
```bash
forge test
```

## Code Style Guidelines

### Solidity

- Follow [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html)
- 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

```solidity
/**
 * @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

```bash
# 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

```solidity
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**:
```bash
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**:
```bash
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**:
```bash
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.