A Brief Introduction To The Node Services¶
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.
Services Within The Node¶
The node services represent the various sub functions of the Corda node.
Some are directly accessible to contracts and flows through the
ServiceHub
, whilst others are the framework internals used to host
the node functions. Any public service interfaces are defined in the
:core
gradle project in the
src/main/kotlin/net/corda/core/node/services
folder. The
ServiceHub
interface exposes functionality suitable for flows.
The implementation code for all standard services lives in the gradle
:node
project under the src/main/kotlin/net/corda/node/services
folder. The src/main/kotlin/net/corda/node/services/api
folder
contains declarations for internal only services and for interoperation
between services.
All the services are constructed in the AbstractNode
start
method (and the extension in Node
). They may also register a
shutdown handler during initialisation, which will be called in reverse
order to the start registration sequence when the Node.stop
is called.
As well as the standard services trusted CorDapp plugins may register
custom services. These plugin services are passed a reference to the
PluginServiceHub
which allows some more powerful functions e.g.
starting flows.
For unit testing a number of non-persistent, memory only services are
defined in the :node
and :test-utils
projects. The
:test-utils
project also provides an in-memory networking simulation
to allow unit testing of flows and service functions.
The roles of the individual services are described below.
Key Management and Identity Services¶
InMemoryIdentityService¶
The InMemoryIdentityService
implements the IdentityService
interface and provides a store of remote mappings between CompositeKey
and remote Parties
. It is automatically populated from the
NetworkMapCache
updates and is used when translating CompositeKey
exposed in transactions into fully populated Party
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 CompositeKey
of nodes need to be hidden
to non-involved parties.
PersistentKeyManagementService and E2ETestKeyManagementService¶
Typical usage of these services is to locate an appropriate
PrivateKey
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 ServiceHub
, but these ultimately
fetch the keys from the KeyManagementService
. The
KeyManagementService
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 PublicKey
/PrivateKey
pairs, but the signing authority will be represented by a
CompositeKey
on the NodeInfo
to allow key clustering and
threshold schemes.
The PersistentKeyManagementService
is a persistent implementation of
the KeyManagementService
interface that records the key pairs to a
key-value storage table in the database. E2ETestKeyManagementService
is a simple implementation of the KeyManagementService
that is used
to track our KeyPairs
for use in unit testing when no database is
available.
Messaging and Network Management Services¶
ArtemisMessagingServer¶
The ArtemisMessagingServer
service is run internally by the Corda
node to host the ArtemisMQ
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
messagingServerAddress
configuration to be the remote broker
address. (The MockNode
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 ArtemisMessagingServer
is responsible
for configuring the network ports (based upon settings in node.conf
)
and the service configures the security settings of the ArtemisMQ
middleware and acts to form bridges between node mailbox queues based
upon connection details advertised by the NetworkMapService
. The
ArtemisMQ
broker is configured to use TLS1.2 with a custom
TrustStore
containing a Corda root certificate and a KeyStore
with a certificate and key signed by a chain back to this root
certificate. These keystores typically reside in the certificates
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.
NodeMessagingClient¶
The NodeMessagingClient
is the implementation of the
MessagingService
interface operating across the ArtemisMQ
middleware layer. It typically connects to the local ArtemisMQ
hosted within the ArtemisMessagingServer
service. However, the
messagingServerAddress
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 CordaRPCOpsImpl
to carry
out the requests.
InMemoryNetworkMapCache¶
The InMemoryNetworkMapCache
implements the NetworkMapCache
interface and is responsible for tracking the identities and advertised
services of authorised nodes provided by the remote
NetworkMapService
. 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
Party
identities to the full NodeInfo
which is used in the
StateMachineManager
to convert between the CompositeKey
, or
Party
based addressing used in the flows/contracts and the
physical host and port information required for the physical
ArtemisMQ
messaging layer.
PersistentNetworkMapService and NetworkMapService¶
The NetworkMapService
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 NetworkMapService
early in the
start-up sequence and wait to synchronise their local
NetworkMapCache
before activating any flows. For the
PersistentNetworkMapService
registered NodeInfo
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 InMemoryNetworkMapService
is also available for unit tests
without a database.
The NetworkMapService
should not be used by any flows, or
contracts. Instead they should access the NetworkMapCache service to
access this data.
Flow Framework And Event Scheduling Services¶
StateMachineManager¶
The StateMachineManager
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 StateMachineManager
wraps the
flow code (extensions of the FlowLogic
class) inside an
instance of the FlowStateMachineImpl
class, which is a
Quasar
Fiber
. This allows the StateMachineManager
to suspend
flows at all key lifecycle points and persist their serialized state
to the database via the DBCheckpointStorage
service. This process
uses the facilities of the Quasar
Fibers
library to manage this
process and hence the requirement for the node to run the Quasar
java instrumentation agent in its JVM.
In operation the StateMachineManager
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 subFlow
. 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
StateMachineManager
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 StateMachineManager
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).
The StateMachineManager
service is not directly exposed to the
flows, or contracts themselves.
NodeSchedulerService¶
The NodeSchedulerService
implements the SchedulerService
interface and monitors the Vault updates to track any new states that
implement the SchedulableState
interface and require automatic
scheduled flow initiation. At the scheduled due time the
NodeSchedulerService
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.
Notary Flow Implementation Services¶
PersistentUniquenessProvider, InMemoryUniquenessProvider and RaftUniquenessProvider¶
These variants of UniquenessProvider
service are used by the notary
flows to track consumed states and thus reject double-spend
scenarios. The InMemoryUniquenessProvider
is for unit testing only,
the default being the PersistentUniquenessProvider
which records the
changes to the DB. When the Raft based notary is active the states are
tracked by the whole cluster using a RaftUniquenessProvider
. Outside
of the notary flows themselves this service should not be accessed
by any CorDapp components.
NotaryService (SimpleNotaryService, ValidatingNotaryService, RaftValidatingNotaryService)¶
The NotaryService
is an abstract base class for the various concrete
implementations of the Notary server flow. By default, a node does
not run any NotaryService
server component. However, the appropriate
implementation service is automatically started if the relevant
ServiceType
id is included in the node’s
extraAdvertisedServiceIds
configuration property. The node will then
advertise itself as a Notary via the NetworkMapService
and may then
participate in controlling state uniqueness when contacted by nodes
using the NotaryFlow.Client
subFlow
. The
SimpleNotaryService
only offers protection against double spend, but
does no further verification. The ValidatingNotaryService
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
RaftValidatingNotaryService
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
notaryClusterAddresses
property).