Finalize an ElementEval by supplying the list policy, root key, and node namespace constants.

In most validators, this becomes a small helper:

use aiken_design_patterns/linked_list

const root_key = #""

const node_key_prefix = "NODE"

const node_key_prefix_length =
  bytearray.length(node_key_prefix)

pub fn finalize_linked_list(
  eval: linked_list.ElementEval<Bool>,
  list_nft_policy_id: PolicyId,
) -> Bool {
  linked_list.run_element_with(
    eval,
    list_nft_policy_id,
    root_key,
    node_key_prefix,
    node_key_prefix_length,
  )
}

Then your minting policy can validate an operation like this:

let linked_list_eval = {
  let
    anchor_input,
    anchor_lovelace_change,
    // etc.
  <-
    linked_list.insert_ascending(...)

  expect anchor_lovelace_change >= 0

  // other validations
}

expect linked_list_eval |> finalize_linked_list(own_policy_id)

If a redeemer branch can only handle a root or only handle a node, use run_root_with or run_node_with with the narrower set of constants.

Finalize a RootEval by supplying the list policy and root key.

Root-only helpers return this reader shape when they do not need the node namespace. Keeping those constants out of the helper avoids requiring every root branch to know the node prefix.

Finalize a NodeEval by supplying the list policy and node namespace constants.

Node-only helpers return this reader shape when they never inspect or validate the root key. The caller is still responsible for supplying the exact prefix length that corresponds to node_key_prefix.

Initialize a linked-list root UTxO with the root NFT and Root datum. The output must contain exactly ADA plus that one root NFT.

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 must be 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, and raw root data. 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 an output selected from ScriptContext.transaction.outputs. This helper authenticates the selected output as a singleton root UTxO, but leaves the selection method to the caller so contracts can use indexes, filtering, or any other shape that fits their redeemer/API.

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.

Deinitialize an empty list.

root_validator args: spent root input, root Lovelace, raw root data.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. The policy-wide singleton-root invariant guarantees that the root_key asset being burned cannot have originated at another payment credential.

Insert a new node into an ascending ordered list.

The anchor element is inferred from inputs by requiring exactly one authentic linked-list element input. Its continued output must preserve the spent anchor address and data, and the new node must use the anchor payment credential.

Ordering rule:

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

additional_validations receives:

1. anchor input
2. anchor Lovelace change
3. anchor key (None for root, Some(key) for node)
4. anchor data
5. new node Lovelace
6. new node key
7. new node data
8. new node link

The default module preserves anchor data. Use linked_list/advanced when insertion should allow caller-validated anchor data changes.

continued_anchor_element_output and new_node_output must both be selected from ScriptContext.transaction.outputs. The caller controls how they are selected, for example by redeemer indexes or by filtering outputs.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

Like insert_ascending, but the ordering is reversed:

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

continued_anchor_element_output and new_node_output must both be selected from ScriptContext.transaction.outputs; this helper validates the selected outputs, not the selection method.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

Append a new terminal node to an unordered list.

The single authentic input is the current terminal anchor. The continued anchor links to the new node, and the new node must be terminal too.

There is no key-order comparison for unordered appends; callers are still responsible for maintaining any application-specific uniqueness or indexing invariant in additional_validations.

additional_validations receives:

1. anchor input
2. anchor Lovelace change
3. anchor key (None for root, Some(key) for node)
4. anchor data
5. new node Lovelace
6. new node key
7. new node data

The default module preserves anchor data. Use linked_list/advanced when appending should allow caller-validated anchor data changes.

continued_anchor_element_output and new_node_output must both be selected from ScriptContext.transaction.outputs. The caller may choose any deterministic selection method that suits the surrounding validator.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

Prepend a new first node to an unordered list.

The single authentic input must be the root. The continued root links to the new node, and the new node links to the root’s old first node.

additional_validations receives:

1. root input
2. root Lovelace change
3. root data
4. new node Lovelace
5. new node key
6. new node data
7. new node link

The default module preserves root data. Use linked_list/advanced when prepending should allow caller-validated root data changes.

continued_root_element_output and new_node_output must both be selected from ScriptContext.transaction.outputs. The helper authenticates the selected outputs and leaves indexing/filtering strategy to the caller.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

Remove the node linked by the selected anchor.

The anchor is identified by anchor_input_outref; the anchor and removing node are inferred from the transaction inputs. The removed node must be the node named by the selected anchor’s current link, and the continued anchor’s link becomes the removed node’s old link.

Only UTxOs authenticated by assets under the list policy participate in this transition. Other UTxOs at the anchor payment credential are independent and never need to be selected, spent, or cleaned up for removal.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

