Release 0.82.0
CordaLedger consists of segregated contract, events, and report cache
com.deondigital.cordapp.client.GenericContractHandler now has a cacheConfiguration property instead of cacheSize to control the configuration of the underlying caches.
This property can be used to control the size of the underlying contract, event, and report cache and the speculative behavior of the event cache.
As before, a default configuration that creates caches of large size and speculative behavior turned on is provided in CordaLedger.DEFAULT_CACHE_CONFIG companion object.
GenericContractHandler(notary, cordaRpcOps, CordaLedger.DEFAULT_CACHE_SIZE, attachment)
becomes
GenericContractHandler(notary, cordaRpcOps, CordaLedger.DEFAULT_CACHE_CONFIG, attachment)
To tightly control the sizes and the speculation behavior, create an appropriate com.deondigital.cordapp.client.CacheConfiguration object.
Queries.pastEvents() exposes a Sequence instead of a List
Since events are not stored in a materialized fashion in the contract cache anymore but in a segregated event cache, com.deondigital.sic.Queries.pastEvents method now returns a lazy Sequence instead of a pre-materialized List for efficient cache access.
The required events can be materialized from the Sequence depending on the access requirements of the application code.
Use appropriate conversion functions e.g., toList() to retrieve all events from the sequence or take(3) to retrieve the earliest 3 elements from the sequence.
ContractHandler returns CachedCSLContractStateHandle instead of CachedCSLContractHandle
The methods addContracts, execute, getCurrentState in com.deondigital.cordapp.client.ContractHandler now return CachedCSLContractStateHandle instead of CachedCSLContractState to enable cache re-organizations.
The CachedCSLContractState can be accessed using the data property in CachedCSLContractStateHandle.
The properties related to events i.e., simulationEvents and versionedEvents that were present in CachedCSLContractState have been relocated to CachedCSLContractStateHandle and exposed as functions to signify they are not pre-materialized but constructed upon access.
Removal of recursive types
CSL no longer supports the definition of recursive datatypes.
In practice, the only recursive type that was actually used was List, and the presence of recursive types complicated many aspects of the language.
Code that uses recursive types other than List must be rewritten.
Running the Corda CSL Platform upgrade script
When upgrading your Corda nodes to the newest version of the CSL Cordapp, you must run a small script to update the contracts to refer to attachments compiled with the newest version of sic.
You should run the script just after you have deployed the Cordapp and started up your nodes.
The script is a runnable jar file, which can be obtained from the Deon maven repo.
The artifact id is com.deondigital:upgrade-from-0-81-0-to-0-82-0.
To run it, we recommend first defining an alias to run the jar
alias upgrade="java -jar upgrade-from-0-81-0-to-0-82-0.jar"
Run upgrade help to see help for the script.
Then, create a file application.conf with RPC credentials to all the nodes you control (include the notary if you can).
Example application.conf:
// file: application.conf
csl {
upgrade {
nodes = [
{ host = "localhost", port = 11000, username = "user1", password = "test" },
{ host = "localhost", port = 11001, username = "user1", password = "test" },
{ host = "localhost", port = 11002, username = "user1", password = "test" }
]
}
}
When run, the script will simply migrate all contracts to refer to the new attachment id for the compiled CSL declaration.
To do this, it needs to at least be given the target attachment to which it must upgrade contracts. You can give the target id either by
supplying the path to the zip file where the compiled code is,
explicitly giving the ID of the new attachment after it has been uploaded to the network, or
giving the name of the attachment after it has been uploaded to the network.
In most cases, the first option is easiest.
If you are using the gradle-sic-plugin to compile your CSL, the file will be located in
build/resources/main/{sicNameSpace}.definitions.zip where sicNameSpace refers to the configuration parameter of the gradle-sic-plugin.
Now, you can simply run upgrade --config=application.conf --target-zip-file={ZIP_FILE_PATH} upgrade and the upgrade process will start.
The upgrade script attempts to infer the old attachment id corresponding to the target attachment id.
If you do not want it to do this, you can pass --source-id and explicitly point to the attachment ID of the contracts you want to upgrade.
There are also a few parameters you can use to guide the inference process. Refer to upgrade help for more details.
In any case, you will be prompted to confirm the contracts you will be upgrading.
If you do not want the prompt you can additionally append --non-interactive to the command above.
Like the mass migration tool, the upgrade process provides real-time insights into the upgrade process.
Once the upgrade is complete, you can resume normal operations.
gradle-sic-plugin no longer implicitly adds dependencies
gradle-sic-plugin previously added a dependency on deon-api and the following target-specific dependencies
Corda:
sic-corda-operationsREST:
deon-api-clientandsic-rest-operations
If you’re using gradle-sic-plugin in your project you should add these dependencies manually in your build.gradle, e.g. implementation(group: 'com.deondigital', name: 'sic-corda-operations, version: CSL_VERSION).
Since the target configuration option was only used to add these dependencies, that option is now removed. To migrate, simply delete the line target = [[Corda|REST]] from you build.gradle csl section.
Additionally, the plugin used to add either the task generateCorda or generateKotlin based on the target.
The plugin now simply adds the generateKotlinFromCSL task.
gradle-sic-plugin’s cslVersion config option removed
In your build.gradle, in the csl configuration block, remove the line cslVersion = ....
gradle-sic-plugin’s output folder structure changed
The way gradle-sic-plugin structures the generated output from the underlying sic CSL compiler has changed slightly.
Previously, if e.g. csl.destinationDir = "generated/sic" and csl.sicNamespace = "com.foo" the generated kotlin code would be output to generated/sic/com/foo and the generated resources would be output to generated/sic/resources.
Now, the generated kotlin code is output to generated/sic/kotlin/com/foo instead.
The generated resources remain in the same location.
This means that after upgrading to the this version of the CSL platform, you’ll have to ./gradlew clean to get rid of the old generated artifacts.
Otherwise you’ll likely encounter duplication definitions errors.
Similarly, if you have configuration in your gradle files to e.g. allow intellij to include the generated kotlin as sources, you should update the paths by postfixing kotlin.
Rename of com.deondigital.cordapp.client.Attachment
The class com.deondigital.cordapp.client.Attachment has been renamed to com.deondigital.cordapp.client.ClasspathCslCordaAttachment.
com.deondigital.cordapp.client.Attachment still exists but is now an interface.
Renamed constructor argument attachmentInfo
The constructor argument attachmentInfo in com.deondigital.cordapp.client.{CordaLedger, GenericContractHandler} has been renamed to attachmentId.
If you’re using named parameters to construct instances of these classes, you should simply update the named parameter to be attachmentId instead of attachmentInfo.
ContractHandler throws RuntimeException on failed event applications
Previously, the method addEvents in ContractHandler threw CordaRuntimeException in certain cases of failed event application and RuntimeException for others.
This method was called internally whenever applyEvent was invoked on a ContractInstance.
This has been fixed now and RuntimeException is thrown when addEvents, addContract, and execute methods in com.deondigital.cordapp.client.ContractHandler interface fail.
The original exception is wrapped in the property cause of the RuntimeException.
If you are explicitly catching CordaRuntimeException for failures, you can change the code to catch RuntimeException instead.
If you want to check the original exception, you can get it from the cause property of the exception.
“Administrative” methods removed from CordaLedger
setParticipants, migrateContract, authorizeMigration, terminateContract have been removed from CordaLedger
Call the corresponding methods on ContractHandler instead.
ContractHandler.cslCordappConfiguration moved to CordaLedger
If you used to override this method to implement custom built-ins, you should now override it on CordaLedger instead of ContractHandler.
The custom built-ins example has been updated to reflect the change.
The classes CSLRequest and CSLAnswer have been removed from the package com.deondigital.sic
Use the corresponding classes from com.deondigital.cordapp.services which are almost identical.
Other than changing the package the only change necessary is to use CSLRequest.instantiationDetails.entryPoint instead of CSLRequest.entryPoint which no longer exists.
Added an RxJava Observable property QueryMonitor.onUnanswerableRequest
This property can be used to react to query monitor requests that are not answerable automatically with the given RespondPolicy.
Removed attachmentId parameter from several flows
The flows ExecuteOperationsFlow, SetParticipantsFlow and TerminateContractFlow no longer take an attachmentId: SecureHash as parameter.
This parameter was used to restrict the flows to only apply to specific attachment ids. This restriction has now been removed.
All flows that modify the ledger now return LedgerUpdateFlowResult
The following flows now return LedgerUpdateFlowResult:
ExecuteOperationsFlow,SetParticipantsFlow,TerminateContractFlow,NovateContractFlow,AuthorizeContractMigrationFlow, andMigrateContractFlow.
The return value of the flows before this change can be accessed in the property value in LedgerUpdateFlowResult.
Syntax for polymorphic external declarations has changed
The syntax for external declarations predates that of explicit variable binders.
Consequently, it used a different scheme where type variables were inferred from usage and constrained in a postfixed where clause.
To streamline the syntax of CSL, the syntax for polymorphic external declarations now resembles that of polymorphic value declarations.
Migrating to the new syntax is a completely mechanical task. For example, to migrate the following external declaration:
external prim__Map_fold : (k -> v -> a -> a) -> a -> Map k v -> a where Ord k
simply introduce all the type variables explicitly like for value declarations:
external <k : Ord, v, a> prim__Map_fold : (k -> v -> a -> a) -> a -> Map k v -> a
Observe that k is constrained at its binding site, replacing the need for the where clause.
test is now a reserved word
test is no longer available as a variable name. Please rename variables that are named test.