ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-24 07:06:44 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Ports docs changes on V1 since V2 was cut.

Browse Source 
* Documents the LegalProseReference annotation. Minor tweaks.

* Updates flow cookbook to use freshKeyAndCert not freshKey.

* Addresses review comments.
This commit is contained in:
Joel Dudley 2017-11-21 11:06:08 +00:00 committed by GitHub
parent b5f5f3f975
commit 12649adb1a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 48 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/source/api-contracts.rst
View File

@ -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
@ -234,3 +236,34 @@ the single command of type ``XContract.Commands`` from the transaction, and bran
}
}
}
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.
}
}

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

@ -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();
SignedTransaction onceSignedTx2 = getServiceHub().signInitialTransaction(txBuilder, otherKey);
PartyAndCertificate otherIdentity = getServiceHub().getKeyManagementService().freshKeyAndCert(getOurIdentityAndCert(), false);
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
/*----------------------------

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

@ -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 onceSignedTx2: SignedTransaction = serviceHub.signInitialTransaction(txBuilder, otherKey)
val otherIdentity: PartyAndCertificate = serviceHub.keyManagementService.freshKeyAndCert(ourIdentityAndCert, false)
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