Corda 5.1 Release Notes

This page lists the key changes in the 5.1 release of Corda and contains the following:

• Enhancements
• Fixed Issues
• Known Issues and Limitations

For information about upgrading a Corda Cluster from 5.0 to 5.1, see Upgrading from 5.0.

Enhancements

Architecture

Java 17

Corda components are now hosted in a Java 17 compatible JVM.

Workers

The following new types of workers have been added:

• Persistence workers
• Uniqueness workers
• Flow mapper workers
• Verification workers
• Token selection workers

Logging

The default log4j configuration was modified to print exception stack traces as text blob within the JSON log message.

CorDapp Development

Logging for Finality Flows

The ID in logs written for finality flows has been made consistent.

Automatic Claim Release

Corda now automatically releases tokens for flows that no longer exist.

Group Parameters

A new interface, GroupParametersLookup, has been added to the net.corda.v5.membership package to enable flows to access current GroupParameters for further verification.

FindUnconsumedByExactType

A new FindUnconsumedByExactType method has been added, which replaces findUnconsumedStatesByType. The performance of this new method is greater than FindUnconsumedByType because it uses the index search that retrieves the given exact-type states (not including subclass states).

Transaction Signature Verification

Signature Verification functionality has been added to a new TransactionSignatureVerificationService interface. This enables it to be injected separately in the verification sandbox.

Signed Group Parameters

Signed group parameters are now distributed via backchain resolution to allow notary continuity verification for historic transactions.

Token Selection Visibility

You can now specify that a state is eligible for selection by implementing the isVisible method on the states’ contract. This replaces isRelevant.

Vault-Named Queries

The following changes have been made for vault-named queries:

• Vault-named query expressions now parse :parameter and ::int within parentheses correctly.
• It is now possible to query by StateRef. States are now stored in a stateRef field under the ContractState JSON object.

CorDapp API Deprecated Items

The following methods are deprecated in this release:

• findUnconsumedStatesByType — see FindUnconsumedByExactType.
• useAndRelease — see Automatic Claim Release.

The UtxoLedgerTokenStateObserver interface has been deprecated. Use UtxoTokenTransactionStateObserver instead.

Deployment

Pre-Install Checks

A preinstall command was added to the Corda CLI. This command enables you to run pre-install checks for Corda. These checks are now also run by default, as part of the deployment process. For more information, see the CLI Reference and Deployment Configuration.

P2P Gateway Configuration

Two servers can now share hostAddress and hostPort pair in the P2P gateway configuration.

Corda CLI Kafka Topics

The script sub-command of the topic Corda CLI command has been replaced with a new command, preview. The preview command generates a preview of the required Kafka topic configuration in YAML. You can save, and if required modify, this content before using the Corda CLI to execute it. For more information, see the CLI Reference.

State Manager Databases

Corda now requires one or more PostgreSQL database instances for the persistence of state between worker types. These are referred to as state manager databases. R3 recommends that you deploy separate isolated state manager database instances for the following workers:

• Flow workers
• Flow mapper workers
• Token selection workers

For more information, see State Manager Databases.

Database Connection Pools Configuration

You can now configure Database connection pools. For more information, see the configuration fields.

Affinity Nodes

You can now configure how worker replicas are spread across nodes by setting affinity parameters in the deployment configuration file. For more information, see Deployment Configuration.

Kubernetes Ingress

You can now configure Kubernetes Ingress to provide the P2P gateway worker with HTTP load balancing. For more information see, Deployment Configuration.

P2P Gateway Worker Metrics

Metrics are now available for the P2P gateway worker. For more information, see the Observability section.

Task Manager Metrics

Metrics are now available for the task manager. For more information, see the Observability section.

Application Networks

Membership Metadata

It is now possible to define the following types of membership metadata:

• A member can specify custom key-value pairs in the registration context. These are distributed as part of the MemberInfo to the rest of the members in the network.
• An MGM can specify custom metadata that is distributed as part of GroupParameters and can be used by the application to execute business logic based on that data. For example, from inside a CorDapp contract to enforce transaction rules for issuers.

