docs/net.corda.core.flows

Package-level declarations

Types

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(val partiallySignedTx: SignedTransaction, val session: FlowSession, val signingKeys: List<PublicKey>) : FlowLogic<List<TransactionSignature>>

Get and check the required signature.

CollectSignaturesFlow

class CollectSignaturesFlow constructor(val partiallySignedTx: SignedTransaction, val sessionsToCollectFrom: Collection<FlowSession>, val myOptionalKeys: Iterable<PublicKey>?, val progressTracker: ProgressTracker = tracker()) : FlowLogic<SignedTransaction>

The CollectSignaturesFlow is used to automate the collection of counterparty signatures for a given transaction.

ComparableRecoveryTimeWindow

data class ComparableRecoveryTimeWindow(val fromTime: Instant, val fromTimestampDiscriminator: Int, val untilTime: Instant, val untilTimestampDiscriminator: Int)

ContractUpgradeFlow

object ContractUpgradeFlow

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

DataVendingFlow

open class DataVendingFlow(val otherSessions: Set<FlowSession>, val payload: Any, txnMetadata: TransactionMetadata? = null) : FlowLogic<Void?>

Destination

@DoNotImplement

interface Destination

An abstraction for flow session destinations. A flow can send to and receive from objects which implement this interface. The specifics of how the messages are routed depend on the implementation.

DistributionList

@DoNotImplement

sealed class DistributionList

DistributionRecord

@DoNotImplement

abstract class DistributionRecord : NamedByHash

DistributionRecordKey

data class DistributionRecordKey(val txnId: SecureHash, val timestamp: Instant, val timestampDiscriminator: Int)

DistributionRecords

class DistributionRecords(val senderRecords: List<SenderDistributionRecord> = emptyList(), val receiverRecords: List<ReceiverDistributionRecord> = emptyList())

DistributionRecordType

enum DistributionRecordType : Enum<DistributionRecordType>

FinalityFlow

@InitiatingFlow

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.

FinalityRecoveryFlow

@StartableByRPC

@InitiatingFlow

class FinalityRecoveryFlow(txIds: Collection<SecureHash> = emptySet(), flowIds: Collection<StateMachineRunId> = emptySet(), matchingCriteria: FlowRecoveryQuery? = null, forceRecover: Boolean = false, recoverAll: Boolean = false, forceRecoverFlowIds: Collection<StateMachineRunId> = emptySet(), val progressTracker: ProgressTracker = ProgressTracker()) : FlowLogic<Map<FlowTransactionInfo, Boolean>>

TWO_PHASE_FINALITY Recovery Flow This flow is exposed via the Core API for use by any CorDapp but its implementation is available in Enterprise only.

FlowException

open class FlowException(message: String?, cause: Throwable?, var originalErrorId: Long? = null) : 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).

FlowExternalAsyncOperation

interface FlowExternalAsyncOperation<R : Any>

FlowExternalAsyncOperation represents an external future that blocks a flow from continuing until the future returned by FlowExternalAsyncOperation.execute has completed. Examples of external processes where FlowExternalAsyncOperation would be useful include, triggering a long running process on an external system or retrieving information from a service that might be down.

FlowExternalOperation

interface FlowExternalOperation<R : Any>

FlowExternalOperation represents an external process that blocks a flow from continuing until the result of execute has been retrieved. Examples of external processes where FlowExternalOperation would be useful include, triggering a long running process on an external system or retrieving information from a service that might be down.

FlowInfo

data class FlowInfo(val flowVersion: Int, val appName: String)

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

FlowInitiator

sealed class FlowInitiator : Principal

Please note that FlowInitiator has been superceded by net.corda.core.context.InvocationContext, which offers more detail for the same event.

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

@DoNotImplement

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

@DoNotImplement

interface FlowLogicRefFactory

The public factory interface for creating validated FlowLogicRef instances as part of the scheduling framework.

FlowRecoveryException

class FlowRecoveryException(message: String, cause: Throwable? = null) : FlowException

FlowRecoveryQuery

data class FlowRecoveryQuery(val timeframe: FlowTimeWindow? = null, val initiatedBy: List<CordaX500Name>? = null, val counterParties: List<CordaX500Name>? = null)

FlowSession

@DoNotImplement

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(val time: Instant, val flowClass: String, val stackFrames: List<FlowStackSnapshot.Frame>)

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

FlowTimeWindow

data class FlowTimeWindow(val fromTime: Instant? = null, val untilTime: Instant? = null)

