ENT-2320 state contract identification (#4285)

* Enforce state/contract agreement validation

* Fix some broken tests

* Ascertain targetVersion by inspecting the jar source of the ContractState

* Docs added and rebased against master

* contextLogger doesn't work here

* Java examples in docs

* Label IRSState with owning contract

* Fix rst formatting

* Add @BelongsToContract annotation to PortfolioState

docs/source/api-contract-constraints.rst

@@ -62,6 +62,58 @@ consumes notary and ledger resources, and is just in general more complex.
 
 .. _implicit_constraint_types:
 
+Contract/State Agreement
+------------------------
+
+Starting with Corda 4, ``ContractState``s must explicitly indicate which ``Contract`` they belong to. When a transaction is
+verified, the contract bundled with each state in the transaction must be its "owning" contract, otherwise we cannot guarantee that
+the transition of the ``ContractState`` will be verified against the business rules that should apply to it.
+
+There are two mechanisms for indicating ownership. One is to annotate the ``ContractState`` with the ``BelongsToContract`` annotation,
+indicating the ``Contract`` class to which it is tied:
+
+.. sourcecode:: java
+
+    @BelongToContract(MyContract.class)
+    public class MyState implements ContractState {
+        // implementation goes here
+    }
+
+
+.. sourcecode:: kotlin
+
+    @BelongsToContract(MyContract::class)
+    data class MyState(val value: Int) : ContractState {
+        // implementation goes here
+    }
+
+
+The other is to define the ``ContractState`` class as an inner class of the ``Contract`` class
+
+.. sourcecode:: java
+
+    public class MyContract implements Contract {
+    
+        public static class MyState implements ContractState {
+            // state implementation goes here
+        }
+
+        // contract implementation goes here
+    }
+
+
+.. sourcecode:: kotlin
+
+    class MyContract : Contract {
+        data class MyState(val value: Int) : ContractState
+    }
+    
+
+If a ``ContractState``'s owning ``Contract`` cannot be identified by either of these mechanisms, and the ``targetVersion`` of the
+CorDapp is 4 or greater, then transaction verification will fail with a ``TransactionRequiredContractUnspecifiedException``. If
+the owning ``Contract`` _can_ be identified, but the ``ContractState`` has been bundled with a different contract, then
+transaction verification will fail with a ``TransactionContractConflictException``.
+
 How constraints work
 --------------------