ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-18 20:47:57 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Docs: sync docs between master/c4 branches.

Browse Source
This commit is contained in:
Mike Hearn 2019-02-25 16:50:35 +01:00
parent 587e57579a
commit 365cde589a
21 changed files with 228 additions and 1730 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/source/api-states.rst
View File

@ -155,7 +155,7 @@ and methods. For example, here is the relatively complex definition for a state
.. container:: codeset
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/contracts/asset/Cash.kt
.. literalinclude:: ../../finance/contracts/src/main/kotlin/net/corda/finance/contracts/asset/Cash.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1

4
docs/source/app-upgrade-notes.rst
View File

@ -401,8 +401,8 @@ Step 12. Possibly update vault state queries
In Corda 4 queries made on a node's vault can filter by the relevancy of those states to the node. As this functionality does not exist in
Corda 3, apps will continue to receive all states in any vault queries. However, it may make sense to migrate queries expecting just those states relevant
to the node in question to query for only relevant states. See :doc:`api-vault-query.rst` for more details on how to do this. Not doing this
may result in queries returning more states than expected if the node is using observer functionality (see ":doc:`tutorial-observer-nodes.rst`").
to the node in question to query for only relevant states. See :doc:`api-vault-query` for more details on how to do this. Not doing this
may result in queries returning more states than expected if the node is using observer functionality (see ":doc:`tutorial-observer-nodes`").
Step 13. Explore other new features that may be useful
------------------------------------------------------

1569
docs/source/changelog.rst
View File

File diff suppressed because it is too large Load Diff

6
docs/source/cipher-suites.rst
View File

@ -15,9 +15,9 @@ carefully selected based on various factors, such as provided security-level and
with various HSM vendors, algorithm standardisation, variety of cryptographic primitives, business demand, option for
post-quantum resistance, side channel security, efficiency and rigorous testing.
Before we present the pool of supported schemes it is useful to be familiar with :doc:`key-concepts-identity`,
:doc:`permissioning` and :doc:`api-identity`. An important design decision in Corda is its shared hierarchy
between the TLS and Node Identity certificates.
Before we present the pool of supported schemes it is useful to be familiar with :doc:`permissioning`
and :doc:`api-identity`. An important design decision in Corda is its shared hierarchy between the
TLS and Node Identity certificates.
Certificate hierarchy
---------------------

38
docs/source/conf.py
View File

@ -1,20 +1,19 @@
# -*- coding: utf-8 -*-
#
# R3 prototyping documentation build configuration file, created by
# sphinx-quickstart on Mon Nov 23 21:19:35 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sphinx_rtd_theme
import sys, os
############################################################################
#
# TEXT SUBSTITUTIONS
rst_epilog = """
.. |java_version| replace:: 8u171
.. |kotlin_version| replace:: 1.2.71
"""
############################################################################
sys.path.append(os.path.abspath('../ext/'))
# If extensions (or modules to document with autodoc) are in another directory,
@ -60,20 +59,11 @@ author = u'R3 DLG'
# built documents.
#
# The short X.Y version.
version = 'V4.0'
version = 'Master'
# The full version, including alpha/beta/rc tags.
release = 'V4.0'
release = 'Master'
# The version for use in the dropdown html.
html_context = {'version': 'V4.0'}
# Properties.
kotlin_version = '1.2.71'
rst_epilog = """
.. |kotlin_version| replace:: {kotlin_version}
""".format(
kotlin_version = kotlin_version,
)
html_context = {'version': 'Master'}
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

45
docs/source/cordapp-build-systems.rst
View File

