From dd3d8ba626523e379b8888177ca19f2e377d0c42 Mon Sep 17 00:00:00 2001 From: josecoll Date: Tue, 3 Oct 2017 17:32:11 +0100 Subject: [PATCH] Merge release-v1 onto master (mostly documentation changes) (#1797) * Updated corda release version to 1.0.0.RC2 (#1641) * Fixed Simm Valuation Demo Test and enable serializabe java 8 lambdas. (#1655) * [CORDA-624] Node Explorer on Issuing cash throws MissingContractAttachements exception (#1656) (cherry picked from commit 27fea4d) * BIGINT fix for H2 coin selection. (#1658) * BIGINT fix for H2 coin selection. * Review feedback * CORDA-637 Node Explorer shows Network Map Service in Cash Issue dropdown (#1665) * [CORDA-637] Node Explorer shows Network Map Service in Cash Issue dropdown * add TODO to remove the hack * Declare this internal message string as "const". (#1676) * Merge "A variety of small fixes" into the 1.0 release branch (#1673) * Minor: improve javadocs in NodeInfo * Minor: use package descriptions in Kotlin build of api docs too, not just javadocs. * RPC: make RPCConnection non-internal, as it's a core API. Move docs around so they're on public API not internal API. * Add an IntelliJ scope that covers the currently supported Corda API. This is useful when used in combination with the "Highlight public declarations with missing KDoc" inspection. * Ironic: upgrade the version of the Gradle plugin that checks for upgraded versions of things. It had broken due being incompatible with the new versions of Gradle itself. * Docs: flesh out javadocs on ServiceHub * Docs: add @suppress to a few things that were polluting the Dokka docs. * Docs: mention RPC access in NodeInfo javadoc * IRS Fixes to bring UI closer to declared financial types (#1662) * Made problematic CordaRPCClient c'tor private (with internal bridge methods) and added correct c'tors for public use. (#1653) initialiseSerialization param has also been removed. * Fixing flow snapshot feature (#1685) * Fix validating notary flow to handle notary change transactions properly. (#1687) Add a notary change test for checking longer chains involving both regular and notary change transactions. * Unification of VaultQuery And VaultService APIs (into single VaultService interface) to simplify node bootstrapping and usability. (#1677) (#1688) * Identity documentation (#1620) * Sketch initial identity docs * Restructure confidential identity docs to better fit structure * Split confidential identities into API and concepts * Further expansion on basic identity conceptS * Merge Party type into api-identity.rst * Address feedback on written content * Rework inline code with literalinclude * Start addressing feedback from Richard * Clarify use of "counterparty" * Address comments on key concepts * Correct back to US english * Clarify distribution/publishing of identities * Update changelog around confidential identities * CORDA-642 Notary demo documentation fixes (#1682) * Notary demo documentation fixes. * One of the tables is prefixed. * CORDA-641: A temporary fix for contract upgrade transactions (#1700) * A temporary fix for contract upgrade transactions: during LedgerTransaction verification run the right logic based on whether it contains the UpgradeCommand. * Move ContractUpgradeFlowTest away from createSomeNodes() * Remove assembleBareTx as it's not used * Update corda version tag to 1.0.0-RC3 (#1705) * Hide SerializationContext from public API on TransactionBuilder (#1707) * Hide SerializationContext from public API on TransactionBuilder (cherry picked from commit 6ff7b7e) * Hide SerializationContext from public API on TransactionBuilder (cherry picked from commit 6ff7b7e) * Address feedback on confidential identities docs (#1701) * Address minor comments on confidential identities docs * Expand on implementation details of confidential identities * Cleanup * Clarify details of the data blob in the swap identites flow * Add that certificate path is not made public for confidential identities * FlowSession docs (#1693) * FlowSession docs (#1660) * FlowSession docs * PR comments * Milder example flow name * Fixes bugs with contract constraints (#1696) * Added schedulable flows to cordapp scanning Fixed a bug where the core flows are included in every cordapp. Added a test to prove the scheduled flows are loaded correctly. Added scheduled flow support to cordapp. Renabled broken test. Fixed test to prove cordapps aren't retreived from network. Review fixes. Fixed a test issue caused by gradle having slightly different paths to IntelliJ * Fixed test for real this time. * Consistent use of CordaException and CordaRuntimeException (#1710) * Custom exceptions in corda, should either derive from an appropriate closely related java exception, or CordaException, or CordaRuntimeException. They should not inherit just from Exception, or RuntimeException. Handle PR comments Add nicer constructors to CordaException and CordaRuntimeException * Fix ambiguous defaulted constructor * Add @suppress (#1725) * Git-ignore Node Explorer config. (#1709) * add message warning windows users they might need to manually kill explorer demo nodes started by gradle (#1717) (#1726) * Misc documentation fixes (#1694) (cherry picked from commit 592896f) * Document -parameters compiler arg for Java CorDapps. (#1712) * Correct non-anonymous two party trade flow (#1731) * Parameterize TwoPartyTradeFlowTests to confirm deanonymised functionality works. * Correct handling of counterparty using well known identity in TWoPartyTradeFlow * CORDA-594 - SIMM Demo doc update (#1723) (#1735) * CORDA-594 - SIMM Demo doc update For V1 write a series of JSON / curl commands a user can follow to run the demo * Review Comments * Updated the rationale behind as to why SIMM was introduced. * typo * Cordapps now have a name field. (#1664) Corrected cordapp name generation. Added changelog entry. * Small API fixes against M16 (#1737) * Move CompositeSignaturesWithKeys into net.corda.core.crypto package. (cherry picked from commit 8f29562) * Rename and move CordaPluginRegistry to reflect its real purpose now. Simplify serialization code a bit. (cherry picked from commit e2ecd3a) * Docs: docsite improvements * Remove discussion of webserver from 'writing a cordapp' page. * Fixup some flow docs. * Add a couple more package descriptions. (cherry picked from commit 2aedc43) * Review comments (cherry picked from commit ba1d007) * Review comments - always apply default whitelist and no longer load it via ServiceLoader (cherry picked from commit 7d4d7bb) * Added wording about renaming services resource file * Update corda version tag to 1.0.0-RC4 (#1734) * Update corda version tag to 1.0.0-RC3 * Update corda version tag to 1.0.0-RC4 * Update build.gradle * V1 tests and fixes for the ContractConstraints work (#1739) * V1 tests and fixes for the ContractConstraints work * More fixes. * Added a contract constraints section to the key concepts doc. (#1704) Documentation for contract constraints. Added to index. Review fixes round 1. More review fixes. Review fixes. Explained package contents. review fixes. Addressed RGB's final review comments. Updated source code type to 'java' * Fixes dead links. (#1749) * Update gradle plugins version to 1.0.0 (#1753) * Update Readme (#1756) * Update Readme Minor tweaks to Readme -- consistent capitalisation and more descriptive list of features (also reordered to put the important things first) * Copied master readme. * Update Readme Minor tweaks to Readme -- consistent capitalisation and more descriptive list of features (also reordered to put the important things first) * Fixes .rst formatting. (#1751) * Updates tutorials. (#1649) * Updates tutorials. * Addresses review comments. * Tutorial refresh for v1.0 and moving of code into separate files. (#1758) * Moves code sections in tutorials to code files. * Removes wallet references. * Updates repo layout doc. * Removes remaining cordapp-tutorial references, replaced with cordapp-example. * Fixes broken link. * Misc docs fixes. * Refreshes the ServiceHub and rpc ops api pages. * Updates the cheat sheet. * Updates cookbooks. * Refreshes the running-a-notary tutorial. * Updates flow-testing tutorial * Updates tear-offs tutorial. * Refreshes integration-testing tutorial. * Updates to contract tutorial and accompanying code to bring inline with V1 release. * Refreshes contract-upgrade tutorial. * Fixed broken code sample in "writing a contract" and updated contracts dsl. * Added contract ref to java code. Fixed broken rst markup. * Updates transaction-building tutorial. * Updates the client-rpc and flow-state-machines tutorials. * Updates the oracles tutorial. * Amended country in X500 names from "UK" to "GB" * Update FlowCookbook.kt * Amended cheatsheet. Minor update on contract upgrades tutoraial. * Added `extraCordappPackagesToScan` to node driver. * Changes to match new function signature. * Update to reflect change in location of cash contract name. * CORDA-670: Correct scanned packages in network visualiser (#1763) * Add CorDapp dependency of IRS to network visualiser * Set CorDapp directories * Checking out the latest milestone will no longer be required. (#1761) * Updated documentation indices (#1754) * Update documentation indices. * Reference a moveable tag for V1 docs. Remove redundant warning text. * Reverted proposed usage of new docs release tag * Minor: print a deprecation warning when the web server starts. (#1767) * Release and upgrade notes for V1.0 (#1736) * Release and upgrade notes for V1.0 * Update changelog.rst * Update changelog.rst * Formatting. * Incorporating review feedback from KB and MN. * "guarantee" instead of "promise" * Updated with final review comments from KB and RGB. * Updated upgrade notes to describe migration from removed CordaPluginRegistry. * Minor clarification. * Minor updates following final RGB feedback. * Kat's further pedantic feedback * Minor changes following feedback from KB. * Incorporating review feedback from MH. * killed 'patent-pending' * Made the visualiser into a regular JVM module - not a CorDapp. (#1771) * Docs: more package descriptions and take non-stabilised APIs out of the docs build. (#1775) * Update corda version tag to 1.0.0 * Updated release notes to fix minor typos (#1779) Fixed bold type on simplified annotation driven scanning bullet and added bold type to module name bullets * Fixed drop down.. probably. (#1780) * fixed formatting for release notes. (#1782) * Improve API page wording (#1784) * Removed "unreleased" sections from the release notes and change log. * Merge remote-tracking branch 'origin/release-V1' into colljos-merge-v1-docs # Conflicts: # build.gradle # client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt # client/rpc/src/main/kotlin/net/corda/client/rpc/CordaRPCClient.kt # client/rpc/src/main/kotlin/net/corda/client/rpc/PermissionException.kt # constants.properties # core/src/main/kotlin/net/corda/core/flows/FlowSession.kt # core/src/test/kotlin/net/corda/core/contracts/DummyContractV2Tests.kt # core/src/test/kotlin/net/corda/core/flows/ContractUpgradeFlowTest.kt # docs/source/api-flows.rst # docs/source/api-index.rst # docs/source/changelog.rst # docs/source/example-code/src/main/java/net/corda/docs/java/tutorial/testdsl/CommercialPaperTest.java # docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt # docs/source/example-code/src/main/kotlin/net/corda/docs/tutorial/contract/TutorialContract.kt # docs/source/example-code/src/main/kotlin/net/corda/docs/tutorial/testdsl/TutorialTestDSL.kt # docs/source/hello-world-state.rst # docs/source/key-concepts-contract-constraints.rst # docs/source/serialization.rst # docs/source/tut-two-party-flow.rst # docs/source/tutorial-tear-offs.rst # node-api/src/main/kotlin/net/corda/nodeapi/internal/serialization/CordaClassResolver.kt # node-api/src/test/java/net/corda/nodeapi/internal/serialization/ForbiddenLambdaSerializationTests.java # node-api/src/test/java/net/corda/nodeapi/internal/serialization/LambdaCheckpointSerializationTest.java # node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt # node/src/integration-test/kotlin/net/corda/services/messaging/MQSecurityTest.kt # node/src/main/kotlin/net/corda/node/internal/NodeStartup.kt # node/src/test/kotlin/net/corda/node/internal/cordapp/CordappLoaderTest.kt # node/src/test/kotlin/net/corda/node/services/NotaryChangeTests.kt # samples/attachment-demo/src/main/kotlin/net/corda/attachmentdemo/AttachmentDemo.kt # samples/trader-demo/src/main/kotlin/net/corda/traderdemo/TraderDemo.kt # testing/node-driver/src/integration-test/kotlin/net/corda/testing/FlowStackSnapshotTest.kt # testing/node-driver/src/main/kotlin/net/corda/testing/driver/Driver.kt # testing/node-driver/src/main/kotlin/net/corda/testing/node/MockNode.kt # webserver/src/main/kotlin/net/corda/webserver/internal/NodeWebServer.kt --- .gitignore | 3 + build.gradle | 2 +- .../client/jfx/model/NetworkIdentityModel.kt | 5 +- .../client/jfx/model/NodeMonitorModel.kt | 4 +- .../kotlin/net/corda/core/flows/FlowLogic.kt | 4 + .../net/corda/core/flows/FlowSession.kt | 4 +- docs/source/_static/versions | 1 + docs/source/api-core-types.rst | 14 - docs/source/api-flows.rst | 93 ++++- docs/source/api-identity.rst | 129 +++++++ docs/source/api-index.rst | 1 + docs/source/changelog.rst | 80 ++-- docs/source/deploying-a-node.rst | 10 +- .../java/net/corda/docs/FlowCookbookJava.java | 3 +- .../kotlin/net/corda/docs/FlowCookbook.kt | 3 +- .../net/corda/docs/LaunchSpaceshipFlow.kt | 99 +++++ docs/source/index.rst | 3 - .../key-concepts-contract-constraints.rst | 4 +- docs/source/key-concepts-identity.rst | 78 ++++ docs/source/key-concepts.rst | 1 + docs/source/release-notes.rst | 105 +++++- docs/source/release-process-index.rst | 2 + docs/source/resources/signatureMetadata.png | Bin 0 -> 18666 bytes docs/source/resources/subTreesPrivacy.png | Bin 0 -> 105835 bytes docs/source/running-the-demos.rst | 13 +- docs/source/serialization.rst | 8 +- docs/source/shell.rst | 4 + docs/source/troubleshooting.rst | 5 + docs/source/tut-two-party-flow.rst | 24 +- docs/source/tutorial-tear-offs.rst | 9 +- docs/source/upgrade-notes.rst | 349 ++++++++++++++++++ .../corda/finance/flows/TwoPartyDealFlow.kt | 2 + .../corda/finance/flows/TwoPartyTradeFlow.kt | 6 +- .../node/services/AttachmentLoadingTests.kt | 9 +- .../node/messaging/TwoPartyTradeFlowTests.kt | 15 +- samples/network-visualiser/build.gradle | 10 +- .../net/corda/netmap/simulation/Simulation.kt | 2 + .../corda/testing/contracts/DummyContract.kt | 4 +- 38 files changed, 980 insertions(+), 128 deletions(-) create mode 100644 docs/source/api-identity.rst create mode 100644 docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt create mode 100644 docs/source/key-concepts-identity.rst create mode 100644 docs/source/resources/signatureMetadata.png create mode 100644 docs/source/resources/subTreesPrivacy.png create mode 100644 docs/source/upgrade-notes.rst diff --git a/.gitignore b/.gitignore index 67dc614169..ae3bd7f4de 100644 --- a/.gitignore +++ b/.gitignore @@ -88,6 +88,9 @@ docs/virtualenv/ # bft-smart **/config/currentView +# Node Explorer +/tools/explorer/conf/CordaExplorer.properties + # vim *.swp *.swn diff --git a/build.gradle b/build.gradle index 47fc8ef7e6..acee113b33 100644 --- a/build.gradle +++ b/build.gradle @@ -40,7 +40,7 @@ buildscript { ext.jopt_simple_version = '5.0.2' ext.jansi_version = '1.14' ext.hibernate_version = '5.2.6.Final' - ext.h2_version = '1.4.194' + ext.h2_version = '1.4.194' // Update docs if renamed or removed. ext.rxjava_version = '1.2.4' ext.dokka_version = '0.9.14' ext.eddsa_version = '0.2.0' diff --git a/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NetworkIdentityModel.kt b/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NetworkIdentityModel.kt index 15cf636622..9ff83660aa 100644 --- a/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NetworkIdentityModel.kt +++ b/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NetworkIdentityModel.kt @@ -42,7 +42,10 @@ class NetworkIdentityModel { }.map { it?.party }.filterNotNull() val notaryNodes: ObservableList = notaries.map { rpcProxy.value?.nodeInfoFromParty(it) }.filterNotNull() - val parties: ObservableList = networkIdentities.filtered { it.legalIdentities.all { it !in notaries } } + val parties: ObservableList = networkIdentities + .filtered { it.legalIdentities.all { it !in notaries } } + // TODO: REMOVE THIS HACK WHEN NETWORK MAP REDESIGN WORK IS COMPLETED. + .filtered { it.legalIdentities.all { it.name.organisation != "Network Map Service" } } val myIdentity = rpcProxy.map { it?.nodeInfo()?.legalIdentitiesAndCerts?.first()?.party } fun partyFromPublicKey(publicKey: PublicKey): ObservableValue = identityCache[publicKey] diff --git a/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt b/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt index 9bece5edcc..9a4da742b0 100644 --- a/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt +++ b/client/jfx/src/main/kotlin/net/corda/client/jfx/model/NodeMonitorModel.kt @@ -57,8 +57,8 @@ class NodeMonitorModel { */ fun register(nodeHostAndPort: NetworkHostAndPort, username: String, password: String) { val client = CordaRPCClient( - hostAndPort = nodeHostAndPort, - configuration = CordaRPCClientConfiguration.DEFAULT.copy( + nodeHostAndPort, + CordaRPCClientConfiguration.DEFAULT.copy( connectionMaxRetryInterval = 10.seconds ) ) diff --git a/core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt b/core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt index 9145ae4baa..fd2c144d9e 100644 --- a/core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt +++ b/core/src/main/kotlin/net/corda/core/flows/FlowLogic.kt @@ -55,6 +55,10 @@ abstract class FlowLogic { */ val serviceHub: ServiceHub get() = stateMachine.serviceHub + /** + * Creates a communication session with [party]. Subsequently you may send/receive using this session object. Note + * that this function does not communicate in itself, the counter-flow will be kicked off by the first send/receive. + */ @Suspendable fun initiateFlow(party: Party): FlowSession = stateMachine.initiateFlow(party, flowUsedForSessions) diff --git a/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt b/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt index 7effaa9f52..07e4b49d33 100644 --- a/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt +++ b/core/src/main/kotlin/net/corda/core/flows/FlowSession.kt @@ -6,8 +6,8 @@ import net.corda.core.utilities.UntrustworthyData /** * - * A [FlowSession] is a handle on a communication sequence between two flows. It is used to send and receive messages - * between flows. + * A [FlowSession] is a handle on a communication sequence between two paired flows, possibly running on separate nodes. + * It is used to send and receive messages between the flows as well as to query information about the counter-flow. * * There are two ways of obtaining such a session: * diff --git a/docs/source/_static/versions b/docs/source/_static/versions index 4110e2dfd6..1152a8e46a 100644 --- a/docs/source/_static/versions +++ b/docs/source/_static/versions @@ -8,5 +8,6 @@ "https://docs.corda.net/releases/release-M12.1": "M12.1", "https://docs.corda.net/releases/release-M13.0": "M13.0", "https://docs.corda.net/releases/release-M14.0": "M14.0", + "https://docs.corda.net/releases/release-V1.0": "V1.0", "https://docs.corda.net/head/": "Master" } diff --git a/docs/source/api-core-types.rst b/docs/source/api-core-types.rst index e69c5d858d..e7f3c898ee 100644 --- a/docs/source/api-core-types.rst +++ b/docs/source/api-core-types.rst @@ -20,20 +20,6 @@ Any object that needs to be identified by its hash should implement the ``NamedB ``SecureHash`` is a sealed class that only defines a single subclass, ``SecureHash.SHA256``. There are utility methods to create and parse ``SecureHash.SHA256`` objects. -Party ------ -Identities on the network are represented by ``AbstractParty``. There are two types of ``AbstractParty``: - -* ``Party``, identified by a ``PublicKey`` and a ``CordaX500Name`` - -* ``AnonymousParty``, identified by a ``PublicKey`` - -For example, in a transaction sent to your node as part of a chain of custody it is important you can convince yourself -of the transaction's validity, but equally important that you don't learn anything about who was involved in that -transaction. In these cases ``AnonymousParty`` should be used. In contrast, for internal processing where extended -details of a party are required, the ``Party`` class should be used. The identity service provides functionality for -resolving anonymous parties to full parties. - CompositeKey ------------ Corda supports scenarios where more than one signature is required to authorise a state object transition. For example: diff --git a/docs/source/api-flows.rst b/docs/source/api-flows.rst index 99cddf74b2..931aa493df 100644 --- a/docs/source/api-flows.rst +++ b/docs/source/api-flows.rst @@ -377,10 +377,11 @@ as it likes, and each party can invoke a different response flow: :end-before: DOCEND 6 :dedent: 12 -.. warning:: If you initiate several counter flows from the same ``@InitiatingFlow`` flow then on the receiving side you - must be prepared to be initiated by any of the corresponding ``initiateFlow()`` calls! A good way of handling this - ambiguity is to send as a first message a "role" message to the initiated flow, indicating which part of the - initiating flow the rest of the counter-flow should conform to. +.. warning:: If you initiate several flows from the same ``@InitiatingFlow`` flow then on the receiving side you must be + prepared to be initiated by any of the corresponding ``initiateFlow()`` calls! A good way of handling this ambiguity + is to send as a first message a "role" message to the initiated flow, indicating which part of the initiating flow + the rest of the counter-flow should conform to. For example send an enum, and on the other side start with a switch + statement. SendAndReceive ~~~~~~~~~~~~~~ @@ -426,20 +427,52 @@ Our side of the flow must mirror these calls. We could do this as follows: :end-before: DOCEND 8 :dedent: 12 -Porting from the old Party-based API -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Why sessions? +^^^^^^^^^^^^^ Before ``FlowSession`` s were introduced the send/receive API looked a bit different. They were functions on ``FlowLogic`` and took the address ``Party`` as argument. The platform internally maintained a mapping from ``Party`` to session, hiding sessions from the user completely. -However we realised that this could introduce subtle bugs and security issues where sends meant for different sessions -may end up in the same session if the target ``Party`` happens to be the same. +Although this is a convenient API it introduces subtle issues where a message that was originally meant for a specific +session may end up in another. -Therefore the session concept is now exposed through ``FlowSession`` which disambiguates which communication sequence a -message is intended for. +Consider the following contrived example using the old ``Party`` based API: -In the old API the first ``send`` or ``receive`` to a ``Party`` was the one kicking off the counterflow. This is now +.. container:: codeset + + .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt + :language: kotlin + :start-after: DOCSTART LaunchSpaceshipFlow + :end-before: DOCEND LaunchSpaceshipFlow + +The intention of the flows is very clear: LaunchSpaceshipFlow asks the president whether a spaceship should be launched. +It is expecting a boolean reply. The president in return first tells the secretary that they need coffee, which is also +communicated with a boolean. Afterwards the president replies to the launcher that they don't want to launch. + +However the above can go horribly wrong when the ``launcher`` happens to be the same party ``getSecretary`` returns. In +this case the boolean meant for the secretary will be received by the launcher! + +This indicates that ``Party`` is not a good identifier for the communication sequence, and indeed the ``Party`` based +API may introduce ways for an attacker to fish for information and even trigger unintended control flow like in the +above case. + +Hence we introduced ``FlowSession``, which identifies the communication sequence. With ``FlowSession`` s the above set +of flows would look like this: + +.. container:: codeset + + .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt + :language: kotlin + :start-after: DOCSTART LaunchSpaceshipFlowCorrect + :end-before: DOCEND LaunchSpaceshipFlowCorrect + +Note how the president is now explicit about which session it wants to send to. + +Porting from the old Party-based API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the old API the first ``send`` or ``receive`` to a ``Party`` was the one kicking off the counter-flow. This is now explicit in the ``initiateFlow`` function call. To port existing code: .. container:: codeset @@ -460,24 +493,28 @@ explicit in the ``initiateFlow`` function call. To port existing code: Subflows -------- -Subflows are pieces of reusable flows that may be run by calling ``FlowLogic.subFlow``. +Subflows are pieces of reusable flows that may be run by calling ``FlowLogic.subFlow``. There are two broad categories +of subflows, inlined and initiating ones. The main difference lies in the counter-flow's starting method, initiating +ones initiate counter-flows automatically, while inlined ones expect some parent counter-flow to run the inlined +counter-part. Inlined subflows ^^^^^^^^^^^^^^^^ -Inlined subflows inherit their calling flow's type when initiating a new session with a counterparty. For example say +Inlined subflows inherit their calling flow's type when initiating a new session with a counterparty. For example, say we have flow A calling an inlined subflow B, which in turn initiates a session with a party. The FlowLogic type used to -determine which counterflow should be kicked off will be A, not B. Note that this means that the other side of this -session must therefore be called explicitly in the kicked off flow as well. +determine which counter-flow should be kicked off will be A, not B. Note that this means that the other side of this +inlined flow must therefore be implemented explicitly in the kicked off flow as well. This may be done by calling a +matching inlined counter-flow, or by implementing the other side explicitly in the kicked off parent flow. An example of such a flow is ``CollectSignaturesFlow``. It has a counter-flow ``SignTransactionFlow`` that isn't -annotated with ``InitiatedBy``. This is because both of these flows are inlined, the kick-off relationship will be +annotated with ``InitiatedBy``. This is because both of these flows are inlined; the kick-off relationship will be defined by the parent flows calling ``CollectSignaturesFlow`` and ``SignTransactionFlow``. In the code inlined subflows appear as regular ``FlowLogic`` instances, `without` either of the ``@InitiatingFlow`` or ``@InitiatedBy`` annotation. -.. note:: Inlined flows aren't versioned, they inherit their parent flow's version. +.. note:: Inlined flows aren't versioned; they inherit their parent flow's version. Initiating subflows ^^^^^^^^^^^^^^^^^^^ @@ -493,7 +530,7 @@ Core initiating subflows ^^^^^^^^^^^^^^^^^^^^^^^^ Corda-provided initiating subflows are a little different to standard ones as they are versioned together with the -platform, and their initiated counterflows are registered explicitly, so there is no need for the ``InitiatedBy`` +platform, and their initiated counter-flows are registered explicitly, so there is no need for the ``InitiatedBy`` annotation. An example is the ``FinalityFlow``/``FinalityHandler`` flow pair. @@ -504,8 +541,10 @@ Built-in subflows Corda provides a number of built-in flows that should be used for handling common tasks. The most important are: * ``CollectSignaturesFlow`` (inlined), which should be used to collect a transaction's required signatures -* ``FinalityFlow`` (initiating), which should be used to notarise and record a transaction -* ``SendTransactionFlow`` (inlined), which should be used to send a signed transaction if it needed to be resolved on the other side. +* ``FinalityFlow`` (initiating), which should be used to notarise and record a transaction as well as to broadcast it to + all relevant parties +* ``SendTransactionFlow`` (inlined), which should be used to send a signed transaction if it needed to be resolved on + the other side. * ``ReceiveTransactionFlow`` (inlined), which should be used receive a signed transaction * ``ContractUpgradeFlow`` (initiating), which should be used to change a state's contract * ``NotaryChangeFlow`` (initiating), which should be used to change a state's notary @@ -641,6 +680,20 @@ We can also send and receive a ``StateAndRef`` dependency chain and automaticall :end-before: DOCEND 14 :dedent: 12 +Why inlined subflows? +^^^^^^^^^^^^^^^^^^^^^ + +Inlined subflows provide a way to share commonly used flow code `while forcing users to create a parent flow`. Take for +example ``CollectSignaturesFlow``. Say we made it an initiating flow that automatically kicks off +``SignTransactionFlow`` that signs the transaction. This would mean malicious nodes can just send any old transaction to +us using ``CollectSignaturesFlow`` and we would automatically sign it! + +By making this pair of flows inlined we provide control to the user over whether to sign the transaction or not by +forcing them to nest it in their own parent flows. + +In general if you're writing a subflow the decision of whether you should make it initiating should depend on whether +the counter-flow needs broader context to achieve its goal. + FlowException ------------- Suppose a node throws an exception while running a flow. Any counterparty flows waiting for a message from the node diff --git a/docs/source/api-identity.rst b/docs/source/api-identity.rst new file mode 100644 index 0000000000..270e31bafd --- /dev/null +++ b/docs/source/api-identity.rst @@ -0,0 +1,129 @@ +API: Identity +============= + +.. note:: Before reading this page, you should be familiar with the key concepts of :doc:`key-concepts-identity`. + +.. contents:: + +Party +----- +Identities on the network are represented by ``AbstractParty``. There are two types of ``AbstractParty``: + +* ``Party``, identified by a ``PublicKey`` and a ``CordaX500Name`` + +* ``AnonymousParty``, identified by a ``PublicKey`` + +For example, in a transaction sent to your node as part of a chain of custody it is important you can convince yourself +of the transaction's validity, but equally important that you don't learn anything about who was involved in that +transaction. In these cases ``AnonymousParty`` should be used by flows constructing when transaction states and commands. +In contrast, for internal processing where extended details of a party are required, the ``Party`` class should be used +instead. The identity service provides functionality for flows to resolve anonymous parties to full parties, dependent +on the anonymous party's identity having been registered with the node earlier (typically this is handled by +``SwapIdentitiesFlow`` or ``IdentitySyncFlow``, discussed below). + +Party names are held within the ``CordaX500Name`` data class, which enforces the structure of names within Corda, as +well as ensuring a consistent rendering of the names in plain text. + +The support for both Party and AnonymousParty classes in Corda enables sophisticated selective disclosure of identity +information. For example, it is possible to construct a Transaction using an AnonymousParty, so nobody can learn of your +involvement by inspection of the transaction, yet prove to specific counterparts that this AnonymousParty actually is +owned by your well known identity. This disclosure is achieved through the use of the PartyAndCertificate data class +which can be propagated to those who need to know, and contains the Party's X.509 certificate path to provide proof of +ownership by a well known identity. + +The PartyAndCertificate class is also used in the network map service to represent well known identities, in which +scenario the certificate path proves its issuance by the Doorman service. + + +Confidential Identities +----------------------- + +Confidential identities are key pairs where the corresponding X.509 certificate (and path) are not made public, so that parties who +are not involved in the transaction cannot identify its participants. They are owned by a well known identity, which +must sign the X.509 certificate. Before constructing a new transaction the involved parties must generate and send new +confidential identities to each other, a process which is managed using ``SwapIdentitiesFlow`` (discussed below). The +public keys of these confidential identities are then used when generating output states and commands for the transaction. + +Where using outputs from a previous transaction in a new transaction, counterparties may need to know who the involved +parties are. One example is in ``TwoPartyTradeFlow`` which delegates to ``CollectSignaturesFlow`` to gather certificates +from both parties. ``CollectSignaturesFlow`` requires that a confidential identity of the initiating node has signed +the transaction, and verifying this requires the receiving node has a copy of the confidential identity for the input +state. ``IdentitySyncFlow`` can be used to synchronize the confidential identities we have the certificate paths for, in +a single transaction, to another node. + +.. note:: ``CollectSignaturesFlow`` requires that the initiating node has signed the transaction, and as such all nodes + providing signatures must recognise the signing key used by the initiating node as being either its well known identity + or a confidential identity they have the certificate for. + +Swap identities flow +~~~~~~~~~~~~~~~~~~~~ + +``SwapIdentitiesFlow`` takes the party to swap identities with in its constructor (the counterparty), and is typically run as a subflow of +another flow. It returns a mapping from well known identities of the calling flow and our counterparty to the new +confidential identities; in future this will be extended to handle swapping identities with multiple parties. +You can see an example of it being used in ``TwoPartyDealFlow.kt``: + +.. container:: codeset + + .. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyDealFlow.kt + :language: kotlin + :start-after: DOCSTART 2 + :end-before: DOCEND 2 + +The swap identities flow goes through the following key steps: + +1. Generate a nonce value to form a challenge to the other nodes. +2. Send nonce value to all counterparties, and receive their nonce values. +3. Generate a new confidential identity from our well known identity. +4. Create a data blob containing the new confidential identity (public key, name and X.509 certificate path), + and the hash of the nonce values. +5. Sign the resulting data blob with the confidential identity's private key. +6. Send the confidential identity and data blob signature to all counterparties, while receiving theirs. +7. Verify the signatures to ensure that identities were generated by the involved set of parties. +8. Verify the confidential identities are owned by the expected well known identities. +9. Store the confidential identities and return them to the calling flow. + +This ensures not only that the confidential identity X.509 certificates are signed by the correct well known identities, +but also that the confidential identity private key is held by the counterparty, and that a party cannot claim ownership +another party's confidential identities belong to its well known identity. + +Identity synchronization flow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When constructing a transaction whose input states reference confidential identities, it is common for other signing +entities (counterparties) to require to know which well known identities those confidential identities map to. The +``IdentitySyncFlow`` handles this process, and you can see an example of its use in ``TwoPartyTradeFlow.kt``: + +.. container:: codeset + + .. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt + :language: kotlin + :start-after: DOCSTART 6 + :end-before: DOCEND 6 + +The identity synchronization flow goes through the following key steps: + +1. Extract participant identities from all input and output states and remove any well known identities. Required signers + on commands are currently ignored as they are presumed to be included in the participants on states, or to be well + known identities of services (such as an oracle service). +2. For each counterparty node, send a list of the public keys of the confidential identities, and receive back a list + of those the counterparty needs the certificate path for. +3. Verify the requested list of identities contains only confidential identities in the offered list, and abort otherwise. +4. Send the requested confidential identities as ``PartyAndCertificate`` instances to the counterparty. + +.. note:: ``IdentitySyncFlow`` works on a push basis. The initiating node can only send confidential identities it has + the X.509 certificates for, and the remote nodes can only request confidential identities being offered (are + referenced in the transaction passed to the initiating flow). There is no standard flow for nodes to collect + confidential identities before assembling a transaction, and this is left for individual flows to manage if required. + +``IdentitySyncFlow`` will serve all confidential identities in the provided transaction, irrespective of well known +identity. This is important for more complex transaction cases with 3+ parties, for example: + +* Alice is building the transaction, and provides some input state *x* owned by a confidential identity of Alice +* Bob provides some input state *y* owned by a confidential identity of Bob +* Charlie provides some input state *z* owned by a confidential identity of Charlie + +Alice may know all of the confidential identities ahead of time, but Bob not know about Charlie's and vice-versa. +The assembled transaction therefore has three input states *x*, *y* and *z*, for which only Alice possesses certificates +for all confidential identities. ``IdentitySyncFlow`` must send not just Alice's confidential identity but also any other +identities in the transaction to the Bob and Charlie. diff --git a/docs/source/api-index.rst b/docs/source/api-index.rst index d229c040ad..c3486e4cea 100644 --- a/docs/source/api-index.rst +++ b/docs/source/api-index.rst @@ -12,6 +12,7 @@ This section describes the APIs that are available for the development of CorDap api-vault-query api-transactions api-flows + api-identity api-service-hub api-rpc api-core-types diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index d02e2d8f62..0012e64902 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -19,6 +19,8 @@ UNRELEASED either annotated with the @CordaSerializable annotation or explicitly whitelisted then a NotSerializableException is thrown. +.. _changelog_v1: + Release 1.0 ----------- @@ -27,36 +29,45 @@ Release 1.0 * Java 8 lambdas now work property with Kryo during check-pointing. +* Java 8 serializable lambdas now work property with Kryo during check-pointing. + * String constants have been marked as ``const`` type in Kotlin, eliminating cases where functions of the form ``get()`` were created for the Java API. These can now be referenced by their name directly. * ``FlowLogic`` communication has been extensively rewritten to use functions on ``FlowSession`` as the base for communication between nodes. + * Calls to ``send()``, ``receive()`` and ``sendAndReceive()`` on FlowLogic should be replaced with calls to the function of the same name on ``FlowSession``. Note that the replacement functions do not take in a destination parameter, as this is defined in the session. * Initiated flows now take in a ``FlowSession`` instead of ``Party`` in their constructor. If you need to access the counterparty identity, it is in the ``counterparty`` property of the flow session. + * Added X509EdDSAEngine to intercept and rewrite EdDSA public keys wrapped in X509Key instances. This corrects an issue with verifying certificate paths loaded from a Java Keystore where they contain EdDSA keys. -* generateSpend() now creates a new confidential identity for the change address rather than using the identity of the - input state owner. +* Confidential identities are now complete: + + * The identity negotiation flow is now called ``SwapIdentitiesFlow``, renamed from ``TransactionKeyFlow``. + * generateSpend() now creates a new confidential identity for the change address rather than using the identity of the + input state owner. + * Please see the documentation :doc:`key-concepts-identity` and :doc:`api-identity` for more details. * Remove the legacy web front end from the SIMM demo. * ``NodeInfo`` and ``NetworkMapCache`` changes: + * Removed ``NodeInfo::legalIdentity`` in preparation for handling of multiple identities. We left list of ``NodeInfo::legalIdentitiesAndCerts``, - the first identity still plays a special role of main node identity. + the first identity still plays a special role of main node identity. * We no longer support advertising services in network map. Removed ``NodeInfo::advertisedServices``, ``serviceIdentities`` - and ``notaryIdentity``. + and ``notaryIdentity``. * Removed service methods from ``NetworkMapCache``: ``partyNodes``, ``networkMapNodes``, ``notaryNodes``, ``regulatorNodes``, - ``getNodesWithService``, ``getPeersWithService``, ``getRecommended``, ``getNodesByAdvertisedServiceIdentityKey``, ``getAnyNotary``, - ``notaryNode``, ``getAnyServiceOfType``. To get all known ``NodeInfo``s call ``allNodes``. + ``getNodesWithService``, ``getPeersWithService``, ``getRecommended``, ``getNodesByAdvertisedServiceIdentityKey``, ``getAnyNotary``, + ``notaryNode``, ``getAnyServiceOfType``. To get all known ``NodeInfo``'s call ``allNodes``. * In preparation for ``NetworkMapService`` redesign and distributing notaries through ``NetworkParameters`` we added - ``NetworkMapCache::notaryIdentities`` list to enable to lookup for notary parties known to the network. Related ``CordaRPCOps::notaryIdentities`` - was introduced. Other special nodes parties like Oracles or Regulators need to be specified directly in CorDapp or flow. + ``NetworkMapCache::notaryIdentities`` list to enable to lookup for notary parties known to the network. Related ``CordaRPCOps::notaryIdentities`` + was introduced. Other special nodes parties like Oracles or Regulators need to be specified directly in CorDapp or flow. * Moved ``ServiceType`` and ``ServiceInfo`` to ``net.corda.nodeapi`` package as services are only required on node startup. * Adding enum support to the class carpenter @@ -71,7 +82,7 @@ Release 1.0 * About half of the code in test-utils has been moved to a new module ``node-driver``, and the test scope modules are now located in a ``testing`` directory. -* CordaPluginRegistry has been renamed to SerializationWhitelist and moved to the net.corda.core.serialization +* ``CordaPluginRegistry`` has been renamed to ``SerializationWhitelist`` and moved to the ``net.corda.core.serialization`` package. The API for whitelisting types that can't be annotated was slightly simplified. This class used to contain many things, but as we switched to annotations and classpath scanning over time it hollowed out until this was the only functionality left. You also need to rename your services resource file to the new class name. @@ -93,10 +104,14 @@ Release 1.0 * Vault Query fix: filter by multiple issuer names in ``FungibleAssetQueryCriteria`` * Following deprecated methods have been removed: + * In ``DataFeed`` + * ``first`` and ``current``, replaced by ``snapshot`` * ``second`` and ``future``, replaced by ``updates`` + * In ``CordaRPCOps`` + * ``stateMachinesAndUpdates``, replaced by ``stateMachinesFeed`` * ``verifiedTransactions``, replaced by ``verifiedTransactionsFeed`` * ``stateMachineRecordedTransactionMapping``, replaced by ``stateMachineRecordedTransactionMappingFeed`` @@ -106,13 +121,12 @@ Release 1.0 ``ResolveTransactionsFlow`` has been made internal. Instead merge the receipt of the ``SignedTransaction`` and the subsequent sub-flow call to ``ResolveTransactionsFlow`` with a single call to ``ReceiveTransactionFlow``. The flow running on the counterparty must use ``SendTransactionFlow`` at the correct place. There is also ``ReceiveStateAndRefFlow`` and ``SendStateAndRefFlow`` for - dealing with ``StateAndRef``s. + dealing with ``StateAndRef``'s. * Vault query soft locking enhancements and deprecations + * removed original ``VaultService`` ``softLockedStates` query mechanism. - * introduced improved ``SoftLockingCondition`` filterable attribute in ``VaultQueryCriteria`` to enable specification - of different soft locking retrieval behaviours (exclusive of soft locked states, soft locked states only, specified - by set of lock ids) + * introduced improved ``SoftLockingCondition`` filterable attribute in ``VaultQueryCriteria`` to enable specification of different soft locking retrieval behaviours (exclusive of soft locked states, soft locked states only, specified by set of lock ids) * Trader demo now issues cash and commercial paper directly from the bank node, rather than the seller node self-issuing commercial paper but labelling it as if issued by the bank. @@ -122,7 +136,7 @@ Release 1.0 If you specifically need well known identities, use the network map, which is the authoritative source of current well known identities. -* Currency-related API in ``net.corda.core.contracts.ContractsDSL`` has moved to ```net.corda.finance.CurrencyUtils`. +* Currency-related API in ``net.corda.core.contracts.ContractsDSL`` has moved to ```net.corda.finance.CurrencyUtils``. * Remove `IssuerFlow` as it allowed nodes to request arbitrary amounts of cash to be issued from any remote node. Use `CashIssueFlow` instead. @@ -174,15 +188,16 @@ Release 1.0 * The unused ``MetaData`` and ``SignatureType`` in ``crypto`` package have been removed. -* The ``class TransactionSignature(bytes: ByteArray, val by: PublicKey, val signatureMetadata: SignatureMetadata): DigitalSignature(bytes)`` - class is now utilised Vs the old ``DigitalSignature.WithKey`` for Corda transaction signatures. Practically, it takes - the ``signatureMetadata`` as an extra input, in order to support signing both the transaction and the extra metadata. +* The ``class TransactionSignature(bytes: ByteArray, val by: PublicKey, val signatureMetadata:`` + ``SignatureMetadata): DigitalSignature(bytes)`` class is now utilised Vs the old ``DigitalSignature.WithKey`` for + Corda transaction signatures. Practically, it takes the ``signatureMetadata`` as an extra input, in order to support + signing both the transaction and the extra metadata. * To reflect changes in the signing process, the ``Crypto`` object is now equipped with the: ``fun doSign(keyPair: KeyPair, signableData: SignableData): TransactionSignature`` and ``fun doVerify(txId: SecureHash, transactionSignature: TransactionSignature): Boolean`` functions. -* ``SerializationCustomization.addToWhitelist()` now accepts multiple classes via varargs. +* ``SerializationCustomization.addToWhitelist()`` now accepts multiple classes via varargs. * Two functions to easily sign a ``FilteredTransaction`` have been added to ``ServiceHub``: ``createSignature(filteredTransaction: FilteredTransaction, publicKey: PublicKey)`` and @@ -212,8 +227,8 @@ Release 1.0 * All of the ``serializedHash`` and ``computeNonce`` functions have been removed from ``MerkleTransaction``. The ``serializedHash(x: T)`` and ``computeNonce`` were moved to ``CryptoUtils``. -* Two overloaded methods ``componentHash(opaqueBytes: OpaqueBytes, privacySalt: PrivacySalt, componentGroupIndex: Int, - internalIndex: Int): SecureHash`` and ``componentHash(nonce: SecureHash, opaqueBytes: OpaqueBytes): SecureHash`` have +* Two overloaded methods ``componentHash(opaqueBytes: OpaqueBytes, privacySalt: PrivacySalt,`` + ``componentGroupIndex: Int, internalIndex: Int): SecureHash`` and ``componentHash(nonce: SecureHash, opaqueBytes: OpaqueBytes): SecureHash`` have been added to ``CryptoUtils``. Similarly to ``computeNonce``, they internally use SHA256d for nonce and leaf hash computations. @@ -224,24 +239,25 @@ Release 1.0 ``FilteredTransaction`` now extend ``TraversableTransaction``. * Two classes, ``ComponentGroup(open val groupIndex: Int, open val components: List)`` and - ``FilteredComponentGroup(override val groupIndex: Int, override val components: List, - val nonces: List, val partialMerkleTree: PartialMerkleTree): ComponentGroup(groupIndex, components)`` - have been added, which are properties of the ``WireTransaction`` and ``FilteredTransaction``, respectively. + ``FilteredComponentGroup(override val groupIndex: Int, override val components:`` + ``List, val nonces: List, val partialMerkleTree:`` + ``PartialMerkleTree): ComponentGroup(groupIndex, components)`` have been added, which are properties + of the ``WireTransaction`` and ``FilteredTransaction``, respectively. * ``checkAllComponentsVisible(componentGroupEnum: ComponentGroupEnum)`` is added to ``FilteredTransaction``, a new function to check if all components are visible in a specific component-group. * To allow for backwards compatibility, ``WireTransaction`` and ``FilteredTransaction`` have new fields and constructors: ``WireTransaction(componentGroups: List, privacySalt: PrivacySalt = PrivacySalt())``, - ``FilteredTransaction private constructor(id: SecureHash,filteredComponentGroups: List, - groupHashes: List``. ``FilteredTransaction`` is still built via - ``buildFilteredTransaction(wtx: WireTransaction, filtering: Predicate). + ``FilteredTransaction private constructor(id: SecureHash,filteredComponentGroups:`` + ``List, groupHashes: List``. ``FilteredTransaction`` is still built via + ``buildFilteredTransaction(wtx: WireTransaction, filtering: Predicate)``. * ``FilteredLeaves`` class have been removed and as a result we can directly call the components from ``FilteredTransaction``, such as ``ftx.inputs`` Vs the old ``ftx.filteredLeaves.inputs``. * A new ``ComponentGroupEnum`` is added with the following enum items: ``INPUTS_GROUP``, ``OUTPUTS_GROUP``, - ``COMMANDS_GROUP``, ``ATTACHMENTS_GROUP``, ``NOTARY_GROUP``, ``TIMEWINDOW_GROUP``. + ``COMMANDS_GROUP``, ``ATTACHMENTS_GROUP``, ``NOTARY_GROUP``, ``TIMEWINDOW_GROUP``. * ``ContractUpgradeFlow.Initiator`` has been renamed to ``ContractUpgradeFlow.Initiate`` @@ -250,6 +266,8 @@ Release 1.0 * Current implementation of SSL in ``CordaRPCClient`` has been removed until we have a better solution which doesn't rely on the node's keystore. +.. _changelog_m14: + Milestone 14 ------------ @@ -343,6 +361,8 @@ Milestone 14 * Added JPA ``AbstractPartyConverter`` to ensure identity schema attributes are persisted securely according to type (well known party, resolvable anonymous party, completely anonymous party). +.. _changelog_m13: + Milestone 13 ------------ @@ -422,8 +442,10 @@ support for more currencies to the DemoBench and Explorer tools. * Upgraded BouncyCastle to v1.57. * Upgraded Requery to v1.3.1. -Milestone 12 ------------- +.. _changelog_m12: + +Milestone 12 (First Public Beta) +-------------------------------- * Quite a few changes have been made to the flow API which should make things simpler when writing CorDapps: diff --git a/docs/source/deploying-a-node.rst b/docs/source/deploying-a-node.rst index 0517d61c4d..562df5952f 100644 --- a/docs/source/deploying-a-node.rst +++ b/docs/source/deploying-a-node.rst @@ -61,6 +61,14 @@ one node as running the network map service, by putting their name in the ``netw .. warning:: When adding nodes, make sure that there are no port clashes! +If your CorDapp is written in Java, you should also add the following Gradle snippet so that you can pass named arguments to your flows via the Corda shell: + +.. sourcecode:: groovy + + tasks.withType(JavaCompile) { + options.compilerArgs << "-parameters" + } + Any CorDapps defined in the project's source folders are also automatically registered with all the nodes defined in ``deployNodes``, even if the CorDapps are not listed in each node's ``cordapps`` entry. @@ -86,4 +94,4 @@ run all the nodes at once. Each node in the ``nodes`` folder has the following s .. note:: Outside of development environments, do not store your node directories in the build folder. -If you make any changes to your ``deployNodes`` task, you will need to re-run the task to see the changes take effect. \ No newline at end of file +If you make any changes to your ``deployNodes`` task, you will need to re-run the task to see the changes take effect. diff --git a/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java b/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java index c9d708540d..1946a2501d 100644 --- a/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java +++ b/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java @@ -267,8 +267,7 @@ public class FlowCookbookJava { // We then need to pair our output state with a contract. // DOCSTART 47 - String contractName = "net.corda.testing.contracts.DummyContract"; - StateAndContract ourOutput = new StateAndContract(ourOutputState, contractName); + StateAndContract ourOutput = new StateAndContract(ourOutputState, DummyContract.PROGRAM_ID); // DOCEND 47 // Commands pair a ``CommandData`` instance with a list of diff --git a/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt b/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt index 8aa248f709..1fbee1e1be 100644 --- a/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt +++ b/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt @@ -255,8 +255,7 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // We then need to pair our output state with a contract. // DOCSTART 47 - val contractName: String = "net.corda.testing.contracts.DummyContract" - val ourOutput: StateAndContract = StateAndContract(ourOutputState, contractName) + val ourOutput: StateAndContract = StateAndContract(ourOutputState, DummyContract.PROGRAM_ID) // DOCEND 47 // Commands pair a ``CommandData`` instance with a list of diff --git a/docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt b/docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt new file mode 100644 index 0000000000..e6826fa213 --- /dev/null +++ b/docs/source/example-code/src/main/kotlin/net/corda/docs/LaunchSpaceshipFlow.kt @@ -0,0 +1,99 @@ +package net.corda.docs + +import co.paralleluniverse.fibers.Suspendable +import net.corda.core.flows.FlowLogic +import net.corda.core.flows.FlowSession +import net.corda.core.flows.InitiatedBy +import net.corda.core.flows.InitiatingFlow +import net.corda.core.identity.Party +import net.corda.core.utilities.unwrap + +// DOCSTART LaunchSpaceshipFlow +@InitiatingFlow +class LaunchSpaceshipFlow : FlowLogic() { + @Suspendable + override fun call() { + val shouldLaunchSpaceship = receive(getPresident()).unwrap { it } + if (shouldLaunchSpaceship) { + launchSpaceship() + } + } + + fun launchSpaceship() { + } + + fun getPresident(): Party { + TODO() + } +} + +@InitiatedBy(LaunchSpaceshipFlow::class) +@InitiatingFlow +class PresidentSpaceshipFlow(val launcher: Party) : FlowLogic() { + @Suspendable + override fun call() { + val needCoffee = true + send(getSecretary(), needCoffee) + val shouldLaunchSpaceship = false + send(launcher, shouldLaunchSpaceship) + } + + fun getSecretary(): Party { + TODO() + } +} + +@InitiatedBy(PresidentSpaceshipFlow::class) +class SecretaryFlow(val president: Party) : FlowLogic() { + @Suspendable + override fun call() { + // ignore + } +} +// DOCEND LaunchSpaceshipFlow + +// DOCSTART LaunchSpaceshipFlowCorrect +@InitiatingFlow +class LaunchSpaceshipFlowCorrect : FlowLogic() { + @Suspendable + override fun call() { + val presidentSession = initiateFlow(getPresident()) + val shouldLaunchSpaceship = presidentSession.receive().unwrap { it } + if (shouldLaunchSpaceship) { + launchSpaceship() + } + } + + fun launchSpaceship() { + } + + fun getPresident(): Party { + TODO() + } +} + +@InitiatedBy(LaunchSpaceshipFlowCorrect::class) +@InitiatingFlow +class PresidentSpaceshipFlowCorrect(val launcherSession: FlowSession) : FlowLogic() { + @Suspendable + override fun call() { + val needCoffee = true + val secretarySession = initiateFlow(getSecretary()) + secretarySession.send(needCoffee) + val shouldLaunchSpaceship = false + launcherSession.send(shouldLaunchSpaceship) + } + + fun getSecretary(): Party { + TODO() + } +} + +@InitiatedBy(PresidentSpaceshipFlowCorrect::class) +class SecretaryFlowCorrect(val presidentSession: FlowSession) : FlowLogic() { + @Suspendable + override fun call() { + // ignore + } +} +// DOCEND LaunchSpaceshipFlowCorrect diff --git a/docs/source/index.rst b/docs/source/index.rst index fab9e1ec77..75f9733f4e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,9 +1,6 @@ Welcome to Corda ! ================== -.. warningX:: This build of the docs is from the "|version|" branch, not a milestone release. It may not reflect the - current state of the code. `Read the docs for milestone release M12.1 `_. - `Corda `_ is a blockchain-inspired open source distributed ledger platform. If you’d like a quick introduction to distributed ledgers and how Corda is different, then watch this short video: diff --git a/docs/source/key-concepts-contract-constraints.rst b/docs/source/key-concepts-contract-constraints.rst index 6c3e536264..39840924fd 100644 --- a/docs/source/key-concepts-contract-constraints.rst +++ b/docs/source/key-concepts-contract-constraints.rst @@ -15,7 +15,7 @@ A typical constraint is the hash of the CorDapp JAR that contains the contract a include constraints that require specific signers of the JAR, or both the signer and the hash. Constraints can be specified when constructing a transaction; if unspecified, an automatic constraint is used. -``TransactionState``s have a ``constraint`` field that represents that state's attachment constraint. When a party +A ``TransactionState`` has a ``constraint`` field that represents that state's attachment constraint. When a party constructs a ``TransactionState`` without specifying the constraint parameter a default value (``AutomaticHashConstraint``) is used. This default will be automatically resolved to a specific ``HashAttachmentConstraint`` that contains the hash of the attachment which contains the contract of that @@ -80,7 +80,7 @@ attachment JAR. This allows for trusting of attachments from trusted entities. Limitations ----------- -``AttachmentConstraint``s are verified by running the ``AttachmentConstraint.isSatisfiedBy`` method. When this is called +An ``AttachmentConstraint`` is verified by running the ``AttachmentConstraint.isSatisfiedBy`` method. When this is called it is provided only the relevant attachment by the transaction that is verifying it. Testing diff --git a/docs/source/key-concepts-identity.rst b/docs/source/key-concepts-identity.rst new file mode 100644 index 0000000000..7f1f9bbcc2 --- /dev/null +++ b/docs/source/key-concepts-identity.rst @@ -0,0 +1,78 @@ +Identity +======== + +.. topic:: Summary + + * *Identities in Corda can represent legal identities or service identities* + * *Identities are attested to by X.509 certificate signed by the Doorman or a well known identity* + * *Well known identities are published in the network map* + * *Confidential identities are only shared on a need to know basis* + +Identities in Corda can represent: + +* Legal identity of an organisation +* Service identity of a network service + +Legal identities are used for parties in a transaction, such as the owner of a cash state. Service identities are used +for those providing transaction-related services, such as notary, or oracle. Service identities are distinct to legal +identities so that distributed services can exist on nodes owned by different organisations. Such distributed service +identities are based on ``CompositeKeys``, which describe the valid sets of signers for a signature from the service. +See :doc:`api-core-types` for more technical detail on composite keys. + +Identities are either well known or confidential, depending on whether their X.509 certificate (and corresponding +certificate path to a trusted root certificate) is published: + +* Well known identities are the generally identifiable public key of a legal entity or service, which makes them + ill-suited to transactions where confidentiality of participants is required. This certificate is published in the + network map service for anyone to access. +* Confidential identities are only published to those who are involved in transactions with the identity. The public + key may be exposed to third parties (for example to the notary service), but distribution of the name and X.509 + certificate is limited. + +Although there are several elements to the Corda transaction privacy model, including ensuring that transactions are +only shared with those who need to see them, and planned use of Intel SGX, it is important to provide defense in depth against +privacy breaches. Confidential identities are used to ensure that even if a third party gets access to an unencrypted +transaction, they cannot identify the participants without additional information. + +Name +---- + +Identity names are X.500 distinguished names with Corda-specific constraints applied. In order to be compatible with +other implementations (particularly TLS implementations), we constrain the allowed X.500 attribute types to a subset of +the minimum supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute: + +* organization (O) +* state (ST) +* locality (L) +* country (C) +* organizational-unit (OU) +* common name (CN) - used only for service identities + +The organisation, locality and country attributes are required, while state, organisational-unit and common name are +optional. Attributes cannot be be present more than once in the name. The "country" code is strictly restricted to valid +ISO 3166-1 two letter codes. + +Certificates +------------ + +Nodes must be able to verify the identity of the owner of a public key, which is achieved using X.509 certificates. +When first run a node generates a key pair and submits a certificate signing request to the network Doorman service +(see :doc:`permissioning`). +The Doorman service applies appropriate identity checks then issues a certificate to the node, which is used as the +node certificate authority (CA). From this initial CA certificate the node automatically creates and signs two further +certificates, a TLS certificate and a signing certificate for the node's well known identity. Finally the node +builds a node info record containing its address and well known identity, and registers it with the network map service. + +From the signing certificate the organisation can create both well known and confidential identities. Use-cases for +well known identities include clusters of nodes representing a single identity for redundancy purposes, or creating +identities for organisational units. + +It is up to organisations to decide which identities they wish to publish in the network map service, making them +well known, and which they wish to keep as confidential identities for privacy reasons (typically to avoid exposing +business sensitive details of transactions). In some cases nodes may also use private network map services in addition +to the main network map service, for operational reasons. Identities registered with such network maps must be +considered well known, and it is never appropriate to store confidential identities in a central directory without +controls applied at the record level to ensure only those who require access to an identity can retrieve its +certificate. + +.. TODO: Revisit once design & use cases of private maps is further fleshed out \ No newline at end of file diff --git a/docs/source/key-concepts.rst b/docs/source/key-concepts.rst index e83d04d093..a252e1a853 100644 --- a/docs/source/key-concepts.rst +++ b/docs/source/key-concepts.rst @@ -13,6 +13,7 @@ This section should be read in order: key-concepts-ecosystem key-concepts-ledger + key-concepts-identity key-concepts-states key-concepts-contracts key-concepts-contract-constraints diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index 4da3939152..845933db05 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -5,17 +5,112 @@ Here are release notes for each snapshot release from M9 onwards. Unreleased ---------- + Release 1.0 ----------- +Corda 1.0 is finally here! -* Flow communications API has been redesigned around session based communication. +This critical step in the Corda journey enables the developer community, clients, and partners to build on Corda with confidence. +Corda 1.0 is the first released version to provide API stability for Corda application (CorDapp) developers. +Corda applications will continue to work against this API with each subsequent release of Corda. The public API for Corda +will only evolve to include new features. -* Merged handling of well known and confidential identities in the identity service. +As of Corda 1.0, the following modules export public APIs for which we guarantee to maintain backwards compatibility, +unless an incompatible change is required for security reasons: -* Remove `IssuerFlow` as it allowed nodes to request arbitrary amounts of cash to be issued from any remote node. + * **core**: + Contains the bulk of the APIs to be used for building CorDapps: contracts, transactions, flows, identity, node services, + cryptographic libraries, and general utility functions. -* Remove the legacy web front end from the SIMM demo. This was a very early sample, and does not reflect the quality of - current Corda code. It may be replaced with a new front end based on a more recent version of AngularJS in a later release. + * **client-rpc**: + An RPC client interface to Corda, for use by both UI facing clients and integration with external systems. + + * **client-jackson**: + Utilities and serialisers for working with JSON representations of basic types. + +Our extensive testing frameworks will continue to evolve alongside future Corda APIs. As part of our commitment to ease of use and modularity +we have introduced a new test node driver module to encapsulate all test functionality in support of building standalone node integration +tests using our DSL driver. + +Please read :doc:`api-index` for complete details. + +.. note:: it may be necessary to recompile applications against future versions of the API until we begin offering + `ABI (Application Binary Interface) `_ stability as well. + We plan to do this soon after this release of Corda. + +Significant changes implemented in reaching Corda API stability include: + +* **Flow framework**: + The Flow framework communications API has been redesigned around session based communication with the introduction of a new + ``FlowSession`` to encapsulate the counterparty information associated with a flow. + All shipped Corda flows have been upgraded to use the new `FlowSession`. Please read :doc:`api-flows` for complete details. + +* **Complete API cleanup**: + Across the board, all our public interfaces have been thoroughly revised and updated to ensure a productive and intuitive developer experience. + Methods and flow naming conventions have been aligned with their semantic use to ease the understanding of CorDapps. + In addition, we provide ever more powerful re-usable flows (such as `CollectSignaturesFlow`) to minimize the boiler-plate code developers need to write. + +* **Simplified annotation driven scanning**: + CorDapp configuration has been made simpler through the removal of explicit configuration items in favour of annotations + and classpath scanning. As an example, we have now completely removed the `CordaPluginRegistry` configuration. + Contract definitions are no longer required to explicitly define a legal contract reference hash. In their place an + optional `LegalProseReference` annotation to specify a URI is used. + +* **Java usability**: + All code has been updated to enable simple access to static API parameters. Developers no longer need to + call getter methods, and can reference static API variables directly. + +In addition to API stability this release encompasses a number of major functional improvements, including: + +* **Contract constraints**: + Provides a means with which to enforce a specific implementation of a State's verify method during transaction verification. + When loading an attachment via the attachment classloader, constraints of a transaction state are checked against the + list of attachment hashes provided, and the attachment is rejected if the constraints are not matched. + +* **Signature Metadata support**: + Signers now have the ability to add metadata to their digital signatures. Whereas previously a user could only sign the Merkle root of a + transaction, it is now possible for extra information to be attached to a signature, such as a platform version + and the signature-scheme used. + + .. image:: resources/signatureMetadata.png + +* **Backwards compatibility and improvements to core transaction data structures**: + A new Merkle tree model has been introduced that utilises sub-Merkle trees per component type. Components of the + same type, such as inputs or commands, are grouped together and form their own Merkle tree. Then, the roots of + each group are used as leaves in the top-level Merkle tree. This model enables backwards compatibility, in the + sense that if new component types are added in the future, old clients will still be able to compute the Merkle root + and relay transactions even if they cannot read (deserialise) the new component types. Due to the above, + `FilterTransaction` has been made simpler with a structure closer to `WireTransaction`. This has the effect of making the API + more user friendly and intuitive for both filtered and unfiltered transactions. + +* **Enhanced component privacy**: + Corda 1.0 is equipped with a scalable component visibility design based on the above sophisticated + sub-tree model and the introduction of nonces per component. Roughly, an initial base-nonce, the "privacy-salt", + is used to deterministically generate nonces based on the path of each component in the tree. Because each component + is accompanied by a nonce, we protect against brute force attacks, even against low-entropy components. In addition, + a new privacy feature is provided that allows non-validating notaries to ensure they see all inputs and if there was a + `TimeWindow` in the original transaction. Due to the above, a malicious user cannot selectively hide one or more + input states from the notary that would enable her to bypass the double-spending check. The aforementioned + functionality could also be applied to Oracles so as to ensure all of the commands are visible to them. + + .. image:: resources/subTreesPrivacy.png + +* **Full support for confidential identities**: + This includes rework and improvements to the identity service to handle both `well known` and `confidential` identities. + This work ships in an experimental module in Corda 1.0, called `confidential-identities`. API stabilisation of confidential + identities will occur as we make the integration of this privacy feature into applications even easier for developers. + +* **Re-designed network map service**: + The foundations for a completely redesigned network map service have been implemented to enable future increased network + scalability and redundancy, support for multiple notaries, and administration of network compatibility zones and business networks. + +Finally, please note that the 1.0 release has not yet been security audited. + +We have provided a comprehensive :doc:`upgrade-notes` to ease the transition of migrating CorDapps to Corda 1.0 + +Upgrading to this release is strongly recommended, and you will be safe in the knowledge that core APIs will no longer break. + +Thank you to all contributors for this release! Milestone 14 ------------ diff --git a/docs/source/release-process-index.rst b/docs/source/release-process-index.rst index f1c9ea2037..eb81e833f0 100644 --- a/docs/source/release-process-index.rst +++ b/docs/source/release-process-index.rst @@ -6,4 +6,6 @@ Release process release-notes changelog + upgrade-notes + codestyle testing \ No newline at end of file diff --git a/docs/source/resources/signatureMetadata.png b/docs/source/resources/signatureMetadata.png new file mode 100644 index 0000000000000000000000000000000000000000..61f0d11e17a25f376ebbefcb534630d92a334ac5 GIT binary patch literal 18666 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 literal 0 HcmV?d00001 diff --git a/docs/source/resources/subTreesPrivacy.png b/docs/source/resources/subTreesPrivacy.png new file mode 100644 index 0000000000000000000000000000000000000000..3a7dae6110f8d735ee0648caf33e94b0afd919c4 GIT binary patch literal 105835 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%0DT|or6oc1(R*d@m`)QEC>>Cfs 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 Aj{pDw literal 0 HcmV?d00001 diff --git a/docs/source/running-the-demos.rst b/docs/source/running-the-demos.rst index 32a99967c6..f9e78737d1 100644 --- a/docs/source/running-the-demos.rst +++ b/docs/source/running-the-demos.rst @@ -143,19 +143,18 @@ To run from the command line in Windows: To run the BFT SMaRt notary demo, use ``nodesBFT`` instead of ``nodesRaft`` in the path (you will see messages from notary nodes trying to communicate each other sometime with connection errors, that's normal). For a single notary node, use ``nodesSingle``. -Notary nodes store consumed states in a replicated commit log, which is backed by a H2 database on each node. +Distributed notary nodes store consumed states in a replicated commit log, which is backed by a H2 database on each node. You can ascertain that the commit log is synchronised across the cluster by accessing and comparing each of the nodes' backing stores by using the H2 web console: - Firstly, download `H2 web console `_ (download the "platform-independent zip"), - and start it using a script in the extracted folder: ``h2/bin/h2.sh`` (or ``h2\bin\h2`` for Windows) + and start it using a script in the extracted folder: ``sh h2/bin/h2.sh`` (or ``h2\bin\h2`` for Windows) - If you are uncertain as to which version of h2 to install or if you have connectivity issues, refer to ``build.gradle`` - located in the ``node`` directory and locate the compile step for ``com.h2database``. Use a client of the same - major version - even if still in beta. + located in the corda directory and locate ``h2_version``. Use a client of the same major version - even if still in beta. - The H2 web console should start up in a web browser tab. To connect we first need to obtain a JDBC connection string. - Each node outputs its connection string in the terminal window as it starts up. In a terminal window where a node is running, + Each node outputs its connection string in the terminal window as it starts up. In a terminal window where a **notary** node is running, look for the following string: ``Database connection url is : jdbc:h2:tcp://10.18.0.150:56736/node`` @@ -163,8 +162,8 @@ by using the H2 web console: You can use the string on the right to connect to the h2 database: just paste it into the `JDBC URL` field and click *Connect*. You will be presented with a web application that enumerates all the available tables and provides an interface for you to query them using SQL -- The committed states are stored in the ``NOTARY_COMMITTED_STATES`` table. Note that the raw data is not human-readable, - but we're only interested in the row count for this demo +- The committed states are stored in the ``NOTARY_COMMITTED_STATES`` table (for Raft) or ``NODE_BFT_SMART_NOTARY_COMMITTED_STATES`` (for BFT). + Note that in the Raft case the raw data is not human-readable, but we're only interested in the row count for this demo .. _bank-of-corda-demo: diff --git a/docs/source/serialization.rst b/docs/source/serialization.rst index ca86da886c..92d542dd71 100644 --- a/docs/source/serialization.rst +++ b/docs/source/serialization.rst @@ -22,8 +22,8 @@ Classes get onto the whitelist via one of three mechanisms: #. Via the ``@CordaSerializable`` annotation. In order to whitelist a class, this annotation can be present on the class itself, on any of the super classes or on any interface implemented by the class or super classes or any interface extended by an interface implemented by the class or superclasses. -#. By returning the class as part of a plugin via the method ``customizeSerialization``. It's important to return - true from this method if you override it, otherwise the plugin will be excluded. See :doc:`writing-cordapps`. +#. By implementing the ``SerializationWhitelist`` interface and specifying a list of `whitelist` classes. + See :doc:`writing-cordapps`. #. Via the built in Corda whitelist (see the class ``DefaultWhitelist``). Whilst this is not user editable, it does list common JDK classes that have been whitelisted for your convenience. @@ -39,8 +39,8 @@ It's reproduced here as an example of both ways you can do this for a couple of them will automatically be whitelisted. This includes `Contract`, `ContractState` and `CommandData`. .. warning:: Java 8 Lambda expressions are not serializable except in flow checkpoints, and then not by default. The syntax to declare a serializable Lambda -expression that will work with Corda is ``Runnable r = (Runnable & Serializable) () -> System.out.println("Hello World");``, or -``Callable c = (Callable & Serializable) () -> "Hello World";``. + expression that will work with Corda is ``Runnable r = (Runnable & Serializable) () -> System.out.println("Hello World");``, or + ``Callable c = (Callable & Serializable) () -> "Hello World";``. .. warning:: We will be replacing the use of Kryo in the serialization framework and so additional changes here are likely. diff --git a/docs/source/shell.rst b/docs/source/shell.rst index 5d00d73890..cdddc4548e 100644 --- a/docs/source/shell.rst +++ b/docs/source/shell.rst @@ -99,6 +99,10 @@ Nested objects can be created using curly braces, as in ``{ a: 1, b: 2}``. This parser is defined for the type you need, for instance, if an API requires a ``Pair`` which could be represented as ``{ first: foo, second: 123 }``. +.. note:: If your CorDapp is written in Java, + named arguments won't work unless you compiled using the ``-parameters`` argument to javac. + See :doc:`deploying-a-node` for how to specify it via Gradle. + The same syntax is also used to specify the parameters for RPCs, accessed via the ``run`` command, like this: ``run registeredFlows`` diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index a07980119c..51e60133c4 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -23,6 +23,11 @@ Some of the unit tests, and our serialization framework in general, rely on the to Java reflection. Make sure you have specified the ``-parameters`` option to the Java compiler. We attempt to set this globally for gradle and IntelliJ, but it's possible this option is not present in your environment for some reason. +"No matching constructor found: - [arg0: int, arg1: Party]: missing parameter arg0" +*********************************************************************************** + +Your CorDapp is written in Java and you haven't specified the ``-parameters`` compiler argument. See :doc:`deploying-a-node` for how it can be done using Gradle. + IDEA issues ----------- diff --git a/docs/source/tut-two-party-flow.rst b/docs/source/tut-two-party-flow.rst index 84acdb6f7c..b19630eb32 100644 --- a/docs/source/tut-two-party-flow.rst +++ b/docs/source/tut-two-party-flow.rst @@ -125,10 +125,10 @@ In a new ``IOUFlowResponder.java`` file in Java, or within the ``App.kt`` file i ... @InitiatedBy(IOUFlow::class) - class IOUFlowResponder(val otherPartyFlow: FlowSession) : FlowLogic() { + class IOUFlowResponder(val otherPartySession: FlowSession) : FlowLogic() { @Suspendable override fun call() { - val signTransactionFlow = object : SignTransactionFlow(otherPartyFlow, SignTransactionFlow.tracker()) { + val signTransactionFlow = object : SignTransactionFlow(otherPartySession, SignTransactionFlow.tracker()) { override fun checkTransaction(stx: SignedTransaction) = requireThat { val output = stx.tx.outputs.single().data "This must be an IOU transaction." using (output is IOUState) @@ -148,7 +148,11 @@ In a new ``IOUFlowResponder.java`` file in Java, or within the ``App.kt`` file i import co.paralleluniverse.fibers.Suspendable; import com.template.state.IOUState; import net.corda.core.contracts.ContractState; - import net.corda.core.flows.*; + import net.corda.core.flows.FlowException; + import net.corda.core.flows.FlowLogic; + import net.corda.core.flows.FlowSession; + import net.corda.core.flows.InitiatedBy; + import net.corda.core.flows.SignTransactionFlow; import net.corda.core.transactions.SignedTransaction; import net.corda.core.utilities.ProgressTracker; @@ -156,18 +160,18 @@ In a new ``IOUFlowResponder.java`` file in Java, or within the ``App.kt`` file i @InitiatedBy(IOUFlow.class) public class IOUFlowResponder extends FlowLogic { - private final FlowSession otherPartyFlow; + private final FlowSession otherPartySession; - public IOUFlowResponder(FlowSession otherPartyFlow) { - this.otherPartyFlow = otherPartyFlow; + public IOUFlowResponder(FlowSession otherPartySession) { + this.otherPartySession = otherPartySession; } @Suspendable @Override public Void call() throws FlowException { - class signTxFlow extends SignTransactionFlow { - private signTxFlow(FlowSession otherPartyFlow, ProgressTracker progressTracker) { - super(otherPartyFlow, progressTracker); + class SignTxFlow extends SignTransactionFlow { + private signTxFlow(FlowSession otherPartySession, ProgressTracker progressTracker) { + super(otherPartySession, progressTracker); } @Override @@ -182,7 +186,7 @@ In a new ``IOUFlowResponder.java`` file in Java, or within the ``App.kt`` file i } } - subFlow(new signTxFlow(otherPartyFlow, SignTransactionFlow.Companion.tracker())); + subFlow(new SignTxFlow(otherPartySession, SignTransactionFlow.Companion.tracker())); return null; } diff --git a/docs/source/tutorial-tear-offs.rst b/docs/source/tutorial-tear-offs.rst index 80d8395112..fe665bf3bf 100644 --- a/docs/source/tutorial-tear-offs.rst +++ b/docs/source/tutorial-tear-offs.rst @@ -49,11 +49,10 @@ The following code snippet is taken from ``NodeInterestRates.kt`` and implements :end-before: DOCEND 1 :dedent: 8 -.. note:: The way the ``FilteredTransaction`` is constructed ensures that after signing of the root hash it's impossible - to add or remove components (leaves). However, it can happen that having transaction with multiple commands one party - reveals only subset of them to the Oracle. As signing is done now over the Merkle root hash, the service signs all - commands of given type, even though it didn't see all of them. In the case however where all of the commands should be - visible to an Oracle, one can type ``ftx.checkAllComponentsVisible(COMMANDS_GROUP)`` before invoking ``ftx.verify``. +.. note:: The way the ``FilteredTransaction`` is constructed ensures that after signing of the root hash it's impossible to add or remove + components (leaves). However, it can happen that having transaction with multiple commands one party reveals only subset of them to the Oracle. + As signing is done now over the Merkle root hash, the service signs all commands of given type, even though it didn't see + all of them. In the case however where all of the commands should be visible to an Oracle, one can type ``ftx.checkAllComponentsVisible(COMMANDS_GROUP)`` before invoking ``ftx.verify``. ``checkAllComponentsVisible`` is using a sophisticated underlying partial Merkle tree check to guarantee that all of the components of a particular group that existed in the original ``WireTransaction`` are included in the received ``FilteredTransaction``. \ No newline at end of file diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst new file mode 100644 index 0000000000..3f6444d497 --- /dev/null +++ b/docs/source/upgrade-notes.rst @@ -0,0 +1,349 @@ +Upgrade notes +============= + +These notes provide helpful instructions to upgrade your Corda Applications (CorDapps) from previous versions, starting +from our first public Beta (:ref:`Milestone 12 `), to :ref:`V1.0 ` + +General +------- +Always remember to update the version identifiers in your project gradle file: + +.. sourcecode:: shell + + ext.corda_release_version = '1.0.0' + ext.corda_gradle_plugins_version = '1.0.0' + +It may be necessary to update the version of major dependencies: + +.. sourcecode:: shell + + ext.kotlin_version = '1.1.4' + ext.quasar_version = '0.7.9' + +Please consult the relevant release notes of the release in question. If not specified, you may assume the +versions you are currently using are still in force. + +We also strongly recommend cross referencing with the :doc:`changelog` to confirm changes. + +:ref:`Milestone 14 ` +------------ + +Build +^^^^^ + +* MockNetwork has moved. + + A new test driver module dependency needs to be including in your project: `corda-node-driver`. To continue using the + mock network for testing, add the following entry to your gradle build file: + +.. sourcecode:: shell + + testCompile "net.corda:corda-node-driver:$corda_release_version" + +.. note:: you may only need `testCompile "net.corda:corda-test-utils:$corda_release_version"` if not using the Driver DSL. + +Configuration +^^^^^^^^^^^^^ + +* ``CordaPluginRegistry`` has been removed. + The one remaining configuration item ``customizeSerialisation``, which defined a optional whitelist of types for use in + object serialization, has been replaced with the ``SerializationWhitelist`` interface which should be implemented to + define a list of equivalent whitelisted classes. + You will need to rename your services resource file to the new class name: + 'resources/META-INF/services/net.corda.core.node.CordaPluginRegistry' becomes 'resources/META-INF/services/net.corda.core.serialization.SerializationWhitelist' + An associated property on ``MockNode`` was renamed from ``testPluginRegistries`` to ``testSerializationWhitelists``. + In general, the ``@CordaSerializable`` annotation is the preferred method for whitelisting as described in :doc:`serialization` + +Missing imports +^^^^^^^^^^^^^^^ + +Use the automatic imports feature of IntelliJ to intelligently resolve the new imports. + +* Missing imports for contract types. + + CommercialPaper and Cash are now contained within the `finance` module, as are associated helpers functions. + For example: + ``import net.corda.contracts.ICommercialPaperState`` becomes ``import net.corda.finance.contracts.ICommercialPaperState`` + + ``import net.corda.contracts.asset.sumCashBy`` becomes ``import net.corda.finance.utils.sumCashBy`` + + ``import net.corda.core.contracts.DOLLARS`` becomes ``import net.corda.finance.DOLLARS`` + + ``import net.corda.core.contracts.issued by`` becomes ``import net.corda.finance.issued by`` + + ``import net.corda.contracts.asset.Cash`` becomes ``import net.corda.finance.contracts.asset.Cash`` + +* Missing imports for utility functions. + + Many common types and helper methods have been consolidated into `net.corda.core.utilities` package. + For example: + ``import net.corda.core.crypto.commonName`` becomes ``import net.corda.core.utilities.commonName`` + + ``import net.corda.core.crypto.toBase58String`` becomes ``import net.corda.core.utilities.toBase58String`` + + ``import net.corda.core.getOrThrow`` becomes ``import net.corda.core.utilities.getOrThrow`` + +* Missing flow imports. + + In general all reusable library flows are contained within the **core** API `net.corda.core.flows` package. + Financial domain library flows are contained within the **finance** module `net.corda.finance.flows` package. + Other flows that have moved include: + + ``import net.corda.core.flows.ResolveTransactionsFlow`` becomes ``import net.corda.core.internal.ResolveTransactionsFlow`` + +Core data structures +^^^^^^^^^^^^^^^^^^^^ + +* Missing Contract override. + + The contract interace attribute ``legalContractReference`` has been removed, and replaced by + the optional annotation ``@LegalProseReference(uri = "")`` + +* Unresolved reference. + + Calls to ``AuthenticatedObject`` are replaced by ``CommandWithParties`` + +* Overrides nothing: ``isRelevant`` in ``LinearState``. + + Removed the concept of relevancy from ``LinearState``. A ``ContractState``'s relevance to the vault is now resolved + internally; the vault will process any transaction from a flow which is not derived from transaction resolution verification. + The notion of relevancy is subject to further improvements to enable a developer to control what state the vault thinks + are relevant. + +* Calls to ``txBuilder.toLedgerTransaction()`` now requires a serviceHub parameter. + + Used by the new Contract Constraints functionality to validate and resolve attachments. + +Flow framework +^^^^^^^^^^^^^^ + +* Flow session deprecations + + ``FlowLogic`` communication has been upgraded to use functions on ``FlowSession`` as the base for communication + between nodes. + + * Calls to ``send()``, ``receive()`` and ``sendAndReceive()`` on FlowLogic should be replaced with calls + to the function of the same name on ``FlowSession``. Note that the replacement functions do not take in a destination + parameter, as this is defined in the session. + + * Initiated flows now take in a ``FlowSession`` instead of ``Party`` in their constructor. If you need to access the + counterparty identity, it is in the ``counterparty`` property of the flow session. + + See ``FlowSession`` for step by step instructions on porting existing flows to use the new mechanism. + +* ``FinalityFlow`` now returns a single ``SignedTransaction``, instead of a ``List`` + +* ``TransactionKeyFlow`` renamed to ``SwapIdentitiesFlow`` + + Note that ``SwapIdentitiesFlow`` must be imported from the *confidential-identities** package ''net.corda.confidential'' + +Node services (ServiceHub) +^^^^^^^^^^^^^^ + +* VaultQueryService: unresolved reference to `vaultQueryService`. + + Replace all references to ``.vaultQueryService`` with ``.vaultService``. + Previously there were two vault APIs. Now there is a single unified API with the same functions: ``VaultService``. + +* ``serviceHub.myInfo.legalIdentity`` no longer exists; use the ``ourIdentity`` property of the flow instead. + + ``FlowLogic.ourIdentity`` has been introduced as a shortcut for retrieving our identity in a flow + +* ``getAnyNotary`` is gone - use ``serviceHub.networkMapCache.notaryIdentities[0]`` instead + + Note: ongoing work to support multiple notary identities is still in progress. + +* ``ServiceHub.networkMapUpdates`` is replaced by ``ServiceHub.networkMapFeed`` + +* ``ServiceHub.partyFromX500Name`` is replaced by ``ServiceHub.wellKnownPartyFromX500Name`` + Note: A "well known" party is one that isn't anonymous and this change was motivated by the confidential identities work. + +RPC Client +^^^^^^^^^^ + +* Missing API methods on `CordaRPCOps` interface. + + * Calls to ``verifiedTransactionsFeed()`` and ``verifiedTransactions()`` have been replaced with: + ``internalVerifiedTransactionsSnapshot()`` and ``internalVerifiedTransactionsFeed()`` respectively + + This is in preparation for the planned integration of Intel SGX™, which will encrypt the transactions feed. + Apps that use this API will not work on encrypted ledgers: you should probably be using the vault query API instead. + + * Accessing the `networkMapCache` via ``services.nodeInfo().legalIdentities`` returns a list of identities. + The first element in the list is the Party object referring to a node's single identity. + + This is in preparation for allowing a node to host multiple separate identities in future. + +Testing +^^^^^^^ + +Please note that `Clauses` have been removed completely as of V1.0. +We will be revisiting this capability in a future release. + +* CorDapps must be explicitly registered in ``MockNetwork`` unit tests. + + This is done by calling ``setCordappPackages``, an extension helper function in the ``net.corda.testing`` package, + on the first line of your `@Before` method. This takes a variable number of `String` arguments which should be the + package names of the CorDapps containing the contract verification code you wish to load. + You should unset CorDapp packages in your `@After` method by using ``unsetCordappPackages()`` after `stopNodes()`. + +* CorDapps must be explicitly registered in ``DriverDSL`` and ``RPCDriverDSL`` integration tests. + + Similarly, you must also register package names of the CorDapps containing the contract verification code you wish to load + using the ``extraCordappPackagesToScan: List`` constructor parameter of the driver DSL. + +Finance +^^^^^^^ + +* `FungibleAsset` interface simplification. + + The ``FungibleAsset`` interface has been made simpler. The ``Commands`` grouping interface + that included the ``Move``, ``Issue`` and ``Exit`` interfaces have all been removed, while the ``move`` function has + been renamed to ``withNewOwnerAndAmount`` to be consistent with the ``withNewOwner`` function of the ``OwnableState``. + + The following errors may be reported: + + * override nothing (FungibleAsset): `move` + * not a subtype of overridden FungibleAsset: `withNewOwner` + * no longer need to override `override val contractHash: SecureHash? = null` + * need to override `override val contract: Class? = null` + + +Miscellaneous +^^^^^^^^^^^^^ + +* ``args[0].parseNetworkHostAndPort()`` becomes ``NetworkHostAndPort.parse(args[0])`` + +* There is no longer a ``NodeInfo.advertisedServices`` property. + + The concept of advertised services has been removed from Corda. This is because it was vaguely defined and real world + apps would not typically select random, unknown counterparties from the network map based on self-declared capabilities. + We will introduce a replacement for this functionality, business networks, in a future release. + +Gotchas +^^^^^^^ + +* Beware to use the correct identity when issuing cash: + + The 3rd parameter to ``CashIssueFlow`` should be the ** notary ** (not the ** node identity **) + + +:ref:`Milestone 13 ` +------------ + +Core data structures +^^^^^^^^^^^^^^^^^^^^ + +* `TransactionBuilder` changes. + + Use convenience class ``StateAndContract`` instead of ``TransactionBuilder.withItems()`` for passing + around a state and its contract. + +* Transaction building DSL changes: + + * now need to explicitly pass the ContractClassName into all inputs and outputs. + * `ContractClassName` refers to the class containing the “verifier” method. + +* Contract verify method signature change. + + ``override fun verify(tx: TransactionForContract)`` becomes ``override fun verify(tx: LedgerTransaction)`` + +* No longer need to override Contract ``contract()`` function. + +Node services (ServiceHub) +^^^^^^^^^^^^^ + +* ServiceHub API method changes. + + ``services.networkMapUpdates().justSnapshot`` becomes ``services.networkMapSnapshot()`` + +Configuration +^^^^^^^^^^^^^ + +* No longer need to define ``CordaPluginRegistry`` and configure ``requiredSchemas`` + + Custom contract schemas are automatically detected at startup time by class path scanning. + For testing purposes, use the ``SchemaService`` method to register new custom schemas: + eg. ``services.schemaService.registerCustomSchemas(setOf(YoSchemaV1))`` + +Identity +^^^^^^^^ + +* Party names are now ``CordaX500Name``, not ``X500Name`` + + ``CordaX500Name`` specifies a predefined set of mandatory (organisation, locality, country) + and optional fields (commonName, organisationUnit, state) with validation checking. + Use new builder CordaX500Name.build(X500Name(target)) or, preferably, explicitly define X500Name parameters using + ``CordaX500Name`` constructor. + +Testing +^^^^^^^ + +* MockNetwork Testing. + + Mock nodes in node tests are now of type ``StartedNode``, rather than ``MockNode`` + MockNetwork now returns a BasketOf(>) + Must call internals on StartedNode to get MockNode: + a = nodes.partyNodes[0].internals + b = nodes.partyNodes[1].internals + +* Host and Port change. + + Use string helper function ``parseNetworkHostAndPort()`` to parse a URL on startup. + eg. ``val hostAndPort = args[0].parseNetworkHostAndPort()`` + +* The node driver parameters for starting a node have been reordered, and the node’s name needs to be given as an + ``CordaX500Name``, instead of using ``getX509Name`` + + +:ref:`Milestone 12 ` (First Public Beta) +----------------------------------- + +Core data structures +^^^^^^^^^^^^^^^^^^^^ + +* Transaction building + + You no longer need to specify the type of a ``TransactionBuilder`` as ``TransactionType.General`` + ``TransactionType.General.Builder(notary)`` becomes ``TransactionBuilder(notary)`` + +Build +^^^^^ + +* Gradle dependency reference changes. + + Module name has changed to include `corda` in the artifacts jar name: + +.. sourcecode:: shell + + compile "net.corda:core:$corda_release_version" -> compile "net.corda:corda-core:$corda_release_version" + compile "net.corda:finance:$corda_release_version" -> compile "net.corda:corda-finance:$corda_release_version" + compile "net.corda:jackson:$corda_release_version" -> compile "net.corda:corda-jackson:$corda_release_version" + compile "net.corda:node:$corda_release_version" -> compile "net.corda:corda-node:$corda_release_version" + compile "net.corda:rpc:$corda_release_version" -> compile "net.corda:corda-rpc:$corda_release_version" + +Node services (ServiceHub) +^^^^^^^^^^^^^ + +* ServiceHub API changes. + + ``services.networkMapUpdates()`` becomes ``services.networkMapFeed()`` + ``services.getCashBalances()`` becomes a helper method within the **finance** module contracts package: ``net.corda.finance.contracts.getCashBalances`` + +Finance +^^^^^^^ + +* Financial asset contracts (Cash, CommercialPaper, Obligations) are now a standalone CorDapp within the **finance** module. + + Need to import from respective package within `finance` module: + eg. ``net.corda.finance.contracts.asset.Cash`` + + Likewise, need to import associated asset flows from respective package within `finance` module: + eg. ``net.corda.finance.flows.CashIssueFlow`` + ``net.corda.finance.flows.CashIssueAndPaymentFlow`` + ``net.corda.finance.flows.CashExitFlow`` + +* Moved ``finance`` gradle project files into a ``net.corda.finance`` package namespace. + + This may require adjusting imports of Cash flow references and also of ``StartFlow`` permission in ``gradle.build`` files. + Associated flows (`Cash*Flow`, `TwoPartyTradeFlow`, `TwoPartyDealFlow`) must now be imported from this package. diff --git a/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyDealFlow.kt b/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyDealFlow.kt index f87bfb2390..0525cead6a 100644 --- a/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyDealFlow.kt +++ b/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyDealFlow.kt @@ -50,12 +50,14 @@ object TwoPartyDealFlow { abstract val notaryParty: Party abstract val otherSideSession: FlowSession + // DOCSTART 2 @Suspendable override fun call(): SignedTransaction { progressTracker.currentStep = GENERATING_ID val txIdentities = subFlow(SwapIdentitiesFlow(otherSideSession.counterparty)) val anonymousMe = txIdentities[ourIdentity] ?: ourIdentity.anonymise() val anonymousCounterparty = txIdentities[otherSideSession.counterparty] ?: otherSideSession.counterparty.anonymise() + // DOCEND 2 progressTracker.currentStep = SENDING_PROPOSAL // Make the first message we'll send to kick off the flow. val hello = Handshake(payload, anonymousMe, anonymousCounterparty) diff --git a/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt b/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt index 47da4a403a..d243792253 100644 --- a/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt +++ b/finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt @@ -169,6 +169,7 @@ object TwoPartyTradeFlow { progressTracker.currentStep = SIGNING val (ptx, cashSigningPubKeys) = assembleSharedTX(assetForSale, tradeRequest, buyerAnonymousIdentity) + // DOCSTART 6 // Now sign the transaction with whatever keys we need to move the cash. val partSignedTx = serviceHub.signInitialTransaction(ptx, cashSigningPubKeys) @@ -180,6 +181,7 @@ object TwoPartyTradeFlow { progressTracker.currentStep = COLLECTING_SIGNATURES val sellerSignature = subFlow(CollectSignatureFlow(partSignedTx, sellerSession, sellerSession.counterparty.owningKey)) val twiceSignedTx = partSignedTx + sellerSignature + // DOCEND 6 // Notarise and record the transaction. progressTracker.currentStep = RECORDING @@ -202,8 +204,8 @@ object TwoPartyTradeFlow { // Register the identity we're about to send payment to. This shouldn't be the same as the asset owner // identity, so that anonymity is enforced. - val wellKnownPayToIdentity = serviceHub.identityService.verifyAndRegisterIdentity(it.payToIdentity) - require(wellKnownPayToIdentity?.party == sellerSession.counterparty) { "Well known identity to pay to must match counterparty identity" } + val wellKnownPayToIdentity = serviceHub.identityService.verifyAndRegisterIdentity(it.payToIdentity) ?: it.payToIdentity + require(wellKnownPayToIdentity.party == sellerSession.counterparty) { "Well known identity to pay to must match counterparty identity" } if (it.price > acceptablePrice) throw UnacceptablePriceException(it.price) diff --git a/node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt b/node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt index 27c9a3d08a..fd803ee9ef 100644 --- a/node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt +++ b/node/src/integration-test/kotlin/net/corda/node/services/AttachmentLoadingTests.kt @@ -1,7 +1,5 @@ package net.corda.node.services -import net.corda.client.rpc.RPCException -import net.corda.core.concurrent.CordaFuture import net.corda.core.contracts.Contract import net.corda.core.contracts.PartyAndReference import net.corda.core.cordapp.CordappProvider @@ -18,7 +16,6 @@ import net.corda.core.transactions.TransactionBuilder import net.corda.core.utilities.OpaqueBytes import net.corda.core.utilities.getOrThrow import net.corda.core.utilities.loggerFor -import net.corda.node.internal.StartedNode import net.corda.node.internal.cordapp.CordappLoader import net.corda.node.internal.cordapp.CordappProviderImpl import net.corda.node.services.transactions.SimpleNotaryService @@ -27,19 +24,15 @@ import net.corda.nodeapi.internal.ServiceInfo import net.corda.testing.DUMMY_BANK_A import net.corda.testing.DUMMY_NOTARY import net.corda.testing.TestDependencyInjectionBase -import net.corda.testing.driver.DriverDSL import net.corda.testing.driver.DriverDSLExposedInterface import net.corda.testing.driver.NodeHandle import net.corda.testing.driver.driver import net.corda.testing.node.MockServices -import net.corda.testing.resetTestSerialization -import org.junit.Assert.* +import org.junit.Assert.assertEquals import org.junit.Before import org.junit.Test import java.net.URLClassLoader import java.nio.file.Files -import java.sql.Driver -import kotlin.test.assertFails import kotlin.test.assertFailsWith class AttachmentLoadingTests : TestDependencyInjectionBase() { diff --git a/node/src/test/kotlin/net/corda/node/messaging/TwoPartyTradeFlowTests.kt b/node/src/test/kotlin/net/corda/node/messaging/TwoPartyTradeFlowTests.kt index 30ec451570..4cdcbc42e4 100644 --- a/node/src/test/kotlin/net/corda/node/messaging/TwoPartyTradeFlowTests.kt +++ b/node/src/test/kotlin/net/corda/node/messaging/TwoPartyTradeFlowTests.kt @@ -51,6 +51,8 @@ import org.assertj.core.api.Assertions.assertThat import org.junit.After import org.junit.Before import org.junit.Test +import org.junit.runner.RunWith +import org.junit.runners.Parameterized import rx.Observable import java.io.ByteArrayInputStream import java.io.ByteArrayOutputStream @@ -69,7 +71,15 @@ import kotlin.test.assertTrue * * We assume that Alice and Bob already found each other via some market, and have agreed the details already. */ -class TwoPartyTradeFlowTests { +@RunWith(Parameterized::class) +class TwoPartyTradeFlowTests(val anonymous: Boolean) { + companion object { + @JvmStatic + @Parameterized.Parameters + fun data(): Collection { + return listOf(true, false) + } + } private lateinit var mockNet: MockNetwork @Before @@ -542,8 +552,7 @@ class TwoPartyTradeFlowTests { private fun runBuyerAndSeller(notary: Party, sellerNode: StartedNode, buyerNode: StartedNode, - assetToSell: StateAndRef, - anonymous: Boolean = true): RunResult { + assetToSell: StateAndRef): RunResult { val buyerFlows: Observable> = buyerNode.internals.registerInitiatedFlow(BuyerAcceptor::class.java) val firstBuyerFiber = buyerFlows.toFuture().map { it.stateMachine } val seller = SellerInitiator(buyerNode.info.chooseIdentity(), notary, assetToSell, 1000.DOLLARS, anonymous) diff --git a/samples/network-visualiser/build.gradle b/samples/network-visualiser/build.gradle index 72ba1207c3..bad1295dbc 100644 --- a/samples/network-visualiser/build.gradle +++ b/samples/network-visualiser/build.gradle @@ -5,10 +5,10 @@ apply plugin: 'application' apply plugin: 'net.corda.plugins.quasar-utils' apply plugin: 'us.kirchmeier.capsule' -dependencies { - compile project(':samples:irs-demo') - compile project(':node-driver') +// Warning: The network visualiser is not a Cordapp so please do not use it as an example of how +// to build a cordapp +dependencies { compile "org.jetbrains.kotlin:kotlin-stdlib-jre8:$kotlin_version" testCompile "junit:junit:$junit_version" @@ -17,8 +17,10 @@ dependencies { compile project(path: ":webserver:webcapsule", configuration: 'runtimeArtifacts') compile project(':core') compile project(':finance') + compile project(':node-driver') + compile project(':finance') + compile project(':samples:irs-demo') - // Cordapp dependencies // GraphStream: For visualisation compileOnly "co.paralleluniverse:capsule:$capsule_version" } diff --git a/samples/network-visualiser/src/main/kotlin/net/corda/netmap/simulation/Simulation.kt b/samples/network-visualiser/src/main/kotlin/net/corda/netmap/simulation/Simulation.kt index faec432e7b..47483f7610 100644 --- a/samples/network-visualiser/src/main/kotlin/net/corda/netmap/simulation/Simulation.kt +++ b/samples/network-visualiser/src/main/kotlin/net/corda/netmap/simulation/Simulation.kt @@ -21,6 +21,7 @@ import net.corda.testing.node.InMemoryMessagingNetwork import net.corda.testing.node.MockNetwork import net.corda.testing.node.TestClock import net.corda.testing.node.setTo +import net.corda.testing.setCordappPackages import net.corda.testing.testNodeConfiguration import rx.Observable import rx.subjects.PublishSubject @@ -261,6 +262,7 @@ abstract class Simulation(val networkSendManuallyPumped: Boolean, val networkInitialisationFinished = allOf(*mockNet.nodes.map { it.nodeReadyFuture.toCompletableFuture() }.toTypedArray()) fun start(): Future { + setCordappPackages("net.corda.irs.contract", "net.corda.finance.contract") mockNet.startNodes() mockNet.registerIdentities() // Wait for all the nodes to have finished registering with the network map service. diff --git a/testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContract.kt b/testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContract.kt index 855994138e..28341e2e92 100644 --- a/testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContract.kt +++ b/testing/test-utils/src/main/kotlin/net/corda/testing/contracts/DummyContract.kt @@ -5,11 +5,13 @@ import net.corda.core.identity.AbstractParty import net.corda.core.identity.Party import net.corda.core.transactions.LedgerTransaction import net.corda.core.transactions.TransactionBuilder -import kotlin.reflect.jvm.jvmName // The dummy contract doesn't do anything useful. It exists for testing purposes, but has to be serializable data class DummyContract(val blank: Any? = null) : Contract { + + val PROGRAM_ID = "net.corda.testing.contracts.DummyContract" + interface State : ContractState { val magicNumber: Int }