diff --git a/docs/source/corda-networks-index.rst b/docs/source/corda-networks-index.rst index cc3e81321e..c56a8f3210 100644 --- a/docs/source/corda-networks-index.rst +++ b/docs/source/corda-networks-index.rst @@ -5,6 +5,7 @@ Networks :maxdepth: 1 setting-up-a-corda-network + running-a-notary permissioning network-map versioning diff --git a/docs/source/key-concepts-notaries.rst b/docs/source/key-concepts-notaries.rst index e1a52c4d2a..8998894819 100644 --- a/docs/source/key-concepts-notaries.rst +++ b/docs/source/key-concepts-notaries.rst @@ -50,6 +50,8 @@ In particular, notary clusters may differ in terms of: * **Consensus algorithm** - a notary cluster may choose to run a high-speed, high-trust algorithm such as RAFT, a low-speed, low-trust algorithm such as BFT, or any other consensus algorithm it chooses +.. _key_concepts_notaries_validation: + Validation ^^^^^^^^^^ A notary cluster must also decide whether or not to provide **validity consensus** by validating each transaction diff --git a/docs/source/running-a-notary-cluster/toctree.rst b/docs/source/running-a-notary-cluster/toctree.rst index 667477749f..2f71bf3ca9 100644 --- a/docs/source/running-a-notary-cluster/toctree.rst +++ b/docs/source/running-a-notary-cluster/toctree.rst @@ -1,6 +1,8 @@ -======================== -Running a notary cluster -======================== +============================== +Setting up a HA notary service +============================== + +This section contains all the information required to add a HA notary service to a network. .. toctree:: :maxdepth: 1 diff --git a/docs/source/running-a-notary.rst b/docs/source/running-a-notary.rst index 511f00c27a..04d797814c 100644 --- a/docs/source/running-a-notary.rst +++ b/docs/source/running-a-notary.rst @@ -1,33 +1,48 @@ -Running a notary service ------------------------- +Setting up a notary service +--------------------------- -At present we have several notary implementations: +Corda comes with several notary implementations built-in: -1. ``SimpleNotaryService`` (single node) -- commits the provided transaction input states without any validation. -2. ``ValidatingNotaryService`` (single node) -- retrieves and validates the whole transaction history - (including the given transaction) before committing. -3. ``RaftNonValidatingNotaryService`` (distributed) -- functionally equivalent to ``SimpleNotaryService``, but stores - the committed states in a distributed collection replicated and persisted in a Raft cluster. For the consensus layer - we are using the `Copycat `_ framework. -4. ``RaftValidatingNotaryService`` (distributed) -- as above, but performs validation on the transactions received. +1. **Single-node**: a simple notary service that persists notarisation requests in the node's database. It is easy to configure + and can be used for testing, or networks that do not have strict availability requirements. +2. **Crash fault-tolerant**: a highly available notary service operated by a single party. +3. **Byzantine fault-tolerant** *(experimental)*: a decentralised highly available notary service operated by a group of parties. -To have a node run a notary service, you need to set appropriate ``notary`` configuration before starting it -(see :doc:`corda-configuration-file` for reference). +Single-node +=========== -For ``SimpleNotaryService`` the config is simply: +To have a regular Corda node provide a notary service you simply need to set appropriate ``notary`` configuration values +before starting it: .. parsed-literal:: notary : { validating : false } -For ``ValidatingNotaryService``, it is: +For a validating notary service specify: .. parsed-literal:: notary : { validating : true } -Setting up a Raft notary is currently slightly more involved and is not recommended for prototyping purposes. There is -work in progress to simplify it. To see it in action, however, you can try out the :ref:`notary-demo`. -Use the `--bootstrap-raft-cluster` command line argument when starting the first node of a notary cluster for the first -time. When the flag is set, the node will act as a seed for the cluster that other members can join. +See :ref:`key_concepts_notaries_validation` for more details about validating versus non-validating notaries. + +For clients to be able to use the notary service, its identity must be added to the network parameters. This will be +done automatically when creating the network, if using :doc:`network-bootstrapper`. See :doc:`setting-up-a-corda-network` +for more details. + +Crash fault-tolerant +==================== + +Corda Enterprise provides a highly available notary service implementation backed by a replicated Percona XtraDB cluster. +This is the recommended implementation for production networks. See :doc:`running-a-notary-cluster/toctree` for detailed +setup steps. + +Byzantine fault-tolerant (experimental) +======================================= + +A prototype BFT notary implementation based on `BFT-Smart `_ is available. You can +try it out on our `notary demo `_ page. Note that it +is still experimental and there is active work ongoing for a production ready solution. + +We do not recommend using it in any long-running test or production deployments. diff --git a/docs/source/tutorials-index.rst b/docs/source/tutorials-index.rst index 8ef20b5c6a..6824ce4ba3 100644 --- a/docs/source/tutorials-index.rst +++ b/docs/source/tutorials-index.rst @@ -26,8 +26,6 @@ World tutorials, and can be read in any order. tutorial-building-transactions flow-state-machines flow-testing - running-a-notary - running-a-notary-cluster/toctree oracles tutorial-custom-notary tutorial-tear-offs