diff --git a/content/en/platform/corda/4.13/enterprise/cordapps/thread-pools.md b/content/en/platform/corda/4.13/enterprise/cordapps/thread-pools.md new file mode 100644 index 0000000000..69389e010a --- /dev/null +++ b/content/en/platform/corda/4.13/enterprise/cordapps/thread-pools.md @@ -0,0 +1,164 @@ +--- +date: '2025-04-20' +menu: + corda-enterprise-4-13: + identifier: corda-enterprise-4-13-cordapps-flows-segthreadpools + parent: corda-enterprise-4-13-cordapps-flows +tags: +- api +- service +- classes +title: Using additional thread pools +weight: 10 +--- + +Corda Enterprise executes flows in *thread pools*. A thread pool is a group of pre-created, idle threads, ready to execute tasks. The default Corda Enterprise configuration creates a single thread pool, whose size is configured by the *[flowThreadPoolSize]({{< relref "../node/setup/corda-configuration-fields.html#enterpriseconfiguration" >}})* parameter. Open Source Corda is single-threaded. + +In Corda 4.12 and previous versions, only the single, default thread pool described above was supported. From Corda 4.13 onward, the Enterprise version enables operators to define *multiple* thread pools and assign flows to them. The reason for this is to enable operators to prioritize particular flows and to segregate them from other flows. + +For example, if there are slow-running reporting flows and more important transactional flows on the same system, the reporting flows can be separated into a dedicated thread pool so that they do not block the transactional flows. + +Corda Enterprise targets the flow thread pools directly when it starts a flow. Therefore, there is no conflict between starting flows if one pool is performing badly and has a big queue. + +## Configuring thread pools + +Thread pools are defined in the [node configuration]({{< relref "../node/setup/corda-configuration-file.md" >}}) by adding an `additionalFlowThreadPools` array within the `tuning` object. The `additionalFlowThreadPools` array can contain one or more objects, each specifying the details of an additional thread pool. Each object contains a `threadpool` and `size` property, respectively defining the name of the thread pool and its size in number of threads. + +### Example 1: Two Defined Thread Pools + +The following sample configuration defines two thread pools based on the example above, `reporting` and `transactions`, each with three available threads: + +```json +enterpriseConfiguration { + tuning { + additionalFlowThreadPools= [ + { + threadPool=reporting, + size=3 + }, + { + threadPool=transactions, + size=3 + }, + ] + } +} +``` + +The related flows then need to be tagged accordingly: + +``` +@FlowThreadPool("reporting") +``` + +and + +``` +@FlowThreadPool("transactions") +``` + +### Example 2: One Defined Thread Pool and Default Thread Pool + +An alternative configuration, rather than defining two thread pools, could instead define one thread pool (in this case, `reporting`) but also use the default thread pool, defining its size using `flowThreadPoolSize`. As in previous versions of Corda, the size of the default thread pool (name: "default") is still specified by the *[flowThreadPoolSize]({{< relref "../node/setup/corda-configuration-fields.html#enterpriseconfiguration" >}})* parameter. + +```json +enterpriseConfiguration { + tuning { + flowThreadPoolSize = 3, + additionalFlowThreadPools= [ + { + threadPool=reporting, + size=3 + }, + ] + } +} +``` + +Only the flows related to reporting then need to be tagged accordingly: + +``` +@FlowThreadPool("reporting") +``` + +## Logging + +The Corda node's [startup log]({{< relref "../node/operating/monitoring-and-logging/overview.md" >}}) outputs the defined thread pools and their sizes; for example: + +``` +Created flow thread pools: reporting(3), transactions(3), default(20) +``` + +## Default flow-to-thread pool mapping rules + +How flows are mapped to thread pools depends on: + +- The thread pool configuration +- Whether or not the CorDapps installed have customized thread pool rules + +The Corda default FlowSchedulerMapper follows these rules, in order of highest priority first: + +1. If a flow is annotated with `@FlowThreadPool("threadpoolname")` and the referenced thread pool is defined in the configuration, then that flow is executed in the specified pool. + If the specified thread pool is not present in the node configuration, then the default thread pool is used instead. + +2. If a thread pool named `Peer-Origin` is defined, then all flows started via a peer Corda node and **not** annotated with a specific thread pool will be executed in that thread pool. Otherwise, such flows are executed in the default thread pool. + +3. If a thread pool named `RPC-Origin` is defined, then all flows started via RPC (for example, by a client application) and **not** annotated with a specific thread pool will be executed in that thread pool. Otherwise, such flows are executed in the default thread pool. + +4. If none of the above rules apply to a flow, then the default behavior is the same as in previous versions of Corda: the flow is executed in the default thread pool. + + +## Customizing flow-to-thread pool mapping rules + +CorDapps can override the above default flow mapping logic by defining a class which implements [the FlowSchedulerMapper interface](https://github.com/corda/corda/blob/release/os/4.13/core/src/main/kotlin/net/corda/core/flows/scheduler/mapper/FlowSchedulerMapper.kt); for example: + +```java +interface FlowSchedulerMapper { + fun getScheduler( + invocationContext: InvocationContext, + flowLogic: Class>, + ourIdentity: CordaX500Name + ): String +} +``` + +The default mapping logic is available [here](https://github.com/corda/corda/blob/release/os/4.13/core/src/main/kotlin/net/corda/core/flows/scheduler/mapper/FlowSchedulerMapperImpl.kt). + + +Corda scans CorDapps at startup time for classes implementing the FlowSchedulerMapper interface. +Corda logs this message if it finds a single candidate: + +``` +Using custom flow scheduler mapper. Class {classname} +``` + +If it has a constructor which accepts a set of Strings, it will use that class as a flow mapper. +Corda aborts with an exception if there is more than one class or there are no matching constructors. + +FlowSchedulerMapper constructors get the set of available additional thread pool names as an argument. +Its `getScheduler` method is called when a flow is scheduled. +Its expected return value is the thread pool's name, which is where the flow should be executed. + +Users should package their custom scheduler mapper in a separate CorDapp. This simplifies adding or removing it from the system. +Also, having the mapper in the same package as the main app would make installing multiple apps impossible due to multiple custom scheduler mappers. + +## Thread pool metrics + +The following [metric]({{< relref "../node/operating/monitoring-and-logging/node-metrics.md" >}}) was introduced in 4.13 specifically for thread pools: + +| Name | Description | +|--------------------------|-------------------------------------| +| QueueSizeTotal | The sum of all thread pool queues | + +The following metrics have now been updated to be divided by thread pool: + +| Previously | Corda 4.13 onward | +|------------------------------------------------|--------------------------------------------------------------------| +| ActiveThreads | ActiveThreads.{threadpoolname} | +| QueueSize | QueueSize.{threadpoolname} | +| QueueSizeOnInsert | QueueSizeOnInsert.{threadpoolname} | +| StartupQueueTime | StartupQueueTime.{threadpoolname} | +| FlowDuration.{Success/Failure}.{flowclassname} | FlowDuration.{Success/Failure}.{flowclassname}.{threadpoolname>} | + +Metrics related to the default thread pool do not have a *.default* suffix; this is for backward compatibility. + diff --git a/content/en/platform/corda/4.13/enterprise/node/operating/monitoring-and-logging/node-metrics.md b/content/en/platform/corda/4.13/enterprise/node/operating/monitoring-and-logging/node-metrics.md index 7b91548c93..673ff41562 100644 --- a/content/en/platform/corda/4.13/enterprise/node/operating/monitoring-and-logging/node-metrics.md +++ b/content/en/platform/corda/4.13/enterprise/node/operating/monitoring-and-logging/node-metrics.md @@ -68,7 +68,7 @@ There are two types of cache: - **Weight-based:**. Measured by the number of bytes of memory occupied by the entries {{< note >}} -The avalable set of metrics depends on the cache type. The `maximum-size` and `sizePercent` metrics are only available for size-based caches, while `maximum-weight`, `weight`, and `weightPercent` metrics are only available for weight-based caches. +The available set of metrics depends on the cache type. The `maximum-size` and `sizePercent` metrics are only available for size-based caches, while `maximum-weight`, `weight`, and `weightPercent` metrics are only available for weight-based caches. {{< /note >}} {{< table >}} @@ -94,12 +94,13 @@ The avalable set of metrics depends on the cache type. The `maximum-size` and `s ## Flows +Note that metrics related to the default thread pool do not have a *.default* suffix; this is for backward compatibility. {{< table >}} |Metric Query|Description| |----------------------------------------------------------------|--------------------------------------------------------------------------------------| -|net.corda:type=Flows,name=ActiveThreads|The total number of threads running flows.| +|net.corda:type=Flows,name=ActiveThreads.{threadpool}|The total number of threads running flows for the specified [thread pool](../../../cordapps/thread-pools.md).| |net.corda:type=Flows,name=CheckpointVolumeBytesPerSecondCurrent|The current rate at which checkpoint data is being persisted.| |net.corda:type=Flows,name=CheckpointVolumeBytesPerSecondHist|A histogram indicating the rate at which bytes are being checkpointed.| |net.corda:type=Flows,name=Checkpointing Rate|The rate at which checkpoint events are occurring.| @@ -107,14 +108,18 @@ The avalable set of metrics depends on the cache type. The `maximum-size` and `s |net.corda:type=Flows,name=ErrorPerMinute|The rate at which flows fail with an error.| |net.corda:type=Flows,name=Finished|The total number of completed flows (both successfully and unsuccessfully).| |net.corda:type=Flows,name=InFlight|The number of in-flight flows.| -|net.corda:type=Flows,name=QueueSize|The current size of the queue for flows waiting to be executed.| -|net.corda:type=Flows,name=QueueSizeOnInsert|A histogram showing the queue size at the point new flows are added.| +|net.corda:type=Flows,name=QueueSize.{threadpool}|The current size of the queue for flows waiting to be executed for the specified thread pool| +|net.corda:type=Flows,name=QueueSizeOnInsert.{threadpool}|A histogram showing the queue size at the point new flows are added for the specified thread pool| +|net.corda:type=Flows,name=QueueSizeTotal | The sum of all thread pool queues. | |net.corda:type=Flows,name=Started|The total number of flows started.| |net.corda:type=Flows,name=StartedPerMinute|The rate at which flows are started.| -|net.corda:type=Flows,name=StartupQueueTime|This timer measures the time a flow spends queued before it is executed.| +|net.corda:type=Flows,name=StartupQueueTime.{threadpool} |This timer measures the time a flow spends queued before it is executed for the specified thread pool. | |net.corda:type=Flows,name=Success|The total number of successful flows.| |net.corda:type=Flows,name=|A histogram indicating the time taken to execute a particular action. See the following section for more details.| - +|net.corda:type=Flows,name=FlowDuration.Success.{flowclassname} | The flow duration for the default thread pool of the specified flow, if successful. | +|net.corda:type=Flows,name=FlowDuration.Failure.{flowclassname}| The flow duration for the default thread pool of the specified flow, if failed. | +|net.corda:type=Flows,name=FlowDuration.Success.{flowclassname}.{threadpoolname} | The flow duration for the specified thread pool of the specified flow, if successful. | +|net.corda:type=Flows,name=FlowDuration.Failure.{flowclassname}.{threadpoolname} | The flow duration for the specified thread pool of the specified flow, if failed. | {{< /table >}} diff --git a/content/en/platform/corda/4.13/enterprise/node/operating/node-database-admin.md b/content/en/platform/corda/4.13/enterprise/node/operating/node-database-admin.md index bf01efc81d..ead7bff614 100644 --- a/content/en/platform/corda/4.13/enterprise/node/operating/node-database-admin.md +++ b/content/en/platform/corda/4.13/enterprise/node/operating/node-database-admin.md @@ -688,7 +688,7 @@ To configure a connection pool, the following custom properties can be set in th {{< note >}} - `maximumPoolSize` cannot be less than `enterpriseConfiguration.tuning.flowThreadPoolSize + enterpriseConfiguration.tuning.rpcThreadPoolSize + 2`. See [Performance tuning]({{< relref "../../performance-testing/performance-results.md" >}}) for more details. Their defaults depend on the machine they are being run, but if the `maximumPoolSize` a error will appear showing what is the minimum required.{{< /note >}} + `maximumPoolSize` cannot be less than `{The sum of the configured threadpools sizes} + enterpriseConfiguration.tuning.rpcThreadPoolSize + 2`. See [Optimising node performance]({{< relref "../../node/operating/optimizing.md" >}}) for more details. Their defaults depend on the machine they are being run, but if the `maximumPoolSize` a error will appear showing what is the minimum required.{{< /note >}} diff --git a/content/en/platform/corda/4.13/enterprise/node/operating/optimizing.md b/content/en/platform/corda/4.13/enterprise/node/operating/optimizing.md index adac528759..481efe3287 100644 --- a/content/en/platform/corda/4.13/enterprise/node/operating/optimizing.md +++ b/content/en/platform/corda/4.13/enterprise/node/operating/optimizing.md @@ -17,9 +17,9 @@ Node performance optimisation can be achieved by adjusting node configuration, n ## Adjusting the node settings -The main parameters that can be tweaked for a Corda Enterprise node are - +The main parameters that can be tweaked for a Corda Enterprise node are: +- **The number of thread pools used:** For more information, see [thread pools]({{< relref "../../cordapps/thread-pools.md" >}}). - **The number of flow threads:** This is the number of flows that can be live and active in the state machine at the same time. The default value for this is twice the number of processor cores available on the machine, capped at 30. - **The number of RPC threads:** This is the number of calls the RPC server can handle in parallel, enqueuing requests to the state machine. The default for this is the number of processor cores available on the machine - **The amount of heap space the node process can allocate:** The default for this is 512 megabytes. @@ -55,7 +55,21 @@ enterpriseConfiguration = { The recommended approach is to start with a low number of flow threads (for example, 1 per gigabyte of heap memory), and increase the number of threads over a number of runs. In tests at R3, it seems that giving a node twice the number of flow threads than RPC threads seemed a sensible number, but that might depend on the hardware and the use case, so it is worthwhile to experiment with this ratio. +You can also define additional thread pools; for more information, see [Using additional thread pools]({{< relref "../../cordapps/thread-pools.md" >}}). + +### Fine-tuning the Artemis configuration + +The following configuration options control some aspects of Artemis and can affect the throughput and latency of an application: +* `p2pConfirmationWindowSize`: The size of the in-memory buffer, used by the broker to buffer completed commands before acknowledging them to the client. +* `brokerConnectionTtlCheckIntervalMs`: The interval at which acknowledgements of completed commands are to be sent in case `p2pConfirmationWindowSize` is not exhausted in time. +* `journalBufferSize`: The size of the in-memory buffer used to store messages before they are flushed to disk. +* `journalBufferTimeout`: The interval at which Artemis messages that are buffered in-memory are to be flushed to disk if the `journalBufferSize` is not exhausted in time. + +As a result, you can control how frequently Artemis persists messages to disk and how frequently acknowledgements are sent back to clients. These values can affect the latency of flows, since a flow is expected to wait less on Artemis if it flushes messages to disk and sends acknowledgements more frequently. However, such configuration tweaks can also affect the throughput of flows, since flushing to disk more frequently and sending acknowledgements more frequently can result in a reduced efficiency of the utilisation of the disk and network resources. It is important that you benchmark any changes to these values in order to make sure that you have achieved the desired balance between throughput and latency. + +### Fine-tuning transaction resolution +In some cases, a node might have to resolve the provenance chain of a transaction from a counterparty. The configuration option `backchainFetchBatchSize` controls how many transactions the node will send at a time when performing this resolution. This defaults to a relatively large value, but you might need to increase it further if you have extremely large chains of transactions that nodes need to resolve. Increasing this value can reduce the latency of flows, since nodes will be able to resolve a transaction chain with fewer round trips. It might also have a positive impact on throughput because this way flows will last less and nodes will be able to complete more of them. However, this might also lead to an increase in the utilisation of network bandwidth and node resources in general. As a result, the actual results will depend on your environment. ## Disk access The node needs to write log files to disk, and has an Artemis spool directory that is used for the durable queues on the hard disk, so disk I/O for the node’s working directory has an impact on the node performance. For optimal performance, this should be on a fast, local disk. diff --git a/content/en/platform/corda/4.13/enterprise/node/setup/corda-configuration-fields.md b/content/en/platform/corda/4.13/enterprise/node/setup/corda-configuration-fields.md index 1151254a3e..23c554a88c 100644 --- a/content/en/platform/corda/4.13/enterprise/node/setup/corda-configuration-fields.md +++ b/content/en/platform/corda/4.13/enterprise/node/setup/corda-configuration-fields.md @@ -346,8 +346,14 @@ Allows fine-grained controls of various features only available in the enterpris * `tuning` - * The Corda node configuration file section that contains performance tuning parameters for Corda Enterprise nodes. + * The Corda Node configuration file section that contains performance tuning parameters for Corda Enterprise nodes. + - `additionalFlowThreadPools` + + * The default Corda Enterprise configuration creates a single thread pool whose size is configured by the *[flowThreadPoolSize]({{< relref "#enterpriseconfiguration" >}})* parameter. You can define *multiple* thread pools and assign flows to them; for example, to prioritize particular flows and to segregate them from other flows. Thread pools are defined by adding an `additionalFlowThreadPools` array within the `tuning` object. The `additionalFlowThreadPools` array can contain one or more objects, each specifying the details of an additional thread pool. Each object contains a `threadpool` and `size` property, respectively defining the name of the thread pool and its size in number of threads. + + For more information and examples, see [Setting thread pools]({{< relref "../../cordapps/thread-pools.md" >}}). + - `backchainFetchBatchSize` * This is an optimization for sharing transaction backchains. Corda Enterprise nodes can request backchain items in bulk instead of one at a time. This field specifies the size of the batch. The value is just an integer indicating the maximum number of states that can be requested at a time during backchain resolution. @@ -360,18 +366,22 @@ Allows fine-grained controls of various features only available in the enterpris - `flowThreadPoolSize` - The number of threads available to handle flows in parallel. This is the number of flows + The number of threads available to handle flows in parallel by the default thread pool. This value does not affect [additional thread pools]({{< relref "../../cordapps/thread-pools.md" >}}). The sum of the sizes of the default thread pool plus all additional thread pools sets the upper limit for the maximum number of flows executable in parallel. + + This is the number of flows that can run in parallel doing something and/or holding resources like database connections. - A larger number of flows can be suspended, for example, waiting for reply from a counterparty. + + Note that this property does not affect the size of additional thread pools as described in [Using additional thread pools]({{< relref "../../cordapps/thread-pools.md" >}}). + + A larger number of flows can be suspended; for example, waiting for reply from a counterparty. When a response arrives, a suspended flow will be woken up if there are any available threads in the thread pool. - Otherwise, a currently active flow must be finished or suspended before the suspended flow can be woken + Otherwise, a currently active flow must be finished or suspended before the suspended flow can be woken up to handle the event. This can have serious performance implications if the flow thread pool is too small, as a flow cannot be suspended while in a database transaction, or without checkpointing its state first. - Corda Enterprise allows the node operators to configure the number of threads the state machine manager can use to execute flows in parallel, allowing more than one flow to be active and/or use resources at the same time. + Corda Enterprise allows the node operators to configure the number of threads the state machine manager can use to execute flows in parallel, allowing more than one flow to be active and/or use resources at the same time. - The ideal value for this parameter depends on a number of factors. These include the hardware the node is running on, the performance profile of the flows, and the database instance backing the node as datastore. Every thread will open a database connection, so for n threads, the database system must have at least n+1 connections available. Also, the database - must be able to actually cope with the level of parallelism to make the number of threads worthwhile - if + The ideal value for this parameter depends on a number of factors. These include the hardware the node is running on, the performance profile of the flows, and the database instance backing the node as datastore. Every thread will open a database connection, so for n threads, the database system must have at least n+1 connections available. Also, the database must be able to actually cope with the level of parallelism to make the number of threads worthwhile - if using for example H2, any number beyond eight does not add any substantial benefit due to limitations with its internal architecture. For these reasons, the default size for the flow framework thread pool is the lower number between either the available number of processors times two, and 30. Overriding this value in the configuration allows you to specify any number. diff --git a/content/en/platform/corda/4.13/enterprise/performance-testing/performance-tuning.md b/content/en/platform/corda/4.13/enterprise/performance-testing/performance-tuning.md index cdfc9461d8..fa8aa8ca0b 100644 --- a/content/en/platform/corda/4.13/enterprise/performance-testing/performance-tuning.md +++ b/content/en/platform/corda/4.13/enterprise/performance-testing/performance-tuning.md @@ -16,179 +16,11 @@ weight: 800 Great, so we have set up a test cluster, have all the CorDapps and JMeter installed, sorted out the firewall rules, we can get a request go through via the JMeter GUI (see [View Results in Table]({{< relref "practical-considerations.md#interpreting-and-trouble-shooting-jmeter-output" >}}) for details how to verify that), we have sorted out an initial test plan and have run a performance test, but these throughput numbers are not quite what we would like to see there. -Time to tune the node. +Time to tune the node. For more information, see [Optimising node performance]({{< relref "../node/operating/optimizing.md" >}}). -## Tweaking the node settings -The main parameters that can be tweaked for a Corda Enterprise node are: -* The number of flow threads (the number of flows that can be live and active in the state machine at the same time). The default -value for this is twice the number of processor cores available on the machine, capped at 30. -* The number of RPC threads (the number of calls the RPC server can handle in parallel, enqueuing requests to the state machine). The default -for this is the number of processor cores available on the machine -* The amount of heap space the node process can allocate. The default for this is 512 megabytes. -For a machine with *n* cores, this will create up to *3n* Corda threads. On top of that, the messaging system (Artemis and Netty) will -create their own messaging handling thread infrastructure. -On a server machine with many processor cores, this can lead to over a 100 threads sharing 512 megabyte of memory - this leaves the -threads fighting for resources, and memory contention and very poor performance will be the result. -In Corda Enterprise, these properties can be controlled via the node configuration. -R3 recommends to keep a diary of changes during the tweaking of any parameters, or ideally have the node configuration under version -control so it is easy to go back and check settings for previous results. - - -### Tweaking the memory - -The first tweak should be to give the node more memory - the instructions how to deploy a node recommend at -least 2GB of memory. Performance tests at R3 typically use 8GB of memory for one node. This depends on the available memory and -how many nodes (and other processes) are run on the same machine. There are various ways to set the heap memory of the node documented at -[Setting JVM arguments]({{< relref "../node/deploy/running-a-node.md#setting-jvm-arguments" >}}). The recommended approach for performance optimisation work is to use the JVM argument section in the node -config file as this captures the memory setting along with any other settings. - -Be careful with the total amount of memory allocated to processes - if the total memory allocated to all processes on one machine exceeds -the physical RAM available in the machine, memory will be swapped out to the file system (if this is enabled) or memory allocation will -fail. Corda node processes do not react kindly to either of those events. In case of a memory allocation failure, the node will -stop and needs to be restarted. If the memory of the node process gets swapped out, expected timings and guarantees within the process can -be broken. This can lead to severe performance degradation, and flows and apps that rely on timings might fail. - -In general, more memory is better for the node, so it might be a good idea to start with as much memory as can be made available without -running into the issues mentioned above, and then proceed with tweaking other parameters. Once the node is tuned, it might be worthwhile -to run a few tests checking whether the amount of memory can be reduced without affecting performance. - - -### Tweaking the thread count - -Especially on large server machines, the default number of flow threads might be on the upper limit of what is sensible. In order to find -the optimal number, it is necessary to tweak that number via the configuration, restart the node(s), and rerun a test plan to see how the -numbers have changed. In order to keep the tests reproducible, it might be a good idea to wipe the database between tests so index sizes -and query times do not skew the test results for later runs (see [Resetting a node]({{< relref "practical-considerations.md#resetting-a-node" >}})). - -Flow and RPC threads can be set explicitly using the [tuning section]({{< relref "../node/setup/corda-configuration-file.md" >}}) of the enterprise configuration. Add the following section to your -node configuration file: - -```kotlin -enterpriseConfiguration = { - tuning = { - rpcThreadPoolSize = 4 - flowThreadPoolSize = 8 - } -} -``` - -The recommended approach is to start with a low number of flow threads (for example, 1 per gigabyte of heap memory), and increase the number of -threads over a number of runs. In tests at R3, it seems that giving a node twice the number of flow threads than RPC threads seemed a -sensible number, but that might depend on the hardware and the use case, so it is worthwhile to experiment with this ratio. - - -### Disk access - -The node needs to write log files to disk, and has an Artemis spool directory that is used for the durable queues on the hard disk, so disk -I/O for the node’s working directory has an impact on the node performance. For optimal performance, this should be on a fast, local disk. -For the Artemis spool directory, this leads to an inherent contradiction, a trade-off for which needs to be carefully considered and tested for -a production installation: the durable queue spool directory should be -as fast as possible in order not to become a bottleneck, on the other hand this data must not get lost or the durable promise of the queue -will be broken, so it should ideally be on a redundant storage medium. - - -### Fine-tuning the Artemis configuration - -The following configuration options control some aspects of Artemis and can affect the throughput and latency of an application: -* `p2pConfirmationWindowSize`: The size of the in-memory buffer, used by the broker to buffer completed commands before acknowledging them to the client. -* `brokerConnectionTtlCheckIntervalMs`: The interval at which acknowledgements of completed commands are to be sent in case `p2pConfirmationWindowSize` is not exhausted in time. -* `journalBufferSize`: The size of the in-memory buffer used to store messages before they are flushed to disk. -* `journalBufferTimeout`: The interval at which Artemis messages that are buffered in-memory are to be flushed to disk if the `journalBufferSize` is not exhausted in time. - -As a result, you can control how frequently Artemis persists messages to disk and how frequently acknowledgements are sent back to clients. These values can affect the latency of flows, since a flow is expected to wait less on Artemis if it flushes messages to disk and sends acknowledgements more frequently. However, such configuration tweaks can also affect the throughput of flows, since flushing to disk more frequently and sending acknowledgements more frequently can result in a reduced efficiency of the utilisation of the disk and network resources. It is important that you benchmark any changes to these values in order to make sure that you have achieved the desired balance between throughput and latency. - -### Fine-tuning transaction resolution - -In some cases, a node might have to resolve the provenance chain of a transaction from a counterparty. The configuration option `backchainFetchBatchSize` controls how many transactions the node will send at a time when performing this resolution. This defaults to a relatively large value, but you might need to increase it further if you have extremely large chains of transactions that nodes need to resolve. Increasing this value can reduce the latency of flows, since nodes will be able to resolve a transaction chain with fewer round trips. It might also have a positive impact on throughput because this way flows will last less and nodes will be able to complete more of them. However, this might also lead to an increase in the utilisation of network bandwidth and node resources in general. As a result, the actual results will depend on your environment. - -## Database optimisation - -The node has a high level of interaction with its database, so the performance of the database has a large impact on the node performance. - - -### Use an enterprise database - -The H2 database that is used by Corda by default is very handy for development, but it cannot handle the throughput that a serious -performance test will generate on any sensible hardware. It has internal locks that will throttle the throughput of the node. To test -actual performance of a Corda system, it is required to use an enterprise level database. - - -### Database server - -The database should be running on a separate server. Corda has some rather unusual requirements for the database: as the node writes its -checkpoints to the database, but only ever reads them when a flow needs to be restarted, the amount of data written to the database can -vastly exceed the amount of data read and index look-ups performed. Checkpoints are usually written once and removed once the flow finishes. -Therefore, a standard, read-optimised database as is e.g. on offer from cloud providers does not suit the performance requirements of Corda -very well. R3 recommends to run a dedicated database on a server that has fast disks, so the writing of checkpoints does not slow -the processing down. - -Depending on the write performance of the database, it might be useful to have a separate database server for each node rather than having -a schema per node in the same database server. - - -## Node interactions - -For any flow that only works within one node (for example, Cash Issuance), the above should allow to tweak the node to be performant. Any flows -that involve connections to other nodes (for example, to the recipient of a payment or a notary) might also be bottlenecked on the performance -of their peers, so they might need to be tweaked as well. - - -### Peers - -How much memory and how many threads are required on a peer node depends on the app being tested. When using the `CashIssueAndPayment` -flow from the performance CorDapp, the receiving node typically only needs half the number of threads/memory compared to the issuing -node to keep up with processing, but this might also depend on the hardware. Keeping one node configuration constant and modifying a peer -configuration is a valid test that needs to be undertaken. - - -### Notaries - -Any flows that require notarisations might be limited by the throughput of the notary. - - -### TLS connections - -Corda uses TLS to encrypt the peer to peer connections between nodes. It can be shown that the maximal throughput that is achievable with -the JVM TLS layer can limit the node throughput for flows that need to send sufficient amount of data between peers. This is e.g. the case -for the *CashIssueAndPayment* flow in the performance test CorDapp. - -Corda nodes can optionally use *boringSsl* for TLS connections - this is an OpenSsl based native SSL/TLS library maintained by Google that -allows much higher peer to peer throughput. Its use can be enabled by adding the following to the node configuration file: - -```kotlin -useOpenSsl=true -``` - - -## Varying the load - -The throughput of the system also varies with the load that is created from the client side - if the incoming request rate is too low, the -system will not reach maximum throughput, if it is too high, resource contention might actually lower the throughput as well. Varying the -load to identify the number of connections at which the node gets saturated and at which point throughput might start to suffer is not -only important to get optimal performance number, but this also needs to be considered when specifying a production system that needs -to be able to handle a certain load. - -The *Number of Threads* setting on a *Thread Group* in the test plan controls how many threads JMeter will run in parallel, each starting -a run and then waiting for the result. If you look at the NightlyBenchmark example test plan, you’ll notice that the same test gets -repeated with different numbers of threads, thus creating a result that reports throughput as a function of number of clients. - -Increasing the number of threads too high might lead to contention on the JMeter server (for example, on the RPC client), therefore it is also -possible to run requests from several JMeter servers. In this case, it is important that the target *host* in the testplan is an actual -machine name or IP address, not *localhost*, as the JMeter servers might run on different machines. Each JMeter server will run the specified -number of threads, so five servers with 200 Threads each would lead to 1000 runs in parallel. - - -## Final considerations - -After optimising the node using a specific test plan, do keep in mind that this might have optimised the node for this specific load that -gets generated by JMeter. While this is probably a good starting point to configure nodes for real world production uses, it is in no way -guaranteed that the configuration is suitable. - -If monitoring a node reveals that it does not perform as expected, further tweaking might be required, or the creation of a test plan that -matches the usage pattern observed with real life use and with the CorDapps that get used. diff --git a/content/en/platform/corda/4.13/enterprise/release-notes-enterprise.md b/content/en/platform/corda/4.13/enterprise/release-notes-enterprise.md index 36b4b0cfd4..d07613b716 100644 --- a/content/en/platform/corda/4.13/enterprise/release-notes-enterprise.md +++ b/content/en/platform/corda/4.13/enterprise/release-notes-enterprise.md @@ -1,6 +1,6 @@ --- -title: Corda Enterprise Edition 4.12 release notes -date: '2023-05-08' +title: Corda Enterprise Edition 4.13 release notes +date: '2025-06-30' menu: corda-enterprise-4-13: @@ -15,395 +15,58 @@ tags: weight: 10 --- -# Corda Enterprise Edition 4.12 release notes +# Corda Enterprise Edition 4.13 release notes -## Corda Enterprise Edition 4.12.5 release notes +The Corda Enterprise Edition 4.13 release introduces .... In this release, Java has been upgraded to Java x from Java x and Kotlin has been upgraded to Kotlin x from x. -Corda Enterprise Edition 4.12.5 is a patch release of Corda Enterprise Edition focused on resolving issues. - -### Upgrade recommendation - -{{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. - -To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. - -For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). -{{< /important >}} - -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). - -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 or below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. - -### Fixed issues - -* In Corda 4.11 and earlier, when the node verified contracts, they were all verified within the Corda node process. This meant that any custom command line attributes defined on the node process via the capsule would be visible to contract verification; for example, system properties. In Corda 4.12, the 4.12 contracts are still verified in the Corda node process, but legacy (that is, 4.11 and earlier) contracts are now verified in the new external verifier process. This external verifier is a separate process, so it does not receive the custom command line attributes set on the Corda node process. To rectify this, a new configuration field has been defined to allow custom command line attributes to be passed to the external verifier process. This new configuration field is `custom.externalVerifierJvmArgs`. - - For more information, see the `custom` configuration field in the [Configuration fields]({{< relref "node/setup/corda-configuration-fields.md#custom" >}}) section. - -## Corda Enterprise Edition 4.12.4 release notes - -Corda Enterprise Edition 4.12.4 is a patch release of Corda Enterprise Edition focused on upgrading dependencies to address security updates. - -### Upgrade recommendation - -{{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. - -To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. - -For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). -{{< /important >}} - -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). - -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 or below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. - -### Fixed issues - -* Log4j has been downgraded from version 2.23.1 to 2.23.0 to avoid a defect in Log4j that could cause excessive messages to be written to the log file. This will be updated to a later version when a fixed Log4j is available. - -### Third-party components upgrade - -The following table lists the dependency version changes between 4.12.3 and 4.12.4 Enterprise Editions: - -| Dependency | Name | Version 4.12.3 Enterprise | Version 4.12.4 Enterprise | -|------------------------------|---------------------|-----------------------------|--------------------------------| -| io.netty:netty-buffer
io.netty:netty-codec*
io.netty:netty-common
io.netty:netty-handler*
io.netty:netty-resolver
io.netty:netty-transport* | Netty | 4.1.109.Final | 4.1.115.Final | -| org.apache.logging.log4j:* | Apache | 2.23.1 | 2.23.0 | - -## Corda Enterprise Edition 4.12.3 release notes - -Corda Enterprise Edition 4.12.3 is a patch release of Corda Enterprise Edition focused on resolving issues. - -### Upgrade recommendation - -{{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. - -To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. - -For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). -{{< /important >}} - -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). - -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 or below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. - -### Fixed issues - -* Fixed an issue where CorDapp builds may fail to build with the error `java.lang.NoSuchFieldError: id_ml_dsa_44`. This issue arose from a version mismatch in Bouncy Castle libraries. A new LTS version of Bouncy Castle introduced this field, and it was being picked up due to version ranges specified in the Bouncy Castle dependencies. The issue has now been resolved by locking the Bouncy Castle dependencies to a specific version within Corda. - -* A `ClassNotFound` error, causing transaction verification to fail, does no longer occur when deserializing commands from a legacy transaction in the external verifier. This would sometimes happen because the class loader used during deserialization did not include any CorDapps and the missing class could not be auto-constructed. In cases where it did work, it was only because Corda managed to construct the missing class. This issue has now been resolved by ensuring that CorDapp classes are available during deserialization. Additionally, the external verifier's ability to auto-construct missing classes has been disabled. - -* Transactions with the in-flight transaction state, introduced in Corda version 4.11 to support transaction recovery, are no longer included when the Ledger Graph CorDapp builds a transaction graph. Instead, the CorDapp now ignores any transactions with an in-flight status. - -* The notary health check client tool now starts without any issues. - -* The Transaction Validator Utility (TVU) with a provided reverification file accurately reports the number of discovered transactions, even when the provided reverification file includes blank lines. - -## Corda Enterprise Edition 4.12.2 release notes - -Corda Enterprise Edition 4.12.2 is a patch release of Corda Enterprise Edition focused on resolving issues. - -### Upgrade recommendation - -{{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. - -To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. - -For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). -{{< /important >}} - -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). - -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 or below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. - -### Transaction Validator Utility Updates - -The following section describes the updated requirements for running the Transaction Validator Utility (TVU) and Corda 4.12 nodes. It clarifies and enhances the previous documentation. The current patch release documentation has been updated to reflect the following: - -* Legacy contracts directory: The legacy contracts directory is no longer required when running the TVU or when running 4.12 nodes, provided all nodes on the network are version 4.12 nodes. - -* 4.12 environment requirement: You must run the TVU in a 4.12 environment (excluding the database). Specifically, the `cordapps` directory must contain only 4.12-compatible CorDapps. See point 1 below. - -* Purpose of legacy contracts directory: The legacy contracts directory is now only needed for enabling 4.12 nodes to build transactions that include legacy contracts. This is only applicable in a mixed network of 4.12 nodes and pre-4.12 nodes. - -* Legacy JARs directory: You may need to include a `legacy-jars` directory when running both the TVU and the node. See point 4 below for further details. - -#### Transaction Validator Utility - -The purpose of the TVU is to mimic what a 4.12 node would do when verifying a legacy transaction, and report any errors found. - -1. You must run the TVU in a 4.12 node directory, using the 4.11 database to be validated (or a database upgraded to 4.11). Ensure that the CorDapps directory contains 4.12 CorDapps, and include any pre-4.12 dependencies in the `legacy-jars` directory if required by existing contract attachments on the ledger (see point 4 below). Note that the `legacy-contracts` directory is not necessary. - -#### Corda 4.12 nodes - -2. If your network includes a mix of 4.12 nodes and pre-4.12 nodes, each 4.12 node must have a `legacy-contracts` directory containing pre-4.12 contract CorDapps. This allows 4.12 nodes to build transactions that include pre-4.12 contracts, enabling interoperability with pre-4.12 nodes. In this scenario, you may also need a `legacy-jars` directory - see point 4 below. - -3. If your network consists solely of upgraded 4.12 nodes, there is no need for the `legacy-contracts` directory. The 4.12 nodes will create transactions without legacy contracts, which is fine as there are no pre-4.12 nodes in the network. In this scenario, since the ledger already contains pre-4.12 transactions, you may still need a `legacy-jars` directory - see point 4 below. - -4. Pre-4.12 transactions are verified in an external verifier process when encountered. This process does not, by default, include all third-party libraries that shipped with Corda 4.11 and earlier, nor does it have the `drivers` directory on the classpath. If your contracts in the ledger attachments depend on such third-party libraries or any contents from the `drivers` directory in Corda 4.11 or earlier, you can place the necessary JAR files in a directory called `legacy-jars` within the node directory. Any JARs in this directory will be added to the classpath of the external verifier. The TVU will assist you in identifying and verifying the resolution of such issues. - -### Fixed issues - -* There is no need for the external verifier to use the `legacy-contracts` folder anymore. The external verifier verifies pre-4.12 transactions and now solely uses the database to retrieve the contract attachments. -* An open telemetry span has been added around the Send to Multiple Parties and Receive from Multiple Parties operations. -* Previously, the transaction builder would log any failed verification attempts when trying to add missing dependencies. Now, these failed attempts are no longer logged if they occur while determining the missing dependencies. -* This release contains AMQP serialisation performance improvements. -* It is now possible to create two nodes whose X.500 names have the same Organisation (O) field value but different Organisation Unit (OU) values when using the driver DSL for testing. -* There is no longer a memory leak when creating a series of mock networks for testing purposes. -* The transaction builder no longer attaches legacy attachments to a transaction if the minimum platform version is 140 (i.e., 4.12). -* If the expected subject name does not match the actual subject name and the Float disconnects, a warning is logged. -* The TVU now includes the CorDapps class loader when deserializing output states as part of its deserialization test. Additionally, the TVU now also includes the same set of add-opens options as the node. -* The TVU is no longer writing the JDK17 attachments to the database when verifying transactions. -* A memory leak in the TVU has been resolved. -* A null pointer exception from the TVU (when resolving some parent paths) has been resolved. -* The TVU is no longer raising an exception when outputting a JSON representation of another exception. -* The TVU now parses configuration files in the same way as the node. -* A new `legacy-jars` directory has been introduced to improve backward compatibility with earlier versions of Corda. See the description above and the upgrade guide for details. -* Contract JAR signing key rotation of R3-provided CorDapps is included in this patch release. - -### Known issues - -* The Finance Contracts CorDapp was inadvertently embedded in the Corda Enterprise 4.12 node JAR, causing issues with various tests and potentially affecting anyone using these contracts in transactions. If you are using the Finance CorDapp, R3 strongly recommends upgrading to this patch release, preferably before going live on version 4.12. - -### Third party components upgrade - -The following table lists the dependency version changes between 4.12.1 and 4.12.2 Enterprise Editions: - -| Dependency | Name | Version 4.12.1 Enterprise | Version 4.12.2 Enterprise | -|------------------------------------------------|------------------------|-----------------------------|--------------------------------| -| org.eclipse.jetty:* | Jetty | 12.0.7 | 12.0.14 | -| commons-io:commons-io | commons IO | 2.7 | 2.17.0 | -| org.apache.commons:commons-configuration2 | commonsConfiguration2 | 2.10.1 | 2.11.0 | -| org.apache.sshd:sshd-common | sshd | 2.12.1 | 2.13.2 | -| org.apache.zookeeper:* | Zookeeper | 3.8.3 | 3.8.4 | - -## Corda Enterprise Edition 4.12.1 release notes - -Corda Enterprise Edition 4.12.1 is a patch release of Corda Enterprise Edition focused on resolving issues. - -### Upgrade recommendation - -{{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. - -To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. - -For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). -{{< /important >}} - -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). - -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 or below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. - -### Fixed issues - -* `ReceiveFinalityFlow` was returning a transaction that was missing the notary signature. This has now been fixed. The returned transaction now includes the notary signature. -* `ReceiveTransactionFlow` was checking that the network parameters on the transaction existed before `ResolveTransactionFlow` was executed. - This could cause a problem in certain scenarios; for example, when sending a top-level transaction to a new node in a migrated network, as the old network parameters would not exist on this new node. This has now been fixed. -* When resolving a party, in some code paths, `wellKnownPartyFromAnonymous` did not consider notaries from network parameters when trying to resolve an X.500 name. This scenario could occur when introducing a new node to a newly-migrated network as the new node would not have the old notary in its network map. This has now been fixed. Notaries from network parameters are now considered in the check. - -## Corda Enterprise Edition 4.12 release notes - -The Corda Enterprise Edition 4.12 release introduces upgrades to the Java and Kotlin versions, along with associated upgrade support. Apart from the features supporting the Java and Kotlin upgrade, no other major new features have been introduced. In this release, Java has been upgraded to Java 17 from Java 8 and Kotlin has been upgraded to Kotlin 1.9.20 from 1.2.71. - -When a CorDapp(s) and a node are successfully upgraded to 4.12, you are able to seamlessly interoperate 4.12 and 4.11 (or earlier) nodes on the same network, including the existing transactions on the ledger. +When a CorDapp(s) and a node are successfully upgraded to 4.13, you are able to seamlessly interoperate 4.12 and 4.11 (or earlier) nodes on the same network, including the existing transactions on the ledger. Supporting new Java and Kotlin versions is a major feature, as we must also handle legacy contracts from existing backchains. The upgraded Java and Kotlin versions also have implications for CorDapp developers. Simply replacing the Corda JAR without introducing other changes is not possible. ### Upgrade recommendation {{< important >}} -When upgrading a node to Corda 4.12, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. +When upgrading a node to Corda 4.13, it is extremely important that you run the Transaction Validator Utility on your node database to verify that the transactions in the old node are compatible with 4.12 nodes. To ensure compatibility of the transactions, you must also run the Transaction Validator Utility on any older nodes that are not being upgraded and will likely interact with any upgraded nodes. For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). {{< /important >}} -As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.11 to 4.12 upgrade guide]({{< relref "upgrade-guide.md" >}}). +As a developer or node operator, you should upgrade to the [latest released version of Corda]({{< relref "../enterprise/_index.md" >}}) as soon as possible. The latest Corda Enterprise release notes are on this page, and for the latest upgrade guide, refer to [Corda Enterprise Edition 4.12 to 4.13 upgrade guide]({{< relref "upgrade-guide.md" >}}). -The steps from this guide only work for direct upgrades from Corda 4.11 to 4.12. If you have any nodes on versions 4.10 and below, you must upgrade them to 4.11 first. To do that, consult the relevant release upgrade documentation. +The steps from this guide only work for direct upgrades from Corda 4.12 to 4.13. If you have any nodes on versions 4.11 and below, you must upgrade them to 4.12 first. To do that, consult the relevant release upgrade documentation. ### Platform version change -Corda 4.12 uses platform version 140. +Corda 4.13 uses platform version xxxx. For more information about platform versions, see [Versioning]({{< relref "cordapps/versioning.md" >}}). ### New features, enhancements and restrictions -#### Java and Kotlin upgrade - -Corda 4.12 requires Java 17 and Kotlin 1.9.20. This means that you must recompile any legacy CorDapps written for 4.11 or earlier to work with Java 17 and Kotlin 1.9.20 to be compatible with Corda 4.12. These upgrades enhance the supportability and security of Corda. - -#### Java 17 compatible releases of Corda SDKs - -The base Corda package includes several SDKs and libraries. These SDKs and libraries are compatible with Java 17 and Kotlin 1.9.20: - -| SDK/library | Java 17 compatible release | -|---------------------------|-------------------------------| -| corda-shell | 4.12 | -| r3-libs | 1.4 | -| confidential-identities | 1.2 | -| accounts | 1.1 | -| token-sdk | 1.3 | -| reissue-cordapp | 1.1 | -| archiving | 1.2 | -| ledger-graph | 1.3 | -| r3-tools | 4.12 | - -#### Collaborative Recovery removed - -The Collaborative Recovery solution, along with the associated CorDapps (LedgerSync and LedgerRecover), is deprecated, and has been removed in Corda 4.12. You are now advised to use the new recovery tools introduced in version 4.11, as described in the [Corda Enterprise Edition 4.11 release notes]({{< relref "../../4.11/enterprise/release-notes-enterprise.md#corda-enterprise-edition-411-release-notes-1" >}}). - -#### Transaction Validator Utility - -Corda 4.12 introduces the Transaction Validator Utility (TVU), a tool that validates transactions committed to the database to avoid post-migration errors when upgrading to Corda 4.12. For more information, see [Transaction Validator Utility]({{< relref "node/operating/tvu/_index.md" >}}). - -#### Support for signature constraints only - -Only CorDapps using signature constraints are supported in Corda 4.12; hash constraints are not supported. Using signature constraints has been recommended in previous releases of Corda as it eases the CorDapp upgrade process. If you have any 4.11 CorDapps using hash constraints, you must migrate them to signature constraints on 4.11 before upgrading to 4.12. - -#### Corda 4.11 and 4.12 CorDapps must be signed by the same set of keys - -Once you have recompiled your 4.12 CorDapps for Java 17 and Kotlin 1.9.20, you must sign them using the same set of keys used by the 4.11 CorDapp. - -#### Explicit contract upgrade is not supported - -Explicit contract upgrade is not supported in Corda 4.12. +* [Multiple thread pools can now be defined and have flows assigned to them]({{< relref "cordapps/thread-pools.md" >}}). Thread pools enable operators to prioritize particular flows and to segregate them from other flows. -#### `toLedgerTransaction.verify` does not work for legacy transactions +* Corda Enterprise targets the flow thread pools directly when it starts a flow. Therefore, there is no conflict between starting flows if one pool is performing badly and has a big queue. -You must review your CorDapps and check for any making the following calls: -* `SignedTransaction.toLedgerTransaction().verify()` -* `WireTransaction.toLedgerTransaction().verify()` -* `TransactionBuilder.toLedgerTransaction().verify()` -CorDapps that make the above calls will not work for legacy transactions. To make those CorDapps compatible, change them to `SignedTransaction.verify()`. -#### Corda node explorer not supported on Java 17 -The node explorer has not been converted to use Java 17 and is not provided in the release packs. If you wish to use a node explorer, the only current option is to use a 4.11 node explorer and use it to connect to a 4.12 node. -#### Samples Kotlin and Java support -The following two public repositories provide various CorDapp samples (branch: release/4.12): -* [Samples Kotlin repository](https://github.com/corda/samples-kotlin/tree/release/4.12) -* [Samples Java repository](https://github.com/corda/samples-java/tree/release/4.12) -Most samples have been converted over to Java 17, Kotlin 1.9.20, and Gradle 7.6.4. - -The samples have been written to work with Corda Open Source. To convert a sample to work with Corda Enterprise, then at a minimum you need to point to a repository where your enterprise artifacts are installed. Also, the artifact group name for ENT (`com.r3`) must be different from OS `(net.corda`). For example, switch `net.corda:corda-node-driver:4.12` (Corda OS) to `com.r3.corda:corda-node-driver:4.12` (Corda ENT). - -The following dependencies have been used in samples and can be switched from Corda OS to Corda Enterprise: -* corda -* corda-confidential-identities -* corda-core-test-utils -* corda-finance-workflows -* corda-jackson -* corda-node -* corda-node-api -* corda-node-driver -* corda-rpc -* corda-shell -* corda-test-utils -* corda-testserver-impl - -The samples listed below have been converted to and tested with Java 17 and Kotlin 1.9.20: - -| CorDapp type | CorDapp | -|--------------------|--------------------------------------| -| Accounts | obligation-accounts | -| | sharestatewithaccount | -| | supplychain | -| | worldcupticketbooking | -| Advanced | duediligence-cordapp | -| | negotiation-cordapp | -| | obligation-cordapp | -| | superyacht-cordapp | -| | syndicated-lending | -| Basic | cordapp-example | -| | flow-database-access | -| | flow-http-access | -| | opentelemetry-cordapp-example | -| | ping-pong | -| | tutorial-applestamp | -| | tutorial-jarsigning | -| | tutorial-networkbootrstrapper | -| Features | attachment-blacklist | -| | attachment-sendfile | -| | confidentialIdentity-whistleblower | -| | contractsdk-recordplayers | -| | cordaService-autopayroll | -| | customlogging-yocordapp | -| | customquery-carinsurance | -| | dockerform-yocordapp | -| | encumbrance-avatar | -| | multioutput-transaction | -| | notarychange-iou | -| | observableStates-tradereporting | -| | oracle-primenumber | -| | postgres-cordapp | -| | queryableState-carinsurance | -| | referenceStates-sanctionsBody | -| | schedulableState-heartbeat | -| | state-reissuance | -| Tokens | bikemarket | -| | dollartohousetoken | -| | fungiblehousetoken | -| | stockpaydividend | -| | tokentofriend | - -#### Kotlin and Java CorDapp templates - -The following Kotlin and Java CorDapp templates have been converted to Java 17, Kotlin 1.9.20, and Gradle 7.6.4. They have been written to work with Corda Open Source Edition (branch: release/4.12): -* [Kotlin CorDapp template](https://github.com/corda/cordapp-template-kotlin/tree/release/4.12) -* [Java CorDapp template](https://github.com/corda/cordapp-template-java/tree/release/4.12) - -### No optional gateway plugins release pack - -The optional gateway plugins release pack contains the flow and node management plugins used by the CENM gateway service. These plugins provide GUI-based flow and node management functionality. Since CENM has not yet been converted to use Java 17, these plugins are not included in the 4.12 release. Once CENM and plugins have been converted, they will be added in a future release. If you wish to use flow and node management functionality, you can obtain the plugins from the 4.11 `optional-gateway-plugins` release pack and use them with the CENM gateway service. - -#### CorDapp using internal APIs or reflective access - -If your CorDapp is using internal APIs or reflective access, then you may need to explicitly open the module on the command line. You can do this by adding one or more `–add-opens` options when starting Corda. ### Fixed issues -#### Thread.contextClassLoader set for resumed flow on node startup -Previously, if a flow was resuming on node startup, the thread context class loader was not set, potentially causing `ClassNotFound` issues for CorDapp classes. This has been fixed now. ### Known issues -#### Extra stack trace output when logging level is `TRACE` - -If you start the node with log level set to trace via the command line option `--logging-level=TRACE`, then you will see some `Unable to format stack trace` outputs from Log4j caused by a bug in Artemis. These can be ignored and have no effect on node operation. They can be removed via a custom log4j.xml where trace output from the `org.apache.activemq.artemis.core.paging.cursor.impl.PageCursorProviderImpl` logger is removed. - -#### Startup warnings from Log4j - -At node startup with the default Log4j, the following message appears: `main WARN The use of package scanning to locate plugins is deprecated and will be removed in a future release.` This is a warning only and can be safely ignored. We are currently investigating alternatives. - -#### `notaryhealthcheck-client` fails to start - -The Corda 4.12 `notaryhealthcheck-client` fails to start. This will be fixed in a future patch release. As an alternative, you can use the `notaryhealthcheck-client` provided with the Corda 4.11 release. - -#### Intermittent warning from Bouncy Castle when running `deployNodes` - -When running the Gradle task `deployNodes`, you may occasionally see the following warning message: - -``` -exception in disposal thread: org/bouncycastle/util/dispose/DisposalDaemon$3 -``` - -This is a warning message from the LTS version of Bouncy Castle we are currently using. There is no user impact and it is related to disposing of references with native code. This will be fixed in a future patch release. - + ### Third party component upgrades +**Following table needs to be updated for 4.13** + The following table lists the dependency version changes between 4.11 and 4.12 Enterprise Editions: | Dependency | Name | Version 4.11 Enterprise | Version 4.12 Enterprise |