additional_validations receives:

1. anchor input
2. anchor Lovelace change
3. anchor key (None for root, Some(key) for node)
4. anchor data
5. removing node input
6. removing node Lovelace
7. removing node key
8. removing node data
9. removing node link

The default module preserves anchor data. Use linked_list/advanced when removal should allow caller-validated anchor data changes.

Fold the root’s first node into the root.

The root is identified by its output reference. The helper authenticates the root, the linked node, and the continued root; preserves the root address/key; burns the folding node NFT; and enforces the root/node namespace checks.

This traverses inputs and expects exactly two authentic list inputs at the list payment credential: the root input and the folding node input. UTxOs without an asset under the list policy are independent of that state and never need to be selected, spent, or cleaned up for the fold.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order.

additional_validations receives:

1. root input
2. root Lovelace change
3. root data
4. folding node input
5. folding node Lovelace
6. folding node key
7. folding node data
8. folding node link
9. continued root data

Spend-side gate for structural operations.

This function is intentionally not a structural validator by itself. It must only be used in a spend script whose paired list minting policy accepts structural mint/burns exclusively through this module’s matching mint helpers (init, insert_*, remove, fold_from_root, deinit, etc.).

The security invariant is split across scripts:

• the spend script uses this gate to permit structural list spends only when a list-policy mint/burn is present;
• the minting policy proves the exact linked-list transition with the corresponding mint helper.

Do not use this as standalone authorization for moving a list UTxO.

A UTxO at the same payment credential without an asset under the list policy is not a list UTxO. This gate deliberately provides no list-state guarantees for it. Such a UTxO is independent, cannot be forced into another party’s transaction, and never needs to be consumed or cleaned up by the list.

Use this for spend branches that allow adding/removing list elements. Use spend_for_updating_elements_data for non-structural continuations where the element is reproduced and no list-policy mint/burn occurs.

Continue an individual element without changing the linked-list structure.

No list-policy mint/burn is allowed; address, NFT, constructor, and link are preserved before UpdateValidation decides the Lovelace and data change.

additional_validations receives:

1. preserved element address
2. Lovelace change
3. element key (None for root, Some(key) for node)
4. old data
5. new data
6. preserved link

inputs and outputs must be the complete, unmodified ScriptContext.transaction.inputs and ScriptContext.transaction.outputs lists in ledger order. The indexes are interpreted against those lists.

Authenticate a root or node UTxO and pass its info to info_validations.

The UTxO must be an inline-datum singleton list element under the supplied policy. The returned key is None for the root and Some(node_key) for a node, where node_key excludes NodeKeyPrefix. Root keys and node-prefix membership are checked before the callback runs.

Authenticate a root UTxO and pass its info to info_validations.

The UTxO must carry the configured root NFT and a Root datum. The callback receives address, Lovelace, raw root payload data, and the root link. Use this when a script only accepts roots and should reject node UTxOs immediately.

Authenticate a node UTxO and pass its info to info_validations.

The UTxO must carry a list NFT whose asset name starts with node_key_prefix and must contain a Node datum. The callback receives address, the node key with the prefix stripped, raw node payload data, and the node link.

Validate exactly one authentic list input while scanning all transaction inputs.

Inputs with no asset under nft_policy_id are not list candidates and are assigned no structural meaning, irrespective of payment credential. After one candidate is found, this optimized scanner rejects a second singleton list-shaped input under the same policy; it assigns no meaning to inputs without an asset under that policy.

The narrow candidate check relies on authentic elements containing exactly ADA plus one list NFT and on ledger values listing ADA first. Other value shapes are not canonical base-list elements and are ignored.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. The exact-one claim is only as complete as the supplied list.

Args: callback receives input, Lovelace, asset name, data, link.

Another internal helper, you probably don’t need this.

Validate exactly two authentic list inputs while scanning all transaction inputs.

This compact fold is specialized for the exact two-list-input shape at one payment credential; it is not a general-purpose transaction-input classifier. This specialization has no bearing on list membership, which is authenticated only by assets under nft_policy_id.

anchor_input_outref selects which found input is passed to the callback as the anchor. Validation fails if neither authentic input has that reference.

inputs must be the complete, unmodified ScriptContext.transaction.inputs list in ledger order. The exact-two claim is only as complete as the supplied list.

Args: callback receives anchor input, anchor Lovelace, anchor asset name, anchor data, anchor link, removing input, removing Lovelace, removing asset name, removing data, removing link.

Another internal helper, you probably don’t need this.