[FR] - Support Dijkstra guards in transaction building

[palas]

Support Dijkstra guards in transaction building

Related: #1291 (Dijkstra/Leios upstreaming), PR #1298.

What guards are

Dijkstra replaces the required-signers field with guards: an ordered set
of credentials in the tx body (same CBOR field, 14).

• Key-hash guard = that key must sign. Same effect as a required signer.
• Script-hash guard = that script must pass. This is new: a script that
  guards the whole transaction, with no fake-withdrawal trick.

The ledger side is released (cardano-ledger-dijkstra-0.3.0.0).

What cardano-api can do today

Only the key-hash half, and only indirectly (since PR #1298): building a
Dijkstra transaction turns TxExtraKeyWitnesses into key-hash guards, and
inspecting a body reports them back the same way.

There is no way to set a script-hash guard, and no way to see guards as
guards.

What needs doing

In the experimental API (the old one is deprecated):

1. Add a txGuards field to TxBodyContent (BodyContent/New.hs) and write
   it with guardsTxBodyL (from Cardano.Ledger.Api.Tx.Body) in
   makeUnsignedTx. Reject it for Conway.
2. Wire script witnesses for script-hash guards. The purpose plumbing already
   exists (GuardingScript, DijkstraGuarding); a guard script's redeemer
   index is its position in the guards set (see the ledger's
   getDijkstraScriptsNeeded).
3. Fees: count key-hash guards in key-witness estimation, and map
   DijkstraGuarding purposes in execution-units evaluation.
4. Report guards in tx-body inspection.

Out of scope (follow-up issues)

• requiredTopLevelGuards (body field 24, per-guard datums): only meaningful
  together with nested-transaction support, which cardano-api does not have.
• RequireGuard in SimpleScript: needs a new constructor and a JSON format
  decision. This is what blocks simple-script support in Dijkstra — it would
  unblock the four remaining TODO Dijkstra stubs: Experimental/AnyScript.hs
  ("Simple script not supported"), fromShelleyMultiSig and
  fromAllegraTimelock (both in Plutus/Internal/Script.hs), and
  txOutParseJson (BodyContent/New.hs — Dijkstra tx outs can carry
  reference scripts of the new native-script type, so parsing them needs it
  too).

Useful facts

• A key-hash guard is enforced exactly like a required signer: the ledger's
  getWitsVKeyNeeded demands those signatures (via reqSignerHashesTxBodyG).
• A transaction that demands a guard it does not carry fails UTXOW with
  MissingRequiredGuards.
• Guard order matters: it determines script-guard redeemer indices.