bloxbean/cardano-client-lib — documented rules

The stream no longer constructs or wraps a FlowExecutor.

ADR 0015, Title DataType Processor Strategy, Summary DataTypeProcessor interface with 10 implementations, EnumMap -based dispatch

ADR 0003, Title Shared Blueprint Type Registry, Summary BlueprintTypeRegistry SPI, SchemaSignatureBuilder , structural matching, AikenBlueprintTypeRegistry

ADR 0018, Title Converter Code Generator Decomposition, Summary FieldCodeGenerator strategy interface, FieldCodeGeneratorRegistry dispatch, TupleInfo -parameterized tuple generation

ADR 0010, Title Validator Name Collision Resolution, Summary ValidatorProcessor.calculateValidatorName() , skip-first-token strategy

Term SharedTypeLookup, Definition The interface through which the processor queries the shared type registry before generating a class

Term TupleInfo, Definition An enum parameterizing Pair/Triple/Quartet/Quintet by arity, class reference, and accessor names to eliminate tuple code duplication

Define a BlueprintTypeRegistry SPI (service-provider interface) that can look up a RegisteredType (a decoupled value object with packageName and simpleName) for a given schema signature.

The context flows from BlueprintAnnotationProcessor through FieldSpecProcessor, ValidatorProcessor, and DataTypeProcessUtil to every registry lookup call.

LookupContext.EMPTY provides a no-hints fallback.

Each builder handles one SchemaClassification and produces a complete TypeSpec: Builder ClassConverterBuilder, Classification CLASS, Responsibility Iterates ClassDefinition.getFields() , delegates each field to the registry, assembles toPlutusData() and fromPlutusData() methods

TupleCodeGenerator generates serialization/deserialization code for any arity by looping over TupleInfo.accessors:

ElementCodeGenerator is a @FunctionalInterface that the registry provides as a callback:

Extender DeployValidatorExtender, Provides deploy() only

The compatibility method RetryPolicy.isRetryable(Throwable) has no phase information.

Accessor executionId(), Meaning Request correlation and durable lookup identity

FlowError.code() is the stable, specific value for program logic.

category() is a coarser dimension for metrics and routing: validation, policy, resource, build, sign, submission, network, backend unavailable, confirmation, rollback, persistence, recovery, cancellation, or internal.

retryable() is advisory context, not permission to submit a replacement transaction.

Calling getEventsAfter(cursor) again returns only newer handle events.

With a durable store, use FlowExecutionStore.readEvents(executionId, cursor, limit) for restart-safe consumption.

Likewise, FlowRegistry tracks legacy FlowHandle instances.

The boolean cancel() method is shorthand for a reasonless request and returns true only for the first accepted signal.

PlutusBlueprintUtil.getPlutusScriptFromCompiledCode applies the double-CBOR wrapping CCL's PlutusScript.cborHex expects — pass the blueprint hex as-is, never pre-wrap it yourself.

The utxo selection strategy can be changed by providing a custom implementation of UtxoSelectionStrategy interface.

LargestFirstUtxoSelectionStrategy

RandomImproveUtxoSelectionStrategy

Existing API TxFlow.fromYaml(yaml), Migration target TxFlowCodec.parse(...), Compatibility action Keep as legacy convenience delegate

Existing API flow.toYaml(), Migration target TxFlowCodec.write(...), Compatibility action Keep, but fail on semantic loss

Existing API StepDependency.filter(...Predicate...), Migration target FlowOutputSelector / UtxoFilterSpec, Compatibility action Keep for Java-only flows reject portable encoding

Existing API FlowExecutor.create(...).with, Migration target immutable FlowEngine.builder(), Compatibility action Keep through adapter/deprecation window

Existing API executor.execute(flow), Migration target engine.start(FlowExecutionRequest), Compatibility action Generate execution ID for legacy call

Existing API executor.resume(flow, previousResult), Migration target engine.recover(FlowRecoveryRequest), Compatibility action Retain current best-effort result resume separately

submit(item) → receipt with a CompletionStage, try-with-resources lifecycle, and progressive disclosure for advanced use.

TxWorkItem.idempotencyKey is carried but never consumed: redelivery from any real source produces duplicate on-chain transactions.

P2 — Projection read access (compaction-safe). handleForStoredSnapshot(...) (FlowEngine.java:480-499) returns a completed handle with an empty event list and no step results, so a MATCHED idempotent re-submit after a restart cannot be projected into a meaningful receipt.

FlowRuntime owns one ordinary engine and the resources it creates;

TxFlowStream still delegates every execution to that engine:

Deterministic execution identity (new in 0.3 — required so MATCHED and the write-ahead binding agree). FlowExecutionRequest.executionId defaults to a random UUID, so a redelivered request would carry a different execution id than the one the stream's write-ahead binding recorded — MATCHED would return the stored execution and the binding would point at an execution that never ran.

TxFlowStream v2 accepts only engine-compilable items — TxPlan-backed payloads and portable FlowSteps — and validates this eagerly at submit(), failing the item immediately with the portability diagnostic instead of poisoning a whole planned flow at compile time.

perItem() planner only — one flow per item, one statically configured lane (LanePolicy.single(ResolvedLane)) with mechanical funding-scope enforcement from day one, no custom planners yet.

LanePolicy.explicit() with dynamic LaneIdentityResolver resolution and multiple concurrent lanes (alias-sharing and overlap validation per Decision 2).

Despite its name, FlowRuntime is only an optional, explicit resource-owning composition boundary around the existing engine and stream. It creates and exposes a normal FlowEngine;

The decision does not create another transaction execution runtime or status machine, create threads inside FlowEngine or TxFlowStream, auto-enable unsafe batching or durability, hide uncertain outcomes, or weaken any funds-safety invariant established by ADRs 0002–0004. Despite its name, FlowRuntime is only an optional, explicit resource-owning composition boundary around the existing engine and stream.

txflow already has an API dependency on backend, and FlowExecutor.create(BackendService) already establishes the standard mapping.

Add a public TxStreamCodes constants class covering codes emitted by the core txflow module.

TxStreamException.getCode() remains supported.

runtime.engine() returns that exact underlying instance;

runtime.open(streamId) builds an ordinary TxFlowStream against the same engine.

graceful close() drains without a default timeout, while close(Duration) bounds the wait.

runtime.open(...) is the discoverable first-hour path and static/builder TxFlowStream.open(...) serves application-owned engines.

trySubmit already provides a non-throwing outcome surface.

TxFlow.validate() checks for:

Strategy FILTER, Description Outputs matching a predicate, Factory Method StepDependency.filter("stepId", predicate)

On restart, the executor calls findStillConfirmedSteps() to identify which transactions are still on-chain, then skips those steps during re-execution.

Method getStatus(), Description Current FlowStatus (PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED)

Method getCurrentStepId(), Description ID of the step currently executing

Method getCompletedStepCount(), Description Number of completed steps

Method getTotalStepCount(), Description Total number of steps

Method isRunning(), Description True if status is IN_PROGRESS

Method isDone(), Description True if the underlying future is complete

Method await(), Description Block until complete, return FlowResult

Method getResult(), Description Non-blocking get result if available

Method getResultFuture(), Description Access the underlying CompletableFuture

Method cancel(), Description Request cancellation (in-progress steps cannot be undone)

A no-op implementation (FlowStateStore.NOOP) is available for testing.

For crash-safe execution, use FlowEngine with a FlowExecutionStore.

For an uncertain disposition the step settles via FlowStepResult.submissionPendingAt(...) — status IN_PROGRESS with the hash retained — never FAILED (a FAILED verdict invites retrying a payment that can still land).

Method getStatus(), Returns FlowStatus, Description Current PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED

Method getCurrentStepId(), Returns Optional<String>, Description Step currently being executed

Method getCompletedStepCount(), Returns int, Description Number of steps finished

Method getTotalStepCount(), Returns int, Description Total steps in the flow

Method isRunning(), Returns boolean, Description True if status == IN_PROGRESS

Method isDone(), Returns boolean, Description True if future is complete

Method await(), Returns FlowResult, Description Block until complete Method await(timeout), Returns FlowResult, Description Block with timeout

Method getResult(), Returns Optional<FlowResult>, Description Non-blocking empty if still running

Method getResultFuture(), Returns CompletableFuture<FlowResult>, Description Underlying future

Method cancel(), Returns boolean, Description Request cancellation

Listeners are wrapped in CompositeFlowListener which catches and logs exceptions from individual listeners, preventing buggy callbacks from crashing flow execution.

S->>St: registerItem(record) fail-closed, BEFORE planning

S->>E: start(request) with claim-derived executionId

E->>X: execute flow

FWS -->|trySubmit| Sink[TxWorkSink]

Path stream/EngineTxFlowStream.java, Role Implementation (~5,146 lines)

Path stream/TxStreamStateStore.java + in-memory impls, Role Stream-side persistence SPI

ExecutionJournalSession has two operations with different guarantees: record(type, stepId, hash, data) — appends to the in-memory event list (visible on the handle immediately) and buffers for the next durable append.

FlowEngine wraps it with everything needed to make execution safe to retry and safe to crash:

File (under txflow/src/main/java/.../txflow/ ) exec/DurableExecutionPersistence.java, Role PersistencePort implementation persists the AttemptState lifecycle + transaction journal events under the fence

DurableLeaseGuard owns acquisition and background renewal (on the maintenance executor) for the execution lease and each resource lease, and produces the MutationFence — execution lease + all resource leases as one composite proof.

persist(state, dataMutation) — flushes buffered events + the snapshot mutation in one fenced append.

S->>St: registerItem(record) — authoritative, BEFORE receipt publication

E->>X: execute flow

onExecutionComplete(execution, result, failure):

All projection writes funnel through project(state, target, mutator, …), which enforces monotonic advancement and store persistence.

FlowExecutor.isUncertainDisposition(confirmation) checks both.

The FlowExecutor settlement sites preserve the captured outputs > of the submitted transaction, but StepRunner.uncertainFailure settles with an empty > list.

the cancel branch in FlowExecutor's terminal handling returns through cancelledFlowResult(...) before the step-terminal notification runs.

NibblePath.EMPTY represents root path

Storage Abstraction - NodeStore interface for pluggable backends

Hash Functions - Generic HashFunction interface with Blake2b-256 implementation