corda/experimental/corda-utils
Arshad Mahmood 6dd33fb8f7 Upgrade to gradle 7.6, kotlin 1.8 and jdk 17
Major changes due to JDK 17:
1. JDK17 JCE Provider now has built-in support for eddsas, corda uses
   the bouncycastle (i2p) implementation. This PR removes the conflicting
   algorithms from the built-in JCE provider.

2. JavaScript scripting has been removed from the JDK, the corda log4j config was using
   scripting to conditionally output additional diagnostic info if the MDC
   was populated. This PR has removed the scripting.

3. The artifactory plug-ins used are now deprecated, this PR has removed them
   and uses the same code as Corda 5 for publishing to artifactory.

4. Javadoc generation has been modified to use the latest dokka plug-ins.

5. Gradle 7.6 has implemented an incredibly annoying change where transitive
   dependencies are not put on the compile classpath, so that they have to be
   explicitly added as dependencies to projects.

6. Mockito has been updated, which sadly meant that quite a few source files
   have to changes to use the new (org.mockito.kotlin) package name. This makes
   this PR appear much larger than it is.

7. A number of tests have been marked as ignored to get a green, broadly they fall
   into 3 classes.

   The first is related to crypto keypair tests, it appears some logic
   in the JDK prefers to use the SunJCE implementation and we prefer to use
   bouncycastle. I believe this issue can be fixed with better test setup.

   The second group is related to our use of a method called "uncheckedCast(..)",
   the purpose of this method was to get rid of the annoying unchecked cast compiler
   warning that would otherwise exist. It looks like the Kotlin 1.9 compiler type
   inference differs and at runtime sometimes the type it infers is "Void" which causes
   an exception at runtime. The simplest solution is to use an explicit cast instead of
   unchecked cast, Corda 5 have removed unchecked cast from their codebase.

   The third class are a number of ActiveMQ tests which appear to have a memory leak somewhere.
2023-11-06 10:24:17 +00:00
..
src [NOTICK] - Enable check in detekt for unused imports () 2020-03-26 15:46:33 +00:00
build.gradle Upgrade to gradle 7.6, kotlin 1.8 and jdk 17 2023-11-06 10:24:17 +00:00
README.md Added the additional Corda utility code with FSM-like transition contract checking 2018-05-21 10:28:27 +02:00

Introduction

This project holds different Corda-related utility code.

Utils

Utils.kt contains various extension functions and other short utility code that aid development on Corda. The code is mostly self-explanatory -- the only exception may be StateRefHere which can be used in situations where multiple states are produced in one transaction, and one state needs to refer to the others, e.g. something like this:

    val tx = TransactionBuilder(//...
    // ...
    tx.addOutputState(innerState, contractClassName)
    val innerStateRef = StateRefHere(null, tx.outputStates().count() - 1)
    tx.addOutputState(OuterState(innerStateRef = innerStateRef), contractClassName)
    // ...

StatusTransitions

StatusTransitions.kt contains utility code related to FSM-style defining possible transactions that can happen with the respect to the contained status and roles of participants. Here's a simple example for illustration. We are going to track package delivery status, so we first define all roles of participants and possible statuses each package could have:

enum class PackageDeliveryRole {
    Sender,
    Receiver,
    Courier
}

enum class DeliveryStatus {
    InTransit,
    Delivered,
    Returned
}

The information about each package is held in PackageState: it contains its involved parties, status, linearId, current location, and information related to delivery attempts:

import net.corda.core.contracts.CommandData
import net.corda.core.contracts.Contract
import net.corda.core.contracts.LinearState
import net.corda.core.contracts.UniqueIdentifier
import net.corda.core.identity.AbstractParty
import net.corda.core.identity.Party
import net.corda.core.transactions.LedgerTransaction
import java.time.Instant

data class PackageState(val sender: Party,
    val receiver: Party,
    val deliveryCompany: Party,
    val currentLocation: String,
    override val status: DeliveryStatus,
    val deliveryAttempts: Int = 0,
    val lastDeliveryAttempt: Instant? = null,
    override val linearId: UniqueIdentifier): LinearState, StatusTrackingContractState<DeliveryStatus, PackageDeliveryRole> {

    override fun roleToParty(role: PackageDeliveryRole): Party {
        return when (role) {
            PackageDeliveryRole.Sender -> sender
            PackageDeliveryRole.Receiver -> receiver
            PackageDeliveryRole.Courier -> deliveryCompany
        }
    }

    override val participants: List<AbstractParty> = listOf(sender, receiver, deliveryCompany)
}

We can then define operations one can do with this state, who can do them and under what circumstances (i.e. from what status):

sealed class DeliveryCommand: CommandData {
    object Send: DeliveryCommand()
    object Transport: DeliveryCommand()
    object ConfirmReceipt: DeliveryCommand()
    object AttemptedDelivery: DeliveryCommand()
    object Return: DeliveryCommand()
}

class PackageDelivery: Contract {
    companion object {
        val transitions = StatusTransitions(PackageState::class,
            DeliveryCommand.Send.txDef(PackageDeliveryRole.Sender, null, listOf(DeliveryStatus.InTransit)),
            DeliveryCommand.Transport.txDef(PackageDeliveryRole.Courier, DeliveryStatus.InTransit, listOf(DeliveryStatus.InTransit)),
            DeliveryCommand.AttemptedDelivery.txDef(PackageDeliveryRole.Courier, DeliveryStatus.InTransit, listOf(DeliveryStatus.InTransit)),
            DeliveryCommand.ConfirmReceipt.txDef(PackageDeliveryRole.Receiver, DeliveryStatus.InTransit, listOf(DeliveryStatus.Delivered)),
            DeliveryCommand.Return.txDef(PackageDeliveryRole.Courier, DeliveryStatus.InTransit, listOf(DeliveryStatus.Returned)))
    }
    override fun verify(tx: LedgerTransaction) {
        transitions.verify(tx)
        // ...
        // other checks -- linearId is preserved, attributes are updated correctly for given commands, return is only allowed after 3 attempts, etc.
    }
}

This definition gives us some basic generic verification -- e.g. that package receipt confirmations need to be signed by package receivers. In addition that, we could visualize the defined transitions in a PUML diagram:

PackageDelivery.transitions.printGraph().printedPUML

Which will result in:

@startuml
title PackageState
[*] --> InTransit : Send (by Sender)
InTransit --> InTransit : Transport (by Courier)
InTransit --> InTransit : AttemptedDelivery (by Courier)
InTransit --> Delivered : ConfirmReceipt (by Receiver)
InTransit --> Returned : Return (by Courier)
@enduml

Generated PlantUML model

Future plans

Depending on particular use cases, this utility library may be enhanced in different ways. Here are a few ideas:

  • More generic verification (e.g. verifying numbers of produced and consumed states of a particular type)
  • More convenient syntax, not abusing nulls so much, etc.
  • ...