Spend Validator

Detailed guide on spend validators including overview, use cases, and example Anvil API interactions.

Overview

Spend validators control the conditions under which UTXOs can be spent from script addresses.

Real-world Use Cases

• Asset Locking: Define conditions for when locked assets can be accessed

• Multi-signature Schemes: Require approval from multiple parties

• Time-locked Funds: Allow access only after certain time conditions

• Conditional Payments: Release funds when specific on-chain/off-chain conditions are met

Required UTxO Fields and Deployed Blueprint

PREREQUISITE: DEPLOYED SMART CONTRACT

Before you can interact with any validator, you must have a compiled and deployed smart contract blueprint. The validator hash used in these examples comes from your deployed blueprint.

Refer to the Blueprint Management guide for details on how to deploy your smart contract blueprint.

Don't forget to lock assets at the script address in a prior transaction. Then when spending, specify the locked UTxO using the outputRef field, which pinpoints the UTxO by its transaction hash and output index.

{
  "txHash": "transaction_hash", // Transaction hash where funds were locked
  "index": 0 // Output index within that transaction
}

Anvil API returns the UTXOs in the order they were added when you previously locked the assets.

Spend Validator API Interaction Example

Use the below examples to build transactions that interact with the spend validator.

If you are unfamiliar with the Anvil API transaction builder, review the Transaction Overview guide first.

1. Locking Assets at Script Address

// Build a transaction to lock funds at a script address
const lockInput = {
  // Address where change outputs will be sent (your wallet address)
  changeAddress: "ADDR_YOUR_CHANGE_ADDRESS",
  
  // Optional message for transaction metadata (appears in block explorers)
  message: "Locking funds using the spend validator",
  
  // UTxOs to use as inputs (hex-encoded transaction outputs)
  // These provide the funds being locked at the script address
  utxos: [
    "8282...", "8282...", "8282...", "8282..."
  ],
  
  // Outputs to create in this transaction
  outputs: [
    {
      // Script address derived from validator hash
      address: scriptAddress,
      
      // Amount of lovelace (unit of ADA) to lock at script address
      lovelace: LOVELACE_AMOUNT,
      
      // Datum stores information needed for future spending
      datum: {
        // Stored directly on-chain (vs. hash-only)
        type: "inline",
        
        // The actual datum content as specified by your validator's blueprint
        value: {
          owner: "addr_test1xyz...",   // Owner's verification key hash who can unlock
        },
        
        // References validator hash and purpose for serialization
        shape: { validatorHash, purpose: "spend" }
      }
    }
  ]
};

2. Spending (Unlocking) Locked UTxO

// Build a transaction to spend (unlock) funds from the script address
const unlockInput = {
  // Address where unlocked funds will be sent (your wallet address)
  changeAddress: "ADDR_YOUR_CHANGE_ADDRESS",
  
  // Optional message for transaction metadata (appears in block explorers)
  message: "Unlocking funds using the spend validator",
  
  // UTxOs to use for transaction fees and collateral
  // These are regular wallet UTxOs, not the script UTxO being spent
  utxos: [
    "8282...", "8282...", "8282...", "8282..."
  ],
  
  // Define how to interact with smart contract validators
  scriptInteractions: [
    {
      // Validator script hash (matches one used when locking funds)
      hash: validatorHash,
      
      // We're using the spend validator
      purpose: "spend",
      
      // Points to the specific UTXO at the script address we want to spend/unlock
      outputRef: { 
        txHash: "TRANSACTION_HASH", // Transaction hash where funds were locked
        index: 0                       // Output index within that transaction
      },
      
      // Redeemer provides arguments to the validator
      // Here we're unlocking the funds with a simple message defined in the smart contract
      redeemer: { 
        type: "json", 
        value: { 
          msg: "hex-encoded-message"  
        } 
      }
    }
  ],
  
  // Transaction must be signed by these key hashes
  // Often matches owner key from the datum to verify authorization
  requiredSigners: [signerKeyHash]
};

See Examples

https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/hello-world-smart-contract.mdhttps://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/escrow/README.md