Contributing to HashScope¶

Thank you for your interest in contributing to HashScope!

Development Setup¶

Backend¶

cd backend
pip install -r requirements.txt

# Set required config
export POOL_HOST=stratum+tcp://your-test-pool.com
export POOL_PORT=3333

# Run tests
pytest -q

# Run in development
uvicorn hashscope.api.app:create_app --factory --reload

Frontend¶

cd frontend
npm ci
npm run dev

Code Style¶

Python¶

Type hints required for all public functions
Follow PEP 8
Use ruff or black for formatting if available
No blocking calls in async code
Structured logging preferred

TypeScript¶

Strict mode enabled
Use functional components with hooks
Prefer composition over complex components
Follow existing component patterns

Testing¶

All new features should include tests:

# Backend
cd backend
pytest -q

# Frontend lint
cd frontend
npm run lint

Pull Request Process¶

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and linters
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Architecture Guidelines¶

Key Principles¶

Never modify message contents - byte-for-byte relay
Best-effort parsing - parse errors should not crash the proxy
Security first - treat all input as untrusted
Type safety - use type hints and TypeScript strictly
Nostr publishing never blocks relay - background tasks only

Development Approach¶

HashScope is built in phases:

Core Proxy: Transparent proxy with real-time visualization
Distributed Testing: Agent fleet with Nostr coordination for load testing
Future Enhancements: Additional protocol support, persistent storage, authentication

Code Review¶

All submissions require review. We look for:

Code quality and style consistency
Test coverage
Documentation updates
Performance considerations
Security implications

Reporting Issues¶

When reporting issues, include:

HashScope version
Steps to reproduce
Expected vs actual behavior
Relevant logs
System information (OS, Docker version, etc.)

Feature Requests¶

We welcome feature requests! Please:

Check existing issues first
Describe the use case
Explain expected behavior
Consider implementation complexity

Questions?¶

Open an issue for any questions about contributing!

License¶

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License).

This project is licensed under the MIT License - see the LICENSE file for details.