Ports docs changes on V1 since V2 was cut.

* Documents the LegalProseReference annotation. Minor tweaks.

* Updates flow cookbook to use freshKeyAndCert not freshKey.

* Addresses review comments.

docs/source/api-contracts.rst

@@ -11,8 +11,8 @@ API: Contracts
 
 .. contents::
 
-Contract
+The Contract interface
---------
+----------------------
 Contracts are classes that implement the ``Contract`` interface. The ``Contract`` interface is defined as follows:
 
 .. container:: codeset
@@ -22,6 +22,8 @@ Contracts are classes that implement the ``Contract`` interface. The ``Contract`
         :start-after: DOCSTART 5
         :end-before: DOCEND 5
 
+verify
+^^^^^^
 ``Contract`` has a single method, ``verify``, which takes a ``LedgerTransaction`` as input and returns
 nothing. This function is used to check whether a transaction proposal is valid, as follows:
 
@@ -78,7 +80,7 @@ Here are the two simplest ``verify`` functions:
 
 LedgerTransaction
 -----------------
-The ``LedgerTransaction`` object passed into ``verify`` has the following properties:
+The ``LedgerTransaction`` instance passed into ``verify`` has the following properties:
 
 .. container:: codeset
 
@@ -233,4 +235,35 @@ the single command of type ``XContract.Commands`` from the transaction, and bran
                     // Transfer verification logic.
                 }
             }
+        }
+
+Legal prose
+-----------
+A ``Contract`` class can be annotated with the ``@LegalProseReference`` annotation. This annotation associates the
+contract with a document that restates the constraints imposed by ``verify`` in legal prose terms. This is not
+required, but can be useful in contexts where it is expected that legal contracts will take precedence over the
+software implementations in case of disagreement.
+
+``@LegalProseReference`` takes a single parameter, ``uri``, which identifies the legal prose document the contract is
+associated with:
+
+.. container:: codeset
+
+   .. sourcecode:: kotlin
+
+        @LegalProseReference(uri = "foo.bar.com/my-legal-doc.html")
+        class MyContract : Contract {
+            override fun verify(tx: LedgerTransaction) {
+                // Contract logic.
+            }
+        }
+
+   .. sourcecode:: java
+
+        @LegalProseReference(uri = "foo.bar.com/my-legal-doc.html")
+        public class MyContract implements Contract {
+            @Override
+            public void verify(LedgerTransaction tx) {
+                // Contract logic.
+            }
         }

docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java

@@ -8,6 +8,7 @@ import net.corda.core.crypto.TransactionSignature;
 import net.corda.core.flows.*;
 import net.corda.core.identity.CordaX500Name;
 import net.corda.core.identity.Party;
+import net.corda.core.identity.PartyAndCertificate;
 import net.corda.core.internal.FetchDataFlow;
 import net.corda.core.node.services.Vault;
 import net.corda.core.node.services.Vault.Page;
@@ -403,8 +404,8 @@ public class FlowCookbookJava {
             // DOCEND 29
             // We can also sign the transaction using a different public key:
             // DOCSTART 30
-            PublicKey otherKey = getServiceHub().getKeyManagementService().freshKey();
+            PartyAndCertificate otherIdentity = getServiceHub().getKeyManagementService().freshKeyAndCert(getOurIdentityAndCert(), false);
-            SignedTransaction onceSignedTx2 = getServiceHub().signInitialTransaction(txBuilder, otherKey);
+            SignedTransaction onceSignedTx2 = getServiceHub().signInitialTransaction(txBuilder, otherIdentity.getOwningKey());
             // DOCEND 30
 
             // If instead this was a ``SignedTransaction`` that we'd received
@@ -414,9 +415,9 @@ public class FlowCookbookJava {
             SignedTransaction twiceSignedTx = getServiceHub().addSignature(onceSignedTx);
             // DOCEND 38
             // Or, if we wanted to use a different public key:
-            PublicKey otherKey2 = getServiceHub().getKeyManagementService().freshKey();
+            PartyAndCertificate otherIdentity2 = getServiceHub().getKeyManagementService().freshKeyAndCert(getOurIdentityAndCert(), false);
             // DOCSTART 39
-            SignedTransaction twiceSignedTx2 = getServiceHub().addSignature(onceSignedTx, otherKey2);
+            SignedTransaction twiceSignedTx2 = getServiceHub().addSignature(onceSignedTx, otherIdentity2.getOwningKey());
             // DOCEND 39
 
             // We can also generate a signature over the transaction without
@@ -430,7 +431,7 @@ public class FlowCookbookJava {
             // DOCEND 40
             // And again, if we wanted to use a different public key:
             // DOCSTART 41
-            TransactionSignature sig2 = getServiceHub().createSignature(onceSignedTx, otherKey2);
+            TransactionSignature sig2 = getServiceHub().createSignature(onceSignedTx, otherIdentity2.getOwningKey());
             // DOCEND 41
 
             /*----------------------------

docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt

@@ -9,6 +9,7 @@ import net.corda.core.crypto.TransactionSignature
 import net.corda.core.flows.*
 import net.corda.core.identity.CordaX500Name
 import net.corda.core.identity.Party
+import net.corda.core.identity.PartyAndCertificate
 import net.corda.core.internal.FetchDataFlow
 import net.corda.core.node.services.Vault.Page
 import net.corda.core.node.services.queryBy
@@ -390,8 +391,8 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty:
         // DOCEND 29
         // We can also sign the transaction using a different public key:
         // DOCSTART 30
-        val otherKey: PublicKey = serviceHub.keyManagementService.freshKey()
+        val otherIdentity: PartyAndCertificate = serviceHub.keyManagementService.freshKeyAndCert(ourIdentityAndCert, false)
-        val onceSignedTx2: SignedTransaction = serviceHub.signInitialTransaction(txBuilder, otherKey)
+        val onceSignedTx2: SignedTransaction = serviceHub.signInitialTransaction(txBuilder, otherIdentity.owningKey)
         // DOCEND 30
 
         // If instead this was a ``SignedTransaction`` that we'd received
@@ -401,9 +402,9 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty:
         val twiceSignedTx: SignedTransaction = serviceHub.addSignature(onceSignedTx)
         // DOCEND 38
         // Or, if we wanted to use a different public key:
-        val otherKey2: PublicKey = serviceHub.keyManagementService.freshKey()
+        val otherIdentity2: PartyAndCertificate = serviceHub.keyManagementService.freshKeyAndCert(ourIdentityAndCert, false)
         // DOCSTART 39
-        val twiceSignedTx2: SignedTransaction = serviceHub.addSignature(onceSignedTx, otherKey2)
+        val twiceSignedTx2: SignedTransaction = serviceHub.addSignature(onceSignedTx, otherIdentity2.owningKey)
         // DOCEND 39
 
         // We can also generate a signature over the transaction without
@@ -417,7 +418,7 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty:
         // DOCEND 40
         // And again, if we wanted to use a different public key:
         // DOCSTART 41
-        val sig2: TransactionSignature = serviceHub.createSignature(onceSignedTx, otherKey2)
+        val sig2: TransactionSignature = serviceHub.createSignature(onceSignedTx, otherIdentity2.owningKey)
         // DOCEND 41
 
         // In practice, however, the process of gathering every signature