Added several improvements for finalizing transactions.

Author: MrMatthewLayton

docs/CHANGELOG-2.1.0.md

@@ -6,9 +6,101 @@ This document serves as the change log for the ONIXLabs Corda Core API.
 
 ## Release Notes
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+This release contains several API improvements for workflow design and composability. Typically when writing flows, we find ourselves repeating a lot of boilerplate code for flow initialisation, transaction composition, verifying, signing, counter-signing and finalising. The APIs in this release move much of that boilerplate code into helpful extension functions, making your flows much more succinct and easier to read.
 
 ---
+
+### buildTransaction _Extension Function_
+
+**Module:** onixlabs-corda-core-workflow
+
+**Package:** io.onixlabs.corda.core.workflow
+
+Provides a DSL-like transaction builder.
+
+```kotlin
+fun FlowLogic<*>.buildTransaction(notary: Party, action: TransactionBuilder.() -> Unit): TransactionBuilder
+```
+
+#### Remarks
+
+To use this function, `BuildingTransactionStep` will need to be evident in your progress tracker.
+
+---
+
+### verifyTransaction _Extension Function_
+
+**Module:** onixlabs-corda-core-workflow
+
+**Package:** io.onixlabs.corda.core.workflow
+
+Verifies a transaction.
+
+```kotlin
+fun FlowLogic<*>.verifyTransaction(transaction: TransactionBuilder)
+```
+
+#### Remarks
+
+To use this function, `VerifyingTransactionStep` will need to be evident in your progress tracker.
+
+---
+
+### signTransaction _Extension Function_
+
+**Module:** onixlabs-corda-core-workflow
+
+**Package:** io.onixlabs.corda.core.workflow
+
+Signs a transaction.
+
+```kotlin
+fun FlowLogic<*>.signTransaction(transaction: TransactionBuilder): SignedTransaction
+```
+
+#### Remarks
+
+To use this function, `SigningTransactionStep` will need to be evident in your progress tracker.
+
+---
+
+### collectSignatures _Extension Function_
+
+**Module:** onixlabs-corda-core-workflow
+
+**Package:** io.onixlabs.corda.core.workflow
+
+Collects all remaining required signatures from the specified counter-parties.
+
+```kotlin
+fun FlowLogic<*>.collectSignatures(transaction: SignedTransaction, sessions: Iter)
+```
+
+#### Remarks
+
+This extension property can be used to determine whether the participants of a state are unique, regardless of the ordering of those participants.
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 ### TypeName _Declaration_
 

onixlabs-corda-core-workflow/src/main/kotlin/io/onixlabs/corda/core/workflow/Extensions.FlowLogic.Transaction.kt

@@ -90,39 +90,39 @@ fun FlowLogic<*>.findTransaction(stateAndRef: StateAndRef<*>): SignedTransaction
 
 /**
  * Provides a DSL-like transaction builder.
- * To use this function, [BuildingTransactionStep] will need to be evident in your progress tracker.
+ * To use this function, [BuildTransactionStep] will need to be evident in your progress tracker.
  *
  * @param notary The notary which will be applied to the transaction.
  * @param action The action which will be used to build the transaction.
  * @return Returns a [TransactionBuilder] representing the built transaction.
  */
 @Suspendable
 fun FlowLogic<*>.buildTransaction(notary: Party, action: TransactionBuilder.() -> Unit): TransactionBuilder {
-    currentStep(BuildingTransactionStep)
+    currentStep(BuildTransactionStep)
     val transactionBuilder = TransactionBuilder(notary)
     action(transactionBuilder)
     return transactionBuilder
 }
 
 /**
  * Verifies a transaction.
- * To use this function, [VerifyingTransactionStep] will need to be evident in your progress tracker.
+ * To use this function, [VerifyTransactionStep] will need to be evident in your progress tracker.
  *
  * @param transaction The transaction to verify.
  */
 @Suspendable
 fun FlowLogic<*>.verifyTransaction(transaction: TransactionBuilder) {
-    currentStep(VerifyingTransactionStep)
+    currentStep(VerifyTransactionStep)
     transaction.verify(serviceHub)
 }
 
 /**
- * Signs a transaction
- * To use this function, [SigningTransactionStep] will need to be evident in your progress tracker.
+ * Signs a transaction.
+ * To use this function, [SignTransactionStep] will need to be evident in your progress tracker.
  */
 @Suspendable
 fun FlowLogic<*>.signTransaction(transaction: TransactionBuilder): SignedTransaction {
-    currentStep(SigningTransactionStep)
+    currentStep(SignTransactionStep)
     val ourSigningKeys = transaction.getOurSigningKeys(serviceHub.keyManagementService)
     return serviceHub.signInitialTransaction(transaction, ourSigningKeys)
 }
@@ -137,11 +137,16 @@ fun FlowLogic<*>.signTransaction(transaction: TransactionBuilder): SignedTransac
  *
  * @param transaction The transaction for which to collect remaining signatures from the specified counter-parties.
  * @param sessions All flow sessions that have been passed to this flow.
