Updates to ENS documentation

Author: fselmo

docs/ens_overview.rst

@@ -1,7 +1,7 @@
 .. _ens_overview:
 
 Ethereum Name Service
-================================
+=====================
 
 The Ethereum Name Service is analogous to the Domain Name Service. It
 enables users and developers to use human-friendly names in place of error-prone
@@ -19,138 +19,121 @@ Create an :class:`~ens.main.ENS` object (named ``ns`` below) in one of three way
 2. Specify an instance or list of :ref:`providers`
 3. From an existing :class:`web3.Web3` object
 
-::
+.. code-block:: python
 
     # automatic detection
     from ens.auto import ns
 
-
     # or, with a provider
     from web3 import IPCProvider
     from ens import ENS
 
     provider = IPCProvider(...)
     ns = ENS(provider)
 
-
     # or, with a w3 instance
     # Note: This inherits the w3 middlewares from the w3 instance and adds a stalecheck middleware to the middleware onion
     from ens import ENS
-
     w3 = Web3(...)
     ns = ENS.fromWeb3(w3)
 
 
 Usage
 -----
 
-Name info
+Name Info
 ~~~~~~~~~
 
 .. _ens_get_address:
 
-Look up the address for an ENS name
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Get the Address for an ENS Name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     from ens.auto import ns
-
-
-    # look up the hex representation of the address for a name
-
     eth_address = ns.address('jasoncarver.eth')
-
     assert eth_address == '0x5B2063246F2191f18F2675ceDB8b28102e957458'
 
-
 The ``ENS`` module has no opinion as to which TLD you can use,
 but will not infer a TLD if it is not provided with the name.
 
 
-Get name from address
-^^^^^^^^^^^^^^^^^^^^^
+Get the Name for an ENS Address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     domain = ns.name('0x5B2063246F2191f18F2675ceDB8b28102e957458')
 
-
     # name() also accepts the bytes version of the address
-
     assert ns.name(b'[ c$o!\x91\xf1\x8f&u\xce\xdb\x8b(\x10.\x95tX') == domain
 
-
     # confirm that the name resolves back to the address that you looked up:
-
     assert ns.address(domain) == '0x5B2063246F2191f18F2675ceDB8b28102e957458'
 
-Get owner of name
-^^^^^^^^^^^^^^^^^
+.. note:: The ``ENS`` module verifies the forward resolution matches the address when retrieving a ``name()`` for an
+    address as this is the only sure way to know whether the reverse resolution is correct. Anyone can claim
+    any name, only forward resolution implies that the owner of the name gave their stamp of approval.
+
+Get the Owner of a Name
+^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     eth_address = ns.owner('exchange.eth')
 
-Set up your name
-~~~~~~~~~~~~~~~~
 
-Point your name to your address
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Set Up Your Name and Address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Do you want to set up your name so that :meth:`~ens.main.ENS.address` will show the
-address it points to?
+Link a Name to an Address
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+You can set up your name so that :meth:`~ens.main.ENS.address` will show the address it points to. In order to do so,
+you must already be the owner of the domain (or its parent).
 
-    ns.setup_address('jasoncarver.eth', '0x5B2063246F2191f18F2675ceDB8b28102e957458')
+.. code-block:: python
 
-You must already be the owner of the domain (or its parent).
+    ns.setup_address('jasoncarver.eth', '0x5B2063246F2191f18F2675ceDB8b28102e957458')
 
-In the common case where you want to point the name to the owning
-address, you can skip the address
+In the common case where you want to point the name to the owning address, you can skip the address.
 
-::
+.. code-block:: python
 
     ns.setup_address('jasoncarver.eth')
 
-You can claim arbitrarily deep subdomains. *Gas costs scale up with the
-number of subdomains!*
+You can claim arbitrarily deep subdomains.
 
-::
+.. code-block:: python
 
     ns.setup_address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth')
 
-Wait for the transaction to be mined, then:
+    # wait for the transaction to be mined, then:
+    assert (
+        ns.address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth')
+        == '0x5B2063246F2191f18F2675ceDB8b28102e957458'
+    )
 
-::
+.. warning:: Gas costs scale up with the number of subdomains!
 
-    assert ns.address('supreme.executive.power.derives.from.a.mandate.from.the.masses.jasoncarver.eth') == \
-        '0x5B2063246F2191f18F2675ceDB8b28102e957458'
 
-Allow people to find your name using your address
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Link an Address to a Name
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Do you want to set up your address so that :meth:`~ens.main.ENS.name` will show the
-name that points to it?
+You can set up your address so that :meth:`~ens.main.ENS.name` will show the name that points to it.
 
