# Contributing to HYPERION
Thank you for your interest in contributing to HYPERION! This document provides guidelines and information for contributors.
## Development Setup
### Prerequisites
- **Rust 1.70+** with 2021 edition support
- **LLVM 15+** (for frontend integration tests)
- **Git** for version control
### Local Development
```bash
# Clone the repository
git clone https://github.com/hyperion-zkvm/hyperion.git
cd hyperion
# Run tests
cargo test
# Run benchmarks
cargo bench
# Generate documentation
cargo doc --open
```
### Fuzz Testing
```bash
# Install fuzzing tools
cargo install cargo-fuzz
# Run fuzz tests
cargo fuzz run field_operations
cargo fuzz run fri_operations
cargo fuzz run vm_operations
```
## Code Standards
### Rust Guidelines
- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `rustfmt` for code formatting
- Run `clippy` for linting: `cargo clippy`
- Write comprehensive documentation for public APIs
### Cryptographic Code
- **Zero unsafe code** in cryptographic primitives
- **Comprehensive testing** including property-based testing
- **Formal verification** where applicable
- **Clear security assumptions** in documentation
### Commit Messages
- Use conventional commit format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
- Example: `feat(fri): add parallel codeword folding`
## Testing Requirements
### Unit Tests
- All public functions must have unit tests
- Test edge cases and error conditions
- Use property-based testing where applicable
### Integration Tests
- End-to-end testing for compilation pipelines
- Cross-component interaction testing
### Performance Tests
- Benchmarks for critical paths
- Memory usage profiling
- Scalability testing
## Pull Request Process
### Before Submitting
1. **Run full test suite**: `cargo test`
2. **Run benchmarks**: `cargo bench`
3. **Check documentation**: `cargo doc`
4. **Run clippy**: `cargo clippy`
5. **Update CHANGELOG.md** if needed
### PR Description
- Clearly describe the changes
- Reference any related issues
- Include performance impact if applicable
- Add test cases for new functionality
### Review Process
- At least one maintainer review required
- All tests must pass
- No breaking changes without discussion
- Cryptographic changes require security review
## Architecture Guidelines
### Module Organization
- `src/vm.rs`: Virtual machine core
- `src/fri.rs`: FRI protocol implementation
- `src/field.rs`: Finite field arithmetic
- `src/circuit_compiler.rs`: Compilation pipeline
- `src/attestor.rs`: Proof generation/verification
### Error Handling
- Use `thiserror` for custom error types
- Provide meaningful error messages
- Handle all Result/Option returns appropriately
### Performance Considerations
- SIMD acceleration where beneficial
- Memory pool usage for large allocations
- Parallel processing for independent operations
- Cache-friendly data structures
## Security Considerations
### Cryptographic Review
- All cryptographic changes require review
- Maintain formal security proofs
- Update security documentation
- Consider side-channel vulnerabilities
### Memory Safety
- No unsafe code in cryptographic components
- Proper bounds checking
- Secure memory zeroization where needed
## Community Guidelines
### Code of Conduct
- Be respectful and inclusive
- Focus on technical merit
- Provide constructive feedback
- Help newcomers learn
### Getting Help
- Use GitHub issues for bugs/features
- Use GitHub discussions for questions
- Check existing documentation first
Thank you for contributing to HYPERION! 🚀