Metadata-Version: 2.1
Name: ape-solidity
Version: 0.8.5
Summary: Plugin for Ape Ethereum Framework for compiling Solidity contracts
Home-page: https://github.com/ApeWorX/ape-solidity
Author: ApeWorX Ltd.
Author-email: admin@apeworx.io
License: Apache-2.0
Keywords: ethereum
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: py-solc-x<3,>=2.0.2
Requires-Dist: eth-ape<0.9,>=0.8.4
Requires-Dist: ethpm-types
Requires-Dist: eth-pydantic-types
Requires-Dist: packaging
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: hypothesis<7.0,>=6.2.0; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: black<25,>=24.10.0; extra == "dev"
Requires-Dist: mypy<2,>=1.13.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: flake8<8,>=7.1.1; extra == "dev"
Requires-Dist: flake8-pydantic; extra == "dev"
Requires-Dist: flake8-type-checking; extra == "dev"
Requires-Dist: isort<6,>=5.13.2; extra == "dev"
Requires-Dist: mdformat>=0.7.18; extra == "dev"
Requires-Dist: mdformat-gfm>=0.3.5; extra == "dev"
Requires-Dist: mdformat-frontmatter>=0.4.1; extra == "dev"
Requires-Dist: mdformat-pyproject>=0.0.1; extra == "dev"
Requires-Dist: Sphinx<7,>=6.1.3; extra == "dev"
Requires-Dist: sphinx-rtd-theme<2,>=1.2.0; extra == "dev"
Requires-Dist: towncrier<20,>=19.2.0; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: setuptools-scm; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine==3.8; extra == "dev"
Requires-Dist: commitizen; extra == "dev"
Requires-Dist: pytest-watch; extra == "dev"
Requires-Dist: IPython; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Provides-Extra: doc
Requires-Dist: Sphinx<7,>=6.1.3; extra == "doc"
Requires-Dist: sphinx-rtd-theme<2,>=1.2.0; extra == "doc"
Requires-Dist: towncrier<20,>=19.2.0; extra == "doc"
Provides-Extra: lint
Requires-Dist: black<25,>=24.10.0; extra == "lint"
Requires-Dist: mypy<2,>=1.13.0; extra == "lint"
Requires-Dist: types-requests; extra == "lint"
Requires-Dist: types-setuptools; extra == "lint"
Requires-Dist: flake8<8,>=7.1.1; extra == "lint"
Requires-Dist: flake8-pydantic; extra == "lint"
Requires-Dist: flake8-type-checking; extra == "lint"
Requires-Dist: isort<6,>=5.13.2; extra == "lint"
Requires-Dist: mdformat>=0.7.18; extra == "lint"
Requires-Dist: mdformat-gfm>=0.3.5; extra == "lint"
Requires-Dist: mdformat-frontmatter>=0.4.1; extra == "lint"
Requires-Dist: mdformat-pyproject>=0.0.1; extra == "lint"
Provides-Extra: release
Requires-Dist: setuptools; extra == "release"
Requires-Dist: setuptools-scm; extra == "release"
Requires-Dist: wheel; extra == "release"
Requires-Dist: twine==3.8; extra == "release"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: hypothesis<7.0,>=6.2.0; extra == "test"
Requires-Dist: pytest-benchmark; extra == "test"

# Quick Start

Compile Solidity contracts.

## Dependencies

- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.

## Installation

### via `pip`

You can install the latest release via [`pip`](https://pypi.org/project/pip/):

```bash
pip install ape-solidity
```

### via `setuptools`

You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:

```bash
git clone https://github.com/ApeWorX/ape-solidity.git
cd ape-solidity
python3 setup.py install
```

## Quick Usage

In your project, make sure you have a `contracts/` directory containing Solidity files (`.sol`).

Then, while this plugin is installed, compile your contracts:

```bash
ape compile
```

The byte-code and ABI for your contracts should now exist in a `__local__.json` file in a `.build/` directory.

### Solidity Versioning

By default, `ape-solidity` tries to use the best versions of Solidity by looking at all the source files' pragma specifications.
However, it is often better to specify a version directly.
If you know the best version to use, set it in your `ape-config.yaml`, like this:

```yaml
solidity:
  version: 0.8.14
```

### EVM Versioning

By default, `ape-solidity` will use whatever version of EVM rules are set as default in the compiler version that gets used.
Sometimes, you might want to use a different version, such as deploying on Arbitrum or Optimism where new opcodes are not supported yet.
If you want to require a different version of EVM rules to use in the configuration of the compiler, set it in your `ape-config.yaml` like this:

```yaml
solidity:
  evm_version: paris
```

### Dependency Mapping

By default, `ape-solidity` knows to look at installed dependencies for potential remapping-values and will use those when it notices you are importing them.
For example, if you are using dependencies like:

```yaml
dependencies:
  - name: openzeppelin
    github: OpenZeppelin/openzeppelin-contracts
    version: 4.4.2
```

And your source files import from `openzeppelin` this way:

```solidity
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
```

Ape knows how to resolve the `@openzeppelin` value and find the correct source.

If you want to override this behavior or add new remappings that are not dependencies, you can add them to your `ape-config.yaml` under the `solidity:` key.
For example, let's say you have downloaded `openzeppelin` somewhere and do not have it installed in Ape.
You can map to your local install of `openzeppelin` this way:

```yaml
solidity:
  import_remapping:
    - "@openzeppelin=path/to/openzeppelin"
```

### Library Linking

To compile contracts that use libraries, you need to add the libraries first.
Use the `add_library()` method from the `ape-solidity` compiler class to add the library.
A typical flow is:

1. Deploy the library.
2. Call `add_library()` using the Solidity compiler plugin, which will also re-compile contracts that need the library.
3. Deploy and use contracts that require the library.

For example:

```python
import pytest


@pytest.fixture
def contract(accounts, project, compilers):
    # Deploy the library.
    account = accounts[0]
    library = project.Set.deploy(sender=account)

    # Add the library to Solidity (re-compiles contracts that use the library).
    compilers.solidity.add_library(library)

    # Deploy the contract that uses the library.
    return project.C.deploy(sender=account)
```

### Compiler Settings

When using `ape-solidity`, your project's manifest's compiler settings will include standard JSON output.
You should have one listed `compiler` per `solc` version used in your project.
You can view your current project manifest, including the compiler settings, by doing:

```python
from ape import project

manifest = project.extract_manifest()

for compiler_entry in manifest.compilers:
    print(compiler_entry.version)
    print(compiler_entry.settings)
```

**NOTE**: These are the settings used during contract verification when using the [Etherscan plugin](https://github.com/ApeWorX/ape-etherscan).

#### `--via-IR` Yul IR Compilation Pipeline

You can enable `solc`'s `--via-IR` flag by adding the following values to your `ape-config.yaml`

```yaml
solidity:
  via_ir: True
```

### Contract Flattening

`ape-solidity` has contract-flattening capabilities.
If you are publishing contracts using Ape, Ape automatically detects and uses the flattened-contract approach if needed.

To manually flatten a contract for your own benefit, use the following code:

```python
from ape import compilers, project

source_path = project.source_paths[0]  # Replace with your path.
flattened_src = compilers.flatten_contract(source_path)
print(str(flattened_src))
```
