corda/experimental/corda-utils/README.md

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

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.
• ...