@ -38,6 +38,8 @@ the following folder and files from the `Kotlin CorDapp Template <https://github
* ``gradlew``
* ``gradlew.bat``
.. _cordapp_dependencies_ref:
Setting your dependencies
-------------------------
@ -527,48 +529,29 @@ For a CorDapp that contains flows and/or services we specify the `workflow` tag:
CorDapp Contract Attachments
----------------------------
As of Corda 4, because there is no Sandbox to run the verification code we require that any jar with code that is downloaded from a peer to be
checked and explicitly whitelisted by the node operator. CorDapp contract JARs must be installed on a node by a trusted uploader, by
As of Corda 4, CorDapp Contract JARs must be installed on a node by a trusted uploader, either by
- installing manually as per :ref:`Installing the CorDapp JAR <cordapp_install_ref>` and re-starting the node.
- uploading the attachment JAR to the node via RPC, either programmatically (see :ref:`Connecting to a node via RPC <clientrpc_connect_ref>`)
or via the :doc:`shell` by issuing the following command:
Which method to use depends on the reason for installing the CorDapp and is detailed below.
``>>> run uploadAttachment jar: path/to/the/file.jar``
.. note:: this behaviour is to protect the node from executing contract code that was not vetted. It is a temporary precaution until the
Deterministic JVM is integrated into Corda whereby execution takes place in a sandboxed environment which protects the node from malicious code.
Installing Contract Attachments for Previously Unknown CorDapps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you are processing a transaction that contains states that need to be verified by contracts in CorDapps not currently installed on the node, the
Contract attachment will be received from a peer over the p2p network. CorDapps received this way are considered **untrusted** and will throw an `UntrustedAttachmentsException`
Contract attachments that are received from a peer over the p2p network are considered **untrusted** and will throw a `UntrustedAttachmentsException` exception
when processed by a listening flow that cannot resolve that attachment from its local attachment storage. The flow will be aborted and sent to the nodes flow hospital for recovery and retry.
The untrusted attachment JAR will be stored in the nodes local attachment store for review by a node operator. It can be downloaded for viewing using the following CRaSH shell command:
``>>> run openAttachment id: <hash of untrusted attachment given by `UntrustedAttachmentsException` exception``
Should the node operator deem the attachment trustworthy, they may then install the CorDapp JAR in the node (see :ref:`Installing the CorDapp JAR <cordapp_install_ref>`)
and subsequently retry the failed flow. Currently this requires a node-restart which will automatically retry the failed flows.
.. note:: from Corda 4.1 you will also be able to upload the attachment to the store, as described below.
Installing Contract Attachments for Older Versions of CorDapps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you need to install older versions of a CorDapp in order to verify chains of states created with older versions of a contract, you can upload the
older CorDapp to the attachment store. Placing the older CorDapp in the ``cordapps`` directory will not work in this case,
as you can only have one CorDapp loaded per contract. The latest version of the CorDapp should be the one installed in the ``cordapps`` folder.
As above, the untrusted attachment JAR will be stored in the nodes local attachment store for review by a node operator. It can be downloaded for
viewing using the following CRaSH shell command:
``>>> run openAttachment id: <hash of untrusted attachment given by `UntrustedAttachmentsException` exception``
Should the node operator deem the attachment trustworthy, they may then issue the following CRaSH shell command to reload it as trusted:
``>>> run uploadAttachment jar: path/to/the/trusted-file.jar``
``>>> run uploadAttachment jar: path/to/the/trusted-file.jar``
and subsequently retry the failed flow (currently this requires a node re-start).
.. note:: this behaviour is to protect the node from executing contract code that was not vetted. It is a temporary precaution until the
Deterministic JVM is integrated into Corda whereby execution takes place in a sandboxed environment which protects the node from malicious code.
and subsequently retry the failed flow. Currently this requires a node-restart which will automatically retry the failed flows.

33
docs/source/cordapp-overview.rst
View File

@ -45,4 +45,35 @@ the following components:
* An ``ExitBondFlow``, allowing existing ``BondState`` states to be exited from the ledger
After installing this CorDapp, the node owner will be able to use the flows defined by the CorDapp to agree ledger
updates related to issuance, sale, purchase and exit of bonds.
updates related to issuance, sale, purchase and exit of bonds.
Writing and building apps that run on both Corda (open source) and Corda Enterprise
-----------------------------------------------------------------------------------
Corda and Corda Enterprise are compatible and interoperable, which means you can write a CorDapp that can run on both.
To make this work in practice you should follow these steps:
1. Ensure your CorDapp is designed per :doc:`Structuring a CorDapp <writing-a-cordapp>` and annotated according to :ref:`CorDapp separation <cordapp_separation_ref>`.
In particular, it is critical to separate the consensus-critical parts of your application (contracts, states and their dependencies) from
the rest of the business logic (flows, APIs, etc).
The former - the **CorDapp kernel** - is the Jar that will be attached to transactions creating/consuming your states and is the Jar
that any node on the network verifying the transaction must execute.
.. note:: It is also important to understand how to manage any dependencies a CorDapp may have on 3rd party libraries and other CorDapps.
Please read :ref:`Setting your dependencies <cordapp_dependencies_ref>` to understand the options and recommendations with regards to correctly Jar'ing CorDapp dependencies.
2. Compile this **CorDapp kernel** Jar once, and then depend on it from your workflows Jar (or Jars - see below). Importantly, if
you want your app to work on both Corda and Corda Enterprise, you must compile this Jar against Corda, not Corda Enterprise.
This is because, in future, we may add additional functionality to Corda Enterprise that is not in Corda and you may inadvertently create a
CorDapp kernel that does not work on Corda open source. Compiling against Corda open source as a matter of course prevents this risk, as well
as preventing the risk that you inadvertently create two different versions of the Jar, which will have different hashes and hence break compatibility
and interoperability.
.. note:: As of Corda 4 it is recommended to use :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>` to leverage the new signature constraints functionality.
3. Your workflow Jar(s) should depend on the **CorDapp kernel** (contract, states and dependencies). Importantly, you can create different workflow
Jars for Corda and Corda Enterprise, because the workflows Jar is not consensus critical. For example, you may wish to add additional features
to your CorDapp for when it is run on Corda Enterprise (perhaps it uses advanced features of one of the supported enterprise databases or includes
advanced database migration scripts, or some other Enterprise-only feature).
In summary, structure your app as kernel (contracts, states, dependencies) and workflow (the rest) and be sure to compile the kernel
against Corda open source. You can compile your workflow (Jars) against the distribution of Corda that they target.

