Docs & rules

bloxbean/cardano-client-libGitHub

This is a public, read-only report. Striff reads this repository's docs, turns each sentence that makes a claim about the code into a rule, and checks the rule against the code on the default branch. How this works

master25568f1Last read Oct 3

Is this yours? Install to manage it

Once installed, Striff checks every pull request.

Rules summary
Documents
Rules
181
32
21
21
11
1
2
7
11
11
23
23
23
23
22
1
120
30
6
14
10
88
7
7
17
15
12
37
2
3
1
1
2
2
3
30 docs
bloxbean/cardano-client-libOpen repository

bloxbean/cardano-client-lib — documented rules

181 of 181 rules, printed November 17, 2026.

The sentence in your docs
ADR 0015, Title DataType Processor Strategy, Summary DataTypeProcessor interface with 10 implementations, EnumMap -based dispatch
DataTypeProcessor is a contract
Holds
ADR 0003, Title Shared Blueprint Type Registry, Summary BlueprintTypeRegistry SPI, SchemaSignatureBuilder , structural matching, AikenBlueprintTypeRegistry
BlueprintTypeRegistry is a contract
Holds
ADR 0012, Title RawData Interface and FieldType Flags, Summary Data<T> / RawData marker interfaces, FieldType encoding flags
2 rules from this sentence
Data is a contract
Holds
RawData is a contract
Holds
ADR 0011, Title Multi-Item Tuple Support, Summary SchemaTypeResolver maps list schemas to Pair/Triple/Quartet/Quintet (2–5 items)
3 rules from this sentence
SchemaTypeResolver depends on Pair
Holds
SchemaTypeResolver depends on Quartet
Holds
SchemaTypeResolver depends on Quintet
Holds
ADR 0018, Title Converter Code Generator Decomposition, Summary FieldCodeGenerator strategy interface, FieldCodeGeneratorRegistry dispatch, TupleInfo -parameterized tuple generation
FieldCodeGenerator is a contract
Holds
ADR 0010, Title Validator Name Collision Resolution, Summary ValidatorProcessor.calculateValidatorName() , skip-first-token strategy
ValidatorProcessor has a calculateValidatorName method
Holds
Term SharedTypeLookup, Definition The interface through which the processor queries the shared type registry before generating a class
SharedTypeLookup is a contract
Holds
Term TupleInfo, Definition An enum parameterizing Pair/Triple/Quartet/Quintet by arity, class reference, and accessor names to eliminate tuple code duplication
TupleInfo is an enumeration
Holds
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.
BlueprintTypeRegistry is a contract
Holds
The context flows from BlueprintAnnotationProcessor through FieldSpecProcessor, ValidatorProcessor, and DataTypeProcessUtil to every registry lookup call.
BlueprintAnnotationProcessor depends on FieldSpecProcessor
Holds
LookupContext.EMPTY provides a no-hints fallback.
LookupContext has EMPTY
Holds
The registry also exposes dispatchNestedSerialization() and dispatchNestedDeserialization() methods that composite generators call to recursively process their element types.
2 rules from this sentence
FieldCodeGeneratorRegistry has a dispatchNestedSerialization method
Holds
FieldCodeGeneratorRegistry has a dispatchNestedDeserialization method
Holds
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
ClassConverterBuilder depends on SerDeMethodBuilder
Holds
TupleCodeGenerator generates serialization/deserialization code for any arity by looping over TupleInfo.accessors:
TupleCodeGenerator depends on TupleInfo
Holds
ElementCodeGenerator is a @FunctionalInterface that the registry provides as a callback:
ElementCodeGenerator is annotated with FunctionalInterface
Holds
Generator TupleFieldCodeGen, Types PAIR, TRIPLE, QUARTET, QUINTET, Parameterization TupleInfo enum + TupleCodeGenerator for arity-agnostic loops
2 rules from this sentence
TupleFieldCodeGen depends on TupleInfo
Holds
TupleFieldCodeGen depends on TupleCodeGenerator
Holds
Extender LockUnlockValidatorExtender, Provides deploy() , lock() , unlock() , unlockToAddress() , unlockToContract()
5 rules from this sentence
LockUnlockValidatorExtender has a deploy method
Holds
LockUnlockValidatorExtender has a lock method
Holds
LockUnlockValidatorExtender has an unlock method
Holds
LockUnlockValidatorExtender has an unlockToAddress method
Holds
LockUnlockValidatorExtender has an unlockToContract method
Holds
Extender MintValidatorExtender, Provides deploy() , mint() , mintToAddress() , mintToContract() , getPolicyId()
5 rules from this sentence
MintValidatorExtender has a deploy method
Holds
MintValidatorExtender has a mint method
Holds
MintValidatorExtender has a mintToAddress method
Holds
MintValidatorExtender has a mintToContract method
Holds
MintValidatorExtender has a getPolicyId method
Holds
Extender DeployValidatorExtender, Provides deploy() only
DeployValidatorExtender has a deploy method
Holds
The compatibility method RetryPolicy.isRetryable(Throwable) has no phase information.
RetryPolicy has an isRetryable method
Holds
FlowExecutionHandle.await() returns a FlowExecutionResult for every normal terminal outcome.
2 rules from this sentence
FlowExecutionHandle depends on FlowExecutionResult
Holds
FlowExecutionHandle has an await method
Holds
Accessor executionId(), Meaning Request correlation and durable lookup identity
FlowExecutionHandle has an executionId method
Holds
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.
FlowError has a category method
Holds
FlowError.code() is the stable, specific value for program logic.
FlowError has a code method
Holds
retryable() is advisory context, not permission to submit a replacement transaction.
FlowError has a retryable method
Holds
Calling getEventsAfter(cursor) again returns only newer handle events.
FlowExecutionHandle has a getEventsAfter method
Holds
With a durable store, use FlowExecutionStore.readEvents(executionId, cursor, limit) for restart-safe consumption.
FlowExecutionStore has a readEvents method
Holds
FlowListener is configured with FlowExecutor.withListener(...);
2 rules from this sentence
FlowExecutor depends on FlowListener
Holds
FlowExecutor has a withListener method
Holds
Likewise, FlowRegistry tracks legacy FlowHandle instances.
FlowRegistry depends on FlowHandle
Holds
The boolean cancel() method is shorthand for a reasonless request and returns true only for the first accepted signal.
FlowExecutionHandle has a cancel method
Holds
FlowRecoveryResult reports the reconciled AttemptState, transaction hash, whether this call resubmitted the identical payload, an optional structured error, and newly observed inclusion metadata.
3 rules from this sentence
FlowRecoveryResult depends on AttemptState
Holds
FlowRecoveryResult has transactionHash
Holds
FlowRecoveryResult has error
Holds
PlutusBlueprintUtil.getPlutusScriptFromCompiledCode applies the double-CBOR wrapping CCL's PlutusScript.cborHex expects — pass the blueprint hex as-is, never pre-wrap it yourself.
PlutusBlueprintUtil has getPlutusScriptFromCompiledCode
Holds
The utxo selection strategy can be changed by providing a custom implementation of UtxoSelectionStrategy interface.
UtxoSelectionStrategy is a contract
Holds
LargestFirstUtxoSelectionStrategy
LargestFirstUtxoSelectionStrategy implements UtxoSelectionStrategy
Holds
RandomImproveUtxoSelectionStrategy
RandomImproveUtxoSelectionStrategy implements UtxoSelectionStrategy
Holds
Existing API TxFlow.fromYaml(yaml), Migration target TxFlowCodec.parse(...), Compatibility action Keep as legacy convenience delegate
TxFlow has a fromYaml method
Holds
Existing API flow.toYaml(), Migration target TxFlowCodec.write(...), Compatibility action Keep, but fail on semantic loss
TxFlow has a toYaml method
Holds
Existing API StepDependency.filter(...Predicate...), Migration target FlowOutputSelector / UtxoFilterSpec, Compatibility action Keep for Java-only flows reject portable encoding
StepDependency has a filter method
Holds
Existing API FlowExecutor.create(...).with, Migration target immutable FlowEngine.builder(), Compatibility action Keep through adapter/deprecation window
FlowExecutor has a create method
Holds
Existing API executor.execute(flow), Migration target engine.start(FlowExecutionRequest), Compatibility action Generate execution ID for legacy call
FlowExecutor has an execute method
Holds
Existing API executor.resume(flow, previousResult), Migration target engine.recover(FlowRecoveryRequest), Compatibility action Retain current best-effort result resume separately
FlowExecutor has a resume method
Holds
submit(item) → receipt with a CompletionStage, try-with-resources lifecycle, and progressive disclosure for advanced use.
TxFlowStream has a submit method
Holds
TxWorkItem.idempotencyKey is carried but never consumed: redelivery from any real source produces duplicate on-chain transactions.
TxWorkItem has idempotencyKey
Holds
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.
FlowEngine has a handleForStoredSnapshot method
Holds
The stream no longer constructs or wraps a FlowExecutor.
TxFlowStream may not depend on FlowExecutor
Holds
FlowRuntime owns one ordinary engine and the resources it creates;
FlowRuntime depends on FlowEngine
Holds
TxFlowStream still delegates every execution to that engine:
TxFlowStream depends on FlowEngine
Holds
Each planned flow is submitted as a FlowExecutionRequest via FlowEngine.start(...);
2 rules from this sentence
FlowEngine depends on FlowExecutionRequest
Holds
FlowEngine has a start method
Holds
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.
FlowExecutionRequest has executionId
Holds
TxStreamReceipt exposes completion() (CompletionStage<TxStreamItemResult>), executionId(), and an event cursor.
2 rules from this sentence
TxStreamReceipt has a completion method
Holds
TxStreamReceipt has an executionId method
Holds
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.
TxFlowStream depends on TxPlan
Holds
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 has a single method
Holds
LanePolicy.explicit() with dynamic LaneIdentityResolver resolution and multiple concurrent lanes (alias-sharing and overlap validation per Decision 2).
LanePolicy has an explicit method
Holds
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;
FlowRuntime depends on FlowEngine
Holds
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.
FlowRuntime depends on TxFlowStream
Holds
txflow already has an API dependency on backend, and FlowExecutor.create(BackendService) already establishes the standard mapping.
FlowExecutor has a create method
Holds
Add a public TxStreamCodes constants class covering codes emitted by the core txflow module.
TxStreamCodes is exported
Holds
TxStreamException.getCode() remains supported.
TxStreamException has a getCode method
Holds
runtime.engine() returns that exact underlying instance;
FlowRuntime has an engine method
Holds
runtime.open(streamId) builds an ordinary TxFlowStream against the same engine.
FlowRuntime has an open method
Holds
graceful close() drains without a default timeout, while close(Duration) bounds the wait.
FlowRuntime has a close method
Holds
runtime.open(...) is the discoverable first-hour path and static/builder TxFlowStream.open(...) serves application-owned engines.
TxFlowStream has an open method
Holds
trySubmit already provides a non-throwing outcome surface.
EngineTxFlowStream has trySubmit
Holds
TxFlow.validate() checks for:
TxFlow has a validate method
Holds
Validation runs automatically before execution (executeSync / execute).
2 rules from this sentence
FlowExecutor has executeSync
Holds
FlowExecutor has execute
Holds
Strategy FILTER, Description Outputs matching a predicate, Factory Method StepDependency.filter("stepId", predicate)
StepDependency has a filter method
Holds
On restart, the executor calls findStillConfirmedSteps() to identify which transactions are still on-chain, then skips those steps during re-execution.
FlowExecutor has a findStillConfirmedSteps method
Holds
Method getStatus(), Description Current FlowStatus (PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED)
FlowHandle has a getStatus method
Holds
Method getCurrentStepId(), Description ID of the step currently executing
FlowHandle has a getCurrentStepId method
Holds
Method getCompletedStepCount(), Description Number of completed steps
FlowHandle has a getCompletedStepCount method
Holds
Method getTotalStepCount(), Description Total number of steps
FlowHandle has a getTotalStepCount method
Holds
Method isRunning(), Description True if status is IN_PROGRESS
FlowHandle has an isRunning method
Holds
Method isDone(), Description True if the underlying future is complete
FlowHandle has an isDone method
Holds
Method await(), Description Block until complete, return FlowResult
FlowHandle has an await method
Holds
Method getResult(), Description Non-blocking get result if available
FlowHandle has a getResult method
Holds
Method getResultFuture(), Description Access the underlying CompletableFuture
FlowHandle has a getResultFuture method
Holds
Method cancel(), Description Request cancellation (in-progress steps cannot be undone)
FlowHandle has a cancel method
Holds
A no-op implementation (FlowStateStore.NOOP) is available for testing.
FlowStateStore has NOOP
Holds
For crash-safe execution, use FlowEngine with a FlowExecutionStore.
FlowEngine depends on FlowExecutionStore
Holds
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).
FlowStepResult has a submissionPendingAt method
Holds
The legacy FlowResult is then FAILED with an empty getFailedStep(), and listeners receive onStepUncertain/onFlowUncertain instead of the failed callbacks.
3 rules from this sentence
FlowListener has onStepUncertain
Holds
FlowListener has onFlowUncertain
Holds
FlowResult has a getFailedStep method
Holds
Method getStatus(), Returns FlowStatus, Description Current PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED
FlowHandle has a getStatus method
Holds
Method getCurrentStepId(), Returns Optional<String>, Description Step currently being executed
FlowHandle has a getCurrentStepId method
Holds
Method getCompletedStepCount(), Returns int, Description Number of steps finished
FlowHandle has a getCompletedStepCount method
Holds
Method getTotalStepCount(), Returns int, Description Total steps in the flow
FlowHandle has a getTotalStepCount method
Holds
Method isRunning(), Returns boolean, Description True if status == IN_PROGRESS
FlowHandle has an isRunning method
Holds
Method isDone(), Returns boolean, Description True if future is complete
FlowHandle has an isDone method
Holds
Method await(), Returns FlowResult, Description Block until complete Method await(timeout), Returns FlowResult, Description Block with timeout
FlowHandle has an await method
Holds
Method getResult(), Returns Optional<FlowResult>, Description Non-blocking empty if still running
FlowHandle has a getResult method
Holds
Method getResultFuture(), Returns CompletableFuture<FlowResult>, Description Underlying future
FlowHandle has a getResultFuture method
Holds
Method cancel(), Returns boolean, Description Request cancellation
FlowHandle has a cancel method
Holds
Listeners are wrapped in CompositeFlowListener which catches and logs exceptions from individual listeners, preventing buggy callbacks from crashing flow execution.
CompositeFlowListener depends on FlowListener
Holds
S->>St: registerItem(record) fail-closed, BEFORE planning
TxFlowStream depends on TxStreamStateStore
Holds
S->>E: start(request) with claim-derived executionId
TxFlowStream depends on FlowEngine
Holds
E->>X: execute flow
FlowEngine depends on FlowExecutor
Holds
Path stream/TxFlowStream.java, Role Public interface + builder
2 rules from this sentence
TxFlowStream is a contract
Holds
TxFlowStream is exported
Holds
Path stream/EngineTxFlowStream.java, Role Implementation (~5,146 lines)
EngineTxFlowStream is a concrete implementation
Holds
Path stream/TxStreamStateStore.java + in-memory impls, Role Stream-side persistence SPI
TxStreamStateStore is a contract
Holds
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.
ExecutionJournalSession has a record method
Holds
FlowEngine wraps it with everything needed to make execution safe to retry and safe to crash:
FlowEngine depends on FlowExecutor
Holds
File (under txflow/src/main/java/.../txflow/ ) exec/FlowEngine.java, Role start() / executeSync() / preflight() / recover() claim + lease + journal orchestration state mapping
4 rules from this sentence
FlowEngine has a start method
Holds
FlowEngine has an executeSync method
Holds
FlowEngine has a preflight method
Holds
FlowEngine has a recover method
Holds
File (under txflow/src/main/java/.../txflow/ ) exec/DurableLeaseGuard.java, Role Acquires/renews execution + resource leases exposes fence() , checkHealthy() , hasFailed()
3 rules from this sentence
DurableLeaseGuard has a fence method
Holds
DurableLeaseGuard has a checkHealthy method
Holds
DurableLeaseGuard has a hasFailed method
Holds
File (under txflow/src/main/java/.../txflow/ ) exec/DurableExecutionPersistence.java, Role PersistencePort implementation persists the AttemptState lifecycle + transaction journal events under the fence
DurableExecutionPersistence implements PersistencePort
Holds
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.
DurableLeaseGuard depends on MutationFence
Holds
persist(state, dataMutation) — flushes buffered events + the snapshot mutation in one fenced append.
ExecutionJournalSession has a persist method
Holds
Path stream/TxFlowStream.java, Role Public interface + Builder Lifecycle start() , reattach() , bootstrap() , submit() , trySubmit() , cancelItem() , getItemStatus() , reconcile() , drain()
9 rules from this sentence
TxFlowStream has a start method
Holds
TxFlowStream has a reattach method
Holds
TxFlowStream has a bootstrap method
Holds
TxFlowStream has a submit method
Holds
TxFlowStream has a trySubmit method
Holds
TxFlowStream has a cancelItem method
Holds
TxFlowStream has a getItemStatus method
Holds
TxFlowStream has a reconcile method
Holds
TxFlowStream has a drain method
Holds
Path stream/TxStreamPlanner.java , BuiltInPlanners.java, Role Planner SPI + perItem() / perWindow() / planner-local perWindow(PIPELINED) / batching()
3 rules from this sentence
TxStreamPlanner has a perItem method
Holds
TxStreamPlanner has a perWindow method
Holds
TxStreamPlanner has a batching method
Holds
Path stream/WindowPolicy.java, Role Window close rules count(n) , time(d) , countOrTime(n, d)
3 rules from this sentence
WindowPolicy has a count method
Holds
WindowPolicy has a time method
Holds
WindowPolicy has a countOrTime method
Holds
Path exec/FlowEngine.java, Role Durable engine start(request) , recover(request)
2 rules from this sentence
FlowEngine has a start method
Holds
FlowEngine has a recover method
Holds
Path exec/FlowExecutor.java, Role Chaining-mode execution (SEQUENTIAL / PIPELINED / BATCH), rollback handling, uncertain-disposition settlement, legacy resumeSync / resume
2 rules from this sentence
FlowExecutor has resumeSync
Holds
FlowExecutor has resume
Holds
S->>St: registerItem(record) — authoritative, BEFORE receipt publication
EngineTxFlowStream depends on TxStreamStateStore
Holds
E->>X: execute flow
FlowEngine depends on FlowExecutor
Holds
FlowEventType events (EXECUTION_STARTED, TRANSACTION_SUBMITTED, TRANSACTION_CONFIRMED, STEP_COMPLETED, …, RECOVERY_REQUIRED) recorded via ExecutionJournalSession before effects are acknowledged.
5 rules from this sentence
FlowEventType has EXECUTION_STARTED
Holds
FlowEventType has TRANSACTION_SUBMITTED
Holds
FlowEventType has TRANSACTION_CONFIRMED
Holds
FlowEventType has STEP_COMPLETED
Holds
FlowEventType has RECOVERY_REQUIRED
Holds
confirmation via ConfirmationTracker (which needs TransactionObservationCapabilities .supportsAuthoritativeAbsence() to distinguish "not seen yet" from "authoritatively absent" for rollback detection).
2 rules from this sentence
ConfirmationTracker depends on TransactionObservationCapabilities
Holds
TransactionObservationCapabilities has a supportsAuthoritativeAbsence method
Holds
onExecutionComplete(execution, result, failure):
EngineTxFlowStream has an onExecutionComplete method
Holds
Otherwise each member is mapped by memberTerminalStatus(stepResult, flowState) (per-member, step result takes precedence) or templateFlowStatus(flowState) (template items, flow-level):
2 rules from this sentence
EngineTxFlowStream has a memberTerminalStatus method
Holds
EngineTxFlowStream has a templateFlowStatus method
Holds
Template projection first checks step and durable-attempt evidence through templateTerminalStatus / templateSnapshotStatus: a CANCELLED flow with any submitted-but-undecided transaction projects RECOVERY_REQUIRED.
2 rules from this sentence
EngineTxFlowStream has templateTerminalStatus
Holds
EngineTxFlowStream has templateSnapshotStatus
Holds
All projection writes funnel through project(state, target, mutator, …), which enforces monotonic advancement and store persistence.
EngineTxFlowStream has a project method
Holds
FlowExecutor.isUncertainDisposition(confirmation) checks both.
FlowExecutor has an isUncertainDisposition method
Holds
The FlowExecutor settlement sites preserve the captured outputs > of the submitted transaction, but StepRunner.uncertainFailure settles with an empty > list.
StepRunner has uncertainFailure
Holds
the cancel branch in FlowExecutor's terminal handling returns through cancelledFlowResult(...) before the step-terminal notification runs.
FlowExecutor has a cancelledFlowResult method
Holds
Area Definition graph, Package or module com.bloxbean.cardano.client.txflow, Owns TxFlow , FlowStep , legacy dependencies, retry value objects
2 rules from this sentence
TxFlow is in com.bloxbean.cardano.client.txflow
Holds
FlowStep is in com.bloxbean.cardano.client.txflow
Holds
NibblePath.EMPTY represents root path
NibblePath has EMPTY
Holds
Storage Abstraction - NodeStore interface for pluggable backends
NodeStore is a contract
Holds
Hash Functions - Generic HashFunction interface with Blake2b-256 implementation
HashFunction is a contract
Holds
181 rules from 19 docs

More open-source reports

Every report →

Other public repositories whose docs Striff read and checked against their code.