# Contributing to ETH.id
Thank you for your interest in contributing to ETH.id! This document provides guidelines and instructions for contributing.
## 🎯 Project Vision
ETH.id is a zero-knowledge document verification system that combines:
- **Zero-Knowledge Proofs** for deterministic claims
- **LLMs** for semantic understanding
- **Privacy-first architecture** where documents never leave the user's machine
## 🚀 Getting Started
### Prerequisites
- Rust 1.70+ ([rustup.rs](https://rustup.rs))
- Git
- (Optional) Noir toolchain for ZK circuits
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/your-org/eth-id.git
cd eth-id
# Build the project
cargo build
# Run tests
cargo test
# Run with debug logging
RUST_LOG=debug cargo run -- verify --doc examples/sample_documents/brazilian_id.txt --claim "maior de 18 anos"
```
## 📋 Development Workflow
### 1. Create a Branch
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
```
### 2. Make Changes
Follow these guidelines:
- Write clear, concise commit messages
- Add tests for new functionality
- Update documentation as needed
- Follow Rust best practices and idioms
### 3. Run Tests
```bash
# Run all tests
cargo test
# Run specific test suite
cargo test --test claims_tests
cargo test --test privacy_tests
cargo test --test adversarial_tests
# Run with coverage (requires cargo-tarpaulin)
cargo tarpaulin --out Html
```
### 4. Format and Lint
```bash
# Format code
cargo fmt
# Run clippy
cargo clippy -- -D warnings
# Fix warnings
cargo fix --allow-dirty
```
### 5. Submit Pull Request
- Push your branch to GitHub
- Create a Pull Request with a clear description
- Link any related issues
- Wait for review
## 🧪 Testing Guidelines
### Test Categories
1. **Unit Tests** - Test individual functions and modules
2. **Integration Tests** - Test end-to-end workflows
3. **Adversarial Tests** - Test security and privacy guarantees
### Writing Tests
```rust
#[tokio::test]
async fn test_your_feature() {
// Arrange
let input = create_test_input();
// Act
let result = your_function(input).await;
// Assert
assert!(result.is_ok());
assert_eq!(result.unwrap(), expected_value);
}
```
### Privacy Test Requirements
All new features that handle document data MUST include tests verifying:
- No sensitive data in filtered output
- Proper hashing and masking
- Compliance with Privacy Filter modes
## 🏗️ Architecture Guidelines
### Module Structure
```
src/
├── cli/ # Command-line interface
├── parser/ # Document parsing (PDF, image, JSON)
├── claims/ # Claim parsing and validation
├── privacy/ # Privacy Filter implementation
├── verifier/ # LLM integration
├── attestation/ # Attestation bundles
└── audit/ # Audit logging
```
### Adding New Claim Types
1. Add enum variant to `ClaimType` in `src/claims/types.rs`
2. Implement parsing logic in `src/claims/engine.rs`
3. Add validation in `src/claims/validator.rs`
4. Update Privacy Filter in `src/privacy/filter.rs`
5. Add tests in `tests/claims_tests.rs`
### Adding New LLM Providers
1. Create new file in `src/verifier/` (e.g., `gemini.rs`)
2. Implement `verify()` function with same signature
3. Add to `LlmProvider` enum in `src/verifier/mod.rs`
4. Update CLI config in `src/cli/config.rs`
5. Add integration tests
## 🔒 Security Guidelines
### Critical Rules
1. **Never log sensitive data** - Only hashes allowed
2. **Zeroize on drop** - Use `zeroize` crate for sensitive structs
3. **Validate all inputs** - Never trust user input
4. **Test adversarial cases** - Add tests for injection attempts
### Code Review Checklist
- [ ] No sensitive data in logs
- [ ] Privacy Filter applied before external calls
- [ ] Proper error handling (no panics in production code)
- [ ] Tests cover edge cases
- [ ] Documentation updated
## 📝 Documentation Standards
### Code Comments
```rust
/// Brief description of function
///
/// # Arguments
/// * `param1` - Description of param1
/// * `param2` - Description of param2
///
/// # Returns
/// Description of return value
///
/// # Errors
/// When this function returns an error
///
/// # Examples
/// ```
/// let result = function(param1, param2);
/// ```
pub fn function(param1: Type1, param2: Type2) -> Result<ReturnType> {
// Implementation
}
```
### Documentation Files
Update these when making significant changes:
- `README.md` - User-facing documentation
- `ARCHITECTURE.md` - System design decisions
- `PRIVACY.md` - Privacy guarantees
- `THREAT_MODEL.md` - Security analysis
## 🐛 Bug Reports
### Good Bug Report Template
```markdown
**Description**
Clear description of the bug
**Steps to Reproduce**
1. Run command: `eth verify --doc ...`
2. Observe error: ...
**Expected Behavior**
What should happen
**Actual Behavior**
What actually happens
**Environment**
- OS: macOS 14.0
- Rust version: 1.75.0
- ETH.id version: 0.1.0
**Logs**
```
Paste relevant logs here
```
```
## ✨ Feature Requests
### Good Feature Request Template
```markdown
**Problem Statement**
What problem does this solve?
**Proposed Solution**
How should it work?
**Alternatives Considered**
What other approaches did you consider?
**Privacy Impact**
Does this affect privacy guarantees?
**Implementation Notes**
Any technical details or constraints
```
## 🎨 Code Style
### Rust Conventions
- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `rustfmt` with default settings
- Prefer explicit types over `auto`
- Use descriptive variable names
### Error Handling
```rust
// Good
let result = parse_document(&path)
.map_err(|e| EthIdError::DocumentParsing(format!("Failed to parse: {}", e)))?;
// Bad
let result = parse_document(&path).unwrap();
```
### Async/Await
```rust
// Good
pub async fn verify(&self, claim: &Claim) -> Result<bool> {
let result = self.llm_client.query(claim).await?;
Ok(result.answer)
}
// Bad - blocking in async context
pub async fn verify(&self, claim: &Claim) -> Result<bool> {
std::thread::sleep(Duration::from_secs(1));
Ok(true)
}
```
## 🚢 Release Process
### Version Numbering
We follow [Semantic Versioning](https://semver.org/):
- MAJOR: Breaking changes
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes
### Release Checklist
- [ ] All tests passing
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version bumped in Cargo.toml
- [ ] Git tag created
- [ ] Binary built and tested
- [ ] Release notes written
## 📞 Getting Help
- **Questions**: Open a GitHub Discussion
- **Bugs**: Open a GitHub Issue
- **Security**: Email security@eth.id (placeholder)
- **Chat**: Join our Discord (placeholder)
## 📜 License
By contributing, you agree that your contributions will be licensed under the MIT License.
## 🙏 Recognition
Contributors are recognized in:
- GitHub contributors page
- CHANGELOG.md for significant contributions
- README.md for major features
Thank you for contributing to ETH.id! 🚀