12
docs/source/docker-image.rst
View File

@ -20,7 +20,7 @@ In this example, the certificates are stored at ``/home/user/cordaBase/certifica
-v /path/to/cordapps:/opt/corda/cordapps \
-p 10200:10200 \
-p 10201:10201 \
corda/corda-zulu-4.0:latest
corda/corda-zulu-5.0-snapshot:latest
As the node runs within a container, several mount points are required:
@ -55,7 +55,7 @@ In this example, we have previously generated a network-parameters file using th
-v /home/user/sharedFolder/network-parameters:/opt/corda/network-parameters \
-p 10200:10200 \
-p 10201:10201 \
corda/corda-zulu-4.0:latest
corda/corda-zulu-5.0-snapshot:latest
There is a new mount ``/home/user/sharedFolder/node-infos:/opt/corda/additional-node-infos`` which is used to hold the ``nodeInfo`` of all the nodes within the network.
As the node within the container starts up, it will place it's own nodeInfo into this directory. This will allow other nodes also using this folder to see this new node.
@ -79,7 +79,7 @@ Joining TestNet
-e LOCALITY="London" -e COUNTRY="GB" \
-v /home/user/docker/config:/etc/corda \
-v /home/user/docker/certificates:/opt/corda/certificates \
corda/corda-zulu-4.0:latest config-generator --testnet
corda/corda-zulu-5.0-snapshot:latest config-generator --testnet
``$MY_PUBLIC_ADDRESS`` will be the public address that this node will be advertised on.
``$ONE_TIME_DOWNLOAD_KEY`` is the one-time code provided for joining TestNet.
@ -104,7 +104,7 @@ It is now possible to start the node using the generated config and certificates
-v /home/user/corda/samples/bank-of-corda-demo/build/nodes/BankOfCorda/cordapps:/opt/corda/cordapps \
-p 10200:10200 \
-p 10201:10201 \
corda/corda-zulu-4.0:latest
corda/corda-zulu-5.0-snapshot:latest
Joining an existing Compatibility Zone
@ -128,7 +128,7 @@ It is possible to configure the name of the Trust Root file by setting the ``TRU
-e MY_EMAIL_ADDRESS="cordauser@r3.com" \
-v /home/user/docker/config:/etc/corda \
-v /home/user/docker/certificates:/opt/corda/certificates \
corda/corda-zulu-4.0:latest config-generator --generic
corda/corda-zulu-5.0-snapshot:latest config-generator --generic
Several environment variables must also be passed to the container to allow it to register:
@ -159,5 +159,5 @@ Once the container has finished performing the initial registration, the node ca
-v /home/user/corda/samples/bank-of-corda-demo/build/nodes/BankOfCorda/cordapps:/opt/corda/cordapps \
-p 10200:10200 \
-p 10201:10201 \
corda/corda-zulu-4.0:latest
corda/corda-zulu-5.0-snapshot:latest

