Corda 5 Developer Preview: Modular APIs

September 27, 2021

We have released Corda 5 Developer Preview I (Corda 5 DP1) with the primary aim of hearing our Corda developers’ thoughts and feedback early, so we can adjust our directions and priorities based on that. One of the main focuses of Corda 5 DP1 is new modular APIs, which means all APIs are in separate modules.

 New interface-based APIs and implementations are separate

In this blog, we want to share the objectives and design decisions we took when developing the new APIs with our community.

Why do we need new APIs?

The following are the main advantages of the new set of modular APIs:

  1. Since APIs are separate from implementations, it lets us upgrade or change implementations without touching APIs. This  also allows us to have APIs that look roughly like final APIs in Corda 5 general release. And we can change the implementation of APIs under the hood rather than rewrite everything.
  2. A clear evolution of APIs. If we do API change, it’s clear API change is not driven by implementation change. 
  3. Modularity provides limited and explicit dependencies between different API modules. There were dependencies in Corda 4.x, which were not necessary for APIs, and created possibilities of circular dependencies. All of these have gone in the DP1 release. In DP1, there are just interfaces with explicit dependencies that developers need on public API.
  4. Since API is interface-based, developers can quickly mock these interfaces to unit test the flows and services of corDapps. In Corda 4.x, developers had to run a mock network with Artemis and databases to test flow. In Corda 5 DP1, developers can have a mock framework that allows testing of their business logic without bringing up a network — this provides quicker writing tests and uses fewer resources during test run time.

Separations of concerns

In Corda 4.x, all the components were on the core module.

Another significant design decision we took in Corda 5 DP1 was to split them into layers as shown on the diagram below:

Corda 5 DP1 was to split them into layers

Breaking up the core module into layers. 

  1. System layer — consist of basic components (base/crypto/serialization) to allow minimum functionality on Corda.
  2. On top of that, there is the Distributed Flow Engine layer, which gives additional application and persistence modules. The application module provides flows, Corda services, and peer-to-peer networking. The persistence module provides database access and the ability to store objects in a database. 
  3. The last layer is the Ledger/Contract; it has two components: ledger and system-flows. The ledger module is still the same and is based on contracts. We might replace it in later releases. Lastly, the system-flows component consists of a finality, send/receive transaction, backchain resolution, and other flows  —  functionality you need to operate a distributed ledger in Corda.

Since APIs are in Kotlin, in Corda 4.x, some of these APIs were awkward to call from Java because they used Kotlin specific mechanisms (such as inline methods or default arguments), making it call from Java. In Corda 5, we eliminated this problem and tested all APIs from Java to ensure all interfaces were callable from Java.