bloxbean/cardano-client-lib — documented rules

ADR [0015](0015-datatype-processor-strategy-pattern.md), Title DataType Processor Strategy, Summary DataTypeProcessor interface with 10 implementations, EnumMap -based dispatch

ADR [0003](0003-shared-blueprint-type-registry.md), Title Shared Blueprint Type Registry, Summary BlueprintTypeRegistry SPI, SchemaSignatureBuilder , structural matching, AikenBlueprintTypeRegistry

ADR [0012](0012-rawdata-interface-and-fieldtype-flags.md), Title RawData Interface and FieldType Flags, Summary Data<T> / RawData marker interfaces, FieldType encoding flags

ADR [0012](0012-rawdata-interface-and-fieldtype-flags.md), Title RawData Interface and FieldType Flags, Summary Data<T> / RawData marker interfaces, FieldType encoding flags

ADR [0011](0011-multi-item-tuple-support.md), Title Multi-Item Tuple Support, Summary SchemaTypeResolver maps list schemas to Pair/Triple/Quartet/Quintet (2–5 items)

ADR [0011](0011-multi-item-tuple-support.md), Title Multi-Item Tuple Support, Summary SchemaTypeResolver maps list schemas to Pair/Triple/Quartet/Quintet (2–5 items)

ADR [0011](0011-multi-item-tuple-support.md), Title Multi-Item Tuple Support, Summary SchemaTypeResolver maps list schemas to Pair/Triple/Quartet/Quintet (2–5 items)

ADR [0018](0018-converter-code-generator-decomposition.md), Title Converter Code Generator Decomposition, Summary FieldCodeGenerator strategy interface, FieldCodeGeneratorRegistry dispatch, TupleInfo -parameterized tuple generation

ADR [0010](0010-validator-name-collision-resolution.md), 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.

The registry also exposes dispatchNestedSerialization() and dispatchNestedDeserialization() methods that composite generators call to recursively process their element types.

The registry also exposes dispatchNestedSerialization() and dispatchNestedDeserialization() methods that composite generators call to recursively process their element types.

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:

Generator TupleFieldCodeGen, Types PAIR, TRIPLE, QUARTET, QUINTET, Parameterization TupleInfo enum + TupleCodeGenerator for arity-agnostic loops

Generator TupleFieldCodeGen, Types PAIR, TRIPLE, QUARTET, QUINTET, Parameterization TupleInfo enum + TupleCodeGenerator for arity-agnostic loops

Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()

Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()

Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()

Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()

Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()

Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()

Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()

Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()

Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()

Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()

Extender DeployValidatorExtender, Provides deploy() only

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

FlowExecutionHandle.await() returns a FlowExecutionResult for every normal terminal outcome.

FlowExecutionHandle.await() returns a FlowExecutionResult for every normal terminal outcome.

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.

FlowListener is configured with FlowExecutor.withListener(...);

FlowListener is configured with FlowExecutor.withListener(...);

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.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

Each FlowDiagnostic has a stable code, severity, message, JSONPath-like document path, optional source line/column, and optional step ID.

FlowRecoveryResult reports the reconciled AttemptState, transaction hash, whether this call resubmitted the identical payload, an optional structured error, and newly observed inclusion metadata.

FlowRecoveryResult reports the reconciled AttemptState, transaction hash, whether this call resubmitted the identical payload, an optional structured error, and newly observed inclusion metadata.

FlowRecoveryResult reports the reconciled AttemptState, transaction hash, whether this call resubmitted the identical payload, an optional structured error, and newly observed inclusion metadata.

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.

The stream no longer constructs or wraps a FlowExecutor.

FlowRuntime owns one ordinary engine and the resources it creates;

TxFlowStream still delegates every execution to that engine:

Each planned flow is submitted as a FlowExecutionRequest via FlowEngine.start(...);

Each planned flow is submitted as a FlowExecutionRequest via FlowEngine.start(...);

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

TxStreamReceipt exposes completion() (CompletionStage<TxStreamItemResult>), executionId(), and an event cursor.

TxStreamReceipt exposes completion() (CompletionStage<TxStreamItemResult>), executionId(), and an event cursor.

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;

This ADR introduces **progressive disclosure on the existing TxFlowStream type**: 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:

Validation runs automatically before execution (executeSync / execute).

Validation runs automatically before execution (executeSync / execute).

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

The legacy FlowResult is then FAILED with an **empty getFailedStep()**, and listeners receive onStepUncertain/onFlowUncertain instead of the failed callbacks.

The legacy FlowResult is then FAILED with an **empty getFailedStep()**, and listeners receive onStepUncertain/onFlowUncertain instead of the failed callbacks.

The legacy FlowResult is then FAILED with an **empty getFailedStep()**, and listeners receive onStepUncertain/onFlowUncertain instead of the failed callbacks.

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.

TxFlowStream depends on TxStreamStateStore

