diff --git a/docs/source/api-contract-constraints.rst b/docs/source/api-contract-constraints.rst index 7aec4ac355..5dc16ef8c9 100644 --- a/docs/source/api-contract-constraints.rst +++ b/docs/source/api-contract-constraints.rst @@ -208,31 +208,27 @@ a flow: Contract attachment non-downgrade rule -------------------------------------- -Contract code is versioned and deployed as an independent jar that gets imported into a nodes database as a contract attachment (either explicitly -loaded via `rpc` or automatically loaded upon node startup for a given corDapp). When constructing new transactions it is paramount to ensure -that the contract version of code associated with new output states is the same or newer than the highest version of any existing inputs states. -This is to prevent the possibility of nodes from selecting older, potentially malicious or buggy, contract code when creating new states from existing consumed states. +Contract code is versioned and deployed as an independent JAR that gets imported into a node's database as a contract attachment (either explicitly +uploaded via RPC or automatically loaded from disk). When constructing new transaction it is paramount to ensure +that the contract version of code associated with new output states is the same or newer than the highest version of any existing input states. +This is to prevent the possibility of nodes selecting older, potentially malicious or buggy contract code when creating new states from +existing consumed states. Transactions contain an attachment for each contract. The version of the output states is the version of this contract attachment. -This can be seen as the version of code that instantiated and serialised those classes. +See :doc:`versioning` for more details on how these versions are set. These can be seen as the version of the code that instantiated and +serialised those classes. -The non-downgrade rule specifies that the version of the code used in the transaction that spends a state needs to be >= highest version of the -input states (eg. spending_version >= creation_version) +The non-downgrade rule specifies that the version of the code used in the transaction that spends a state needs to be greater than or equal to +the highest version of the input states (i.e. spending_version >= creation_version) -The Contract attachment non-downgrade rule is enforced in two locations: +The contract attachment non-downgrade rule is enforced in two locations: - - Transaction building, upon creation of new output states. During this step, the node also selects the latest available attachment - (eg. the contract code with the latest contract class version). - - Transaction verification, upon resolution of existing transaction chains +1. Transaction building, upon creation of new output states. During this step, the node also selects the latest available attachment + (i.e. the contract code with the latest contract class version). +2. Transaction verification, upon resolution of existing transaction chains. -A Contracts version identifier is stored in the manifest information of the enclosing jar file. This version identifier should be a whole number starting from 1. - -.. sourcecode:: groovy - - 'Cordapp-Contract-Name': "My contract name" - 'Cordapp-Contract-Version': 1 - -This information should be set using the Gradle cordapp plugin or manually as described in :ref:`CorDapp separation `. +A version number is stored in the manifest information of the enclosing JAR file. This version identifier should be a whole number starting +from 1. This information should be set using the Gradle cordapp plugin, or manually, as described in :doc:`versioning`. Issues when using the HashAttachmentConstraint ---------------------------------------------- diff --git a/docs/source/versioning.rst b/docs/source/versioning.rst index 0f0bd80dc7..90b436f465 100644 --- a/docs/source/versioning.rst +++ b/docs/source/versioning.rst @@ -96,4 +96,9 @@ It's entirely expected and reasonable to have an open source contracts module an sophisticated or proprietary business logic, machine learning models, even user interface code. There's nothing that restricts it to just being Corda flows or services. +.. important:: The ``versionId`` specified for the JAR manifest is checked by the platform. Downgrades are not allowed: you cannot take a state + that was created with version 5 of your app, and then create a state with version 4. This is to prevent attacks in which bugs + are fixed, but an adversary uses an old version of the app to continue exploiting them. Version tracking in states is handled for you + automatically as long as the information is provided in your Gradle file. See ":ref:`contract_non-downgrade_rule_ref`" for more information. + .. note:: You can read the original design doc here: :doc:`design/targetversion/design`. \ No newline at end of file