7
docs/source/docker.rst
View File

@ -1,7 +0,0 @@
Docker
=====
.. toctree::
:maxdepth: 1
docker-image

2
docs/source/event-scheduling.rst
View File

@ -67,7 +67,7 @@ Let's take an example of the interest rate swap fixings for our scheduled events
.. container:: codeset
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/contract/IRS.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/contracts-irs/src/main/kotlin/net/corda/irs/contract/IRS.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1

12
docs/source/flow-state-machines.rst
View File

@ -93,7 +93,7 @@ Our flow has two parties (B and S for buyer and seller) and will proceed as foll
transaction in B's local vault, and then sending it on to S who also checks it and commits the transaction to S's
local vault.
You can find the implementation of this flow in the file ``finance/src/main/kotlin/net/corda/finance/TwoPartyTradeFlow.kt``.
You can find the implementation of this flow in the file ``finance/workflows/src/main/kotlin/net/corda/finance/TwoPartyTradeFlow.kt``.
Assuming no malicious termination, they both end the flow being in possession of a valid, signed transaction that
represents an atomic asset swap.
@ -201,7 +201,7 @@ Let's implement the ``Seller.call`` method that will be run when the flow is inv
.. container:: codeset
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
:language: kotlin
:start-after: DOCSTART 4
:end-before: DOCEND 4
@ -237,7 +237,7 @@ OK, let's do the same for the buyer side:
.. container:: codeset
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
@ -367,7 +367,7 @@ override ``checkTransaction()`` to add our own custom validation logic:
.. container:: codeset
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
:language: kotlin
:start-after: DOCSTART 5
:end-before: DOCEND 5
@ -454,7 +454,7 @@ A flow might declare some steps with code inside the flow class like this:
.. container:: codeset
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2
@ -478,7 +478,7 @@ is a good idea, as that will help the users see what is coming up. You can pre-c
.. container:: codeset
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
.. literalinclude:: ../../finance/workflows/src/main/kotlin/net/corda/finance/flows/TwoPartyTradeFlow.kt
:language: kotlin
:start-after: DOCSTART 3
:end-before: DOCEND 3

17
docs/source/getting-set-up.rst
View File

@ -3,20 +3,17 @@ Getting set up for CorDapp development
Software requirements
---------------------
Corda uses industry-standard tools:
* **Oracle JDK 8 JVM** - minimum supported version **8u171**
* **Java 8 JVM** - we require at least version **|java_version|**, but do not currently support Java 9 or higher.
We have tested with Oracle JDK, Amazon Corretto, and Red Hat's OpenJDK builds. Please note that OpenJDK builds
usually exclude JavaFX, which our GUI tools require.
* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x** (with Kotlin plugin version |kotlin_version|)
* **Git**
We also use Gradle and Kotlin, but you do not need to install them. A standalone Gradle wrapper is provided, and it
will download the correct version of Kotlin.
* **Gradle** - we use 4.10 and the ``gradlew`` script in the project / samples directories will download it for you.
Please note:
* Corda runs in a JVM. JVM implementations other than Oracle JDK 8 are not actively supported. However, if you do
choose to use OpenJDK, you will also need to install OpenJFX
* Applications on Corda (CorDapps) can be written in any language targeting the JVM. However, Corda itself and most of
the samples are written in Kotlin. Kotlin is an
`official Android language <https://developer.android.com/kotlin/index.html>`_, and you can read more about why
@ -26,7 +23,7 @@ Please note:
`getting started guide <https://kotlinlang.org/docs/tutorials/>`_, and a series of
`Kotlin Koans <https://kotlinlang.org/docs/tutorials/koans.html>`_
* IntelliJ IDEA is recommended due to the strength of its Kotlin integration
* IntelliJ IDEA is recommended due to the strength of its Kotlin integration.
Following these software recommendations will minimize the number of errors you encounter, and make it easier for
others to provide support. However, if you do use other tools, we'd be interested to hear about any issues that arise.
@ -131,7 +128,7 @@ Jetbrains offers a pre-built snap package that allows for easy, one-step install
.. _fedora-label:
Fedora
-------------
------
.. warning:: If you are using a Mac, Windows or Debian/Ubuntu machine, please follow the :ref:`mac-label`, :ref:`windows-label` or :ref:`deb-ubuntu-label` instructions instead.

3
docs/source/index.rst
View File

@ -33,6 +33,7 @@ We look forward to seeing what you can do with Corda!
release-notes
app-upgrade-notes
node-upgrade-notes
.. toctree::
:caption: Development
@ -69,7 +70,7 @@ We look forward to seeing what you can do with Corda!
:if_tag: htmlmode
corda-network/index.md
corda-network/uat.md
corda-network/UAT.md
.. conditional-toctree::
:caption: Contents

10
docs/source/key-concepts-node.rst
View File

@ -81,11 +81,13 @@ The node also has several CorDapps installed by default to handle common tasks s
* Upgrading contracts
* Broadcasting agreed ledger updates for recording by counterparties
.. _draining-mode:
Draining mode
^^^^^^^^^^^^^
-------------
In order to operate a clean shutdown of a node, it is important than no flows are in-flight, meaning no checkpoints should
be persisted. The node is able to be put in a Flows Draining Mode, during which:
be persisted. The node is able to be put in draining mode, during which:
* Commands requiring to start new flows through RPC will be rejected.
* Scheduled flows due will be ignored.
@ -93,4 +95,6 @@ be persisted. The node is able to be put in a Flows Draining Mode, during which:
* All other activities will proceed as usual, ensuring that the number of in-flight flows will strictly diminish.
As their number - which can be monitored through RPC - reaches zero, it is safe to shut the node down.
This property is durable, meaning that restarting the node will not reset it to its default value and that a RPC command is required.
This property is durable, meaning that restarting the node will not reset it to its default value and that a RPC command is required.
The node can be safely shut down via a drain using the shell.

4
docs/source/node-administration.rst
View File

@ -128,7 +128,7 @@ due to expensive run-time costs. They can be turned on and off explicitly regard
When starting Corda nodes using Cordformation runner (see :doc:`running-a-node`), you should see a startup message similar to the following:
**Jolokia: Agent started with URL http://127.0.0.1:7005/jolokia/**
When starting Corda nodes using the `DriverDSL`, you should see a startup message in the logs similar to the following:
When starting Corda nodes using the 'driver DSL', you should see a startup message in the logs similar to the following:
**Starting out-of-process Node USA Bank Corp, debug port is not enabled, jolokia monitoring port is 7005 {}**
@ -203,6 +203,8 @@ For launching on Windows without PowerShell, it is not possible to perform comma
.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history.
.. _ref-backup-recommendations:
Backup recommendations
----------------------

20
docs/source/oracles.rst
View File

