IntersectMBO / IntersectMBO/cardano-ledger

Better communication/clarity on phase-1 validation and serialization criteria

Open
#2,941 20 comments 6 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
295
Forks
179
Avg merge
4d 7h
Merged PRs (30d)
29

Description

# Overview

A perennial issue on a team I manage has been understanding what _exactly_ comprises phase-1 validation. I would like to see a clear, plain English listing of the criteria that must be satisfied by a script context or transaction in order to actually function on the main net.

Full disclaimer: I've not fully read the specs or the implementation myself and this issue is, in part, to request a resource to which I can direct developers to in lieu of a code-dive or spec-read.

## Current Understanding

The consensus among my coworkers is that:

- Phase-1 validation is "everything besides script execution" -- which is too vague to actually build off of.
- Phase-1 validation _is_ specified in the formal specifications -- which is too much of a deep dive
- Certain invariants/constraints are ensured by serialization, and these are neither explicitly specified nor readily apparent in the code base. These also appear to be defined on a `Tx` type rather than a `TxInfo`, meaning there's a lot of extra things that would be unsuitable for simply validating a `TxInfo` or `ScriptContext`.
- Alternate implementations (even if the behavior is technically "specification compliant") would be considered invalid by IO, meaning there may be some _de facto_ "standard" behavior that is not specified.

## Our use case

The reason for why we need this is to be able to construct script contexts in Haskell and know whether or not they are realistic to what we would see in practice. My understanding is that tools like `EmulatorTrace` have failed to perform this sufficiently -- failing to completely normalize `Value`s, for example. This leads to situations where developers are unsure whether they need to check for phase-1 validity in phase-2.

We would, in particular, like to be able to have a set of checks like `isValueNormalized`, `is transactionBalanced`, `areOutputsSorted`, and so forth, that we can combine into something that corresponds to `isPhase1Valid`. The final property should be that `isPhase1Valid` is true if and only if a given transaction/script context can

- A.) Be constructed _by the actual implementation_
- B.) Pass through to phase 2 validation

We'd be happy to write these if needed, but they would ideally be provided for us. It's insufficient to fully serialize a transaction using the various utilities available, because we _want_ to be able to define partially-invalid script contexts at certain stages in the development process, _but also understand which validation checks would fail_ on a given object.

Finally, we'd want to partially auto-generate script contexts, possibly exhaustively within certain bounds, so we'd want these checks to be _fast_. Full serialization would ostensibly be much slower than a pure `isPhase1Valid` function, and partial validation would certainly be faster than either if we only cared about a subset of checks.

## Ideal Outcome

- [ ] Detail exactly what checks are performed during phase-1 validation, in plain English, with back-references to implementation/spec if applicable, and add this to the "Ledger Explanations" webpage
- [ ] Detail exactly what invariants emerge during serialization, and to what extent these are considered mandatory -- i.e., whether alternate implementations _SHOULD_ or _MUST_ uphold these conditions -- and add this to the "Ledger Explanations".
- [ ] _If_ alternate implementations are _required_ to uphold these invariants and _if_ they are not listed in the formal spec, add them.
- [ ] Provide helper utilities and tests that developers can utilize to build libraries such as those described above
- [ ] Add these checks to `EmulatorTrace` and other IO utilities.
- [ ] Test these functions/findings against the actual implementation.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.