Term 3 Grants - Summary

🌱 ENS Ecosystem
16

Author’s note: this post is very similar to the earlier Announcement Post. Reposting it here to support an earlier request from the ENS Ecosystem WG.

Python ENS Normalize

What We Built

NameHash has built and open sourced a Python implementation of ENS Normalize.

This work is based on the new ENSIP-15 Normalize Standard and became the second implementation of this new standard, following the first reference implementation in Javascript.

What this impacts

This library enables Python developers to normalize ENS names!

With many Ethereum tools and libraries written in Python, the Python implementation of the ENS Normalize library makes it easier to integrate ENS into new and existing Python applications.

This means ENS just became even more accessible for developers around the world to incorporate into their applications :rocket:

In the end, we hope this helps to contribute to a bigger ENS community and wider ENS adoption !

Give it a try

The NameHash Python Implementation of ENS Normalize is now available here:

You can also try it in a Google Colab Notebook.

Why We Built It

NameHash is building a platform with fun new ways to discover and register ENS names. Some of these features required a Python implementation of the new ENS Normalize. None existed yet. So our team put a special effort into creating one. We’ve open sourced our results to help empower builders from all parts of the ENS and Web3 community. We’re excited to see what others will create with it !

NameHash contributions to the new ENS Normalize Standard

The journey to build a new ENS Normalization Standard has been a long one ! There’s been a large effort, led by raffy.eth, and involving many contributors, to advance this new standard. Our team has been closely following each step in this effort. For more than a year, each time there’s been updates to raffy.eth’s Javascript implementation, our team would implement parallel updates to this Python implementation.

In general we’ve been followers behind raffy.eth here. But we’ve also made an effort to positively influence the standard in a few ways. This includes:

  1. Advocated for inclusion of all characters regularly used in languages such as Polish which we think is valuable for future ENS adoption.
  2. Identified various bugs and provided suggested solutions.
  3. Proposed the need for ens_normalize_fragment which is important for substring searches of normalized names.

The Python library we’re open sourcing also includes a few new features that go beyond a minimal implementation of the standard:

  1. A carefully crafted glossary for some of the technical ideas related to ENS names.
  2. Optimized modeling of normalization errors, including detailed error information.
  3. Implemented “ens_cure” - an algorithm that can “cure” many normalization errors that would fail ens_normalize.
  4. Python documentation with real-world examples.
  5. A developer guide for improving and updating the Python library.

This library includes an exhaustive testing and validation effort to ensure compatibility with the standard:

  • Passes 100% of the official validation tests (validated automatically with pytest).
  • Passes an additional suite of further tests for compatibility with the official Javascript reference implementation.
  • Provides 100% code testing coverage.
  • Passes all of these tests across Linux, MacOS, and Windows.

The Python ENS Normalize library demonstrated there can be multiple mature implementations of the new ENS Normalization standard. We hope this library and the careful testing that went into its creation increased confidence for the ENS DAO when it approved the new ENSIP-15 ENS Normalize.

New Feature: ens_cure

This algorithm can “cure” many normalization errors that would fail ens_normalize. ens_cure is NOT a part of the ENS Normalization Standard, but might be a useful utility for some situations. For example, if a user input fails ens_normalize, a user could be prompted with a more helpful error message such as: “Did you mean curedname.eth?”. Here’s a Venn diagram (not to scale) that summarizes how ens_cure expands the set of input values that can be normalized.

ENS Normalize - Venn Diagram
ENS Normalize - Venn Diagram732Ă—732 23.9 KB

New Feature: Optimized modeling of normalization errors

Users just looking to normalize names in Python are free to ignore these new features and simply catch Python Exception objects with user-friendly messages.

As a quick summary: we’ve created a “hierarchy” for handling normalizations, cures, and errors:

  • A “normalizable sequence” which represents a change that must be made to the input name to confirm with the normalization standard, e.g. uppercase to lowercase conversion.
  • A “curable sequence” which represents an issue with the input name that is not normalizable through ens_normalize, but that might be resolved through a specific change suggestion in the input name, e.g. removing a space.
  • A “disallowed sequence” which represents an issue that cannot be cured through ens_cure automatically because it is challenging to describe the specific substring transformation that might be needed.

Full details on the optimized modeling of normalization errors can be in the GitHub repo.

This error hierarchy enabled our implementation of ens_cure:

  • ens_normalize automatically applies “normalizations”.
  • ens_cure automatically applies “normalizations” and “cures”.
  • “disallowed sequences” continue to be thrown from both ens_normalize and ens_cure.

Additional Resources Related to Python ENS Normalize

Other Popular Python libraries for web3

  • Web3.py: A Python library for interacting with the Ethereum blockchain, which provides functionality for sending transactions, querying data, and interacting with smart contracts.
  • Brownie: A Python-based development framework for building smart contracts and dApps on the Ethereum blockchain. It includes a built-in testing framework, an interactive console, and other tools for developing and deploying smart contracts.
  • eth-utils: A Python library that provides utility functions for working with Ethereum data types, such as addresses, hashes, and private keys.
  • eth-abi: A Python library that provides functions for encoding and decoding Ethereum contract ABI (Application Binary Interface) data.
  • py-solc-x: A Python library for compiling Solidity smart contracts into bytecode for deployment on the Ethereum blockchain.
2 Likes