Datum for UTxOs locked at the cage script address.

The cage script can hold two types of UTxOs:

• State UTxOs (StateDatum): contain the caged NFT and its MPF root. There is exactly one State UTxO per caged token. It holds the NFT in its value and the current MPF root in its datum.
• Request UTxOs (RequestDatum): contain pending requests to modify a token’s MPF. These hold only ADA (no NFT). Multiple Request UTxOs can exist for the same caged token.

Dispatch Logic in the Spending Validator

The spending validator pattern-matches on the datum to determine which operations are valid:

• RequestDatum + Retract -> request owner reclaims request
• RequestDatum + Contribute(ref) -> validate request targets correct token
• StateDatum + Modify(proofs) -> fold requests into MPF
• StateDatum + End -> REFUSED (no owner role; no termination)
• mint Migrating / Burning, any Sweep -> REFUSED

Any other combination (e.g., RequestDatum + End) will fail because the expect pattern match in the validator will not succeed.

Test Hints

• Construct transactions with mismatched datum/redeemer combinations and verify they all fail
• Verify that inline datums round-trip correctly through serialization

Core type definitions for the MPF Cage validator.

This module defines the data structures used for:

• Minting and burning caged tokens
• Managing state updates via the Merkle Patricia Forestry
• Processing contribution requests from other users

Cage Pattern Overview

