Metadata-Version: 2.2
Name: ape-ens
Version: 0.8.2
Summary: ape-ens: Ape plugin for ENS argument conversion and contracts
Home-page: https://github.com/ApeWorX/ape-ens
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 :: Apache Software 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
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9,<4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: eth-ape<0.9,>=0.8.25
Requires-Dist: web3<8,>=6.20.1
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: ape-polygon; extra == "test"
Provides-Extra: lint
Requires-Dist: black<25,>=24.10.0; extra == "lint"
Requires-Dist: mypy<2,>=1.13.0; extra == "lint"
Requires-Dist: types-setuptools; extra == "lint"
Requires-Dist: flake8<8,>=7.1.1; extra == "lint"
Requires-Dist: flake8-breakpoint<2,>=1.1.0; extra == "lint"
Requires-Dist: flake8-print<6,>=5.0.0; 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.19; 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.2; extra == "lint"
Provides-Extra: doc
Requires-Dist: sphinx-ape; extra == "doc"
Provides-Extra: release
Requires-Dist: setuptools>=75.6.0; extra == "release"
Requires-Dist: setuptools-scm; extra == "release"
Requires-Dist: wheel; extra == "release"
Requires-Dist: twine; extra == "release"
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: ape-polygon; extra == "dev"
Requires-Dist: black<25,>=24.10.0; extra == "dev"
Requires-Dist: mypy<2,>=1.13.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: flake8<8,>=7.1.1; extra == "dev"
Requires-Dist: flake8-breakpoint<2,>=1.1.0; extra == "dev"
Requires-Dist: flake8-print<6,>=5.0.0; 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.19; 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.2; extra == "dev"
Requires-Dist: sphinx-ape; extra == "dev"
Requires-Dist: setuptools>=75.6.0; extra == "dev"
Requires-Dist: setuptools-scm; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: commitizen; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest-watch; extra == "dev"
Requires-Dist: IPython; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Quick Start

Ape plugin for ENS argument conversion and 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-ens
```

### 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-ens.git
cd ape-ens
python3 setup.py install
```

## Quick Usage

Ensure you are satisfied with your Ethereum mainnet setup in Ape, as this plugin requires a connection to Ethereum to resolve ENS domains.
More information on networks can be found in [Ape's network guide](https://docs.apeworx.io/ape/stable/userguides/networks.html#networks).

If using Ape and not connected to mainnet, `ape-ens` will temporarily connect to Ethereum mainnet to resolve addresses, using your default mainnet provider.

To configure a default mainnet provider, do:

```yaml
ethereum:
  mainnet:
    default_provider: alchemy  # Example, you can use any mainnet provider
```

Otherwise, the plugin should still work with Ape's defaults, using an RPC from the `evmchains` library.

This plugin contains two primary features:

- A conversion API implementation: this allows you to use ENS values in contract calls and transaction kwargs.
- a CLI for interacting with ENS from the command line.

### Conversion API

When this plugin is installed, you can use ENS names in contract-calls, and they resolve to the addresses automatically:

```python
from ape import accounts, Contract

ens_name = "vitalik.eth"  # Going to use this later...
contract = Contract("0x123...")
me = accounts.load("me")

# Ape resolves "me" to my account's address and "vitalik.eth" to Vitalik's Ethereum address.
# It is thanks to the ape-ens plugin that "vitalik.eth" works as a transaction input.
contract.transferFrom(me, ens_name, 100, sender=me)
```

You can use Ape's conversion utility directly:

```python
from ape import convert
from ape.types import AddressType

convert("vitalik.eth", AddressType)
# returns: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
```

Additionally, you can get the Ethereum Name Service (ENS) namehash using the `namehash` function:

```py
from ape_ens.utils import namehash

namehash("foo.eth")
# HexBytes("0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f")
```

### CLI

`ape-ens` comes with a CLI for using ENS.

Resolve ENS domains from the command line:

```shell
ape ens resolve vitalik.eth
# outputs: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

Reverse-lookup an ENS domain:

```shell
ape ens name 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# outputs: vitalik.eth
```

Get the owner of an ENS domain:

```shell
ape ens owner vitalik.eth
# outputs: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

Get the namehash of an ENS name:

```shell
ape ens namehash foo.eth
# outputs: 0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f
```

### Using `ape-ens` as a library.

You can also use the `ape_ens.ENS` class directly for programmatically referring to ENS.

```python
from ape_ens import ENS

ens = ENS()
vitalik = ens.resolve("vitalik.eth")
print(vitalik)
```

### Local registry

**WARNING**: By default, `ape-ens` caches results during each Python session for faster name resolution in scripts and testing.
Be careful using ENS names in long-running scripts where it would be bad if the name resolved differently in the future.
To disable caching, configure `ape-ens` to always read from Ethereum by adding to your `pyproject.toml`:

```toml
[tool.ape.ens]
use_cache = false
```

or using `ape-config.yaml`:

```yaml
ens:
  use_cache: false
```

To manually add entries to the cache, you can include them under the `registry:` key in the config:

```toml
[tool.ape.ens]
registry = { vitalik.eth = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }
```

or using `ape-config.yaml`:

```yaml
ens:
  registry:
    vitalik.eth: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
```

Configuring entries is useful for:

1. Testing in the `local` network.
2. Attaining faster performance (no Ethereum call).
3. Avoiding connecting to Ethereum mainnet.

### Change Registry

Change the registry contract address by configuring it in your `pyproject.toml`:

```toml
[tool.ape.ens]
registry_address = "0x123..."
```

or using `ape-config.yaml`:

```yaml
ens:
  registry_address: "0x123..."
```

You can also switch the registry adhoc during CLI commands:

```shell
ape ens resolve vitalik.eth --registry-address 0x123...311
```
