Declarative Scenario Engine (TxPlan/TxFlow) — F11

[beanbot-gh]

Declarative Scenario Engine (TxPlan / TxFlow)

Make Yaci DevKit the execution, key-management, and debugging home for cardano-client-lib's declarative YAML transaction format. Today developers must build transactions imperatively to reach any non-trivial chain state; there's no way to describe a sequence of transactions once, commit it, and replay it to bring a fresh devnet to a known state.

cardano-client-lib 0.8.0-pre ships the missing language:

• TxPlan (cardano-client-quicktx) — declarative YAML for one or more transactions: payments, multi-asset, native + Plutus mint/spend, reference inputs, inline/hash datums (raw CBOR or structured PlutusData with @name), metadata, full staking lifecycle, and the complete Conway governance surface. ${...} variables; a SignerRegistry resolves account://… / policy://… refs so keys stay out of YAML.
• TxFlow (cardano-client-txflow) — multi-step orchestration over TxPlan: ordered steps with depends_on UTXO chaining, confirmation tracking, retry, and devnet-tuned rollback recovery (ConfirmationConfig.devnet()).

Both are pure Java libraries with no execution home, no CLI, no key management — exactly what Yaci already provides (it embeds the library, uses QuickTxBuilder, and manages 20 pre-funded accounts + a default minting policy).

Design ADR: adr/0013-declarative-scenario-engine.md. Roadmap context: adr/PRODUCT_ROADMAP.md (F11, #1 priority).

Goal

1. Take a TxPlan or TxFlow YAML and execute it against the running devnet.
2. Auto-wire a SignerRegistry from the 20 default accounts (account://acc0…account://acc19) + the default minting policy (policy://default) — scenario YAML needs no embedded keys.
3. API-first: one engine, consumed by REST + CLI + MCP (viewer later).
4. Seed a fresh devnet to a known state at create-node time.
5. Target state-determinism (identical resulting UTxO set / balances / datums across runs). Hash-determinism is out of scope for v1.

Scope (v1)

• Bump cardano-client-lib/-backend/-backend-blockfrost 0.7.2 → 0.8.0-pre4; add cardano-client-txflow:0.8.0-pre4.
• ScenarioService — single engine: detect TxPlan vs TxFlow, build SignerRegistry from default accounts + policy, obtain BackendService (reuse existing pattern), execute, return ScenarioResult (success + tx hashes + clear error).
• ScenarioController — POST /local-cluster/api/scenarios/run.
• CLI run-scenario --file <path.yaml>.
• MCP tool devnet_run_scenario(yaml) (enables AI-driven NL→YAML→run).
• create-node --seed <file.yaml> seeds the devnet after it's ready.
• Starter scenario library under examples/scenarios/ (payment, NFT mint, script lock, governance register→propose→vote, delegation) + determinism guidance README.

Out of scope (later milestones)

Viewer scenario panel + TxFlow DAG visualization, tx → YAML export, scripted reorg scenarios, assertion layer for test plans, JSON-Schema generation for AI authoring.

Acceptance criteria

• CLI builds against 0.8.0-pre4; existing tx flows still work.
• A payment, a Plutus mint, and a governance register→propose→vote scenario each execute from YAML and produce the expected on-chain state (verified via Yaci Store).
• create-node --seed brings up a devnet in the seeded state; re-running yields the same resulting state (state-deterministic).
• The MCP devnet_run_scenario tool works end-to-end.

Risks

• Preview dependency (0.8.0-pre4) — pinned; the feature is additive and isolated to ScenarioService.
• 0.7.2 → 0.8.0-pre4 bump may surface API changes in existing CLI tx code — bump and verify first.

All transaction semantics stay in cardano-client-lib; Yaci owns only thin wiring. Keep it simple and maintainable.

[beanbot-gh]

Update — core scenario engine (F11a) implemented, verified, and reviewed

The declarative scenario engine is implemented as an API-first layer: one ScenarioService consumed by REST, CLI, and MCP. All transaction semantics are delegated to cardano-client-lib; Yaci owns only thin wiring (signer registry + backend + I/O). Design: adr/0013-declarative-scenario-engine.md.

Done

• Dependency bump — cardano-client-lib/-backend/-backend-blockfrost 0.7.2 → 0.8.0-pre4; added cardano-client-txflow:0.8.0-pre4. Full build passes.
• Engine — ScenarioService auto-detects TxPlan vs TxFlow, builds a SignerRegistry from the 20 default accounts (account://acc0…acc19) + policy://default, runs against the devnet, returns ScenarioResult (success + tx hashes + clear error). TxFlow uses SEQUENTIAL chaining + ConfirmationConfig.devnet() for reproducible state.
• Surfaces — POST /local-cluster/api/scenarios/run; CLI run-scenario --file <yaml> (alias run); MCP tool devnet_run_scenario(yaml).
• Refactor — extracted shared LocalBackendServiceProvider (yaci-store / yano-only), reused by the engine and TestTransactionService.
• Examples — examples/scenarios/ (payment.yaml, flow-payment.yaml, README with signer-ref + determinism notes).
• Tests — unit tests for format detection, fail-fast on missing backend, and registry wiring.

Verified live (devnet + yaci-store)

• TxPlan payment (acc0 → acc1, 25 ADA): POST /scenarios/run → HTTP 200, success; tx indexed; receiver UTxO confirmed via Yaci Store.
• TxFlow payment (via FlowExecutor): → HTTP 200, success, tx hash returned.

Review

Reviewed by three agents (Cardano/cclib correctness, simplicity/conventions, requirements-validation). Incorporated: default the cluster name for REST/headless callers, return non-2xx on failure (consistent with sibling controllers), close FlowExecutor (try-with-resources), add the run alias. Confirmed policy://default key derivation is correct.

Deferred to follow-up (F11b)

• create-node --seed <file.yaml> (seed at devnet creation — needs yaci-store readiness orchestration).
• Richer scenario library (NFT mint via policy://default, script lock, governance register→propose→vote) + live verification of those paths.
• e2e-tests/ integration scenarios.