Stake Validator

Detailed guide on stake validators including overview, use cases, and example Anvil API interactions for managing stake rewards.

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.

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.

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

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.

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

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

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.

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 guide first.

1. Registering a Script-Controlled Stake Address

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

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