FlowTransactionInfo

data class FlowTransactionInfo(val stateMachineRunId: StateMachineRunId, val txId: String, val status: TransactionStatus, val timestamp: Instant, val metadata: TransactionMetadata?)

Transaction recovery type information.

HospitalizeFlowException

open class HospitalizeFlowException(message: String?, cause: Throwable?) : CordaRuntimeException

This exception allows a flow to pass itself to the flow hospital. Once the flow reaches the hospital it will determine how to progress depending on what causes the exception wraps. Assuming there are no important wrapped exceptions, throwing a HospitalizeFlowException will place the flow in overnight observation, where it will be replayed at a later time.

IllegalFlowLogicException

class IllegalFlowLogicException(val type: String, msg: String) : IllegalArgumentException

Thrown if the structure of a class implementing a flow is not correct. There can be several causes for this such as not inheriting from FlowLogic, not having a valid constructor and so on.

InitiatedBy

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class InitiatedBy(val value: KClass<out FlowLogic<*>>)

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

@Target(allowedTargets = [AnnotationTarget.CLASS])

@Inherited

annotation class InitiatingFlow(val version: Int = 1)

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.

KilledFlowException

class KilledFlowException(val id: StateMachineRunId, message: String) : CordaRuntimeException

An exception that is thrown when a flow has been killed.

LedgerRecoveryException

class LedgerRecoveryException(message: String) : FlowException

LedgerRecoveryFlow

@StartableByRPC

class LedgerRecoveryFlow(parameters: LedgerRecoveryParameters, val progressTracker: ProgressTracker = ProgressTracker()) : FlowLogic<LedgerRecoveryResult>

Ledger Recovery Flow (available in Enterprise only).

LedgerRecoveryParameters

data class LedgerRecoveryParameters(val recoveryPeers: Collection<Party>, val timeWindow: RecoveryTimeWindow? = null, val useAllNetworkNodes: Boolean = false, val dryRun: Boolean = false, val useTimeWindowNarrowing: Boolean = true, val verboseLogging: Boolean = false, val recoveryBatchSize: Int = 1000, val alsoFinalize: Boolean = false)

LedgerRecoveryResult

data class LedgerRecoveryResult(val totalRecoveredRecords: Long, val totalRecoveredTransactions: Long, val totalRecoveredInFlightTransactions: Long, val totalErrors: Long)

MaybeSerializedSignedTransaction

class MaybeSerializedSignedTransaction(val id: SecureHash, val serialized: SerializedBytes<SignedTransaction>?, val nonSerialised: SignedTransaction?, val inFlight: Boolean) : NamedByHash

In the words of Matt working code is more important then pretty code. This class that contains code that may be serialized. If it were always serialized then the local disk fetch would need to serialize then de-serialize which wastes time. However over the wire we get batch fetch items serialized. This is because we need to get the exact length of the objects to pack them into the 10MB max message size buffer. We do not want to serialize them multiple times so it's a lot more efficient to send the byte stream.

NotarisationPayload

data class NotarisationPayload(val transaction: Any, val requestSignature: NotarisationRequestSignature)

Container for the transaction and notarisation request signature. This is the payload that gets sent by a client to a notary service for committing the input states of the transaction.

NotarisationRequest

class NotarisationRequest(statesToConsume: List<StateRef>, val transactionId: SecureHash)

A notarisation request specifies a list of states to consume and the id of the consuming transaction. Its primary purpose is for notarisation traceability – a signature over the notarisation request, NotarisationRequestSignature, allows a notary to prove that a certain party requested the consumption of a particular state.

NotarisationRequestSignature

data class NotarisationRequestSignature(val digitalSignature: DigitalSignature.WithKey, val platformVersion: Int)

A wrapper around a digital signature used for notarisation requests.

NotarisationResponse

data class NotarisationResponse(val signatures: List<TransactionSignature>)

Payload returned by the notary service flow to the client.

NotaryChangeFlow

@InitiatingFlow

class NotaryChangeFlow<out T : ContractState>(originalState: StateAndRef<T>, newNotary: Party, progressTracker: ProgressTracker = AbstractStateReplacementFlow.Instigator.tracker()) : AbstractStateReplacementFlow.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

Specifies the cause for notarisation request failure.

NotaryException

class NotaryException(val error: NotaryError, val txId: SecureHash? = null) : FlowException

Exception thrown by the notary service if any issues are encountered while trying to commit a transaction. The underlying error specifies the cause of failure.

NotaryFlow