@ -101,12 +101,12 @@ class that binds it to the network layer.
Here is an extract from the ``NodeInterestRates.Oracle`` class and supporting types:
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/contracts/FinanceTypes.kt
.. literalinclude:: ../../finance/contracts/src/main/kotlin/net/corda/finance/contracts/FinanceTypes.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
.. literalinclude:: ../../finance/src/main/kotlin/net/corda/finance/contracts/FinanceTypes.kt
.. literalinclude:: ../../finance/contracts/src/main/kotlin/net/corda/finance/contracts/FinanceTypes.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2
@ -166,7 +166,7 @@ parameter and ``CommandData`` classes.
Let's see how the ``sign`` method for ``NodeInterestRates.Oracle`` is written:
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/api/NodeInterestRates.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/api/NodeInterestRates.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
@ -192,7 +192,7 @@ Binding to the network
The first step is to create the oracle as a service by annotating its class with ``@CordaService``. Let's see how that's
done:
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/api/NodeInterestRates.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/api/NodeInterestRates.kt
:language: kotlin
:start-after: DOCSTART 3
:end-before: DOCEND 3
@ -201,7 +201,7 @@ done:
The Corda node scans for any class with this annotation and initialises them. The only requirement is that the class provide
a constructor with a single parameter of type ``ServiceHub``.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/api/NodeInterestRates.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/api/NodeInterestRates.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2
@ -219,7 +219,7 @@ We mentioned the client sub-flow briefly above. They are the mechanism that cli
use to interact with your oracle. Typically there will be one for querying and one for signing. Let's take a look at
those for ``NodeInterestRates.Oracle``.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/flows/RatesFixFlow.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/flows/RatesFixFlow.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
@ -238,7 +238,7 @@ The oracle is invoked through sub-flows to query for values, add them to the tra
the transaction signed by the oracle. Following on from the above examples, this is all encapsulated in a sub-flow
called ``RatesFixFlow``. Here's the ``call`` method of that flow.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/flows/RatesFixFlow.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/flows/RatesFixFlow.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2
@ -255,7 +255,7 @@ As you can see, this:
Here's an example of it in action from ``FixingFlow.Fixer``.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/flows/FixingFlow.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/flows/FixingFlow.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
@ -276,10 +276,10 @@ containing your oracle service.
You can then write tests on your mock network to verify the nodes interact with your Oracle correctly.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/test/kotlin/net/corda/irs/api/OracleNodeTearOffTests.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/test/kotlin/net/corda/irs/api/OracleNodeTearOffTests.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2
:dedent: 4
See `here <https://github.com/corda/corda/samples/irs-demo/cordapp/src/test/kotlin/net/corda/irs/api/OracleNodeTearOffTests.kt>`_ for more examples.
See `here <https://github.com/corda/corda/samples/irs-demo/cordapp/workflows-irs/src/test/kotlin/net/corda/irs/api/OracleNodeTearOffTests.kt>`_ for more examples.

130
docs/source/quickstart-index.rst
View File

