API stability guarantees

Corda makes certain commitments about which parts of the Corda 4 API will preserve stability and which will not. Over time, more of the Corda 4 API will fall under the stability guarantees. Thus, APIs can be categorized in the following two broad categories:

The following modules form part of the Corda 4 public API and we commit to API/ABI stability in following releases, unless an incompatible change is required for security reasons:

  • Core (net.corda.core): core Corda libraries such as crypto functions, types for Corda’s building blocks: states, contracts, transactions, attachments, etc. and some interfaces for nodes and protocols.
  • Client RPC (net.corda.client.rpc): client RPC
  • Client Jackson (net.corda.client.jackson): JSON support for client applications
  • DSL Test Utils (net.corda.testing.dsl): a simple DSL for building pseudo-transactions (not the same as the wire protocol) for testing purposes.
  • Test Node Driver (net.corda.testing.node, net.corda.testing.driver): test utilities to run nodes programmatically
  • Test Utils (net.corda.testing.core): generic test utilities
  • Http Test Utils (net.corda.testing.http): a small set of utilities for making HttpCalls, aimed at demos and tests.
  • Dummy Contracts (net.corda.testing.contracts): dummy state and contracts for testing purposes
  • Mock Services (net.corda.testing.services): mock service implementations for testing purposes

Additionally, the Tokens SDK (com.r3.corda.lib.tokens) available in the Tokens GitHub repository has a stable API.

The following are not part of the Corda 4 public API and no stability guarantees are provided:

  • Incubating modules, for which we will do our best to minimise disruption to developers using them until we are able to graduate them into the public API
  • Internal modules, which are not to be used, and will change without notice
  • Anything defined in a package containing .internal (for example, net.corda.core.internal and sub-packages should not be used)
  • Any interfaces, classes or methods whose name contains the word internal or Internal

The finance module was the first CorDapp ever written and is a legacy module. Although it is not a part of our API guarantees, we also don’t anticipate much future change to it. Users should use the tokens SDK instead.

  • net.corda.confidential: experimental support for confidential identities on the ledger
  • net.corda.client.jfx: support for Java FX UI
  • net.corda.client.mock: client mock utilities
  • Cordformation: Gradle integration plugins

Every other module is internal and will change without notice, even deleted, and should not be used.

Some of the public modules may depend on internal modules, so be careful to not rely on these transitive dependencies. In particular, the testing modules depend on the node module and so you may end having the node in your test classpath.

Certain interfaces and abstract classes within the Corda API have been annotated as @DoNotImplement. While we undertake not to remove or modify any of these classes’ existing functionality, the annotation is a warning that we may need to extend them in future versions of Corda. Cordapp developers should therefore just use these classes “as is”, and not attempt to extend or implement any of them themselves.

This annotation is inherited by subclasses and sub-interfaces.

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.