A “caged” token is an NFT locked at a script address with an associated Merkle Patricia Forestry (MPF) root. Anyone can fold pending requests into the MPF via permissionless Modify (no owner signs since issue #79), enabling collaborative data structures on-chain.

Two-UTxO Architecture

The cage script manages two fundamentally different kinds of UTxOs, distinguished by their datum type:

1. State UTxOs (StateDatum): Hold the caged NFT and the current MPF root hash. Only one State UTxO exists per caged token. There is no registry-owner role (operator ruling NOTE-028/A-003): Modify (folding) is permissionless since issue #79, and End, migration, burning and Sweep refuse for every party. Request and application authority and ordinary funding signatures keep their own clauses.

2. Request UTxOs (RequestDatum): Created by users who want to contribute data to someone else’s caged token. They do NOT hold the NFT – they sit at the same script address with a different datum. The requestToken field links the request to a specific caged token.

Lifecycle

Mint  -->  State UTxO (empty root)
               |
               |  <-- Request UTxOs arrive (from contributors)
               |
               v
           Modify (folds requests into MPF, updates root)
               |
               v
           State UTxO (updated root)

The M1 action set has no termination, migration or deposit-recovery operation: End (burns the NFT), migration, burning and Sweep refuse. This statement is about this design, not about all possible future registries.

Request UTxOs that are not yet accepted can be reclaimed by their creator via the Retract redeemer (request-owner authority, a separate domain, untouched).

Test Planning Notes

The types themselves don’t have validation logic, but tests should verify that:

• All datum variants can be serialized/deserialized as inline datums
• Pattern matching on CageDatum correctly distinguishes RequestDatum from StateDatum
• The seven edge row indices land on their seven-admitted-edges rows (0 insertAbsent through 6 witnessTerminal)
• MintRedeemer and UpdateRedeemer cover all action types exhaustively Parameters for migrating a caged token from an old validator to a new one.

During migration, the old token is burned (under oldPolicy) and a new token is minted (under the new policy) in the same transaction. The tokenId is preserved across migration (same asset name).

Uniqueness of the new token is guaranteed by the atomic burn of the old one – no OutputReference consumption is needed.

Redeemer for the minting policy.

The minting policy handles three cases:

• Minting: Full validation is applied (see validateMint in state.ak). The seed OutputReference that authorizes the mint and derives the asset name is the validator’s parameter, not a redeemer field.
• Migrating: REFUSED (operator ruling NOTE-028/A-003, issue #77 repair). Migration is a destructive re-policying with no ownerless justification. Constructor kept for the wire shape.
• Burning: REFUSED (same ruling). Burning the caged token destroys the registry without touching End at all. Constructor kept for the wire shape.

The open application’s mint redeemer (#173 I1).

It names the scoping tuple the approval is being minted for. The policy recomputes lib.approvalName over exactly these four components and requires the minted asset name to equal it, so the redeemer cannot point a token at a tuple it does not commit to. destination is the same pair the cage’s Request carries: the binary address bytes and the BLAKE2b-256 hash of the receiving output’s inline datum.

The seven-admitted-edges row index of a request (#183, Lean Request.edge). An edge names its own leaf bytes, so no value bytes travel with the request:

The constants live in lib.ak (edgeInsertAbsent … edgeWitnessTerminal). A tag outside 0..6 is refused edge-inadmissible before approval and before any proof is checked.

Each edge maps directly to a merkle_patricia_forestry step with the leaf bytes above; the proof demonstrates the transition given the current trie. Illegal value-byte shapes of the old Operation wire (G1/G3) are not expressible in this encoding and retired with the wire; see the slice-(b) decision record for the per-trace mapping.

A request to modify a caged token’s MPF, on the Lean wire (#183).

The request carries the seven-admitted-edges row index (edge 0-6, Lean Request.edge) instead of value bytes: the edge names its own leaf bytes (see above), so illegal value-byte shapes are inexpressible. No tip field: the fold requires the input lovelace to reach state.tip (Lean lovelaceCoversTip); deposit is the value above the tip the request rides with (held - state.tip). approval (Lean) is the carried asset under the application policy, not a datum field; claimed (Lean) is the transaction mint, not a datum field; refundAddress (Lean) is destination’s first component for the absent edges and the custody refund otherwise.

Requests are created by users who want to contribute data to someone else’s caged token. Anyone can then fold the request by including it in a permissionless Modify transaction.

Request Lifecycle

1. Creation: A user creates a UTxO at the cage script address with a RequestDatum(Request { ... }) inline datum. The UTxO typically holds only ADA (no NFT).

2. Contribution: The request UTxO is spent with Contribute(tokenRef) redeemer, which validates that requestToken matches the token at tokenRef. This step is permissionless.

3. Processing: The request UTxO appears as an input in a Modify transaction. The validator reads the request’s edge and requestKey, applies the edge’s trie move with the provided proof, and advances the root hash.

4. Retraction (alternative to 2-3): If the request is still pending, the request creator can spend it back with Retract when it is an insert or read request (update/delete requests are not retractable since issue #79), which requires requestOwner’s signature.

Linking Mechanism

The requestToken field is a TokenId (just an asset name). It must match the asset name of the caged NFT. The policy ID is implicit – it’s the cage script’s own policy ID.

Test Hints

• Request targeting token A processed in Modify for token A -> should succeed
• Request targeting token A included in Modify for token B -> should be skipped (mkUpdate checks requestToken == tokenId and skips non-matching requests)
• Request with edge 1 for key “bar” -> inserts 0x01 at “bar”
• Two requests for same key in same Modify tx -> depends on order and edge type (e.g., edge 1 then edge 5 would insert then immediately delete)

Per-request action in a Modify redeemer.

Each action corresponds to one request input in the transaction:

• Update(proof): verify the Merkle proof and apply the MPF operation
• Rejected: refund the owner held − tip, in any window (a reject carries no admission, #320) and skip proof verification

On-chain encoding

• Update(proof) → Constr 0 [proof]
• Rejected → Constr 1 []

The state of a caged token, stored as inline datum.

This represents the MPF root and oracle economics of the caged token. A State value lives inside a StateDatum wrapper as part of a CageDatum. There is no owner field and no ownership model (operator ruling NOTE-028/A-003, issue #77 repair).

Root Hash

The root field is a raw ByteArray (32 bytes for SHA2-256) representing the MPF root hash. It starts as root(empty) when freshly minted. It is updated each time Modify processes requests.

Test Hints

• Verify root must match computed MPF root after folding requests
• Verify initial root is root(empty) after minting

A unique identifier for a token, consisting of just the asset name.

The policy ID is provided separately in functions that need it, allowing the same TokenId to be used across different contexts.

Why Only AssetName

In the cage system, the policy ID is always the cage script’s own hash (since it’s a combined minting+spending validator). By storing only the asset name, we avoid carrying redundant policy ID references through the datum structures. The asset name alone uniquely identifies a caged token within the cage script’s namespace.

Derivation

The asset name is derived from an OutputReference via assetName(). It is the SHA2-256 hash of (transaction_id ++ output_index_as_2_bytes).

Redeemer for spending caged UTxOs.

This redeemer is used by the spending validator in cage.ak. The five variants correspond to five distinct operations, each requiring a different datum type on the UTxO being spent:

Constructors are kept so the redeemer wire shape does not shift; the End and Sweep arms refuse (operator ruling NOTE-028/A-003).

Test Hints

• Using End on any datum -> should fail (refused, owner-signed or not)
• Using Retract on a StateDatum UTxO -> should fail (expects RequestDatum)
• Using Modify without owner signature -> succeeds when the fold is otherwise valid (permissionless since issue #79)
• Using Contribute with a request targeting a different token -> should fail
• Using Retract without request owner signature -> should fail
• Using Sweep on any datum -> should fail (refused, owner-signed or not)