Skip to content

tests: script contexts for scripts with several purposes - #274

Draft
Unisay wants to merge 4 commits into
mainfrom
yura/cape-tests-several-purposes
Draft

Unisay wants to merge 4 commits into
mainfrom
yura/cape-tests-several-purposes

Conversation

@Unisay

@Unisay Unisay commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

A cape-tests.json suite could only build a spending context at a placeholder script address, with an empty mint field, no redeemers and 64-byte transaction ids. This PR adds ten opt-in fields and patches, so a suite can describe a script that has a minting and a spending purpose, in a context the ledger could have built. A suite that does not use them builds the same bytes as before: the htlc and linear_vesting contexts are identical under the production and the preview evaluator.

Addition Effect
Patch set_script_info Switches the purpose to minting or rewarding and keeps the transaction, so one transaction can run under each purpose it triggers.
Patch set_mint Sets txInfoMint through the PlutusCore.Value path that buildValue takes: sorted, signed quantities, no ADA entry.
Patches set_fee, set_tx_id, set_redeemers Set txInfoFee, txInfoId and txInfoRedeemers.
address on add_input_utxo Places an input at any address.
reference_script on add_input_utxo and add_output_utxo Gives the UTXO a reference script hash.
staking in an address Adds a staking credential.
@reference in script_hash Resolves to the bytes of a B #hex value, as pubkey_hash already did.
# before the transaction id in utxo_ref Reads the id as hex, so 64 digits give 32 bytes.

Hash literals and transaction ids without # keep their old reading as raw ASCII bytes.

Three fixes touch the same files. The schema now matches the parser: only the spending baseline exists, and asset fields take B #hex literals. cape submission verify validates the scenario suite against that schema. The loader now reports the parse error of a shared script context; it used to say "not found".

measure also gets a --debug-trace option. The evaluator used to drop the messages of the trace builtin; with the option each test prints them, so a submitter can see which check of a validator rejects a transaction.

The ADR doc/adr/20261113-script-contexts-for-scripts-with-several-purposes.md records the decision and the rejected alternatives. Revision 2 of two_party_escrow for #272 needs these additions and follows in a separate PR.

A test suite could only build spending contexts at a placeholder script
address. Six additions, all opt-in, so the htlc and linear_vesting
contexts stay byte for byte the same:

- `set_script_info` switches a context to the minting or the rewarding
  purpose and keeps the transaction, so one transaction can be evaluated
  under each purpose it triggers.
- `set_mint` sets the mint field through the same PlutusCore.Value path
  as `buildValue`: sorted, signed quantities, no ADA entry.
- `add_input_utxo` takes an optional `address`.
- `script_hash` and `pubkey_hash` resolve an @reference to its bytes.
  A literal stays raw ASCII.
- An address takes an optional `staking` credential.
- A `utxo_ref` whose transaction id starts with `#` is hex.

Also: the schema now matches the parser (only the `spending` baseline
exists, asset fields take `B #hex` literals), `cape submission verify`
validates the scenario suite against it, and a shared script context
that fails to parse is no longer reported as "not found".
… and reference scripts

The builder left `txInfoFee` at 0, `txInfoRedeemers` empty and `txInfoId`
at a 64-byte placeholder, and every output had no reference script. A
validator that decodes the whole context pays for the redeemers map on
chain, so a context without it measures less than the ledger charges.

Four more opt-in additions:

- `set_fee` sets the transaction fee.
- `set_tx_id` sets the transaction id, in the two forms of `utxo_ref`.
- `set_redeemers` sets the redeemers of the transaction, in the given
  order. It is independent of `set_redeemer`, the redeemer of the script
  under test.
- `add_input_utxo` and `add_output_utxo` take an optional
  `reference_script` hash.
Records why the test format grows by patches on the one spending baseline instead of a second baseline, and what each of the ten additions does.
`measure` ran the CEK machine without an emitter, so the messages of the
`trace` builtin were lost. A submitter who debugs a failing test, or who
wants to see which check of a validator rejects a transaction, had to
rebuild the applied program for another evaluator.

With `--debug-trace` every test prints one `DEBUG_TRACE[<test>]: <message>`
line per log entry, in the order the program emitted them. The log also
holds the diagnostic of a builtin that fails, for example `unIData` on a
value that is not an integer; the machine does not mark which entry is
which. Without the option the machine runs as before, and the budget is
the same in both modes.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant