Investigate incorporating cquisitor-style local tx validation (phase 1 + phase 2) into cardano-cli

[Jimbo4350]

Context

There is currently no cardano-cli command to perform a local dry run of a signed transaction — i.e. run phase 1 and phase 2 validation against the current ledger state without actually submitting the tx to the network.

A community tool, cquisitor (built by Evgenii Lisitskii, a core contributor to cardano-serialization-lib), already does this:

• Webapp: https://cardananium.github.io/cquisitor/
• Repo: https://github.com/cardananium/cquisitor
• Stack: Rust + JavaScript
• Behaviour: paste a tx CBOR → runs phase 1 and phase 2 validation locally with enhanced failure feedback and a visual breakdown of the transaction structure.

Users repeatedly hit cryptic submission errors and resort to external tools like cquisitor to debug them. We should investigate folding equivalent functionality into cardano-cli directly.

Originating discussion: a user asked in Slack whether there is a dry-run command for tx submission to check phases 1 and 2 without submitting, and was directed to cquisitor as the answer.

Investigation tasks

• Review cquisitor's implementation to understand how it runs phase 1 and phase 2 validation locally (what ledger APIs / serialization libs it uses, how it sources protocol parameters and UTxO context).
• Identify the equivalent Haskell building blocks already available in cardano-api / cardano-ledger for running phase 1 (evaluateTransactionBalance, era-specific tx validation rules) and phase 2 (evaluateTransactionExecutionUnits, Plutus script evaluation with detailed traces).
• Determine what's missing in cardano-api to expose a clean "validate signed tx end-to-end against current ledger state" entry point.
• Decide whether validation should be done against a live node (via local-state-query) or fully offline with user-supplied protocol params + UTxO snapshot (or both).
• Propose a cardano-cli UX for the feature, e.g. cardano-cli <era> transaction validate --tx-file <signed.tx> that returns structured phase-1 / phase-2 results with rich error messages.
• Scope the work and open follow-up implementation issues.

Why this matters

• Better developer experience — users currently leave the cardano-cli toolchain to debug tx errors.
• Faster iteration on script-heavy transactions without burning collateral on failed submissions.
• A natural home for the rich error reporting that the ledger already produces but cardano-cli submit swallows.

[palas]

How does cquisitor do the validation of both stages locally?

First it looks at the transaction, it decides which on-chain info it needs, and then gets it from Koios (alternatively from Blockfrost, but some functionalities are disabled for Blockfrost).

It gets information including:

• input UTxOs
• dRep/pool/committee state
• governance actions
• protocol parameters
• current slot
• the treasury value

Dependencies

cquisitor uses the result of compiling to WASM cquisitor-lib which is written in Rust.

cquisitor-lib basically reimplements the ledger rules required, except for UPLC evaluation, for which it uses the evaluator from Aiken. cquisitor-lib, depends on some other Rust libraries, including:

• cardano-serialization-lib - For CBOR deserialization of Cardano types and for the types themselves
• pallas-{codec, traverse, primitives, crypto, addresses} - For cardano primitive manipulation
• uplc - Plutus UPLC evaluator from the Aiken project
• blst - For BLS12-381 cryptography
• cryptoxide - For Ed25519 signatures

It can be seen in the cargo file of cquisitor-lib: https://github.com/cardananium/cquisitor-lib/blob/main/Cargo.toml

Actual validation

Validated here: https://github.com/cardananium/cquisitor-lib/blob/main/src/validators/validator.rs#L427

Phase 2

Validated specifically here: https://github.com/cardananium/cquisitor-lib/blob/main/src/validators/phase_2/validation.rs#L15

[palas]

What equivalent building blocks do we have in cardano-api/cardano-ledger?

• For phase 2. We already have: evaluateTransactionExecutionUnits
• For phase 1. cardano-api could take advantage of applyTx from ledger and expose a new validateTx that works with phase 1 + phase 2. Or just phase 1. We'll need a way to differentiate between phase 1 or phase 2 errors.
  mkMempoolEnv -> mkMempoolState -> applyTx
• For hints, we would need to implement those, but they are not complicated to implement.

[palas]

Potential next steps

• We can implement online full transaction validation transaction validate (reuse applyTx and evaluateTransactionExecutionUnits).
  • We can separate phase 1 and phase 2 and run both even if phase 1 fails.
• We can add cquisitor-like hints.
• We can improve the way the validation errors are displayed, even make them JSON and classified by phase and type of error.

Offline vs Online

• I would start with online
• We already have phase 2 offline validation in cardano-cli
• We could add offline phase 1 validation, but it wouldn't be very practical for user to provide all the context.
  • We can do it progressive, validate only what is provided, but then we cannot just use applyTx, so it is more work.
    • There may be a hacky way of doing this using applyTx by providing some dummy state and translating the "this doesn't exist" errors to "this wasn't validated because we don't have enough on-chain info available"

[palas]

Scope for first step: #1380

[carbolymer]

Once validateTransactionPhase1 lands in cardano-api (per #1380), we could wire it into cardano-rpc's EvalTx to return phase 1 results alongside the phase 2 evaluation we already have.

Right now EvalTx evaluates scripts, computes the minimum fee, and checks the balance, but it doesn't run ledger rule validation (TTL, signatures, collateral, certificates, governance, etc.). The TxEval proto's errors field already accepts transaction-level errors (utxorpc/spec#202), so the proto wouldn't need changing.

Out of scope here - just noting it as a follow-on for when the cardano-api bits are in place.