Skip to content

Latest commit

 

History

History
100 lines (65 loc) · 5.07 KB

CONTRIBUTING.md

File metadata and controls

100 lines (65 loc) · 5.07 KB

Contributing to Slither

First, thanks for your interest in contributing to Slither! We welcome and appreciate all contributions, including bug reports, feature suggestions, tutorials/blog posts, and code improvements.

If you're unsure where to start, we recommend our good first issue and help wanted issue labels.

Bug reports and feature suggestions

Bug reports and feature suggestions can be submitted to our issue tracker. For bug reports, attaching the contract that caused the bug will help us in debugging and resolving the issue quickly. If you find a security vulnerability, do not open an issue; email [email protected] instead.

Questions

Questions can be submitted to the "Discussions" page, and you may also join our chat room (in the #ethereum channel).

Code

Submit contributions via pull request.

  • Minimize irrelevant changes (formatting, whitespace). Save style fixes for separate PRs.
  • Split large changes into smaller focused PRs.
  • PR description: summarize changes. For bug fixes, explain root cause.
  • PR title: describe what it's changing (not just "Fixes #123").
  • Commit messages: ≤72 char subject, prefix with fix:, feat:, docs:, test:, refactor:.

Directory Structure

See the Architecture section in CLAUDE.md for directory layout. A code walkthrough is available here.

Development Environment

Instructions for installing a development version of Slither can be found in our wiki.

For development setup, we use uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup development environment
make dev  # Installs dependencies and pre-commit hooks

Run make test for all tests, or make test TESTS=$name for specific tests. List test names with pytest tests --collect-only.

Linters

Run make lint to check and make reformat to auto-fix. We use ruff for Python and yamllint for YAML.

Pre-commit Hooks (Recommended)

We use prek, a fast Rust-based pre-commit runner:

prek install               # One-time setup
prek run --all-files       # Run manually
prek auto-update --cooldown-days 7  # Update hook versions

Testing

Slither's test suite has three categories:

  • End-to-end (tests/e2e): Invoke Slither and check output (printers, detectors).
  • Unit (tests/unit): Test individual objects and functions.
  • Tools (tests/tools): Tests for slither/tools.

Adding detector tests

For each new detector, at least one regression tests must be present.

  1. Create a folder in tests/e2e/detectors/test_data with the detector's argument name.
  2. Create a test contract in tests/e2e/detectors/test_data/<detector_name>/.
  3. Update ALL_TESTS in tests/e2e/detectors/test_detectors.py.
  4. Run python tests/e2e/detectors/test_detectors.py --compile to create a ZIP file of the compilation artifacts.
  5. pytest tests/e2e/detectors/test_detectors.py --insta update-new. This will generate a snapshot of the detector output in tests/e2e/detectors/snapshots/. If updating an existing detector, run pytest tests/e2e/detectors/test_detectors.py --insta review and accept or reject the updates.
  6. Run pytest tests/e2e/detectors/test_detectors.py to ensure everything worked. Then, add and commit the files to git.

Tip: Filter with -k ReentrancyReadBeforeWritten (class) or -k 0.7.6 (version). Add --cov=slither/detectors --cov-report=html for coverage.

Adding parsing tests

  1. Create a test in tests/e2e/solc_parsing/
  2. Update ALL_TESTS in tests/e2e/solc_parsing/test_ast_parsing.py.
  3. Run python tests/e2e/solc_parsing/test_ast_parsing.py --compile. This will compile the artifact in tests/e2e/solc_parsing/compile. Add the compiled artifact to git.
  4. Run python tests/e2e/solc_parsing/test_ast_parsing.py --generate. This will generate the json artifacts in tests/e2e/solc_parsing/expected_json. Add the generated files to git.
  5. Run pytest tests/e2e/solc_parsing/test_ast_parsing.py and check that everything worked.

Tip: Filter with -k user_defined_value_type (filename), -k 0.8.12 (version), or -k legacy (format). Add --cov=slither/solc_parsing --cov-report=html for coverage.

Coordinating Changes with crytic-compile

Slither depends on crytic-compile for compilation. When making changes that require updates to both repos:

  1. Create a branch in crytic-compile with your changes
  2. Update slither's pyproject.toml to point to that branch: 
    "crytic-compile @ git+https://github.com/crytic/crytic-compile.git@your-branch"
  3. Create a PR in slither and verify CI passes
  4. After crytic-compile merges, update slither to use the released version