feat: add redeemer index

Author: solidsnakedev

docs/content/docs/architecture/index.mdx

@@ -169,6 +169,15 @@ Architectural patterns provide consistency:
   <Card title="Deferred Execution" href="/docs/architecture/deferred-execution">
     Immutable builder pattern, program-as-value semantics, and composition
   </Card>
+  <Card title="Coin Selection" href="/docs/architecture/coin-selection">
+    UTxO selection algorithms for covering transaction requirements
+  </Card>
+  <Card title="Redeemer Indexing" href="/docs/architecture/redeemer-indexing">
+    Deferred redeemer construction for Plutus script index optimization
+  </Card>
+  <Card title="Script Evaluation" href="/docs/architecture/script-evaluation">
+    Plutus validator execution and ExUnits calculation
+  </Card>
   <Card title="Provider Layer" href="/docs/architecture/provider-layer">
     Blockchain access abstraction across Blockfrost, Kupmios, Maestro, Koios
   </Card>

docs/content/docs/architecture/meta.json

@@ -4,6 +4,7 @@
     "index",
     "transaction-flow",
     "coin-selection",
+    "redeemer-indexing",
     "script-evaluation",
     "unfrack-optimization",
     "devnet",

docs/content/docs/architecture/redeemer-indexing.mdx

@@ -0,0 +1,306 @@
+---
+title: Redeemer Indexing
+description: Deferred redeemer construction for Plutus script index optimization
+---
+
+import { Mermaid } from "@/components/mdx/mermaid"
+
+## Abstract
+
+Plutus validators receive transaction context including sorted input indices. Validators can use these indices for efficient lookups instead of traversing entire input lists. However, input indices depend on the **final sorted order** of all transaction inputs, including those added during coin selection. This creates a circular dependency: redeemer construction needs final indices, but final indices aren't known until after coin selection. The architecture resolves this through **deferred redeemer construction**: store a builder function instead of a concrete redeemer, then invoke it during the build phase once all inputs are known and sorted.
+
+## Purpose and Scope
+
+**Purpose**: Enable Plutus validators to use input indices efficiently by deferring redeemer construction until final input ordering is determined.
+
+**Scope**:
+- Defines the `RedeemerBuilder` pattern for deferred redeemer construction
+- Supports two variants: `"batch"` (multiple inputs) and `"self"` (single input per UTxO)
+- Provides both index and UTxO data to builder functions
+- Integrates with deferred execution model
+- Resolves indices after coin selection when canonical input order is final
+
+**Out of Scope**:
+- Redeemer encoding/serialization
+- Script evaluation and execution units
+- Plutus validator implementation patterns (on-chain concerns)
+
+## Design Philosophy
+
+### The Index Problem
+
+Cardano transactions sort inputs lexicographically by `(txHash, outputIndex)` before validation. When a Plutus validator executes, it receives inputs in this canonical order. Validators often need to correlate their own input with corresponding outputs. This is the classic "UTxO indexer" pattern for preventing double satisfaction attacks.
+
+<Mermaid chart={`
+graph LR
+    subgraph Naive["Naive: O(n) Lookup"]
+        N1[Iterate through<br/>all inputs] --> N2[Compare each<br/>to own reference] --> N3[Found after<br/>n comparisons]
+    end
+    
+    subgraph Optimized["Optimized: O(1) Lookup"]
+        O1[Redeemer contains<br/>input index] --> O2[Direct array access<br/>inputs#91;index#93;] --> O3[Single equality<br/>check]
+    end
+    
+    style Naive fill:#fee2e2,stroke:#b91c1c,stroke-width:2px
+    style Optimized fill:#d1fae5,stroke:#059669,stroke-width:2px
+`} />
+
+This optimization requires the off-chain code to know the input's index. But the index depends on the final sorted order of **all** inputs, including wallet UTxOs added during coin selection for fees and balancing.
+
+### The Circular Dependency
+
+<Mermaid chart={`
+graph TD
+    subgraph Problem["The Circular Dependency"]
+        P1["1. User specifies script inputs<br/>with redeemer"] --> P2["2. Redeemer needs input index..."]
+        P2 -.->|"depends on"| P4
+        P3["3. Transaction structure completed"] --> P4["4. Coin selection adds<br/>wallet UTxOs"]
+        P4 --> P5["5. Inputs sorted canonically<br/>→ indices now known"]
+        P5 --> P6["6. Too late!<br/>Redeemer already built"]
+    end
+    
+    style P2 fill:#fef3c7,stroke:#d97706,stroke-width:2px
+    style P6 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px
+`} />
+
+The architecture resolves this by **deferring** redeemer construction: instead of building the redeemer immediately, store a **builder function** that will be invoked after coin selection completes.
+
+### Deferred Redeemer Construction
+
+<Mermaid chart={`
+sequenceDiagram
+    participant User
+    participant Builder
+    participant CoinSelection
+    participant Resolver
+
+    User->>Builder: Add script inputs with RedeemerBuilder
+    Note over Builder: Store builder function<br/>(don't execute yet)
+    
+    User->>Builder: build()
+    Builder->>CoinSelection: Run selection
+    CoinSelection-->>Builder: Wallet UTxOs added
+    
+    Builder->>Resolver: All inputs now known
+    Resolver->>Resolver: Sort inputs canonically
+    Resolver->>Resolver: Compute index for each input
+    Resolver->>Resolver: Call makeRedeemer(index, utxo)
+    Resolver-->>Builder: Concrete redeemer returned
+    
+    Builder-->>User: Transaction ready
+`} />
+
+When a user provides a `RedeemerBuilder` instead of a concrete redeemer:
+
+1. The builder stores a **deferred operation** (the intent without the final redeemer)
+2. During `build()`, coin selection runs and all inputs are collected
+3. Inputs are sorted canonically and indices are computed
+4. The builder function is called with both **index and UTxO data**
+5. The returned redeemer completes the operation
+
+## Index-Only vs Full-Context Callbacks
+
+Some transaction building approaches only provide indices to the redeemer builder callback. This becomes problematic when validators need UTxO data to construct the redeemer. For example, unique token minting where the asset name derives from the output reference being spent.
+
+**The Problem**: If the callback only receives an index, the UTxO data must be captured externally and correlated manually. This is error-prone and awkward.
+
+**The Solution**: Provide both index **and** UTxO to the callback.
+
+<Mermaid chart={`
+graph TD
+    subgraph IndexOnly["Index-Only Approach"]
+        L1["makeRedeemer(indices)"]
+        L2[Only Index]
+        L1 --> L2
+        L2 --> L3["No UTxO Data<br/>Must capture externally"]
+    end
+    
+    subgraph IndexedInput["Full-Context Approach"]
+        E1["makeRedeemer(indexedInputs)"]
+        E2["{ index, utxo }"]
+        E1 --> E2
+        E2 --> E3["Full Context<br/>Index + UTxO Data"]
+    end
+    
+    style IndexOnly fill:#fee2e2,stroke:#b91c1c,stroke-width:2px
+    style IndexedInput fill:#d1fae5,stroke:#059669,stroke-width:2px
+    style L3 fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
+    style E3 fill:#a7f3d0,stroke:#059669,stroke-width:2px,color:#064e3b
+`} />
+
+The `IndexedInput` structure provides both:
+- **index**: Position in canonical input order (for the validator's O(1) lookup)
+- **utxo**: Full UTxO data (for constructing redeemers that depend on output references)
+
+## RedeemerBuilder Variants
+
+### Batch Variant
+
+For operations requiring indices of **multiple specified inputs**. The callback receives an array of `{ index, utxo }` pairs, maintaining the same order as the originally specified inputs.
+
+<Mermaid chart={`
+graph TD
+    Start([Specify script inputs<br/>with RedeemerBuilder]) --> Store[Store deferred operation<br/>+ input list]
+    
+    Store --> Build["build() called"]
+    Build --> CoinSelect[Coin Selection<br/>adds wallet UTxOs]
+    CoinSelect --> SortInputs[Sort All Inputs<br/>Canonically]
+    
+    SortInputs --> ComputeIndices[Compute Index Map<br/>txHash+outputIndex → index]
+    ComputeIndices --> LookupBatch[Lookup Indices for<br/>all specified inputs]
+    
+    LookupBatch --> CallMaker["Call makeRedeemer with<br/>array of { index, utxo }"]
+    
+    CallMaker --> ReturnRedeemer[Single Redeemer Returned<br/>with all indices]
+    ReturnRedeemer --> CompleteOp[Complete operation<br/>with concrete redeemer]
+    
+    CompleteOp --> End([Transaction Built])
+    
+    style Start fill:#ecf0f1,stroke:#34495e,stroke-width:3px,color:#000000
+    style End fill:#2ecc71,stroke:#27ae60,stroke-width:3px,color:#ffffff
+    style CallMaker fill:#3b82f6,stroke:#1e3a8a,stroke-width:3px,color:#ffffff
+`} />
+
+**Use Cases**:
+- Batch spending: redeemer contains list of `(inputIndex, outputIndex)` pairs
+- Multi-validator coordination: indices reference inputs across multiple scripts
+- Mint policies checking specific spend indices
+
+### Self Variant
+
+For operations where **each input needs its own redeemer with its own index**. The callback is invoked once per UTxO, receiving a single `{ index, utxo }` each time.
+
+<Mermaid chart={`
+graph TD
+    Start([Specify script inputs<br/>with self RedeemerBuilder]) --> Store[Store deferred operation<br/>for each UTxO]
+    
+    Store --> Build["build() called"]
+    Build --> CoinSelect[Coin Selection<br/>adds wallet UTxOs]
+    CoinSelect --> SortInputs[Sort All Inputs<br/>Canonically]
+    
+    SortInputs --> ComputeIndices[Compute Index Map]
+    
+    ComputeIndices --> ForEach["For each UTxO:"]
+    ForEach --> LookupIndex[Lookup this UTxO's Index]
+    LookupIndex --> CallMaker["Call makeRedeemer with<br/>single { index, utxo }"]
+    
+    CallMaker --> AddInput[Add Input with<br/>this UTxO's Redeemer]
+    AddInput --> MoreUtxos{More UTxOs?}
+    MoreUtxos -->|Yes| ForEach
+    MoreUtxos -->|No| End([Transaction Built])
+    
+    style Start fill:#ecf0f1,stroke:#34495e,stroke-width:3px,color:#000000
+    style End fill:#2ecc71,stroke:#27ae60,stroke-width:3px,color:#ffffff
+    style CallMaker fill:#3b82f6,stroke:#1e3a8a,stroke-width:3px,color:#ffffff
+    style ForEach fill:#f59e0b,stroke:#92400e,stroke-width:3px,color:#ffffff
+`} />
+
+**Use Cases**:
+- Simple spend validators that only need their own index
+- Validators that lookup their input via `inputs[redeemer]`
+- Unique token minting where asset name derives from output reference
+
+## Integration with Deferred Execution
+
+RedeemerBuilder integrates with the deferred execution model:
+
+<Mermaid chart={`
+sequenceDiagram
+    participant User
+    participant Builder
+    participant State
+    participant Resolver
+
+    User->>Builder: Add inputs with RedeemerBuilder
+    Note over Builder: [1] Store deferred operation<br/>NO execution yet
+    
+    User->>Builder: Add outputs, metadata, etc.
+    Note over Builder: [2] Store more operations
+    
+    User->>Builder: build()
+    Builder->>State: [3] Create fresh state
+    Builder->>State: [4] Execute operations<br/>(deferred ones wait)
+    State->>State: [5] Coin selection runs<br/>wallet UTxOs added
+    
+    Builder->>Resolver: [6] Resolve all RedeemerBuilders
+    Resolver->>Resolver: Sort all inputs canonically
+    Resolver->>Resolver: Build index map
+    
+    loop For each deferred operation
+        Resolver->>Resolver: Lookup indices for specified inputs
+        Resolver->>Resolver: Call makeRedeemer({ index, utxo })
+        Resolver->>State: Complete operation with concrete redeemer
+    end
+    
+    Builder-->>User: [7] Transaction ready for signing
+`} />
+
+**Phase Integration:**
+
+1. **Operation Storage**: Adding inputs with `RedeemerBuilder` stores a deferred operation instead of executing immediately
+2. **Fresh State**: Each `build()` creates new state; redeemer resolution is independent per execution
+3. **Operation Execution**: Regular operations execute, accumulating inputs and outputs
+4. **Coin Selection**: Selection phase adds wallet UTxOs to cover requirements
+5. **Redeemer Resolution**: After selection, all inputs are known; resolve deferred operations
+6. **Index Computation**: Sort inputs canonically, build lookup table for indices
+7. **Builder Invocation**: Call each builder function with computed `{ index, utxo }`
+
+## Index Resolution Algorithm
+
+<Mermaid chart={`
+graph TD
+    Start([Start Resolution]) --> CollectInputs[Collect All Inputs<br/>from Transaction State]
+    CollectInputs --> Sort[Sort Canonically<br/>by txHash, outputIndex]
+    
+    Sort --> BuildMap[Build Index Lookup Table]
+    BuildMap --> MapLogic["key = txHash + outputIndex<br/>value = position in sorted list"]
+    
+    MapLogic --> IterateBuilders[Iterate Deferred Operations]
+    IterateBuilders --> CheckVariant{Builder Variant?}
+    
+    CheckVariant -->|batch| LookupMultiple[Lookup Index for<br/>each specified input]
+    CheckVariant -->|self| LookupEach[For each UTxO<br/>lookup its index]
+    
+    LookupMultiple --> CallBatch["Call makeRedeemer with<br/>array of { index, utxo }"]
+    LookupEach --> CallSelf["Call makeRedeemer with<br/>single { index, utxo }"]
+    
+    CallBatch --> UseRedeemer[Use Redeemer for<br/>all inputs together]
+    CallSelf --> UseRedeemerPer[Use Redeemer for<br/>this specific input]
+    
+    UseRedeemer --> MoreBuilders{More Operations?}
+    UseRedeemerPer --> MoreBuilders
+    MoreBuilders -->|Yes| IterateBuilders
+    MoreBuilders -->|No| End([Resolution Complete])
+    
+    style Start fill:#ecf0f1,stroke:#34495e,stroke-width:3px,color:#000000
+    style End fill:#2ecc71,stroke:#27ae60,stroke-width:3px,color:#ffffff
+    style CheckVariant fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#000000
+    style CallBatch fill:#3b82f6,stroke:#1e3a8a,stroke-width:3px,color:#ffffff
+    style CallSelf fill:#3b82f6,stroke:#1e3a8a,stroke-width:3px,color:#ffffff
+`} />
+
+**Algorithm Steps:**
+
+1. **Collect**: Gather all inputs from transaction state (explicit inputs + coin selection additions)
+2. **Sort**: Apply canonical ordering, lexicographic by `(txHash, outputIndex)`
+3. **Index Map**: Create lookup table mapping each input's identifier to its position
+4. **Resolve Batch**: For `"batch"` variant, lookup all specified input indices, call builder once with array
+5. **Resolve Self**: For `"self"` variant, iterate inputs, call builder per UTxO with its index
+
+## Error Handling
+
+Resolution can fail if specified inputs are missing from the final transaction:
+
+**Missing Input Error**: A `RedeemerBuilder` references a UTxO that wasn't included in the final input set. This occurs if:
+- The UTxO was never added via `collectFrom`
+- The UTxO was filtered out during processing
+- The UTxO reference is malformed
+
+**Resolution After Selection Error**: If coin selection adds inputs that change the transaction balance, requiring another selection round, previously-resolved redeemers may have stale indices. The system detects this and fails with guidance to set a minimum fee.
+
+## Related Topics
+
+- [Deferred Execution](/docs/architecture/deferred-execution) - Program storage and fresh state model
+- [Transaction Flow](/docs/architecture/transaction-flow) - Build phases and state machine
+- [Coin Selection](/docs/architecture/coin-selection) - How wallet UTxOs are added
+- [Script Evaluation](/docs/architecture/script-evaluation) - ExUnits calculation after redeemer resolution