# 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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/ape-ens",
"name": "ape-ens",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/c3/28/b1992c60788e74578eb81835d610f38e50bed35e32c61abc1d3797fddfe8/ape_ens-0.8.2.tar.gz",
"platform": null,
"description": "# Quick Start\n\nApe plugin for ENS argument conversion and contracts\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install ape-ens\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/ape-ens.git\ncd ape-ens\npython3 setup.py install\n```\n\n## Quick Usage\n\nEnsure you are satisfied with your Ethereum mainnet setup in Ape, as this plugin requires a connection to Ethereum to resolve ENS domains.\nMore information on networks can be found in [Ape's network guide](https://docs.apeworx.io/ape/stable/userguides/networks.html#networks).\n\nIf using Ape and not connected to mainnet, `ape-ens` will temporarily connect to Ethereum mainnet to resolve addresses, using your default mainnet provider.\n\nTo configure a default mainnet provider, do:\n\n```yaml\nethereum:\n mainnet:\n default_provider: alchemy # Example, you can use any mainnet provider\n```\n\nOtherwise, the plugin should still work with Ape's defaults, using an RPC from the `evmchains` library.\n\nThis plugin contains two primary features:\n\n- A conversion API implementation: this allows you to use ENS values in contract calls and transaction kwargs.\n- a CLI for interacting with ENS from the command line.\n\n### Conversion API\n\nWhen this plugin is installed, you can use ENS names in contract-calls, and they resolve to the addresses automatically:\n\n```python\nfrom ape import accounts, Contract\n\nens_name = \"vitalik.eth\" # Going to use this later...\ncontract = Contract(\"0x123...\")\nme = accounts.load(\"me\")\n\n# Ape resolves \"me\" to my account's address and \"vitalik.eth\" to Vitalik's Ethereum address.\n# It is thanks to the ape-ens plugin that \"vitalik.eth\" works as a transaction input.\ncontract.transferFrom(me, ens_name, 100, sender=me)\n```\n\nYou can use Ape's conversion utility directly:\n\n```python\nfrom ape import convert\nfrom ape.types import AddressType\n\nconvert(\"vitalik.eth\", AddressType)\n# returns: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'\n```\n\nAdditionally, you can get the Ethereum Name Service (ENS) namehash using the `namehash` function:\n\n```py\nfrom ape_ens.utils import namehash\n\nnamehash(\"foo.eth\")\n# HexBytes(\"0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f\")\n```\n\n### CLI\n\n`ape-ens` comes with a CLI for using ENS.\n\nResolve ENS domains from the command line:\n\n```shell\nape ens resolve vitalik.eth\n# outputs: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n```\n\nReverse-lookup an ENS domain:\n\n```shell\nape ens name 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n# outputs: vitalik.eth\n```\n\nGet the owner of an ENS domain:\n\n```shell\nape ens owner vitalik.eth\n# outputs: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n```\n\nGet the namehash of an ENS name:\n\n```shell\nape ens namehash foo.eth\n# outputs: 0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f\n```\n\n### Using `ape-ens` as a library.\n\nYou can also use the `ape_ens.ENS` class directly for programmatically referring to ENS.\n\n```python\nfrom ape_ens import ENS\n\nens = ENS()\nvitalik = ens.resolve(\"vitalik.eth\")\nprint(vitalik)\n```\n\n### Local registry\n\n**WARNING**: By default, `ape-ens` caches results during each Python session for faster name resolution in scripts and testing.\nBe careful using ENS names in long-running scripts where it would be bad if the name resolved differently in the future.\nTo disable caching, configure `ape-ens` to always read from Ethereum by adding to your `pyproject.toml`:\n\n```toml\n[tool.ape.ens]\nuse_cache = false\n```\n\nor using `ape-config.yaml`:\n\n```yaml\nens:\n use_cache: false\n```\n\nTo manually add entries to the cache, you can include them under the `registry:` key in the config:\n\n```toml\n[tool.ape.ens]\nregistry = { vitalik.eth = \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\" }\n```\n\nor using `ape-config.yaml`:\n\n```yaml\nens:\n registry:\n vitalik.eth: \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\"\n```\n\nConfiguring entries is useful for:\n\n1. Testing in the `local` network.\n2. Attaining faster performance (no Ethereum call).\n3. Avoiding connecting to Ethereum mainnet.\n\n### Change Registry\n\nChange the registry contract address by configuring it in your `pyproject.toml`:\n\n```toml\n[tool.ape.ens]\nregistry_address = \"0x123...\"\n```\n\nor using `ape-config.yaml`:\n\n```yaml\nens:\n registry_address: \"0x123...\"\n```\n\nYou can also switch the registry adhoc during CLI commands:\n\n```shell\nape ens resolve vitalik.eth --registry-address 0x123...311\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "ape-ens: Ape plugin for ENS argument conversion and contracts",
"version": "0.8.2",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/ape-ens"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "451917a43e564196af76dedcfea6fdf07ab55b3da656a543a20ef71207879b80",
"md5": "3b84531acdc603d7dffeb25406693cd7",
"sha256": "cb36f3a2c10e0d348c7a116cbd666aad8d88f5bc2a149edbc42b20956b0df34b"
},
"downloads": -1,
"filename": "ape_ens-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b84531acdc603d7dffeb25406693cd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 14643,
"upload_time": "2025-02-08T00:08:22",
"upload_time_iso_8601": "2025-02-08T00:08:22.072986Z",
"url": "https://files.pythonhosted.org/packages/45/19/17a43e564196af76dedcfea6fdf07ab55b3da656a543a20ef71207879b80/ape_ens-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c328b1992c60788e74578eb81835d610f38e50bed35e32c61abc1d3797fddfe8",
"md5": "67b5571698e950c2793c2b3f59467247",
"sha256": "766ef3a244c90070f6f170530d0197cc7c8f33bc4997953e45b9367a2ed3923c"
},
"downloads": -1,
"filename": "ape_ens-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "67b5571698e950c2793c2b3f59467247",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 24737,
"upload_time": "2025-02-08T00:08:24",
"upload_time_iso_8601": "2025-02-08T00:08:24.513457Z",
"url": "https://files.pythonhosted.org/packages/c3/28/b1992c60788e74578eb81835d610f38e50bed35e32c61abc1d3797fddfe8/ape_ens-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 00:08:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "ape-ens",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ape-ens"
}
JSON