-This is like Caller ID. It enables you and others to take an account and
-determine what name points to it. Sometimes this is referred to as
-"reverse" resolution.
+This is like Caller ID. It enables you and others to take an account and determine what name points to it. Sometimes
+this is referred to as "reverse" resolution since it uses the ENS Reverse Resolver for this functionality.
 
-::
+.. code-block:: python
 
     ns.setup_name('jasoncarver.eth', '0x5B2063246F2191f18F2675ceDB8b28102e957458')
 
-.. note:: Do not rely on reverse resolution for security.
-
-  Anyone can claim any "caller ID". Only forward resolution implies that
-  the owner of the name gave their stamp of approval.
-
 If you don't supply the address, :meth:`~ens.main.ENS.setup_name` will assume you want the
 address returned by :meth:`~ens.main.ENS.address`.
 
-::
+.. code-block:: python
 
     ns.setup_name('jasoncarver.eth')
 
@@ -159,26 +142,30 @@ call :meth:`~ens.main.ENS.setup_address` for you.
 
 Wait for the transaction to be mined, then:
 
-::
+.. code-block:: python
 
     assert ns.name('0x5B2063246F2191f18F2675ceDB8b28102e957458') == 'jasoncarver.eth'
 
+
+Text Records
+~~~~~~~~~~~~
+
 Set Text Metadata for an ENS Record
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As the owner of an ENS record, you can add text metadata.
 A list of supported fields can be found in the
 `ENS documentation <https://docs.ens.domains/contract-api-reference/publicresolver#get-text-data>`_.
 You'll need to setup the address first, and then the text can be set:
 
-::
+.. code-block:: python
 
     ns.setup_address('jasoncarver.eth', 0x5B2063246F2191f18F2675ceDB8b28102e957458)
     ns.set_text('jasoncarver.eth', 'url', 'https://example.com')
 
 A transaction dictionary can be passed as the last argument if desired:
 
-::
+.. code-block:: python
 
     transaction_dict = {'from': '0x123...'}
     ns.set_text('jasoncarver.eth', 'url', 'https://example.com', transaction_dict)
@@ -187,12 +174,61 @@ If the transaction dictionary is not passed, sensible defaults will be used, and
 a transaction dictionary is passed but does not have a ``from`` value,
 the default will be the ``owner``.
 
+
 Read Text Metadata for an ENS Record
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Anyone can read the data from an ENS Record:
 
-::
+.. code-block:: python
 
     url = ns.get_text('jasoncarver.eth', 'url')
     assert url == 'https://example.com'
+
+
+Working With Resolvers
+~~~~~~~~~~~~~~~~~~~~~~
+
+Get the Resolver for an ENS Record
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can get the resolver for an ENS name via the :meth:`~ens.main.ENS.resolver` method.
+
+.. code-block:: python
+
+    >>> resolver = ns.resolver('jasoncarver.eth')
+    >>> resolver.address
+    '0x5FfC014343cd971B7eb70732021E26C35B744cc4'
+
+
+Wildcard Resolution Support
+---------------------------
+
+The ``ENS`` module supports Wildcard Resolution for resolvers that implement the ``ExtendedResolver`` interface
+as described in `ENSIP-10 <https://docs.ens.domains/ens-improvement-proposals/ensip-10-wildcard-resolution>`_.
+Resolvers that implement the extended resolver interface should return ``True`` when calling the
+``supportsInterface()`` function with the extended resolver interface id ``0x9061b923`` and should resolve subdomains
+to a unique address.
+
+A working example of a resolver that supports wildcard resolution is the resolver for the ``hatch.eth`` record on the
+Ropsten testnet.
+
+.. code-block:: python
+
+    # connect to the Ropsten testnet
+    >>> w3 = Web3(WebsocketProvider("wss://{ropsten_provider}"))
+    >>> ns = ENS.fromWeb3(w3)
+
+    # get the resolver for `hatch.eth`
+    >>> resolver = ns.resolver('hatch.eth')
+    >>> resolver.address
+    '0x8fc4C380c5d539aE631daF3Ca9182b40FB21D1ae'
+
+    # verify extended resolver interface support
+    >>> resolver.caller.supportsInterface('0x9061b923')
+    True
+
+    >>> ns.address('random-subdomain.hatch.eth')
+    '0x49D4c4ff230688e4A357bc057e7E35e64d271939'
+    >>> ns.address('another-random-subdomain.hatch.eth')
+    '0xb35359B6450B0CbC9BE15A4eE6bcb8c5b0d9fC4A'