@ -16,86 +16,86 @@ I want to:
Learn about Corda for the first time
------------------------------------
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+=========================================================================================================+
| :doc:`key-concepts` | The key concepts and features of the Corda Platform |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`getting-set-up` | Set up your machine for running and developing CorDapps |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`tutorial-cordapp` | A guide to running a simple CorDapp |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+============================================================================================+
| :doc:`key-concepts` | The key concepts and features of the Corda Platform |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`getting-set-up` | Set up your machine for running and developing CorDapps |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`tutorial-cordapp` | A guide to running a simple CorDapp |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
.. _quickstart-develop:
Develop a CorDapp
-----------------
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+=========================================================================================================+
| :doc:`hello-world-introduction` | A coding walk-through of a basic CorDapp |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`cordapp-overview` | An introduction to CordApps |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`writing-a-cordapp` | How to structure a CorDapp project |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`cordapp-build-systems` | How to build a CorDapp |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`corda-api` | A guide to the CorDapp API |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+============================================================================================+
| :doc:`hello-world-introduction` | A coding walk-through of a basic CorDapp |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`cordapp-overview` | An introduction to CordApps |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`writing-a-cordapp` | How to structure a CorDapp project |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`cordapp-build-systems` | How to build a CorDapp |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`corda-api` | A guide to the CorDapp API |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
.. _quickstart-run:
Run and test a CorDapp on local Corda network
---------------------------------------------
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+=========================================================================================================+
| :doc:`generating-a-node` | Guidance on creating Corda nodes for development and testing locally and on Docker |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`node-structure` | The Corda node folder structure and how to name your node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`corda-configuration-file` | A detailed description of the Corda node configuration file with examples |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`running-a-node` | Guidance on running Corda nodes locally and on Docker |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`setting-up-a-corda-network` | Considerations for setting up a Corda network |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`shell` | Guidance on using an embedded command line to control and monitor a node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`node-administration` | How to monitor a Corda node using an RPC interface |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`node-explorer` | A GUI-based tool to view transactional data and transactional history for a node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
+------------------------------------------------+----------------------------------------------------------------------------------------+
| Useful links | Description |
+================================================+========================================================================================+
| :doc:`generating-a-node` | Guidance on creating Corda nodes for development and testing locally and on Docker |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`node-structure` | The Corda node folder structure and how to name your node |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`corda-configuration-file` | A detailed description of the Corda node configuration file with examples |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`running-a-node` | Guidance on running Corda nodes locally and on Docker |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`setting-up-a-dynamic-compatibility-zone` | Considerations for setting up a Corda network |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`shell` | Guidance on using an embedded command line to control and monitor a node |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`node-administration` | How to monitor a Corda node using an RPC interface |
+------------------------------------------------+----------------------------------------------------------------------------------------+
| :doc:`node-explorer` | A GUI-based tool to view transactional data and transactional history for a node |
+------------------------------------------------+----------------------------------------------------------------------------------------+
.. _quickstart-add:
Add a node to an existing test Corda network
--------------------------------------------
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+=========================================================================================================+
| :doc:`node-structure` | The Corda node folder structure and how to name your node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`corda-configuration-file` | A detailed description of the Corda node configuration file with examples |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`deploying-a-node` | A step-by-step guide on deploying a Corda node to your own server |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`azure-vm` | A step-by-step guide on creating a Corda Network on Azure |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`aws-vm` | A step-by-step guide on creating a Corda Network on AWS |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`shell` | Guidance on using an embedded command line to control and monitor a node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`node-administration` | How to monitor a Corda node using an RPC interface |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`node-explorer` | A GUI-based tool to view transactional data and transactional history for a node |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
| :doc:`blob-inspector` | A troubleshooting tool allowing you to read the contents of a binary blob file |
+--------------------------------------------+---------------------------------------------------------------------------------------------------------+
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| Useful links | Description |
+============================================+============================================================================================+
| :doc:`node-structure` | The Corda node folder structure and how to name your node |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`corda-configuration-file` | A detailed description of the Corda node configuration file with examples |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`deploying-a-node` | A step-by-step guide on deploying a Corda node to your own server |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`azure-vm` | A step-by-step guide on creating a Corda Network on Azure |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`aws-vm` | A step-by-step guide on creating a Corda Network on AWS |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`shell` | Guidance on using an embedded command line to control and monitor a node |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`node-administration` | How to monitor a Corda node using an RPC interface |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`node-explorer` | A GUI-based tool to view transactional data and transactional history for a node |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
| :doc:`blob-inspector` | A troubleshooting tool allowing you to read the contents of a binary blob file |
+--------------------------------------------+--------------------------------------------------------------------------------------------+
.. _quickstart-production:
@ -103,5 +103,9 @@ Add a node to an existing production network
--------------------------------------------
+---------------------------------------------------------------------------------------------------------+
| Contact R3 Solutions Engineering at support@r3.com |
| Corda Network is a global production network of Corda nodes, operated by the independent |
| Corda Network Foundation. You can learn more here: https://corda.network/participation/index.html |
+---------------------------------------------------------------------------------------------------------+
| Corda Testnet is a test network, operated for the community by R3. You can learn |
| more here: https://testnet.corda.network |
+---------------------------------------------------------------------------------------------------------+

36
docs/source/release-notes.rst
View File

