Deimos
Deimos

Contributing to Deimos

We really appreciate and value contributions to Deimos. Please take time to review the items listed below to make sure that your contributions are merged as soon as possible.

Contribution Workflow

Before starting development, contributors should create an issue to open discussion, validate that the PR is wanted, and coordinate implementation details.

GitHub Issues: https://github.com/BlocSoc-iitr/Deimos/issues/new/choose

Standard Workflow

The typical contribution workflow includes:

  • Fork the repository and keep it synchronized
  • Branch from dev with descriptive branch names
  • Make changes and commit with proper messages
  • Run tests and linters before submission
  • Create pull requests with issue references
  • Address maintainer feedback

Code Quality Requirements

All code must pass the following checks:

  • Rust formatting with cargo fmt
  • Clippy linting with all warnings as errors
  • Typo checking

Ways to Contribute

Add New Circuits

  • Implement new hash functions (BLAKE3, SHA3-512, etc.)
  • Add signature schemes (EdDSA, ECDSA)
  • Create application-level circuits (JWT parsing, etc.)
  • Optimize existing circuit implementations

Integrate New Frameworks

  • Add support for imp1
  • Add support for ProveKit
  • Add support for RISC Zero
  • Add support for SP1
  • Implement Noir circuits

Improve Mobile Apps

  • Enhance UI/UX of benchmarking apps
  • Add more detailed metrics collection
  • Implement battery usage tracking
  • Add export functionality for benchmark results
  • Create iOS implementations

Enhance Documentation

  • Improve setup guides
  • Add tutorials and examples
  • Document best practices
  • Create video walkthroughs
  • Translate documentation

Build Dashboard Features

  • Implement database integration
  • Create visualization components
  • Add comparison tools
  • Build result export features
  • Implement filtering and search

Report Issues

  • Bug reports with detailed reproduction steps
  • Performance issues
  • Documentation gaps or errors
  • Feature requests

Development Workflow

1. Fork and Clone

Bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/Deimos.git
cd Deimos

# Add upstream remote
git remote add upstream https://github.com/BlocSoc-iitr/Deimos.git

2. Keep Your Fork Updated

Bash
# Fetch latest changes from upstream
git fetch upstream

# Update your local dev branch
git checkout dev
git pull --rebase upstream dev

3. Create a Feature Branch

Bash
# Branch from dev
git checkout dev
git checkout -b fix/some-bug-short-description-#123

# Or for features
git checkout -b feature/new-feature-description-#123

# Note: Postfixing #123 associates your PR with issue #123

4. Make Your Changes

  • Write clean, readable code
  • Follow existing code style and conventions
  • Add tests for new functionality
  • Update documentation as needed
  • Keep commits focused and atomic

5. Test Your Changes

Bash
# For Rust code
cd your-app-location
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

# For circuits
circom your_circuit.circom --r1cs --wasm --sym
snarkjs groth16 fullprove input.json circuit.wasm circuit.zkey proof.json public.json

# For website
cd website
npm run build
npm run lint

# Check for typos
typos

6. Commit and Push

# Stage your changes
git add src/file.rs

# Commit with descriptive message
git commit -m "Fix some bug short description #123"

# Push to your fork
git push origin -u fix/some-bug-short-description-#123

7. Create Pull Request

  • Go to https://github.com/BlocSoc-iitr/Deimos
  • Click "New Pull Request"
  • Select your branch
  • Begin the body with "Fixes #123" or "Resolves #123"
  • Provide clear description of changes
  • Include screenshots for UI changes
  • List any breaking changes

8. Address Review Feedback

Maintainers will review your code and may request changes. Please pay attention to feedback as it's necessary to maintain code quality standards.

Bash
# Make requested changes
git add modified_files
git commit -m "Address review feedback"
git push origin fix/some-bug-short-description-#123

Adding New Applications

