Skip to content

[vm-scalus] Implement and certify protocol-aware LedgerEvaluationTarget evaluation #74

Description

@satran004

Summary

Implement and verify the canonical protocol-aware evaluation API for the Scalus backend.

This is not a regression in the existing V3 compatibility API. The following path remains functional:

vm.setCostModelParams(values, PlutusLanguage.PLUTUS_V3, 11, 0);
vm.evaluate(program);

ScalusVmProvider retains both the custom MachineParams and MajorProtocolVersion(11), and the language-only evaluation path constructs PlutusVM.makePlutusV3VM(machineParams, protocolVersion). That path therefore supplies PV11 to Scalus when it has first been configured.

The gap is that Scalus does not override the newer canonical methods accepting LedgerEvaluationTarget. They inherit the default fail-closed implementation and throw UnsupportedOperationException:

vm.evaluate(program, LedgerEvaluationTarget.pv11(PlutusLanguage.PLUTUS_V3));

As a result, Scalus is currently excluded from the pinned cardano-node 11.0.1 parity claim even though its legacy configured V3 path can receive PV11.

Related umbrella: #65
ADR task: PV11-036 in ADR-029
Reference baseline: cardano-node 11.0.1 / Plutus 1.63.0.0 at f92b7d7d82622a26caf456a6be33859f697e2cfc

Current behavior

Path Current result
V3 language-only after setCostModelParams(..., V3, 11, ...) Uses the supplied model and PV11 in Scalus
V3 language-only without configuration Uses Scalus defaults; no JuLC ledger target is established
V1/V2 setCostModelParams Records the protocol version but ignores the supplied parameter array and uses Scalus built-in V1/V2 VMs
Any explicit LedgerEvaluationTarget evaluation Fails closed as unsupported

Why this matters

The explicit target API is the canonical ledger-validation path. It binds language and protocol semantics to each evaluation and prevents a call from silently relying on an unrelated or stale provider configuration. Java and Truffle already implement this contract and reject a configured cost model whose protocol semantics do not match the requested target.

Scalus should either provide the same verified contract for a profile or continue to fail closed for that profile. Merely accepting a protocol number is not enough for a node-parity claim; builtin availability, semantics, program validation, cost parameters, and resulting budgets must be verified together.

Proposed scope

  • Implement evaluate and evaluateWithArgs overloads accepting LedgerEvaluationTarget.
  • Bind the selected Scalus VM, protocol version, and configured cost model to the same requested target.
  • Reject mismatches between a configured model and the requested language/protocol major version.
  • Preserve the existing configured language-only V3 behavior for compatibility.
  • Define the exact V1/V2 behavior. Do not silently claim custom-cost support while Scalus uses built-in parameters.
  • Run a backend-specific versioned conformance and budget matrix against the pinned node 11.0.1 Plutus snapshot.
  • Document only the language/PV combinations proven by that matrix; continue failing closed elsewhere.
  • Update ADR-029, ADR-030, and ADR-029: PV11 ledger-conformant evaluation readiness tracker #65 when the supported matrix is established.

Acceptance criteria

  • Explicit V3/PV10 and V3/PV11 targets select the corresponding Scalus protocol semantics.
  • setCostModelParams(values, target) followed by explicit evaluation uses the matching supplied model.
  • A configured model/target mismatch fails deterministically before evaluation.
  • Both plain evaluation and evaluation with arguments have equivalent target handling.
  • PV-sensitive tests cover at least builtin availability, UPLC feature gating, case-on-builtin behavior, PV11 bounds, and semantics variants relevant to Scalus.
  • Exact budget comparisons pass for every profile included in the support claim against cardano-node 11.0.1 / Plutus commit f92b7d7d82622a26caf456a6be33859f697e2cfc.
  • V1/V2 custom-cost limitations are either resolved and tested or explicitly rejected/documented.
  • Existing language-only V3 configuration tests remain green.
  • The disabled or skip-heavy Scalus conformance coverage is replaced with an explicit, reviewable support matrix.
  • ADR-029/ADR-030 and the backend Javadocs state the final verified scope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions