This is an update for Canton Network dApp developers for the upcoming Splice 0.6.0 and Canton 3.5 upcoming release. See the schedule for dates.
Logical Synchronizer Upgrade (LSU) is a new feature targeted for Canton 3.5 which enables zero downtime Canton upgrades and enables data continuity across an upgrade. This memo is an early announcement of some side effects of LSU so that the community is aware early and can mitigate the side effects.
The change is that the format of the synchronizer_id metadata field value in a prepared transaction will change when upgrading from Canton 3.4 (protocol version 34) to Canton 3.5 (protocol version 35). This is not an API breaking change but to the format of the synchronizer_id field shown below:
Current format example (protocol version 34):
global_sync::12204457ac942c4d839331d402f82ecc941c6232de06a88097ade653350a2d6fc9c5
New format example (protocol version 35):
global_sync::12204457ac942c4d839331d402f82ecc941c6232de06a88097ade653350a2d6fc9c5::35-0
As shown, the 3.5 format adds a suffix compared to the current 3.4 format. Applications must ensure that they do not rely on the format of this field in a way that would break functionality. If the field must be parsed then it is recommended to support both formats.
This will cause the DSO Global Synchronizer ID to adjust as shown in the example above.
Please note that the API specification does not give any guarantee on the synchronizer_id format, so the recommended approach is to treat synchronizer_id metadata as an opaque string in the application logic. In general, this is the recommended approach since the synchronizer_id field may change in the future. If you must parse the synchronizer_id, the recommendation is to support both formats.
LSU also introduces a new transient failure that the application needs to be able to mitigate. The transient failure is explained as follows:
- A client prepares an external transaction and signs it with a hash value.
- An LSU is performed so the Canton version is upgraded without stopping the dApp.
- The client submits the external transaction to the new Canton version.
- However, confirming participants will use the new version of the Canton protocol which will calculate a different hash value so the transaction fails.
- An error is sent to the client to indicate that this issue is non-retryable.
- The mitigation is for the client application to detect the error code and reprepare the external transaction, reinitiating the process with a refreshed external transaction.
This type of retry is different from a network timeout where a retry with the exact same transaction is possible.