From f17309fdb82dff412d5abefc0f25158fc553f1c2 Mon Sep 17 00:00:00 2001
From: Nick Gheorghita <nickgheorghita@gmail.com>
Date: Mon, 30 Mar 2020 16:08:49 -0500
Subject: [PATCH] Add examples of how to use ethpm for contract
 factories/instances

---
 docs/examples.rst          | 69 ++++++++++++++++++++++++++++++++++++++
 newsfragments/1617.doc.rst |  1 +
 2 files changed, 70 insertions(+)
 create mode 100644 newsfragments/1617.doc.rst

diff --git a/docs/examples.rst b/docs/examples.rst
index dde92106ca..482213ab93 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -301,6 +301,75 @@ Output:
      'transactionHash': HexBytes('0x3ac3518cc59d1698aa03a0bab7fb8191a4ef017aeda7429b11e8c6462b20a62a'),
      'transactionIndex': 0}
 
+Working with Contracts via ethPM
+--------------------------------
+
+`ethPM <http://www.ethpm.com/>`__ packages contained 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.
+You can find some available registries to explore in the `ethPM explorer <http://explorer.ethpm.com/>`__. 
+
+In this example we will use the ``ethregistrar@1.0.1`` 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
 ------------------------------------
diff --git a/newsfragments/1617.doc.rst b/newsfragments/1617.doc.rst
new file mode 100644
index 0000000000..f8da9710d4
--- /dev/null
+++ b/newsfragments/1617.doc.rst
@@ -0,0 +1 @@
+Add examples for using web3.contract via the ethpm module.