Add examples of how to use ethpm for contract factories/instances

docs/examples.rst

@@ -301,6 +301,75 @@ Output:
      'transactionHash': HexBytes('0x3ac3518cc59d1698aa03a0bab7fb8191a4ef017aeda7429b11e8c6462b20a62a'),
      'transactionIndex': 0}
 
+Working with Contracts via ethPM
+--------------------------------
+
+`ethPM <http://www.ethpm.com/>`__ packages contain configured contracts ready for use. Web3's ``ethpm`` module (``web3.pm``)
+extends Web3's native ``Contract`` module, with a few modifications for how you instantiate ``Contract`` factories and instances.
+
+All you need is the package name, version and ethPM registry address for the package you wish to use.
+An ethPM registry is essentially an on-chain datastore for the release data associated with an ethPM package. You can find some sample registries to explore in the `ethPM explorer <http://explorer.ethpm.com/>`__. Remember, you should only use packages from registries whose maintainer you trust not to inject malicious code!
+
+In this example we will use the ``[email protected]`` package sourced from the ``ens.snakecharmers.eth`` registry.
+
+``web3.pm`` uses the ``Package`` class to represent an ethPM package. This object houses all of the contract assets
+within a package, and exposes them via an API. So, before we can interact with our package, we need to generate
+it as a ``Package`` instance.
+
+.. code-block:: python3
+
+    from web3.auto.infura import w3
+
+    # Note. To use the web3.pm module, you will need to instantiate your w3 instance
+    # with a web3 provider connected to the chain on which your registry lives.
+
+    # The ethPM module is still experimental and subject to change,
+    # so for now we need to enable it via a temporary flag.
+    w3.enable_unstable_package_management_api()
+
+    # Then we need to set the registry address that we want to use.
+    # This should be an ENS address, but can also be a checksummed contract address.
+    w3.pm.set_registry("ens.snakecharmers.eth")
+
+    # This generates a Package instance of the target ethPM package.
+    ens_package = w3.pm.get_package("ethregistrar", "1.0.1")
+
+
+Now that we have a ``Package`` representation of our target ethPM package, we can generate contract factories 
+and instances from this ``Package``. However, it's important to note that some packages might be missing
+the necessary contract assets needed to generate an instance or a factory. You can use the
+`ethPM explorer <http://explorer.ethpm.com/>`__ to figure out the names of the contract types and deployments
+available within an ethPM package.
+
+.. code-block:: python3
+
+    # To interact with a deployment located in an ethPM package.
+    # Note. This will only expose deployments located on the
+    # chain of the connected provider (in this example, mainnet)
+    mainnet_registrar = ens_package.deployments.get_instance("BaseRegistrarImplementation")
+
+    # Now you can treat mainnet_registrar like any other Web3 Contract instance!
+    mainnet_registrar.caller.balanceOf("0x123...")
+    > 0
+
+    mainnet_registrar.functions.approve("0x123", 100000).transact()
+    > 0x123abc...  # tx_hash
+
+    # To create a contract factory from a contract type located in an ethPM package.
+    registrar_factory = ens_package.get_contract_factory("BaseRegistrarImplementation")
+
+    # Now you can treat registrar_factory like any other Web3 Contract factory to deploy new instances!
+    # Note. This will deploy new instances to the chain of the connected provider (in this example, mainnet)
+    registrar_factory.constructor(...).transact()
+    > 0x456def...  # tx_hash
+
+    # To connect your Package to a new chain - simply pass it a new Web3 instance
+    # connected to your provider of choice. Now your factories will automatically
+    # deploy to this new chain, and the deployments available on a package will
+    # be automatically filtered to those located on the new chain.
+    from web3.auto.infura.goerli import w3 as goerli_w3
+    goerli_registrar = ens_package.update_w3(goerli_w3)
+
 
 Working with an ERC20 Token Contract
 ------------------------------------

newsfragments/1617.doc.rst

@@ -0,0 +1 @@
+Add examples for using web3.contract via the ethpm module.