When adding a new mobile application, follow the Application Integration Guide:

  • Use the MoPro framework for consistency
  • Follow the directory structure of existing apps
  • Include comprehensive README with setup instructions
  • Add test vectors for your circuits
  • Document benchmark results
  • Include both Android and iOS implementations (if possible)

Reference: APP_INTEGRATION_GUIDE.md in the repository

Code Style Guidelines

Rust Code

  • Use cargo fmt for formatting
  • Address all cargo clippy warnings
  • Write descriptive variable and function names
  • Add doc comments for public APIs
  • Keep functions focused and small

Circom Circuits

  • Use pragma circom 2.0.0 or higher
  • Add comments explaining circuit logic
  • Follow naming conventions from existing circuits
  • Include template documentation
  • Use meaningful signal names

TypeScript/JavaScript

  • Use TypeScript for type safety
  • Follow ESLint rules
  • Use functional components in React
  • Keep components small and focused
  • Add prop types and interfaces

Kotlin (Android)

  • Follow Kotlin coding conventions
  • Use Material Design components
  • Implement proper error handling
  • Add KDoc comments for public APIs
  • Use coroutines for async operations

Swift (iOS)

  • Follow Swift API design guidelines
  • Use SwiftUI or UIKit consistently
  • Implement proper error handling
  • Add documentation comments
  • Use async/await for async operations

Testing Requirements

Circuit Testing

  • Test with zero input
  • Test with known test vectors
  • Verify output matches reference implementation
  • Test proof generation and verification
  • Document constraint count

Code Testing

  • Write unit tests for new functions
  • Add integration tests for features
  • Test error handling paths
  • Verify edge cases
  • Maintain or improve code coverage

Mobile Testing

  • Test on physical devices
  • Test on multiple device models
  • Test on different OS versions
  • Verify memory usage is acceptable
  • Test performance under load

Documentation Requirements

  • Update README if adding new features
  • Add inline code comments for complex logic
  • Document API changes
  • Include usage examples
  • Update relevant guides
  • Add screenshots for UI changes

Branch Policy

  • main: Stable releases only. Do not submit PRs directly to main.
  • dev: Active development branch. Submit all PRs to dev.
  • feature/*: Feature branches for new functionality
  • fix/*: Bug fix branches
  • docs/*: Documentation improvement branches

Commit Message Guidelines

Write clear, descriptive commit messages:

# Good commit messages
Add Keccak-256 circuit implementation #45
Fix memory leak in proof generation #67
Update MoPro integration guide
Optimize SHA-256 constraint count

# Bad commit messages
fix bug
update
changes
wip

Format:

  • Use imperative mood ("Add" not "Added")
  • Keep first line under 72 characters
  • Reference issue numbers
  • Be specific about what changed

Pull Request Guidelines

PR Title

  • Clear and descriptive
  • Reference issue number
  • Use imperative mood

PR Description

Include:

  • What changes were made
  • Why the changes were necessary
  • How to test the changes
  • Screenshots for UI changes
  • Breaking changes (if any)
  • Related issues

PR Checklist

  • Code follows project style guidelines
  • Tests pass locally
  • New tests added for new functionality
  • Documentation updated
  • No merge conflicts
  • Commits are clean and focused
  • PR is linked to relevant issue

Getting Help

If you need help with your contribution:

  • Check existing documentation and guides
  • Look at similar implementations in the codebase
  • Ask questions in your issue or PR
  • Join community discussions
  • Reach out to maintainers

Good First Issues

If you're new to the project, look for issues labeled "Good first issue". These are beginner-friendly tasks that will help you get familiar with the codebase.

Find good first issues: https://github.com/BlocSoc-iitr/Deimos/labels/good%20first%20issue

Code of Conduct

Be respectful and inclusive. We want to maintain a welcoming environment for all contributors.

  • Be respectful of differing opinions
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members

License

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

Thank You!

Thank you for taking the time to contribute to Deimos. Your contributions help make mobile ZK proving better for everyone!