Notaries in Corda 5: Pluggable Notary Protocols

July 12, 2023

By: Ramzi El-Yafi, Staff Software Engineer at R3

In a previous blog post, we looked at the Notary Architecture in Corda 5 as a whole. As part of this, we briefly mentioned that notary functionality is provided in the form of “plugin” CorDapps. Since then, we have added official documentation to explain the implications of this architecture on CorDapp Developers and Network Operators. This blog post provides some more background as to why we have adopted this model. It also poses some questions that both CorDapp Developers and Network Operators need to ask as part of the development and operational lifecycle.

Photo by Emre Turkan on Unsplash
Photo by Emre Turkan on Unsplash

Plugin Philosophy

In Corda 4, notary functionality is fixed function. When specifying a notary in the configuration, a single setting (the validating flag) indicates whether the notary supports the non-validating or validating notarization protocol. Under the hood, these are both sub-flows that execute as part of transaction finality. They share much of the same code, specifically around uniqueness checking. The non-validating notary plugin performs only minimal additional checks beyond uniqueness checking, whilst the validating notary plugin performs full contract validation against states in a transaction and all of the relevant back-chain.

Ultimately, the distinctiveness between these protocols is entirely within flow logic. This led to the realization that we had implemented fixed-function logic, whereas a solution that implemented the flows in CorDapps would provide superior flexibility. As a result of this, the decision was taken to implement notarization flows in CorDapps, whilst making a separate “uniqueness service” available to these flows to perform fixed-function double-spend prevention checks. This provides flexibility to add additional notary protocols in future, either provided by R3, or a third-party developer.


Notary plugin CorDapps must provide an initiator and corresponding responder flow. These flows are slightly special, in that they are not directly invokable from the flow REST API. Instead, they are intended to be invoked as sub-flows, as part of transaction finality. Each notary service on the network will have a named protocol that it supports, defined in its Membership Group Manager (MGM) metadata. This corresponds to the protocol name of an initiating flow within the notary plugin, which is automatically invoked as a sub-flow during transaction finality. Whilst not required, it is recommended that a notary plugin is split into three distinct Corda Packages (CPKs):

  • A client CPK, which is included as part of an “application” Corda Package Bundle (CPB), installed on standard virtual nodes on the network. This contains the initiating flow.
  • A server CPK, which is included as part of a “notary” CPB, installed on notary virtual nodes on the network. This contains the responder flow.
  • An API CPK, which is included on both sides and is used to define the message payload between the initiator and responder flow.

This diagram outlines the structure of the non-validating notary plugin, which is shipped as part of the Corda 5.0 release:

Diagram outlining the structure of the non-validating notary plugin
Diagram outlining the structure of the non-validating notary plugin

This structure allows for the proper separation of responsibilities. Only notary virtual nodes have the responder flow installed and with it, the ability to respond to notarization requests. Similarly, only application virtual nodes have the ability to initiate notarization requests.


Lets now consider the implications of this architecture from the perspective of different personas.

CorDapp Developers

The biggest impact of this architecture is arguably on CorDapp Developers. Since application CPBs are produced by CorDapp Developers, they decide which notary protocols that their CorDapp will support and it is they who ensure the relevant notary plugin CPKs are bundled as part of their application CPB. Right now, this decision is trivial since R3 only provides a non-validating notary plugin, so the decision comes down to whether their CorDapp utilizes the UTXO ledger. If it does, this requires notarization and therefore the relevant non-validating notary CPKs must be included. Alternatively, if their CorDapp does not utilize the UTXO ledger (for example if the CorDapp only uses flows and not a ledger), then there is no need to include any notary protocol.

Things may get more interesting in future as more notary protocols are added. The CorDapp Developer does not know anything about the network that their CorDapp will be deployed on, so they must bundle all appropriate plugins that are supported by their CorDapp. Conversely, it may be that their CorDapp needs a specialized notary protocol, written either by themselves or by another entity. In this scenario, they may forgo bundling the “standard” notarization protocols and only bundle the specialized protocol.

Notary Plugin Developers

The packaging decisions for Notary Plugin Developers are not so clear. One or more CPKs must be produced to support a custom notarization protocol. It’s also clear that there should be a separate notary CPB produced for installation on notary virtual nodes.

For the non-validating notary protocol, R3 produces and distributes a standard notary server CPB for this purpose. We are able to do this because the protocol is simple and requires no third-party CPKs to operate. However, we can imagine a situation where this is not possible. For example, if we were to re-implement the validating notary protocol from Corda 4, which performs validation against the contracts of states in a transaction during notarization, this would require the notary server CPB to contain a CPK from the “application”, because it would need a custom set of contracts to verify against. In this situation, the Plugin Developer could only produce CPKs, and would require the CorDapp Developer to build a notary and an application CPB.

Network Operators

Network Operators must decide which notarization protocols that their network will support and build one or more notary server Corda Package Installers (CPIs) from provided CPBs. These CPIs must then be installed on the relevant notary virtual nodes. Again, this is trivial whilst there is a single supported notary protocol, but this may become more involved if the network supports multiple notary protocols (and by extension, supports multiple notary services).


Whilst the changes to notarization protocols in Corda 5 require CorDapp Developers and Network Operators to think about which protocols that they will support, the Corda 5.0 release represents the beginning of a journey to develop the functional capabilities of the notary. This approach provides an extensible framework that allows us to easily add additional notarization capabilities throughout the life of the Corda 5 platform.

Corda 5 is generally available. Download the Corda artifacts, learn more in the Corda docs, and start building for free.