diff --git a/docs/source/cordapp-build-systems.rst b/docs/source/cordapp-build-systems.rst
index 5ddfe945d2..5444790601 100644
--- a/docs/source/cordapp-build-systems.rst
+++ b/docs/source/cordapp-build-systems.rst
@@ -527,29 +527,48 @@ For a CorDapp that contains flows and/or services we specify the `workflow` tag:
 CorDapp Contract Attachments
 ----------------------------
 
-As of Corda 4, CorDapp Contract JARs must be installed on a node by a trusted uploader, either by
+As of Corda 4, because there is no Sandbox to run the verification code we require that any jar with code that is downloaded from a peer to be
+checked and explicitly whitelisted by the node operator. CorDapp contract JARs must be installed on a node by a trusted uploader, by
 
 - installing manually as per :ref:`Installing the CorDapp JAR <cordapp_install_ref>` and re-starting the node.
 
 - uploading the attachment JAR to the node via RPC, either programmatically (see :ref:`Connecting to a node via RPC <clientrpc_connect_ref>`)
-  or via the :doc:`shell` by issuing the following command:
 
-``>>> run uploadAttachment jar: path/to/the/file.jar``
-
-Contract attachments that are received from a peer over the p2p network are considered **untrusted** and will throw a `UntrustedAttachmentsException` exception
-when processed by a listening flow that cannot resolve that attachment from its local attachment storage. The flow will be aborted and sent to the nodes flow hospital for recovery and retry.
-The untrusted attachment JAR will be stored in the nodes local attachment store for review by a node operator. It can be downloaded for viewing using the following CRaSH shell command:
-
-``>>> run openAttachment id: <hash of untrusted attachment given by `UntrustedAttachmentsException` exception``
-
-Should the node operator deem the attachment trustworthy, they may then issue the following CRaSH shell command to reload it as trusted:
-
-``>>> run uploadAttachment jar: path/to/the/trusted-file.jar``
-
-and subsequently retry the failed flow (currently this requires a node re-start).
+Which method to use depends on the reason for installing the CorDapp and is detailed below.
 
 .. note:: this behaviour is to protect the node from executing contract code that was not vetted. It is a temporary precaution until the
    Deterministic JVM is integrated into Corda whereby execution takes place in a sandboxed environment which protects the node from malicious code.
 
 
+Installing Contract Attachments for Previously Unknown CorDapps
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+When you are processing a transaction that contains states that need to be verified by contracts in CorDapps not currently installed on the node, the
+Contract attachment will be received from a peer over the p2p network. CorDapps received this way are considered **untrusted** and will throw an `UntrustedAttachmentsException`
+when processed by a listening flow that cannot resolve that attachment from its local attachment storage. The flow will be aborted and sent to the nodes flow hospital for recovery and retry.
+The untrusted attachment JAR will be stored in the nodes local attachment store for review by a node operator. It can be downloaded for viewing using the following CRaSH shell command:
+
+``>>> run openAttachment id: <hash of untrusted attachment given by `UntrustedAttachmentsException` exception``
+
+Should the node operator deem the attachment trustworthy, they may then install the CorDapp JAR in the node (see :ref:`Installing the CorDapp JAR <cordapp_install_ref>`)
+and subsequently retry the failed flow. Currently this requires a node-restart which will automatically retry the failed flows.
+
+.. note:: from Corda 4.1 you will also be able to upload the attachment to the store, as described below.
+
+Installing Contract Attachments for Older Versions of CorDapps
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to install older versions of a CorDapp in order to verify chains of states created with older versions of a contract, you can upload the
+older CorDapp to the attachment store. Placing the older CorDapp in the ``cordapps`` directory will not work in this case,
+as you can only have one CorDapp loaded per contract. The latest version of the CorDapp should be the one installed in the ``cordapps`` folder.
+
+As above, the untrusted attachment JAR will be stored in the nodes local attachment store for review by a node operator. It can be downloaded for
+viewing using the following CRaSH shell command:
+
+``>>> run openAttachment id: <hash of untrusted attachment given by `UntrustedAttachmentsException` exception``
+
+Should the node operator deem the attachment trustworthy, they may then issue the following CRaSH shell command to reload it as trusted:
+
+ ``>>> run uploadAttachment jar: path/to/the/trusted-file.jar``
+
+and subsequently retry the failed flow. Currently this requires a node-restart which will automatically retry the failed flows.