+ * @param additionalSigningAction Allows additional signing actions to be specified. This will be executed after all other activity in this flow.
  * @return Returns a transaction which should be signed by all required signers.
  * @throws FlowException if the local node has been passed to this function as a counter-party or in a flow session.
  */
 @Suspendable
-fun FlowLogic<*>.collectSignatures(transaction: SignedTransaction, sessions: Iterable<FlowSession>): SignedTransaction {
+fun FlowLogic<*>.collectSignatures(
+    transaction: SignedTransaction,
+    sessions: Iterable<FlowSession>,
+    additionalSigningAction: ((SignedTransaction) -> SignedTransaction)? = null
+): SignedTransaction {
     currentStep(CollectTransactionSignaturesStep)
     val missingSigningKeys = transaction.getMissingSigners()
 
@@ -155,14 +160,16 @@ fun FlowLogic<*>.collectSignatures(transaction: SignedTransaction, sessions: Ite
 
     sessions.forEach { it.send(it in signingSessions) }
 
-    return if (signingSessions.isEmpty()) transaction else subFlow(
+    val signedTransaction = if (signingSessions.isEmpty()) transaction else subFlow(
         CollectSignaturesFlow(transaction, signingSessions, CollectTransactionSignaturesStep.childProgressTracker())
     )
+
+    return additionalSigningAction?.invoke(signedTransaction) ?: signedTransaction
 }
 
 /**
  * Signs a transaction.
- * To use this function, [SigningTransactionStep] will need to be evident in your progress tracker.
+ * To use this function, [SignTransactionStep] will need to be evident in your progress tracker.
  * Due to the way this function works, it is intended to be paired with [collectSignatures] in the initiating flow.
  *
  * @param session The flow session of the initiating flow that is requesting a transaction signature.
@@ -175,35 +182,67 @@ fun FlowLogic<*>.collectSignaturesHandler(
 ): SignedTransaction? {
     val isRequiredToSign = session.receive<Boolean>().unwrap { it }
     return if (isRequiredToSign) {
-        currentStep(SigningTransactionStep)
-        subFlow(object : SignTransactionFlow(session, SigningTransactionStep.childProgressTracker()) {
+        currentStep(SignTransactionStep)
+        subFlow(object : SignTransactionFlow(session, SignTransactionStep.childProgressTracker()) {
             override fun checkTransaction(stx: SignedTransaction) = action(stx)
         })
     } else null
 }
 
 /**
  * Finalizes a transaction.
- * To use this function, [FinalizingTransactionStep] will need to be evident in your progress tracker.
+ * To use this function, [SendStatesToRecordStep] and [FinalizeTransactionStep] will need to be evident in your progress tracker.
+ *
+ * This function allows the initiator to specify how counter-parties should record states of the finalized transaction.
+ * For each session of the [statesToRecordBySession] object, the counter-party will receive their [StatesToRecord]
+ * enumeration, unless they have specified an override via the [finalizeTransactionHandler] function. Finally they
+ * will record the finalized transaction.
+ *
+ * @param transaction The transaction to finalize and record.
+ * @param statesToRecordBySession Determines how counter-parties should record states in the transaction.
+ * @param ourStatesToRecord Determines how our node should record states in the transaction.
+ * @return Returns a fully signed, finalized and recorded transaction.
+ */
+@Suspendable
+fun FlowLogic<*>.finalizeTransaction(
+    transaction: SignedTransaction,
+    statesToRecordBySession: StatesToRecordBySession,
+    ourStatesToRecord: StatesToRecord = StatesToRecord.ONLY_RELEVANT
+): SignedTransaction {
+    return statesToRecordBySession.finalizeTransaction(transaction, this, ourStatesToRecord)
+}
+
+/**
+ * Finalizes a transaction.
+ * To use this function, [SendStatesToRecordStep] and [FinalizeTransactionStep] will need to be evident in your progress tracker.
+ *
+ * This function allows the initiator to specify how counter-parties should record states of the finalized transaction.
+ * Each session will record the transaction states according to the [counterpartyStatesToRecord] parameter, unless they
+ * have specified an override via the [finalizeTransactionHandler] function. Finally they will record the finalized transaction.
  *
  * @param transaction The transaction to be finalized.
  * @param sessions The sessions for all counter-parties and observers where this transaction should be recorded.
- * @param statesToRecord Determines which states from the transaction should be recorded.
+ * @param counterpartyStatesToRecord Determines how counter-parties should record states in the transaction.
+ * @param ourStatesToRecord Determines how our node should record states in the transaction.
  * @return Returns a fully signed, finalized and recorded transaction.
  */
 @Suspendable
 fun FlowLogic<*>.finalizeTransaction(
     transaction: SignedTransaction,
     sessions: Iterable<FlowSession>,
-    statesToRecord: StatesToRecord = StatesToRecord.ONLY_RELEVANT
+    counterpartyStatesToRecord: StatesToRecord = StatesToRecord.ONLY_RELEVANT,
+    ourStatesToRecord: StatesToRecord = StatesToRecord.ONLY_RELEVANT
 ): SignedTransaction {
-    currentStep(FinalizingTransactionStep)
-    return subFlow(FinalityFlow(transaction, sessions.toSet(), statesToRecord))
+    val statesToRecordBySession = StatesToRecordBySession(sessions, counterpartyStatesToRecord)
+    return finalizeTransaction(transaction, statesToRecordBySession, ourStatesToRecord)
 }
 
 /**
  * Finalizes a transaction.
- * To use this function, [RecordingFinalizedTransactionStep] will need to be evident in your progress tracker.
+ * To use this function, [ReceiveStatesToRecordStep] and [RecordFinalizedTransactionStep] will need to be evident in your progress tracker.
+ *
+ * This function will first receive the [StatesToRecord] from the initiating node, however this can be overridden using
+ * the [statesToRecord] parameter. Finally the transaction will be received and recorded.
  *
  * @param session The flow session of the initiating flow that is requesting the transaction to be finalized.
  * @param expectedTransactionId The expected transaction ID of the transaction to be recorded.
@@ -214,8 +253,12 @@ fun FlowLogic<*>.finalizeTransaction(
 fun FlowLogic<*>.finalizeTransactionHandler(
     session: FlowSession,
     expectedTransactionId: SecureHash? = null,
-    statesToRecord: StatesToRecord = StatesToRecord.ONLY_RELEVANT
+    statesToRecord: StatesToRecord? = null
 ): SignedTransaction {
-    currentStep(RecordingFinalizedTransactionStep)
-    return subFlow(ReceiveFinalityFlow(session, expectedTransactionId, statesToRecord))
+    currentStep(ReceiveStatesToRecordStep)
+    val receivedStatesToRecord = session.receive<StatesToRecord>().unwrap { it }
+    val ourStatesToRecord = statesToRecord ?: receivedStatesToRecord
+
+    currentStep(RecordFinalizedTransactionStep)
+    return subFlow(ReceiveFinalityFlow(session, expectedTransactionId, ourStatesToRecord))
 }

onixlabs-corda-core-workflow/src/main/kotlin/io/onixlabs/corda/core/workflow/FlowSteps.kt

@@ -19,28 +19,29 @@ package io.onixlabs.corda.core.workflow
 import net.corda.core.flows.CollectSignaturesFlow
 import net.corda.core.flows.FinalityFlow
 import net.corda.core.flows.SignTransactionFlow
+import net.corda.core.node.StatesToRecord
 import net.corda.core.utilities.ProgressTracker
 import net.corda.core.utilities.ProgressTracker.Step
 
 /**
  * Represents a progress tracker step indicating that a flow is being initialized.
  */
-object InitializingFlowStep : Step("Initializing flow.")
+object InitializeFlowStep : Step("Initializing flow.")
 
 /**
  * Represents a progress tracker step indicating that a transaction is being built.
  */
-object BuildingTransactionStep : Step("Building transaction.")
+object BuildTransactionStep : Step("Building transaction.")
 
 /**
  * Represents a progress tracker step indicating that a transaction is is being verified.
  */
-object VerifyingTransactionStep : Step("Verifying transaction.")
+object VerifyTransactionStep : Step("Verifying transaction.")
 
 /**
  * Represents a progress tracker step indicating that a transaction is being signed.
  */
-object SigningTransactionStep : Step("Signing transaction.") {
+object SignTransactionStep : Step("Signing transaction.") {
     override fun childProgressTracker(): ProgressTracker = SignTransactionFlow.tracker()
 }
 
@@ -51,14 +52,24 @@ object CollectTransactionSignaturesStep : Step("Collecting counter-party signatu
     override fun childProgressTracker(): ProgressTracker = CollectSignaturesFlow.tracker()
 }
 
+/**
+ * Represents a progress tracker step indicating that that [StatesToRecord] is being send to a counter-party.
+ */
+object SendStatesToRecordStep : Step("Sending states to record to counter-party.")
+
+/**
+ * Represents a progress tracker step indicating that that [StatesToRecord] is being received from a counter-party.
+ */
+object ReceiveStatesToRecordStep : Step("Receiving states to record from counter-party.")
+
 /**
  * Represents a progress tracker step indicating that a transaction is being finalized and recorded.
  */
-object FinalizingTransactionStep : Step("Finalizing transaction.") {
+object FinalizeTransactionStep : Step("Finalizing transaction.") {
     override fun childProgressTracker(): ProgressTracker = FinalityFlow.tracker()
 }
 
 /**
  * Represents a progress tracker step indicating that a transaction is being recorded.
  */
-object RecordingFinalizedTransactionStep : Step("Recording finalized transaction.")
+object RecordFinalizedTransactionStep : Step("Recording finalized transaction.")

onixlabs-corda-core-workflow/src/main/kotlin/io/onixlabs/corda/core/workflow/InternalSerializationWhitelist.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2020-2021 ONIXLabs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.onixlabs.corda.core.workflow
+
+import net.corda.core.node.StatesToRecord
+import net.corda.core.serialization.SerializationWhitelist
+
+/**
+ * Represents an internal list of classes to be whitelisted for serialization.
+ */
+internal class InternalSerializationWhitelist : SerializationWhitelist {
+    override val whitelist: List<Class<*>> = listOf(StatesToRecord::class.java)
+}