advanced

Advanced linked-list helpers reuse the default module’s element type, aliases, runners, spend helper, and structural invariants.

The list policy is the authentication boundary. Anyone can create a UTxO at the list payment credential without invoking the spend script or list policy. A UTxO with no asset under the list policy is not list state, even at that credential; namespace-aware scanners ignore it completely and these helpers make no claim about its datum, value, or spendability. UTxOs at one credential are independent and transactions consume only explicitly selected inputs, so an outside party cannot force such a UTxO into or use it to block a list transition. The list never needs to collect or clean it up. Off-chain discovery must authenticate a reserved structural token and canonical element shape under the list policy, not infer state from address.

<list_nft_policy_id, root_key> is globally reserved as the singleton root asset. A one-time init is its only permitted mint, the init callback pins it to the canonical root at the list payment credential, every continuation keeps it there, and deinit is its only permitted burn. Every other policy branch, including application-specific same-policy branches, must reject changes to root_key. A valid deployment therefore cannot contain this token at another payment credential. Root-anchored scanning relies on this policy-wide invariant.

Key differences from default:

Reference-script-aware callbacks are available for init, structural node operations, reads, and updates. Continued structural anchors preserve their reference scripts.
Structural node mint/burn helpers and deinit may accept additional same-policy mint/burn outside the root key and node-key namespace and expose it as NonStructuralListAssets. List element UTxOs remain exactly ADA plus one list NFT; root init and non-structural continuations remain strict. The same operations expose same-policy inputs found at other payment credentials as NonStructuralListInputs. Continued anchors or, for deinit, the canonical root input authenticate the list payment credential internally. Inputs without list-policy assets never enter either classification.
Insert/remove callbacks receive both spent and continued anchor data; caller callbacks decide valid data changes while structural identity and links are enforced.
Advanced structural mint/burn helpers still pair with the base spend-side helper aiken_design_patterns/linked_list.spend_for_adding_or_removing_an_element.
Every Output passed to an advanced mint helper must come from ScriptContext.transaction.outputs. The helpers validate the selected outputs as linked-list UTxOs, but the caller chooses how to select them: indexes, filtering, list.find, or another contract-specific method are all valid as long as the Output is not redeemer data or a locally constructed value.
Every inputs argument passed to a structural helper or namespace-aware scanner must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. Do not pass a filtered, reordered, reconstructed, or redeemer-provided list. The scanner can only classify inputs it receives. Insert/remove callbacks share an anchor prefix: (anchor input, anchor Lovelace change, anchor key, spent anchor data, continued anchor data). anchor key is None for root data and Some(key) for node data.

Types

AppendValidation

Callback for appending an unordered node.

The shared advanced anchor prefix is followed by the new terminal node’s Lovelace, key, data, reference script, and permitted same-policy mint/burn changes. The library has already checked that the anchor was terminal, the new node is terminal, and the continued anchor points to the new node. The final two arguments are NonStructuralListAssets from mint/burn changes and NonStructuralListInputs from consumed transaction inputs. This unordered operation does not enforce application-specific key uniqueness. The produced node address is available from the new_node_output supplied to the helper.

Alias

AppendValidation = fn(
    Input,
    LovelaceChange,
    Option<NodeKey>,
    Data,
    Data,
    Lovelace,
    NodeKey,
    NodeData,
    Option<ScriptHash>,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool

ElementInfo<a>

Element-info continuation, including any reference script.

Args: Address, Lovelace, element key (None for root, Some(key) for node), data, link, reference script.

Alias

ElementInfo<a> = fn(
    Address,
    Lovelace,
    Option<NodeKey>,
    Data,
    Link,
    Option<ScriptHash>,
  ) ->
    a

FoldValidation

Callback for folding from the root.

The library has already selected the root by output reference, authenticated the folded node, proved that the root points to that node, preserved the continued root address/NFT/reference script, and moved the folded node’s old link onto the continued root.

Args: root input, root Lovelace change, spent root data, folding node input, folding node Lovelace, folding node key, folding node data, folding node link, continued root data, NonStructuralListAssets mint/burn changes, and NonStructuralListInputs.

Alias

FoldValidation = fn(
    Input,
    LovelaceChange,
    RootData,
    Input,
    Lovelace,
    NodeKey,
    NodeData,
    Link,
    RootData,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool

NodeElementInfo<a>

Node-info continuation, including any reference script.

Args: Address, Lovelace, node key, node data, link, reference script.

Alias

NodeElementInfo<a> = fn(
    Address,
    Lovelace,
    NodeKey,
    NodeData,
    Link,
    Option<ScriptHash>,
  ) ->
    a

NonStructuralListAssets

Type alias to represent other assets outside reserved root and node namespaces, under the list policy. These are not assets carried by list element UTxOs.

Positive quantities are mints; negative quantities are burns.

Alias

NonStructuralListAssets = Dict<AssetName, Int>

NonStructuralListInputs

Non-structural inputs carrying assets under the list policy.

Each pair contains the unchanged input and the complete dictionary of its same-policy names and quantities. These inputs are outside the authenticated list payment credential; their asset names are not interpreted or restricted. Inputs are kept in transaction order; ADA and foreign-policy assets remain available through the Input.

UTxOs with no asset under the list policy are absent from this type and are ignored even at the list payment credential. The unclassified names in this type do not relax the policy-wide root invariant: a correctly wired policy can never place <list_nft_policy_id, root_key> at an external credential. The scanner relies on that lifetime invariant rather than re-proving the provenance of an already existing token.

This list is complete only when the helper received the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

Alias

NonStructuralListInputs = Pairs<Input, NonStructuralListAssets>

OrderedInsertValidation

Callback for ordered insertion.

The shared advanced anchor prefix is: (anchor input, anchor Lovelace change, anchor key, spent anchor data, continued anchor data), where anchor key is None for root anchors and Some(key) for node anchors.

After that prefix, this callback receives the authenticated new node Lovelace, key, data, link, reference script, and permitted same-policy mint/burn changes. Structural identity, link wiring, reference-script preservation on the continued anchor, minting, and key ordering have already been checked. The final two arguments are NonStructuralListAssets from mint/burn changes and NonStructuralListInputs from consumed transaction inputs. The produced node address is not repeated in this callback; callers that need full-address checks can capture the new_node_output they passed to the insertion helper.

Alias

OrderedInsertValidation = fn(
    Input,
    LovelaceChange,
    Option<NodeKey>,
    Data,
    Data,
    Lovelace,
    NodeKey,
    NodeData,
    Link,
    Option<ScriptHash>,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool

PrependValidation

Callback for prepending an unordered node.

The anchor has already been authenticated as the root, the continued root has been checked to point to the new node, and the new node has been checked to point to the root’s previous first node. The produced node address is available from the new_node_output supplied to the helper.

Args: root input, root Lovelace change, spent root data, continued root data, new node Lovelace, new node key, new node data, new node link, new node reference script, NonStructuralListAssets mint/burn changes, and NonStructuralListInputs.

Alias

PrependValidation = fn(
    Input,
    LovelaceChange,
    RootData,
    RootData,
    Lovelace,
    NodeKey,
    NodeData,
    Link,
    Option<ScriptHash>,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool

RemainingSamePolicyAssetChanges

Same-policy changes left after removing an expected structural NFT.

This intermediate value may still contain other structural asset names. Callers must process and validate the remainder before treating it as non-structural.

Alias

RemainingSamePolicyAssetChanges = Dict<AssetName, Int>

RemoveValidation

Callback for removal.

The shared advanced anchor prefix is followed by the authenticated removing node input, Lovelace, key, data, link, and permitted same-policy mint/burn changes. The library has already selected the anchor by output reference, proved that the anchor points to the removed node, preserved the continued anchor address/NFT/reference script, and checked that the continued link skips over the removed node. The final two arguments are NonStructuralListAssets from mint/burn changes and NonStructuralListInputs from consumed transaction inputs.

Alias

RemoveValidation = fn(
    Input,
    LovelaceChange,
    Option<NodeKey>,
    Data,
    Data,
    Input,
    Lovelace,
    NodeKey,
    NodeData,
    Link,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool

RootElementInfo<a>

Root-info continuation, including any reference script.

Args: Address, Lovelace, root data, link, reference script.

Alias

RootElementInfo<a> = fn(Address, Lovelace, RootData, Link, Option<ScriptHash>) ->
    a

StructuralToken

A structural list token classified once by the namespace-aware input scanner.

RootToken proves that the scanned asset name equals the configured root_key. NodeToken retains both the complete asset name and its prefix-stripped key because downstream operations need each representation. RootToken classification relies on the policy-wide invariant that no external root_key token can exist; matching the name alone does not re-prove the token’s lifetime provenance.

Constructors

```
RootToken
```

NodeToken { asset_name: AssetName, key: NodeKey }

UpdateValidation

Callback for non-structural element continuations.

The updater preserves address, NFT, constructor, and link; this callback controls the Lovelace change, data transition, and reference-script transition.

Args: preserved element address, Lovelace change, element key (None for root), old data, old reference script, new data, new reference script, preserved link.

Alias

UpdateValidation = fn(
    Address,
    LovelaceChange,
    Option<NodeKey>,
    Data,
    Option<ScriptHash>,
    Data,
    Option<ScriptHash>,
    Link,
  ) ->
    Bool

Constants

spend_for_adding_or_removing_an_element: fn(PolicyId, Value) -> Bool

Re-export of the base structural spend gate.

This is not standalone authorization: it only checks that some list-policy mint/burn is present. The paired minting policy must prove the transition with the matching linked-list mint helper. Namespace-aware mint helpers must receive the complete transaction input list.

Functions

validate_list_nft_and_get_remaining_same_policy_asset_changes(
  v: Value,
  expected_nft_policy: PolicyId,
  expected_nft_name: AssetName,
  expected_nft_qty: Int,
) -> RemainingSamePolicyAssetChanges

Validate the expected structural NFT mint/burn and return the remaining changes under the same policy.

validate_no_reserved_list_asset_changes(
  remaining_same_policy_asset_changes: RemainingSamePolicyAssetChanges,
  root_key: AssetName,
  node_key_prefix: AssetName,
  node_key_prefix_length: Int,
) -> Bool

Validates that additional same-policy asset changes do not use reserved list asset names. Applies to both mints and burns.

A remaining same-policy asset whose name starts with node_key_prefix would collide with the list node namespace. A remaining asset whose name equals root_key would collide with the list root NFT. Rejecting both here lets advanced callers allow unrelated same-policy assets without weakening the structural root/node-key invariants.

This validates only the branch that calls it. The policy-wide singleton-root invariant requires every other redeemer branch under the same policy to reject minting or burning root_key as well.

Initialization and De-initialization

init(
  nonce_validated: Bool,
  produced_element_output: Output,
  tx_mint: Value,
  root_validator: fn(Address, Lovelace, Data, Option<ScriptHash>) -> Bool,
) -> RootEval<Bool>

Initialize the root while passing its reference script to the callback. No extra mint/burn changes under the list NFT policy are allowed.

nonce_validated must prove a unique consumed nonce or equivalent one-time authorization. Passing literal True is only appropriate in tests and fixtures.

This one-time initialization is the only policy branch allowed to mint <list_nft_policy_id, root_key>. It mints exactly one, and root_validator must pin the produced root to the intended list payment credential. No other policy branch may mint that reserved asset.

root_validator receives the produced address, Lovelace quantity, raw root data, and optional reference script. The address is passed explicitly even though callers could inspect produced_element_output, so callbacks can validate the destination without destructuring the output again.

produced_element_output must be selected from ScriptContext.transaction.outputs. This helper authenticates that selected output as the produced root; it deliberately leaves index/filter selection to the surrounding validator.

It is up to callers to ensure this address has a script payment credential controlled by a script that only uses the spend helpers from this library. In other words, the destination script must ensure list NFTs never leave its custody.

deinit(
  inputs: List<Input>,
  tx_mint: Value,
  root_validator: fn(
    Input,
    Lovelace,
    Data,
    NonStructuralListAssets,
    NonStructuralListInputs,
  ) ->
    Bool,
) -> ElementEval<Bool>

Deinitialize an empty list while exposing non-structural same-policy mint/burn changes and inputs to the callback.

The canonical root input establishes the authenticated list payment credential. Inputs without list-policy assets are ignored at every payment credential, including the root credential. Every additional same-policy input at the root credential is rejected, while same-policy inputs at another credential are passed through without interpreting their asset names.

Locating the root by root_key relies on the policy-wide singleton-root invariant: only the one-time init can mint this asset, it remains at the canonical list credential, and this deinit is its only burn. A root_key token at another credential is unreachable under the required policy.

Deinitialization must burn the root NFT. Additional changes under the list policy are permitted only outside the root and node namespaces and are passed separately as NonStructuralListAssets.

root_validator receives the spent root input, root Lovelace, raw root data, permitted same-policy changes, and collected same-policy inputs. It can inspect root_input.output.reference_script through the input argument.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. This mint helper must be paired with aiken_design_patterns/linked_list.spend_for_adding_or_removing_an_element in the root spend branch.

Element Addition and Removal

insert_ascending(
  continued_anchor_element_output: Output,
  new_node_output: Output,
  inputs: List<Input>,
  tx_mint: Value,
  additional_validations: OrderedInsertValidation,
) -> ElementEval<Bool>

Insert a node into an ascending ordered list.

This is the advanced variant of the base module’s insert_ascending. It preserves the anchor address, NFT, reference script, constructor, and structural links, but passes both spent and continued anchor payload data to additional_validations. That lets the caller validate an application data transition while the library still enforces the linked-list structure.

Ordering rule:

root anchor: new < old_first
node anchor: anchor < new < old_next

The required new node NFT must be minted under the list policy. Additional same-policy mint/burn changes are allowed only outside the root key and node-key namespace, then passed to the callback as NonStructuralListAssets. Same-policy inputs at other payment credentials are passed separately as NonStructuralListInputs without interpreting their names.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. Passing a filtered, reordered, reconstructed, or redeemer-provided list invalidates the scanner’s completeness guarantee.

continued_anchor_element_output and new_node_output must both be selected from ScriptContext.transaction.outputs. This helper validates the selected outputs and intentionally leaves their selection strategy to the caller.

insert_descending(
  continued_anchor_element_output: Output,
  new_node_output: Output,
  inputs: List<Input>,
  tx_mint: Value,
  additional_validations: OrderedInsertValidation,
) -> ElementEval<Bool>

Insert a node into a descending ordered list.

Same contract as insert_ascending, except the bytearray ordering is reversed:

root anchor: new > old_first
node anchor: anchor > new > old_next