mirror of
https://github.com/corda/corda.git
synced 2024-12-20 13:33:12 +00:00
622 lines
41 KiB
HTML
622 lines
41 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>A Brief Introduction To The Node Services — R3 Corda latest documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="top" title="R3 Corda latest documentation" href="index.html"/>
|
|
<link rel="next" title="Creating a Cordapp" href="creating-a-cordapp.html"/>
|
|
<link rel="prev" title="The Corda Configuration File" href="corda-configuration-files.html"/>
|
|
|
|
|
|
<script src="_static/js/modernizr.min.js"></script>
|
|
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav" role="document">
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search">
|
|
|
|
|
|
|
|
|
|
<a href="index.html" class="icon icon-home"> R3 Corda
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
<div class="version">
|
|
latest
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
<br>
|
|
<a href="api/index.html">API reference</a>
|
|
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
<p class="caption"><span class="caption-text">Getting started</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="inthebox.html">What’s included?</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="getting-set-up.html">Getting set up</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="running-the-demos.html">Running the demos</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Key concepts</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="data-model.html">Data model</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="transaction-data-types.html">Data types</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="merkle-trees.html">Transaction Tear-offs</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="consensus.html">Consensus model</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">The Corda node</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="messaging.html">Networking and messaging</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="node-administration.html">Node administration</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="corda-configuration-files.html">The Corda Configuration File</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">A Brief Introduction To The Node Services</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#services-within-the-node">Services Within The Node</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#key-management-and-identity-services">Key Management and Identity Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#inmemoryidentityservice">InMemoryIdentityService</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#persistentkeymanagementservice-and-e2etestkeymanagementservice">PersistentKeyManagementService and E2ETestKeyManagementService</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#messaging-and-network-management-services">Messaging and Network Management Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#artemismessagingserver">ArtemisMessagingServer</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#nodemessagingclient">NodeMessagingClient</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#inmemorynetworkmapcache">InMemoryNetworkMapCache</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#persistentnetworkmapservice-and-networkmapservice">PersistentNetworkMapService and NetworkMapService</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#storage-and-persistence-related-services">Storage and Persistence Related Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#storageserviceimpl">StorageServiceImpl</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#dbcheckpointstorage">DBCheckpointStorage</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage">DBTransactionMappingStorage and InMemoryStateMachineRecordedTransactionMappingStorage</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#dbtransactionstorage">DBTransactionStorage</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#nodeattachmentservice">NodeAttachmentService</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#flow-framework-and-event-scheduling-services">Flow Framework And Event Scheduling Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#statemachinemanager">StateMachineManager</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#nodeschedulerservice">NodeSchedulerService</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#notary-flow-implementation-services">Notary Flow Implementation Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider">PersistentUniquenessProvider, InMemoryUniquenessProvider and RaftUniquenessProvider</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice">NotaryService (SimpleNotaryService, ValidatingNotaryService, RaftValidatingNotaryService)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#vault-related-services">Vault Related Services</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#nodevaultservice">NodeVaultService</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#nodeschemaservice-and-hibernateobserver">NodeSchemaService and HibernateObserver</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">CorDapps</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html">Creating a Cordapp</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html#gradle-plugins-for-cordapps">Gradle Plugins for Cordapps</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Tutorials</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="where-to-start.html">Where to start</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract.html">Writing a contract</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-contract-clauses.html">Writing a contract using clauses</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-test-dsl.html">Writing a contract test</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-clientrpc-api.html">Client RPC API Tutorial</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="flow-state-machines.html">Flow state machines</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="oracles.html">Writing oracle services</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial-attachments.html">Using attachments</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="event-scheduling.html">Event scheduling</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Other</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="network-simulator.html">Network Simulator</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="node-explorer.html">Node Explorer</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="initial-margin-agreement.html">Initial Margin Agreements</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Component library</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="contract-catalogue.html">Contract catalogue</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="contract-irs.html">Interest Rate Swaps</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Appendix</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="loadtesting.html">Load testing</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="secure-coding-guidelines.html">Secure coding guidelines</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-process.html">Release process</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-process.html#steps-to-cut-a-release">Steps to cut a release</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Glossary</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">R3 Corda</a>
|
|
</nav>
|
|
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
<div class="rst-content">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
<ul class="wy-breadcrumbs">
|
|
<li><a href="index.html">Docs</a> »</li>
|
|
|
|
<li>A Brief Introduction To The Node Services</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="_sources/node-services.txt" rel="nofollow"> View page source</a>
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<div class="section" id="a-brief-introduction-to-the-node-services">
|
|
<h1>A Brief Introduction To The Node Services<a class="headerlink" href="#a-brief-introduction-to-the-node-services" title="Permalink to this headline">¶</a></h1>
|
|
<p>This document is intended as a very brief introduction to the current
|
|
service components inside the node. Whilst not at all exhaustive it is
|
|
hoped that this will give some context when writing applications and
|
|
code that use these services, or which are operated upon by the internal
|
|
components of Corda.</p>
|
|
<div class="section" id="services-within-the-node">
|
|
<h2>Services Within The Node<a class="headerlink" href="#services-within-the-node" title="Permalink to this headline">¶</a></h2>
|
|
<p>The node services represent the various sub functions of the Corda node.
|
|
Some are directly accessible to contracts and flows through the
|
|
<code class="docutils literal"><span class="pre">ServiceHub</span></code>, whilst others are the framework internals used to host
|
|
the node functions. Any public service interfaces are defined in the
|
|
<code class="docutils literal"><span class="pre">:core</span></code> gradle project in the
|
|
<code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/core/node/services</span></code> folder. The
|
|
<code class="docutils literal"><span class="pre">ServiceHub</span></code> interface exposes functionality suitable for flows.
|
|
The implementation code for all standard services lives in the gradle
|
|
<code class="docutils literal"><span class="pre">:node</span></code> project under the <code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/node/services</span></code>
|
|
folder. The <code class="docutils literal"><span class="pre">src/main/kotlin/net/corda/node/services/api</span></code> folder
|
|
contains declarations for internal only services and for interoperation
|
|
between services.</p>
|
|
<p>All the services are constructed in the <code class="docutils literal"><span class="pre">AbstractNode</span></code> <code class="docutils literal"><span class="pre">start</span></code>
|
|
method (and the extension in <code class="docutils literal"><span class="pre">Node</span></code>). They may also register a
|
|
shutdown handler during initialisation, which will be called in reverse
|
|
order to the start registration sequence when the <code class="docutils literal"><span class="pre">Node.stop</span></code>
|
|
is called.</p>
|
|
<p>As well as the standard services trusted CorDapp plugins may register
|
|
custom services. These plugin services are passed a reference to the
|
|
<code class="docutils literal"><span class="pre">PluginServiceHub</span></code> which allows some more powerful functions e.g.
|
|
starting flows.</p>
|
|
<p>For unit testing a number of non-persistent, memory only services are
|
|
defined in the <code class="docutils literal"><span class="pre">:node</span></code> and <code class="docutils literal"><span class="pre">:test-utils</span></code> projects. The
|
|
<code class="docutils literal"><span class="pre">:test-utils</span></code> project also provides an in-memory networking simulation
|
|
to allow unit testing of flows and service functions.</p>
|
|
<p>The roles of the individual services are described below.</p>
|
|
</div>
|
|
<div class="section" id="key-management-and-identity-services">
|
|
<h2>Key Management and Identity Services<a class="headerlink" href="#key-management-and-identity-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="inmemoryidentityservice">
|
|
<h3>InMemoryIdentityService<a class="headerlink" href="#inmemoryidentityservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">InMemoryIdentityService</span></code> implements the <code class="docutils literal"><span class="pre">IdentityService</span></code>
|
|
interface and provides a store of remote mappings between <code class="docutils literal"><span class="pre">CompositeKey</span></code>
|
|
and remote <code class="docutils literal"><span class="pre">Parties</span></code>. It is automatically populated from the
|
|
<code class="docutils literal"><span class="pre">NetworkMapCache</span></code> updates and is used when translating <code class="docutils literal"><span class="pre">CompositeKey</span></code>
|
|
exposed in transactions into fully populated <code class="docutils literal"><span class="pre">Party</span></code> identities. This
|
|
service is also used in the default JSON mapping of parties in the web
|
|
server, thus allowing the party names to be used to refer to other node
|
|
legal identities. In the future the Identity service will be made
|
|
persistent and extended to allow anonymised session keys to be used in
|
|
flows where the well-known <code class="docutils literal"><span class="pre">CompositeKey</span></code> of nodes need to be hidden
|
|
to non-involved parties.</p>
|
|
</div>
|
|
<div class="section" id="persistentkeymanagementservice-and-e2etestkeymanagementservice">
|
|
<h3>PersistentKeyManagementService and E2ETestKeyManagementService<a class="headerlink" href="#persistentkeymanagementservice-and-e2etestkeymanagementservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>Typical usage of these services is to locate an appropriate
|
|
<code class="docutils literal"><span class="pre">PrivateKey</span></code> to complete and sign a verified transaction as part of a
|
|
flow. The normal node legal identifier keys are typically accessed via
|
|
helper extension methods on the <code class="docutils literal"><span class="pre">ServiceHub</span></code>, but these ultimately
|
|
fetch the keys from the <code class="docutils literal"><span class="pre">KeyManagementService</span></code>. The
|
|
<code class="docutils literal"><span class="pre">KeyManagementService</span></code> interface also allows other keys to be
|
|
generated if anonymous keys are needed in a flow. Note that this
|
|
interface works at the level of individual <code class="docutils literal"><span class="pre">PublicKey</span></code>/<code class="docutils literal"><span class="pre">PrivateKey</span></code>
|
|
pairs, but the signing authority will be represented by a
|
|
<code class="docutils literal"><span class="pre">CompositeKey</span></code> on the <code class="docutils literal"><span class="pre">NodeInfo</span></code> to allow key clustering and
|
|
threshold schemes.</p>
|
|
<p>The <code class="docutils literal"><span class="pre">PersistentKeyManagementService</span></code> is a persistent implementation of
|
|
the <code class="docutils literal"><span class="pre">KeyManagementService</span></code> interface that records the key pairs to a
|
|
key-value storage table in the database. <code class="docutils literal"><span class="pre">E2ETestKeyManagementService</span></code>
|
|
is a simple implementation of the <code class="docutils literal"><span class="pre">KeyManagementService</span></code> that is used
|
|
to track our <code class="docutils literal"><span class="pre">KeyPairs</span></code> for use in unit testing when no database is
|
|
available.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="messaging-and-network-management-services">
|
|
<h2>Messaging and Network Management Services<a class="headerlink" href="#messaging-and-network-management-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="artemismessagingserver">
|
|
<h3>ArtemisMessagingServer<a class="headerlink" href="#artemismessagingserver" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> service is run internally by the Corda
|
|
node to host the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code> messaging broker that is used for
|
|
reliable node communications. Although the node can be configured to
|
|
disable this and connect to a remote broker by setting the
|
|
<code class="docutils literal"><span class="pre">messagingServerAddress</span></code> configuration to be the remote broker
|
|
address. (The <code class="docutils literal"><span class="pre">MockNode</span></code> used during testing does not use this
|
|
service, and has a simplified in-memory network layer instead.) This
|
|
service is not exposed to any CorDapp code as it is an entirely internal
|
|
infrastructural component. However, the developer may need to be aware
|
|
of this component, because the <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> is responsible
|
|
for configuring the network ports (based upon settings in <code class="docutils literal"><span class="pre">node.conf</span></code>)
|
|
and the service configures the security settings of the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
|
|
middleware and acts to form bridges between node mailbox queues based
|
|
upon connection details advertised by the <code class="docutils literal"><span class="pre">NetworkMapService</span></code>. The
|
|
<code class="docutils literal"><span class="pre">ArtemisMQ</span></code> broker is configured to use TLS1.2 with a custom
|
|
<code class="docutils literal"><span class="pre">TrustStore</span></code> containing a Corda root certificate and a <code class="docutils literal"><span class="pre">KeyStore</span></code>
|
|
with a certificate and key signed by a chain back to this root
|
|
certificate. These keystores typically reside in the <code class="docutils literal"><span class="pre">certificates</span></code>
|
|
sub folder of the node workspace. For the nodes to be able to connect to
|
|
each other it is essential that the entire set of nodes are able to
|
|
authenticate against each other and thus typically that they share a
|
|
common root certificate. Also note that the address configuration
|
|
defined for the server is the basis for the address advertised in the
|
|
NetworkMapService and thus must be externally connectable by all nodes
|
|
in the network.</p>
|
|
</div>
|
|
<div class="section" id="nodemessagingclient">
|
|
<h3>NodeMessagingClient<a class="headerlink" href="#nodemessagingclient" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NodeMessagingClient</span></code> is the implementation of the
|
|
<code class="docutils literal"><span class="pre">MessagingService</span></code> interface operating across the <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
|
|
middleware layer. It typically connects to the local <code class="docutils literal"><span class="pre">ArtemisMQ</span></code>
|
|
hosted within the <code class="docutils literal"><span class="pre">ArtemisMessagingServer</span></code> service. However, the
|
|
<code class="docutils literal"><span class="pre">messagingServerAddress</span></code> configuration can be set to a remote broker
|
|
address if required. The responsibilities of this service include
|
|
managing the node’s persistent mailbox, sending messages to remote peer
|
|
nodes, acknowledging properly consumed messages and deduplicating any
|
|
resent messages. The service also handles the incoming requests from new
|
|
RPC client sessions and hands them to the <code class="docutils literal"><span class="pre">CordaRPCOpsImpl</span></code> to carry
|
|
out the requests.</p>
|
|
</div>
|
|
<div class="section" id="inmemorynetworkmapcache">
|
|
<h3>InMemoryNetworkMapCache<a class="headerlink" href="#inmemorynetworkmapcache" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">InMemoryNetworkMapCache</span></code> implements the <code class="docutils literal"><span class="pre">NetworkMapCache</span></code>
|
|
interface and is responsible for tracking the identities and advertised
|
|
services of authorised nodes provided by the remote
|
|
<code class="docutils literal"><span class="pre">NetworkMapService</span></code>. Typical use is to search for nodes hosting
|
|
specific advertised services e.g. a Notary service, or an Oracle
|
|
service. Also, this service allows mapping of friendly names, or
|
|
<code class="docutils literal"><span class="pre">Party</span></code> identities to the full <code class="docutils literal"><span class="pre">NodeInfo</span></code> which is used in the
|
|
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> to convert between the <code class="docutils literal"><span class="pre">CompositeKey</span></code>, or
|
|
<code class="docutils literal"><span class="pre">Party</span></code> based addressing used in the flows/contracts and the
|
|
physical host and port information required for the physical
|
|
<code class="docutils literal"><span class="pre">ArtemisMQ</span></code> messaging layer.</p>
|
|
</div>
|
|
<div class="section" id="persistentnetworkmapservice-and-networkmapservice">
|
|
<h3>PersistentNetworkMapService and NetworkMapService<a class="headerlink" href="#persistentnetworkmapservice-and-networkmapservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NetworkMapService</span></code> is a node internal component responsible for
|
|
managing and communicating the directory of authenticated registered
|
|
nodes and advertised services in the Corda network. Only a single node
|
|
in the network (in future this will be a clustered service) should host
|
|
the NetworkMapService implementation. All other Corda nodes initiate
|
|
their remote connection to the <code class="docutils literal"><span class="pre">NetworkMapService</span></code> early in the
|
|
start-up sequence and wait to synchronise their local
|
|
<code class="docutils literal"><span class="pre">NetworkMapCache</span></code> before activating any flows. For the
|
|
<code class="docutils literal"><span class="pre">PersistentNetworkMapService</span></code> registered <code class="docutils literal"><span class="pre">NodeInfo</span></code> data is
|
|
persisted and will include nodes that are not currently active. The
|
|
networking layer will persist any messages directed at such inactive
|
|
nodes with the expectation that they will be delivered eventually, or
|
|
else that the source flow will be terminated by admin intervention.
|
|
An <code class="docutils literal"><span class="pre">InMemoryNetworkMapService</span></code> is also available for unit tests
|
|
without a database.</p>
|
|
<p>The <code class="docutils literal"><span class="pre">NetworkMapService</span></code> should not be used by any flows, or
|
|
contracts. Instead they should access the NetworkMapCache service to
|
|
access this data.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="storage-and-persistence-related-services">
|
|
<h2>Storage and Persistence Related Services<a class="headerlink" href="#storage-and-persistence-related-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="storageserviceimpl">
|
|
<h3>StorageServiceImpl<a class="headerlink" href="#storageserviceimpl" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">StorageServiceImpl</span></code> service simply hold references to the various
|
|
persistence related services and provides a single grouped interface on
|
|
the <code class="docutils literal"><span class="pre">ServiceHub</span></code>.</p>
|
|
</div>
|
|
<div class="section" id="dbcheckpointstorage">
|
|
<h3>DBCheckpointStorage<a class="headerlink" href="#dbcheckpointstorage" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">DBCheckpointStorage</span></code> service is used from within the
|
|
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> code to persist the progress of flows. Thus
|
|
ensuring that if the program terminates the flow can be restarted
|
|
from the same point and complete the flow. This service should not
|
|
be used by any CorDapp components.</p>
|
|
</div>
|
|
<div class="section" id="dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage">
|
|
<h3>DBTransactionMappingStorage and InMemoryStateMachineRecordedTransactionMappingStorage<a class="headerlink" href="#dbtransactionmappingstorage-and-inmemorystatemachinerecordedtransactionmappingstorage" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">DBTransactionMappingStorage</span></code> is used within the
|
|
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> code to relate transactions and flows. This
|
|
relationship is exposed in the eventing interface to the RPC clients,
|
|
thus allowing them to track the end result of a flow and map to the
|
|
actual transactions/states completed. Otherwise this service is unlikely
|
|
to be accessed by any CorDapps. The
|
|
<code class="docutils literal"><span class="pre">InMemoryStateMachineRecordedTransactionMappingStorage</span></code> service is
|
|
available as a non-persistent implementation for unit tests with no database.</p>
|
|
</div>
|
|
<div class="section" id="dbtransactionstorage">
|
|
<h3>DBTransactionStorage<a class="headerlink" href="#dbtransactionstorage" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">DBTransactionStorage</span></code> service is a persistent implementation of
|
|
the <code class="docutils literal"><span class="pre">TransactionStorage</span></code> interface and allows flows read-only
|
|
access to full transactions, plus transaction level event callbacks.
|
|
Storage of new transactions must be made via the <code class="docutils literal"><span class="pre">recordTransactions</span></code>
|
|
method on the <code class="docutils literal"><span class="pre">ServiceHub</span></code>, not via a direct call to this service, so
|
|
that the various event notifications can occur.</p>
|
|
</div>
|
|
<div class="section" id="nodeattachmentservice">
|
|
<h3>NodeAttachmentService<a class="headerlink" href="#nodeattachmentservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NodeAttachmentService</span></code> provides an implementation of the
|
|
<code class="docutils literal"><span class="pre">AttachmentStorage</span></code> interface exposed on the <code class="docutils literal"><span class="pre">ServiceHub</span></code> allowing
|
|
transactions to add documents, copies of the contract code and binary
|
|
data to transactions. The data is persisted to the local file system
|
|
inside the attachments subfolder of the node workspace. The service is
|
|
also interfaced to by the web server, which allows files to be uploaded
|
|
via an HTTP post request.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="flow-framework-and-event-scheduling-services">
|
|
<h2>Flow Framework And Event Scheduling Services<a class="headerlink" href="#flow-framework-and-event-scheduling-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="statemachinemanager">
|
|
<h3>StateMachineManager<a class="headerlink" href="#statemachinemanager" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> is the service that runs the active
|
|
flows of the node whether initiated by an RPC client, the web
|
|
interface, a scheduled state activity, or triggered by receipt of a
|
|
message from another node. The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> wraps the
|
|
flow code (extensions of the <code class="docutils literal"><span class="pre">FlowLogic</span></code> class) inside an
|
|
instance of the <code class="docutils literal"><span class="pre">FlowStateMachineImpl</span></code> class, which is a
|
|
<code class="docutils literal"><span class="pre">Quasar</span></code> <code class="docutils literal"><span class="pre">Fiber</span></code>. This allows the <code class="docutils literal"><span class="pre">StateMachineManager</span></code> to suspend
|
|
flows at all key lifecycle points and persist their serialized state
|
|
to the database via the <code class="docutils literal"><span class="pre">DBCheckpointStorage</span></code> service. This process
|
|
uses the facilities of the <code class="docutils literal"><span class="pre">Quasar</span></code> <code class="docutils literal"><span class="pre">Fibers</span></code> library to manage this
|
|
process and hence the requirement for the node to run the <code class="docutils literal"><span class="pre">Quasar</span></code>
|
|
java instrumentation agent in its JVM.</p>
|
|
<p>In operation the <code class="docutils literal"><span class="pre">StateMachineManager</span></code> is typically running an active
|
|
flow on its server thread until it encounters a blocking, or
|
|
externally visible operation, such as sending a message, waiting for a
|
|
message, or initiating a <code class="docutils literal"><span class="pre">subFlow</span></code>. The fiber is then suspended
|
|
and its stack frames serialized to the database, thus ensuring that if
|
|
the node is stopped, or crashes at this point the flow will restart
|
|
with exactly the same action again. To further ensure consistency, every
|
|
event which resumes a flow opens a database transaction, which is
|
|
committed during this suspension process ensuring that the database
|
|
modifications e.g. state commits stay in sync with the mutating changes
|
|
of the flow. Having recorded the fiber state the
|
|
<code class="docutils literal"><span class="pre">StateMachineManager</span></code> then carries out the network actions as required
|
|
(internally one flow message exchanged may actually involve several
|
|
physical session messages to authenticate and invoke registered
|
|
flows on the remote nodes). The flow will stay suspended until
|
|
the required message is returned and the scheduler will resume
|
|
processing of other activated flows. On receipt of the expected
|
|
response message from the network layer the <code class="docutils literal"><span class="pre">StateMachineManager</span></code>
|
|
locates the appropriate flow, resuming it immediately after the
|
|
blocking step with the received message. Thus from the perspective of
|
|
the flow the code executes as a simple linear progression of
|
|
processing, even if there were node restarts and possibly message
|
|
resends (the messaging layer deduplicates messages based on an id that
|
|
is part of the checkpoint).</p>
|
|
<p>The <code class="docutils literal"><span class="pre">StateMachineManager</span></code> service is not directly exposed to the
|
|
flows, or contracts themselves.</p>
|
|
</div>
|
|
<div class="section" id="nodeschedulerservice">
|
|
<h3>NodeSchedulerService<a class="headerlink" href="#nodeschedulerservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NodeSchedulerService</span></code> implements the <code class="docutils literal"><span class="pre">SchedulerService</span></code>
|
|
interface and monitors the Vault updates to track any new states that
|
|
implement the <code class="docutils literal"><span class="pre">SchedulableState</span></code> interface and require automatic
|
|
scheduled flow initiation. At the scheduled due time the
|
|
<code class="docutils literal"><span class="pre">NodeSchedulerService</span></code> will create a new flow instance passing it
|
|
a reference to the state that triggered the event. The flow can then
|
|
begin whatever action is required. Note that the scheduled activity
|
|
occurs in all nodes holding the state in their Vault, it may therefore
|
|
be required for the flow to exit early if the current node is not
|
|
the intended initiator.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="notary-flow-implementation-services">
|
|
<h2>Notary Flow Implementation Services<a class="headerlink" href="#notary-flow-implementation-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider">
|
|
<h3>PersistentUniquenessProvider, InMemoryUniquenessProvider and RaftUniquenessProvider<a class="headerlink" href="#persistentuniquenessprovider-inmemoryuniquenessprovider-and-raftuniquenessprovider" title="Permalink to this headline">¶</a></h3>
|
|
<p>These variants of <code class="docutils literal"><span class="pre">UniquenessProvider</span></code> service are used by the notary
|
|
flows to track consumed states and thus reject double-spend
|
|
scenarios. The <code class="docutils literal"><span class="pre">InMemoryUniquenessProvider</span></code> is for unit testing only,
|
|
the default being the <code class="docutils literal"><span class="pre">PersistentUniquenessProvider</span></code> which records the
|
|
changes to the DB. When the Raft based notary is active the states are
|
|
tracked by the whole cluster using a <code class="docutils literal"><span class="pre">RaftUniquenessProvider</span></code>. Outside
|
|
of the notary flows themselves this service should not be accessed
|
|
by any CorDapp components.</p>
|
|
</div>
|
|
<div class="section" id="notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice">
|
|
<h3>NotaryService (SimpleNotaryService, ValidatingNotaryService, RaftValidatingNotaryService)<a class="headerlink" href="#notaryservice-simplenotaryservice-validatingnotaryservice-raftvalidatingnotaryservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NotaryService</span></code> is an abstract base class for the various concrete
|
|
implementations of the Notary server flow. By default, a node does
|
|
not run any <code class="docutils literal"><span class="pre">NotaryService</span></code> server component. However, the appropriate
|
|
implementation service is automatically started if the relevant
|
|
<code class="docutils literal"><span class="pre">ServiceType</span></code> id is included in the node’s
|
|
<code class="docutils literal"><span class="pre">extraAdvertisedServiceIds</span></code> configuration property. The node will then
|
|
advertise itself as a Notary via the <code class="docutils literal"><span class="pre">NetworkMapService</span></code> and may then
|
|
participate in controlling state uniqueness when contacted by nodes
|
|
using the <code class="docutils literal"><span class="pre">NotaryFlow.Client</span></code> <code class="docutils literal"><span class="pre">subFlow</span></code>. The
|
|
<code class="docutils literal"><span class="pre">SimpleNotaryService</span></code> only offers protection against double spend, but
|
|
does no further verification. The <code class="docutils literal"><span class="pre">ValidatingNotaryService</span></code> checks
|
|
that proposed transactions are correctly signed by all keys listed in
|
|
the commands and runs the contract verify to ensure that the rules of
|
|
the state transition are being followed. The
|
|
<code class="docutils literal"><span class="pre">RaftValidatingNotaryService</span></code> further extends the flow to operate
|
|
against a cluster of nodes running shared consensus state across the
|
|
RAFT protocol (note this requires the additional configuration of the
|
|
<code class="docutils literal"><span class="pre">notaryClusterAddresses</span></code> property).</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="vault-related-services">
|
|
<h2>Vault Related Services<a class="headerlink" href="#vault-related-services" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="nodevaultservice">
|
|
<h3>NodeVaultService<a class="headerlink" href="#nodevaultservice" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">NodeVaultService</span></code> implements the <code class="docutils literal"><span class="pre">VaultService</span></code> interface to
|
|
allow access to the node’s own set of unconsumed states. The service
|
|
does this by tracking update notifications from the
|
|
<code class="docutils literal"><span class="pre">TransactionStorage</span></code> service and processing relevant updates to delete
|
|
consumed states and insert new states. The resulting update is then
|
|
persisted to the database. The <code class="docutils literal"><span class="pre">VaultService</span></code> then exposes query and
|
|
event notification APIs to flows and CorDapp plugins to allow them
|
|
to respond to updates, or query for states meeting various conditions to
|
|
begin the formation of new transactions consuming them. The equivalent
|
|
services are also forwarded to RPC clients, so that they may show
|
|
updating views of states held by the node.</p>
|
|
</div>
|
|
<div class="section" id="nodeschemaservice-and-hibernateobserver">
|
|
<h3>NodeSchemaService and HibernateObserver<a class="headerlink" href="#nodeschemaservice-and-hibernateobserver" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal"><span class="pre">HibernateObserver</span></code> runs within the node framework and listens for
|
|
vault state updates, the <code class="docutils literal"><span class="pre">HibernateObserver</span></code> then uses the mapping
|
|
services of the <code class="docutils literal"><span class="pre">NodeSchemaService</span></code> to record the states in auxiliary
|
|
database tables. This allows Corda state updates to be exposed to
|
|
external legacy systems by insertion of unpacked data into existing
|
|
tables. To enable these features the contract state must implement the
|
|
<code class="docutils literal"><span class="pre">QueryableState</span></code> interface to define the mappings.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="creating-a-cordapp.html" class="btn btn-neutral float-right" title="Creating a Cordapp" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="corda-configuration-files.html" class="btn btn-neutral" title="The Corda Configuration File" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2016, Distributed Ledger Group, LLC.
|
|
|
|
</p>
|
|
</div>
|
|
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT:'./',
|
|
VERSION:'latest',
|
|
COLLAPSE_INDEX:false,
|
|
FILE_SUFFIX:'.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.StickyNav.enable();
|
|
});
|
|
</script>
|
|
|
|
|
|
</body>
|
|
</html> |