Re-registering Members

Members can now modify custom metadata, CPI version, platform version, and software version of the memberInfo and request to re-register into the network. Re-registration follows the same process as registration, where it may require manual approval depending on the configuration of the network. For more information, see Re-register a Member. Upgrading a CPI now triggers the member to re-register with the MGM. This ensures the MGM has the correct information about the CPIs that virtual nodes are running.

Notary Ledger Keys

Notary virtual nodes no longer require a ledger key when onboarding to an application network. Corda now rejects any registrations of notary virtual nodes that contain ledger keys.

Managing Members

serial-number is now mandatory when suspending or re-activating a member.

REST API Improvements

• A new version of the REST API, v5_1, is included in this release. Old endpoints from v1 work in 5.1 but a warning is written to the REST Worker log and in the HTTP response.
• The certificates and keys endpoints have been renamed to certificate and key.
• The GET/hsm/{tenantid}/{category} endpoint now returns an HTTP 404 status if the category does not exist.
• The loginname parameter of the GET user endpoint has been changed to a path parameter.
• The members endpoint now returns the MemberInfo for the member on behalf of whom the lookup is performed even if the member has a status of suspended. This ensures that a member is able to check their status at any point in time.
• The upgrade virtual node endpoint /api/v5_1/virtualnode/{virtualnodeshortid}/cpi/{targetcpifilechecksum} now takes an optional query parameter, forceupgrade. Set this to true if a previous upgrade attempt failed. The default value is false.
• A new endpoint has been added that returns the result of a flow as JSON: /flow/{holdingidentityshorthash}/{clientrequestid}/result.

Fixed Issues

Custom Ledger Queries

In some instances, ledger custom queries that used paging skipped rows of data if any of the fields in the query where-clause changed. This most commonly occurred if the query used the consumed field as part of the where-clause and one or more of the states in a previously retrieved page were consumed prior to the final page of the query being returned. As a result of this change, VaultNamedParameterizedQuery no longer allows offset to be specified on the query. Invoking setOffset on this interface now throws an exception. CorDapp flows must not set this attribute. Instead, if query paging is desired, the ResultSet returned from the first query invocation should be used.

Known Issues and Limitations

Queries with no Limit

An error occurs if vault-named or standard persistence queries are executed with no limit.

Crypto Database Password Changed in Vault

The crypto database cluster-level password is not re-read from Vault if it changes.

Notary Selection

The notary virtual node selection logic (NotaryVirtualNodeSelectorServiceImpl) includes pending and suspended members.

Flow Service Exception

In some instances, the flow service throws an exception if a lambda expression is used. This issue is caused by a bug in the ASM library.

Token Selection Sharding and Ingress

Enabling sharding for the token selection worker can interfere with Ingress enabled for the REST and P2P Gateway workers. As multiple Ingress controllers attempt to process the Ingress resources, you may see repeated updates to the status of the Ingress resources and experience a loss in connectivity to the REST API or P2P Gateway.

As a workaround, provide the NGINX Ingress controller deployed for token selection sharding with read access to IngressClass resources. For example, if the name of the namespace to which Corda is deployed is specified by the environment variable CORDA_NAMESPACE, and the name of the Corda Helm release is specified by the environment variable CORDA_RELEASE, execute the following commands before deploying Corda:

kubectl create clusterrole "${CORDA_NAMESPACE}-${CORDA_RELEASE}-token-selection-worker-nginx" \
  --verb=get,list,watch --resource=ingressclasses
kubectl create clusterrolebinding "${CORDA_NAMESPACE}-${CORDA_RELEASE}-token-selection-worker-nginx" \
  --clusterrole="${CORDA_NAMESPACE}-${CORDA_RELEASE}-token-selection-worker-nginx" \
  --serviceaccount="${CORDA_NAMESPACE}:${CORDA_RELEASE}-token-selection-worker-nginx"