class NotaryFlow

NotarySigCheck

object NotarySigCheck

ReceiveFinalityFlow

class ReceiveFinalityFlow(otherSideSession: FlowSession, expectedTxId: SecureHash? = null, statesToRecord: StatesToRecord = ONLY_RELEVANT, handlePropagatedNotaryError: Boolean? = null) : FlowLogic<SignedTransaction>

The receiving counterpart to FinalityFlow.

ReceiverDistributionRecord

data class ReceiverDistributionRecord(val txId: SecureHash, val peerPartyId: SecureHash, val timestamp: Instant, val timestampDiscriminator: Int, val encryptedDistributionList: OpaqueBytes, val receiverStatesToRecord: StatesToRecord) : DistributionRecord

ReceiveStateAndRefFlow

class ReceiveStateAndRefFlow<out T : ContractState>(otherSideSession: FlowSession) : FlowLogic<List<StateAndRef<T>>>

The ReceiveStateAndRefFlow should be called in response to the SendStateAndRefFlow.

ReceiveTransactionFlow

open class ReceiveTransactionFlow(otherSideSession: FlowSession, checkSufficientSignatures: Boolean = true, statesToRecord: StatesToRecord = StatesToRecord.NONE, handlePropagatedNotaryError: Boolean? = null) : FlowLogic<SignedTransaction>

The ReceiveTransactionFlow should be called in response to the SendTransactionFlow.

RecoveryTimeWindow

data class RecoveryTimeWindow(val fromTime: Instant, val untilTime: Instant = Instant.now())

ResultSerializationException

class ResultSerializationException : CordaRuntimeException

Thrown whenever a flow result cannot be serialized when attempting to save it in the database

SchedulableFlow

@Target(allowedTargets = [AnnotationTarget.CLASS])

@Inherited

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.

SenderDistributionRecord

data class SenderDistributionRecord(val txId: SecureHash, val peerPartyId: SecureHash, val timestamp: Instant, val timestampDiscriminator: Int, val senderStatesToRecord: StatesToRecord, val receiverStatesToRecord: StatesToRecord) : DistributionRecord

SendStateAndRefFlow

open class SendStateAndRefFlow(otherSideSession: FlowSession, stateAndRefs: List<StateAndRef<*>>) : 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(val stx: SignedTransaction, val participantSessions: Set<FlowSession>, val observerSessions: Set<FlowSession>, val senderStatesToRecord: StatesToRecord, recordMetaDataEvenIfNotFullySigned: Boolean = false) : 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.

SignedTransactionWithDistributionList

data class SignedTransactionWithDistributionList(val stx: SignedTransaction, val distributionList: ByteArray, val isFinality: Boolean)

SignTransactionFlow

abstract class SignTransactionFlow constructor(val otherSideSession: FlowSession, val progressTracker: ProgressTracker = tracker()) : 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(val className: String)

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.

StartableByRPC

@Target(allowedTargets = [AnnotationTarget.CLASS])

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.

StartableByService

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class StartableByService

Any FlowLogic which is to be started by the AppServiceHub interface from within a CordaService must have this annotation. If it's missing the flow will not be allowed to start and an exception will be thrown.

StateConsumptionDetails

data class StateConsumptionDetails(val hashOfTransactionId: SecureHash, val type: StateConsumptionDetails.ConsumedStateType)

Contains information about the consuming transaction for a particular state.

StateMachineRunId

data class StateMachineRunId(val uuid: UUID)

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.

StateReplacementException

open class StateReplacementException constructor(message: String? = null, cause: Throwable? = null) : FlowException

TransactionMetadata

data class TransactionMetadata(val initiator: CordaX500Name, val distributionList: DistributionList)

UnexpectedFlowEndException

class UnexpectedFlowEndException(message: String, cause: Throwable?, val originalErrorId: Long?) : 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.

WaitTimeUpdate

data class WaitTimeUpdate(val waitTime: Duration)

Sent by the notary when the notary detects it will unlikely respond before the client retries.

WithReferencedStatesFlow

class WithReferencedStatesFlow<T : Any> constructor(val progressTracker: ProgressTracker = tracker(), flowLogicProducer: () -> FlowLogic<T>) : FlowLogic<T>

Given a flow which uses reference states, the WithReferencedStatesFlow will execute the flow as a subFlow. If the flow fails due to a NotaryError.Conflict for a reference state, then WithReferencedStatesFlow will be suspended until the state refs for the reference states are consumed. In this case, a consumption means that: