corda / net.corda.core.flows

Package net.corda.core.flows

Base data types and abstract classes for implementing Corda flows. To implement a new flow start with FlowLogic, or see CollectSignaturesFlow for a simple example flow. Flows are started via a node's ServiceHub.

Corda flows are a tool for modelling the interactions between two or more nodes as they negotiate a workflow. This can range from a simple case of completing a trade which has been agreed upon externally, to more complex processes such as handling fixing of interest rate swaps.

Types

AbstractStateReplacementFlow

abstract class AbstractStateReplacementFlow

Abstract flow to be used for replacing one state with another, for example when changing the notary of a state. Notably this requires a one to one replacement of states, states cannot be split, merged or issued as part of these flows.

CollectSignatureFlow

class CollectSignatureFlow : FlowLogic<List<TransactionSignature>>

Get and check the required signature.

CollectSignaturesFlow

class CollectSignaturesFlow : FlowLogic<SignedTransaction>

The CollectSignaturesFlow is used to automate the collection of counter-party signatures for a given transaction.

ContractUpgradeFlow

object ContractUpgradeFlow

A flow to be used for authorising and upgrading state objects of an old contract to a new contract.

DataVendingFlow

sealed class DataVendingFlow : FlowLogic<Void?>

FinalityFlow

class FinalityFlow : FlowLogic<SignedTransaction>

Verifies the given transaction, then sends it to the named notary. If the notary agrees that the transaction is acceptable then it is from that point onwards committed to the ledger, and will be written through to the vault. Additionally it will be distributed to the parties reflected in the participants list of the states.

FlowInfo

data class FlowInfo

Version and name of the CorDapp hosting the other side of the flow.

FlowInitiator

sealed class FlowInitiator : Principal

FlowInitiator holds information on who started the flow. We have different ways of doing that: via RPC FlowInitiator.RPC, communication started by peer node FlowInitiator.Peer, scheduled flows FlowInitiator.Scheduled or via the Corda Shell FlowInitiator.Shell.

FlowLogic

abstract class FlowLogic<out T>

A sub-class of FlowLogic implements a flow using direct, straight line blocking code. Thus you can write complex flow logic in an ordinary fashion, without having to think about callbacks, restarting after a node crash, how many instances of your flow there are running and so on.

FlowLogicRef

interface FlowLogicRef

A handle interface representing a FlowLogic instance which would be possible to safely pass out of the contract sandbox. Use FlowLogicRefFactory to construct a concrete security checked instance.

FlowLogicRefFactory

interface FlowLogicRefFactory

The public factory interface for creating validated FlowLogicRef instances as part of the scheduling framework. Typically this would be used from within the nextScheduledActivity method of a QueryableState to specify the flow to run at the scheduled time.

FlowSession

abstract class FlowSession

A FlowSession is a handle on a communication sequence between two paired flows, possibly running on separate nodes. It is used to send and receive messages between the flows as well as to query information about the counter-flow.

FlowStackSnapshot

data class FlowStackSnapshot

Main data object representing snapshot of the flow stack, extracted from the Quasar stack.

NotaryChangeFlow

class NotaryChangeFlow<out T : ContractState> : Instigator<T, T, Party>

A flow to be used for changing a state's Notary. This is required since all input states to a transaction must point to the same notary.

NotaryError

sealed class NotaryError

NotaryFlow

class NotaryFlow

ReceiveStateAndRefFlow

class ReceiveStateAndRefFlow<out T : ContractState> : FlowLogic<List<StateAndRef<T>>>

The ReceiveStateAndRefFlow should be called in response to the SendStateAndRefFlow.

ReceiveTransactionFlow

class ReceiveTransactionFlow : FlowLogic<SignedTransaction>

The ReceiveTransactionFlow should be called in response to the SendTransactionFlow.

SendStateAndRefFlow

open class SendStateAndRefFlow : DataVendingFlow

The SendStateAndRefFlow should be used to send a list of input StateAndRef to another peer that wishes to verify the input's integrity by resolving and checking the dependencies as well. The other side should invoke ReceiveStateAndRefFlow at the right point in the conversation to receive the input state and ref and perform the resolution back-and-forth required to check the dependencies.

SendTransactionFlow

open class SendTransactionFlow : DataVendingFlow

The SendTransactionFlow should be used to send a transaction to another peer that wishes to verify that transaction's integrity by resolving and checking the dependencies as well. The other side should invoke ReceiveTransactionFlow at the right point in the conversation to receive the sent transaction and perform the resolution back-and-forth required to check the dependencies and download any missing attachments.

SignTransactionFlow

abstract class SignTransactionFlow : FlowLogic<SignedTransaction>

The SignTransactionFlow should be called in response to the CollectSignaturesFlow. It automates the signing of a transaction providing the transaction:

StackFrameDataToken

data class StackFrameDataToken

Token class, used to indicate stack presence of the corda internal data. Since this data is of no use for a CordApp developer, it is skipped from serialisation and its presence is only marked by this token.

StateMachineRunId

data class StateMachineRunId

A unique identifier for a single state machine run, valid across node restarts. Note that a single run always has at least one flow, but that flow may also invoke sub-flows: they all share the same run id.

TransactionParts

data class TransactionParts

The minimum amount of information needed to notarise a transaction. Note that this does not include any sensitive transaction details.

Annotations

InitiatedBy

annotation class InitiatedBy

This annotation is required by any FlowLogic that is designed to be initiated by a counterparty flow. The class must have at least a constructor which takes in a single net.corda.core.identity.Party parameter which represents the initiating counterparty. The FlowLogic that does the initiating is specified by the value property and itself must be annotated with InitiatingFlow.

InitiatingFlow

annotation class InitiatingFlow

This annotation is required by any FlowLogic which has been designated to initiate communication with a counterparty and request they start their side of the flow communication.

SchedulableFlow

annotation class SchedulableFlow

Any FlowLogic which is schedulable and is designed to be invoked by a net.corda.core.contracts.SchedulableState must have this annotation. If it's missing FlowLogicRefFactory.create will throw an exception when it comes time to schedule the next activity in net.corda.core.contracts.SchedulableState.nextScheduledActivity.

StartableByRPC

annotation class StartableByRPC

Any FlowLogic which is to be started by the RPC interface (net.corda.core.messaging.CordaRPCOps.startFlowDynamic and net.corda.core.messaging.CordaRPCOps.startTrackedFlowDynamic) must have this annotation. If it's missing the flow will not be allowed to start and an exception will be thrown.

Exceptions

FlowException

open class FlowException : CordaException

Exception which can be thrown by a FlowLogic at any point in its logic to unexpectedly bring it to a permanent end. The exception will propagate to all counterparty flows and will be thrown on their end the next time they wait on a FlowSession.receive or FlowSession.sendAndReceive. Any flow which no longer needs to do a receive, or has already ended, will not receive the exception (if this is required then have them wait for a confirmation message).

IllegalFlowLogicException

class IllegalFlowLogicException : IllegalArgumentException

NotaryException

class NotaryException : FlowException

StateReplacementException

open class StateReplacementException : FlowException

UnexpectedFlowEndException

class UnexpectedFlowEndException : CordaRuntimeException

Thrown when a flow session ends unexpectedly due to a type mismatch (the other side sent an object of a type that we were not expecting), or the other side had an internal error, or the other side terminated when we were waiting for a response.