# Spend Validator

## 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

{% hint style="warning" %}
**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](https://dev.ada-anvil.io/guides/smart-contract/blueprint-management) guide for details on how to deploy your smart contract blueprint.
{% endhint %}

{% hint style="warning" %}
**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.

```json
{
  "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.**
{% endhint %}

## 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](https://dev.ada-anvil.io/guides/transaction) guide first.

### 1. Locking Assets at Script Address

```typescript
// 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

```typescript
// 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

{% content-ref url="<https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/hello-world-smart-contract.md>" %}
<https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/hello-world-smart-contract.md>
{% endcontent-ref %}

{% content-ref url="<https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/escrow/README.md>" %}
<https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/escrow/README.md>
{% endcontent-ref %}