Contributing

We actively welcome contributions to uniswap-python! Whether you are fixing a bug, adding support for a new Layer-2 deployment, or improving the documentation, your efforts help the community.

Repository Architecture

Before contributing, it is helpful to understand the layout of the project:

uniswap/uniswap.py: The core logic class. This file is large and handles routing logic, transaction building, and ABI parsing across all three protocol versions.
uniswap/assets/: Contains raw .abi files for Uniswap smart contracts (V1, V2, V3, and generic ERC20 interfaces). If you are adding new contract interactions, you may need to update these.
tests/: A comprehensive pytest suite. It tests functionality by communicating with a local Ethereum fork.

Development Environment Setup

We use Poetry to enforce dependency versions and handle builds.

Clone the repository:

git clone https://github.com/uniswap-python/uniswap-python.git
cd uniswap-python

Install dependencies: This command creates a virtual environment and installs all runtime and developer dependencies.
```
poetry install
```

Running the Test Suite

Because interactions with Uniswap require deep blockchain state (liquidity pools, tick bitmaps), mocking the tests is impractical. Instead, we run tests against a live fork of Ethereum Mainnet using ganache.

Install Ganache: Ensure you have ganache globally installed via Node.js (Node 12+ recommended).
```
npm install -g [email protected]
```
Set your Provider: The test suite requires an archive-capable RPC endpoint to fork the blockchain state.
```
export PROVIDER="https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID"
```
Execute the Tests: We use standard Make targets to run the suite.
```
make test
```
If you need to debug a specific test or see print statements, bypass Make and use pytest directly:
```
poetry run pytest --capture=no -k "test_name_here"
```

Code Quality & Standards

All pull requests are evaluated in our CI/CD pipeline using GitHub Actions. Before submitting, ensure your code passes our strict linting and type-checking rules.

Static Type Checking (MyPy): We heavily utilize Python type hints (AddressLike, Wei, etc.). Ensure no typing errors exist.
```
make typecheck
```
Linting and Formatting: We use black for formatting and flake8 for linting.
```
make lint
make format
```
Run all Pre-commit Checks: Run everything together to ensure your PR will pass the CI pipeline.
```
make precommit
```

Pull Request Guidelines

Keep it focused: Submit separate PRs for separate features or fixes.
Update tests: If you add new functionality (e.g., interacting with a new V3 peripheral contract), add a corresponding test case in tests/test_uniswap.py.
Update Documentation: If your feature changes the public API, update the appropriate markdown files.