TxFlowStream depends on FlowEngine

FlowWorkSource depends on TxWorkSink

Path stream/TxFlowStream.java, Role Public interface + builder

Path stream/TxFlowStream.java, Role Public interface + builder

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

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

FlowEngine depends on FlowExecutor

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/FlowEngine.java, Role start() / executeSync() / preflight() / recover() claim + lease + journal orchestration state mapping

File (under txflow/src/main/java/.../txflow/ ) exec/FlowEngine.java, Role start() / executeSync() / preflight() / recover() claim + lease + journal orchestration state mapping

File (under txflow/src/main/java/.../txflow/ ) exec/FlowEngine.java, Role start() / executeSync() / preflight() / recover() claim + lease + journal orchestration state mapping

File (under txflow/src/main/java/.../txflow/ ) exec/FlowEngine.java, Role start() / executeSync() / preflight() / recover() claim + lease + journal orchestration state mapping

File (under txflow/src/main/java/.../txflow/ ) exec/DurableLeaseGuard.java, Role Acquires/renews execution + resource leases exposes fence() , checkHealthy() , hasFailed()

File (under txflow/src/main/java/.../txflow/ ) exec/DurableLeaseGuard.java, Role Acquires/renews execution + resource leases exposes fence() , checkHealthy() , hasFailed()

File (under txflow/src/main/java/.../txflow/ ) exec/DurableLeaseGuard.java, Role Acquires/renews execution + resource leases exposes fence() , checkHealthy() , hasFailed()

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.

ExecutionJournalSession has two operations with different guarantees:

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()

Path stream/TxStreamPlanner.java , BuiltInPlanners.java, Role Planner SPI + perItem() / perWindow() / planner-local perWindow(PIPELINED) / batching()

Path stream/TxStreamPlanner.java , BuiltInPlanners.java, Role Planner SPI + perItem() / perWindow() / planner-local perWindow(PIPELINED) / batching()

Path stream/TxStreamPlanner.java , BuiltInPlanners.java, Role Planner SPI + perItem() / perWindow() / planner-local perWindow(PIPELINED) / batching()

Path stream/WindowPolicy.java, Role Window close rules count(n) , time(d) , countOrTime(n, d)

Path stream/WindowPolicy.java, Role Window close rules count(n) , time(d) , countOrTime(n, d)

Path stream/WindowPolicy.java, Role Window close rules count(n) , time(d) , countOrTime(n, d)

Path exec/FlowEngine.java, Role Durable engine start(request) , recover(request)

Path exec/FlowEngine.java, Role Durable engine start(request) , recover(request)

Path exec/FlowExecutor.java, Role Chaining-mode execution (SEQUENTIAL / PIPELINED / BATCH), rollback handling, uncertain-disposition settlement, legacy resumeSync / resume

Path exec/FlowExecutor.java, Role Chaining-mode execution (SEQUENTIAL / PIPELINED / BATCH), rollback handling, uncertain-disposition settlement, legacy resumeSync / resume

EngineTxFlowStream depends on TxStreamStateStore

FlowEngine depends on FlowExecutor/StepRunner

FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.

FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.

FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.

FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.

FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.

confirmation via ConfirmationTracker (which needs TransactionObservationCapabilities .supportsAuthoritativeAbsence() to distinguish "not seen yet" from "authoritatively absent" for rollback detection).

confirmation via ConfirmationTracker (which needs TransactionObservationCapabilities .supportsAuthoritativeAbsence() to distinguish "not seen yet" from "authoritatively absent" for rollback detection).

onExecutionComplete(execution, result, failure):

Otherwise each member is mapped by **memberTerminalStatus(stepResult, flowState)** (per-member, step result takes precedence) or **templateFlowStatus(flowState)** (template items, flow-level):

Otherwise each member is mapped by **memberTerminalStatus(stepResult, flowState)** (per-member, step result takes precedence) or **templateFlowStatus(flowState)** (template items, flow-level):

Template projection first checks step and durable-attempt evidence through templateTerminalStatus / templateSnapshotStatus: a CANCELLED flow with any submitted-but-undecided transaction projects RECOVERY_REQUIRED.

Template projection first checks step and durable-attempt evidence through templateTerminalStatus / templateSnapshotStatus: a CANCELLED flow with any submitted-but-undecided transaction projects RECOVERY_REQUIRED.

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.

Area Definition graph, Package or module com.bloxbean.cardano.client.txflow, Owns TxFlow , FlowStep , legacy dependencies, retry value objects

Area Definition graph, Package or module com.bloxbean.cardano.client.txflow, Owns TxFlow , FlowStep , legacy dependencies, retry value objects

NibblePath.EMPTY represents root path

**Storage Abstraction** - NodeStore interface for pluggable backends

**Hash Functions** - Generic HashFunction interface with Blake2b-256 implementation