@ -3,23 +3,27 @@ Release notes for Corda 4
.. _release_notes_v4_0:
Here we are, 9 months and 1500 plus commits later... and it's a bouncing baby software release!
Welcome to the Corda 4 release notes. Please read these carefully to understand what's new in this
release and how the changes can help you. Just as prior releases have brought with them commitments
to wire and API stability, Corda 4 comes with those same guarantees. States and apps valid in
Corda 3 are transparently usable in Corda 4.
We are really proud to release Corda 4 to the open source community today. It's been a long time in
the making, but we think you'll agree worth the wait.
For app developers, we strongly recommend reading ":doc:`app-upgrade-notes`". This covers the upgrade
procedure, along with how you can adjust your app to opt-in to new features making your app more secure and
easier to upgrade in future.
Just as prior releases have brought with them commitments to wire and API stability, Corda 4
comes with those same guarantees. States and apps valid in Corda 3 are transparently usable in Corda 4.
For node operators, we recommend reading ":doc:`node-upgrade-notes`". The upgrade procedure is simple but
it can't hurt to read the instructions anyway.
.. important:: We strongly recommend reading ":doc:`app-upgrade-notes`". This covers the upgrade procedure,
along with how you can adjust your app to opt-in to new features making your app more secure and
easier to upgrade.
Additionally, be aware that the data model upgrades are changes to the Corda consensus rules. To use
Additionally, be aware that the data model improvements are changes to the Corda consensus rules. To use
apps that benefit from them, *all* nodes in a compatibility zone must be upgraded and the zone must be
enforcing that upgrade. This may take time in large zones like the testnet. Please take this into
account for your own schedule planning.
.. warning:: There is a bug in Corda 3.3 that causes problems when receiving a ``FungibleState`` created
by Corda 4. There will shortly be a followup Corda 3.4 release that corrects this error. Interop between
Corda 3 and Corda 4 will require that Corda 3 users are on the latest patchlevel release.
.. contents::
Changes for developers in Corda 4
@ -29,9 +33,9 @@ Reference states
++++++++++++++++
With Corda 4 we are introducing the concept of "reference input states". These allow smart contracts
to read data from the ledger without simultaneously updating it. They're useful not only for any kind of
reference data such as rates, healthcare codes, geographical information etc, but for anywhere
you might have used a SELECT JOIN in a SQL based app.
to reference data from the ledger in a transaction without simultaneously updating it. They're useful
not only for any kind of reference data such as rates, healthcare codes, geographical information etc,
but for anywhere you might have used a SELECT JOIN in a SQL based app.
A reference input state is a ``ContractState`` which can be referred to in a transaction by the contracts
of input and output states but, significantly, whose contract is not executed as part of the transaction
@ -211,9 +215,9 @@ version requirement if they start using new features and APIs.
Dependency upgrades
+++++++++++++++++++
We've raised the minimum JDK to 8u171, needed to get fixes for certain ZIP compression bugs.
We've raised the minimum JDK to |java_version|, needed to get fixes for certain ZIP compression bugs.
We've upgraded to Kotlin 1.2.71 so your apps can now benefit from the new features in this language release.
We've upgraded to Kotlin |kotlin_version| so your apps can now benefit from the new features in this language release.
We've upgraded to Gradle 4.10.1.
@ -297,4 +301,4 @@ Miscellaneous changes
To learn more about smaller changes, please read the :doc:`changelog`.
Finally, we have added some new jokes. Thankyou and good night!
Finally, we have added some new jokes. Thank you and good night!

4
docs/source/tutorial-custom-notary.rst
View File

@ -11,7 +11,7 @@ This will ensure that it is recognised as a notary service.
The custom notary service class should provide a constructor with two parameters of types ``ServiceHubInternal`` and ``PublicKey``.
Note that ``ServiceHubInternal`` does not provide any API stability guarantees.
.. literalinclude:: ../../samples/notary-demo/src/main/kotlin/net/corda/notarydemo/MyCustomNotaryService.kt
.. literalinclude:: ../../samples/notary-demo/workflows/src/main/kotlin/net/corda/notarydemo/MyCustomNotaryService.kt
:language: kotlin
:start-after: START 1
:end-before: END 1
@ -20,7 +20,7 @@ The next step is to write a notary service flow. You are free to copy and modify
as ``ValidatingNotaryFlow``, ``NonValidatingNotaryFlow``, or implement your own from scratch (following the
``NotaryFlow.Service`` template). Below is an example of a custom flow for a *validating* notary service:
.. literalinclude:: ../../samples/notary-demo/src/main/kotlin/net/corda/notarydemo/MyCustomNotaryService.kt
.. literalinclude:: ../../samples/notary-demo/workflows/src/main/kotlin/net/corda/notarydemo/MyCustomNotaryService.kt
:language: kotlin
:start-after: START 2
:end-before: END 2

2
docs/source/tutorial-observer-nodes.rst
View File

@ -17,7 +17,7 @@ Just define a new flow that wraps the SendTransactionFlow/ReceiveTransactionFlow
.. container:: codeset
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/flows/AutoOfferFlow.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/flows/AutoOfferFlow.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1

2
docs/source/tutorial-tear-offs.rst
View File

@ -49,7 +49,7 @@ transaction components is exactly the same. Note that unlike ``WireTransaction``
The following code snippet is taken from ``NodeInterestRates.kt`` and implements a signing part of an Oracle.
.. literalinclude:: ../../samples/irs-demo/cordapp/src/main/kotlin/net/corda/irs/api/NodeInterestRates.kt
.. literalinclude:: ../../samples/irs-demo/cordapp/workflows-irs/src/main/kotlin/net.corda.irs/api/NodeInterestRates.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1