Cardano Updates

`OutputVRF` is small in size and is persisted in memory for some time,
since we keep around block headers for a while. In order to not
contribute to pinned memory fragmentation and not to retain unnecessary
bytes it is better to switch to unpinned `ByteArray` from pinned
`ByteString`

As it turns out `cborg` library whenever decoing `ByteString` it will
take a slice in constant time of the original large buffer that is
being fed to the decoder, while it can't do the same when decoding
`ByteArray#`. Concidering that for `PackedBytes` this intermediate
buffer is short lived, because it is only needed for packing operation,
it totally makes sense to not make a redundant copy of this buffer.

Co-authored-by: Copilot <[email protected]>

Also highlight that `getDatum` gets the datum of the spent output (look
up `txin` in the UTxO; if the output stores a datum hash, look it up in
`DataOf tx`). It's a spending-input datum lookup (not a reference-input
datum lookup).

1. Introduce subTx info type (using an alias for `TxInfo` for now).
2. Extend `TxInfo` with field `txInfoSubTxs : Maybe (List SubTxInfo)`.
3. Define a purpose-built builder:

   + Top-level Guard scripts ⇒ `txInfoSubTxs = just (...)`
   + Everything else ⇒ `txInfoSubTxs = nothing`
   + SubTx scripts ⇒ always `nothing` (even for `Guard` at sub level)

Co-authored-by: Copilot <[email protected]>

+  Remove contradiction between "ref inputs may refer to earlier tx outputs in the batch" vs "all inputs must exist before applying any tx in the batch." The new text punts the exact constraint to the UTxO rules (where it belongs).
+  Fix Plutus bullet (old "nor earlier versions" reads like "no Plutus at all").
+  Align fees with current Agda (`txFee : InTopLevel …`), but leave room for later CIP-driven updates.

* Add LEDGER stubs

* Add isTopLevelValid logic to SUBLEDGER

* Add skeleton for rules

* Fix parameters

* Fix conformance

---------

Co-authored-by: William DeMeo <[email protected]>

* Add helpers for grouping top-level guard requests

* Fix prose explaining CIP 118.

+  Remove contradiction between "ref inputs may refer to earlier tx outputs in the batch" vs "all inputs must exist before applying any tx in the batch." The new text punts the exact constraint to the UTxO rules (where it belongs).
+  Fix Plutus bullet (old "nor earlier versions" reads like "no Plutus at all").
+  Align fees with current Agda (`txFee : InTopLevel …`), but leave room for later CIP-driven updates.

* update CHANGELOG

* Update src/Ledger/Dijkstra/Specification/Transaction.lagda.md

Co-authored-by: Copilot <[email protected]>

* change txRequiredTopLevelGuards type from list to set

   agreeing with Carlos' observation/suggestion

* changed nomenclature

   Agreeing with Carlos' suggestion to avoid "request."

* convert code comments to (literate) documentation

* Add `requiredTopLevelGuardsSatisfied` predicate.

* Add initial versions of Utxo and Utxow modules

   + a minimal `UTXOS` rule as a stub/hook (so `UTXO` can call something),
   + a minimal `UTXO` rule with just the new phase-1 premise (plus an explicit "calls UTXOS"),
   + a minimal `UTXOW`; just a wrapper over `UTXO` for now.

* Make `ScriptPurpose.Guard` carry a `Credential`

   Key idea:

   +  Keep `txGuards` as a set **for now**.
   +  Define an ordered view `guardsList : List Credential` via `setToList`.
   +  Make `indexOfGuard` operate on that list.
   +  Let `rdptr` compute the `Ix` using `indexOfGuard`.

   For the "required top-level guards requested by subTxs" (i.e., `txRequiredTopLevelGuards` requests), we don't need a new ScriptPurpose constructor yet, because:

   +  phase-1 ensures those requested credentials are contained in top-level `txGuards`
   +  the later work (#1004 / #1006) will decide how to construct TxInfo / datum arguments for running those guard scripts batch-wide

---------

Co-authored-by: Copilot <[email protected]>

Signed-off-by: William Hankins <[email protected]>

# Conflicts:
#	modules/tx_unpacker/src/tx_unpacker.rs