> For the complete documentation index, see [llms.txt](https://dev.ada-anvil.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.ada-anvil.io/guides/smart-contract/validators/stake-validator.md).

# Stake Validator

## Overview

Stake validators (also called reward validators) control access to staking rewards associated with script-controlled stake addresses. They determine when and how accumulated rewards can be withdrawn, enabling programmatic control over staking operations.

{% hint style="info" %}
**TERMINOLOGY NOTE**

In official Cardano terminology, these are called **Stake Validators** with the script purpose **Rewarding**. However, the Anvil API uses `purpose: "withdraw"` in the transaction structure. This documentation uses the terms interchangeably.
{% endhint %}

## Real-world Use Cases

* **DAO Treasury Management**: Automated governance of reward withdrawals based on DAO votes
* **Delegated Staking Pools**: Programmatically manage stake delegation and reward distribution
* **Reward Distribution Systems**: Automate the fair distribution of staking rewards among multiple parties
* **Conditional Reward Access**: Restrict reward withdrawals based on time, market conditions, or other parameters

## Required Fields for Reward Withdrawals

{% hint style="info" %}
**For stake validators, you need two key components in your transaction:**

1. **scriptInteractions**: Specifies the validator hash, purpose ("withdraw" in Anvil API), and redeemer
2. **withdrawals**: An array specifying which stake address to withdraw rewards from

The validator hash must match the script that controls the stake address you're withdrawing from.

```json
{
  "scriptInteractions": [{ ... }],
  "withdrawals": ["stake_script_address_here"]
}
```

**Note**: The stake address must be registered and have delegated ADA to accumulate rewards before withdrawal can occur.
{% endhint %}

{% 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](/guides/smart-contract/blueprint-management.md) guide for details on how to deploy your smart contract blueprint.
{% endhint %}

## Stake Validator API Interaction Example

Use the below examples to build transactions that interact with withdraw validators.

If you are unfamiliar with the Anvil API transaction builder, review the [Transaction Overview](/guides/transaction.md) guide first.

### 1. Registering a Script-Controlled Stake Address

```typescript
// Build a transaction to register a script-controlled stake address
const registerInput = {
  // 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: "Registering script-controlled stake address",
  
  // UTxOs to use as inputs (hex-encoded transaction outputs)
  utxos: [
    "8282...", "8282...", "8282...", "8282..."
  ],
  
  // Certificate for stake address registration
  certificates: [{
    type: "stakeRegistration",  // Register a stake credential
    // Stake credential controlled by the script
    credential: {
      type: "script",
      hash: withdrawValidatorHash // Hash of your withdraw validator
    }
  }],
  
  // Other possible certificate types include:
  // - "stakeDelegation": Delegate stake to a pool 
  // - "stakeDeregistration": Unregister a stake address
  // - "voteDelegation": Delegate voting power (CIP-36)
  
  // Pay the stake registration deposit (2 ADA on mainnet)
  deposits: "auto" // Automatically calculate required deposits ("auto" or specific amount in lovelace)
};
```

### 2. Withdrawing Rewards from a Script-Controlled Stake Address

```typescript
// Build a transaction to withdraw rewards from a script-controlled stake address
const withdrawInput = {
  // Address where withdrawn rewards and change will be sent
  changeAddress: "ADDR_YOUR_TREASURY_ADDRESS",
  
  // Optional message for transaction metadata
  message: "Withdrawing staking rewards using script",
  
  // UTxOs to use for transaction fees and collateral
  utxos: [
    "8282...", "8282...", "8282...", "8282..."
  ],
  
  // Define how to interact with the withdraw validator script
  scriptInteractions: [{
    // Validator script hash (matches the one used when registering)
    hash: withdrawValidatorHash,
    
    // We're using the withdraw validator
    purpose: "withdraw",
    
    // Redeemer provides arguments to the validator
    redeemer: { 
      type: "json", 
      value: { 
        action: "withdraw",
        authorizer: treasuryKeyHash,  // Key hash authorized to perform withdrawals
        beneficiary: "addr_test1..."  // Where rewards will go (if different from changeAddress)
      } 
    }
  }],
  
  // Specify the script-controlled stake address to withdraw from
  withdrawals: ["stake_script_address_here"],
  
  // Transaction must be signed by these key hashes
  // Often matches authorizer key from the redeemer to verify authorization
  requiredSigners: [treasuryKeyHash]
};
```

## Important Technical Notes

### Stake Address Lifecycle

1. **Registration**: Script-controlled stake addresses must be registered before they can receive rewards
2. **Delegation**: After registration, ADA must be delegated to a stake pool
3. **Rewards Accrual**: Rewards begin accruing after 2-3 epochs (10-15 days)
4. **Withdrawal**: Rewards can be withdrawn using the withdraw validator

### Security Considerations

* The redeemer is the only way to pass parameters to the validator
* Include proper authorization checks in your validator logic
* Consider time-locking or multi-signature requirements for high-value treasuries

### Performance Optimization

* Consider batching multiple reward withdrawals in a single transaction when possible

## See Examples