Chainlink Automation: Building a Deadman Switch for Emergency Fund Recovery

1. License and Version Declaration

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

• // SPDX-License-Identifier: MIT - Standard license identifier for open source contracts
• pragma solidity ^0.8.24; - Specifies Solidity version 0.8.24 or higher (^ means compatible versions)

2. Documentation Comment

/**
 * Single-contract demo of Chainlink Automation with MANY vaults.
 * - Users create vaults (structs) in this hub; no new contracts deployed.
 * - Fund per-vault via deposit(vaultId) payable.
 * - One upkeep scans a bounded window and pays expired vaults in batches.
 * - Failed sends are recorded as "owed[vaultId][recipient]" for later claim.
 */

This comment explains the contract's purpose: it's a single contract that manages multiple vaults (not separate contracts), uses batching for gas efficiency, and handles failed transfers gracefully.

3. Automation Interface

interface IAutomation {
  function checkUpkeep(bytes calldata) external view returns (bool, bytes memory);
  function performUpkeep(bytes calldata) external;
}

This interface defines the two required functions for Chainlink Automation. Instead of importing the full Chainlink contract, we define our own interface to reduce dependencies and gas costs.

It took me a few attempts of incompatibility issues and "insufficient funds"to realize this. 😬

4. Data Structures

struct Beneficiary { address payable to; uint16 bps; } // 10000 = 100%
struct Vault {
  address owner;
  uint32  heartbeat;    // seconds
  uint32  grace;        // seconds
  uint64  lastHeartbeat;
  bool    executed;
  uint256 balance;      // ETH earmarked for this vault
  Beneficiary[] bens;
}

• Beneficiary - Stores recipient address and their percentage (bps = basis points, 10000 = 100%)
• Vault - Contains all vault data: owner, timing, execution status, balance, and beneficiaries
• uint32 grace Amount of time after the heartbeat to allow for late check-ins
• uint32 heartbeat Amount of time between check-ins and uint32 to saves gas compared to uint256
• uint64 lastHeartbeat Last time user checks in and uint64for timestamps is sufficient and more gas-efficient
• bool executed Indicates if the vault has been executed by returning true or false
• uint256 balance Amount of ETH in the vault
• Beneficiary[] bens Array of beneficiaries

A STRUCT is a blueprint for creating objects that contain multiple pieces of information. Each struct can contain different data types (addresses, numbers, booleans, etc.) and even arrays of other structs.

BPS or basis points are used instead of percentages or decimals because Solidity only recognizes whole numbers. So we use 10000 to represent 100%, 100 to represent 1%, and so on.

5. Storage Variables

Vault[] public vaults;
mapping(uint256 => mapping(address => uint256)) public owed; // vaultId => recipient => amount

// Upkeep paging: small, predictable gas
uint256 public cursor;                       // srart scanning at last stopped position
uint256 public constant SCAN_LIMIT  = 25;    // how many vaults to scan per check
uint256 public constant BATCH_LIMIT = 10;    // how many payouts to execute per perform

• vaults[] - Dynamic array storing all vaults
• Mapping - used to map through addresses and their corresponding values
• owed - Nested mapping tracking failed transfers (that are still owed)for later claiming
• cursor - Tracks where to start scanning, beginning from last stopped position
• SCAN_LIMIT - Maximum vaults to check per upkeep call (gas limit protection)
• BATCH_LIMIT - Maximum payouts to execute per upkeep call

6. Events

event VaultCreated(uint256 indexed id, address indexed owner);
event Deposited(uint256 indexed id, address indexed from, uint256 amount);
event CheckedIn(uint256 indexed id, uint256 nextDeadline);
event Payout(uint256 indexed id, address indexed to, uint256 amount, bool ok);
event Executed(uint256 indexed id, uint256 when);
event OwedClaimed(uint256 indexed id, address indexed to, uint256 amount);

• VaultCreated - Emitted when a vault is created along with the vault ID and owner
• Deposited - Emitted when a deposit is made
• CheckedIn - Emitted when a check-in is made along with the vault ID and next deadline
• Payout - Emitted when a payout is made along with the vault ID, recipient, amount, and if the transfer succeeded
• Executed - Emitted when a vault is executed along with the vault ID and timestamp
• OwedClaimed - Emitted when an owed claim is made

Events are indexed for easy filtering and provide transparency for all major contract actions. The bool ok indicates if the transfer succeeded (ok or !ok).

7. Modifier

modifier onlyOwner(uint256 id) {
  require(id < vaults.length, "bad id");
  require(msg.sender == vaults[id].owner, "not owner");
  _;
}

Then onlyOwner modifier ensures only the vault owner can perform certain actions. It checks both that the vault ID is valid and that the caller is the owner.

8. Create Vault Function

function createVault(
  address payable[] calldata recipients,
  uint16[] calldata bps,
  uint32 heartbeatSec,
  uint32 graceSec
) external payable returns (uint256 id) {
  require(heartbeatSec > 0, "heartbeat=0");
  require(recipients.length == bps.length && bps.length > 0, "bad arrays");

• calldata - More gas-efficient than memory for arrays passed as parameters
• recipients - Array of addresses of the beneficiaries
• bps - Array of basis points of the beneficiaries
• heartbeatSec - Heartbeat in seconds
• graceSec - Grace period in seconds
• payable - Allows the function to receive ETH
• require - Validates heartbeat is positive and arrays match in length

Note:After hours (maybe days?) of trying to figure out why my funds were not being transferred after execution, I realized that the payable keyword was missing. 🤦‍♀️

9. Vault Creation Logic

// build vault
id = vaults.length;
vaults.push();
Vault storage v = vaults[id];
v.owner = msg.sender;
v.heartbeat = heartbeatSec;
v.grace = graceSec;
v.lastHeartbeat = uint64(block.timestamp);

• id = vaults.length - New vault gets the next available ID
• vaults.push() - Adds a new empty vault to the array
• Vault storage v - Creates a storage reference for gas efficiency
• lastHeartbeat - Set to current timestamp (vault starts "alive")

10. Beneficiary Validation

uint256 sum;
for (uint256 i = 0; i < recipients.length; i++) {
  require(recipients[i] != address(0) && bps[i] > 0, "bad ben");
  v.bens.push(Beneficiary(recipients[i], bps[i]));
  sum += bps[i];
}
require(sum == 10000, "sum!=10000");

This loop validates each beneficiary (non-zero address, positive percentage) and ensures all percentages add up to exactly 10000 (100%). This prevents rounding errors and ensures complete fund distribution.

11. Check In Function

function checkIn(uint256 id) external onlyOwner(id) {
  Vault storage v = vaults[id];
  require(!v.executed, "executed");
  v.lastHeartbeat = uint64(block.timestamp);
  emit CheckedIn(id, nextDeadline(id));
}

The critical "heartbeat" function that resets the timer. Only the vault owner can call it, and it updates the last heartbeat timestamp, effectively extending the deadline.

12. Chainlink Automation - checkUpkeep

function checkUpkeep(bytes calldata)
  external
  view
  override
  returns (bool upkeepNeeded, bytes memory performData)
{
  uint256 n = vaults.length;
  if (n == 0) return (false, "");

  uint256 found;
  uint256[BATCH_LIMIT] memory ids; // fixed-size scratch array

Chainlink Automation is the core of the switch. It is the function that monitors the vaults and checks if they are expired and need to be executed. This function runs off-chain to determine if upkeep is needed. It uses a fixed-size array to avoid dynamic allocation, scanning up to SCAN_LIMIT vaults to find expired ones.

• checkUpkeep is the function that monitors the vaults and checks if they are expired and need to be executed.
• external is used to indicate that the function is external.
• override is used to override the function in the IAutomation interface.
• bytes calldata is the data passed to the function.
• view is used to indicate that the function does not modify the state of the contract.
• returns is used to return the data from the function.
• upkeepNeeded is a boolean that indicates if upkeep is needed.
• performData is the data that is passed to the function.

checkUpkeep and performUpkeep are the two functions that are used to monitor the vaults and execute the expired vaults.

Chainlink will look for these 2 functions to decide if your contract is automation compatible.

13. Expiration Check Logic

// Constants defined earlier in contract
uint256 public constant SCAN_LIMIT  = 25;    // how many vaults to scan per check
uint256 public constant BATCH_LIMIT = 10;    // how many payouts to execute per perform

for (uint256 i = 0; i < SCAN_LIMIT && found < BATCH_LIMIT; i++) {
  uint256 idx = (cursor + i) % n;
  Vault storage v = vaults[idx];
  if (!v.executed && v.balance > 0 && block.timestamp >= (uint256(v.lastHeartbeat) + v.heartbeat + v.grace)) {
    ids[found++] = idx;
  }
}

• for (uint256 i = 0; i < SCAN_LIMIT - loop through vaults starting from cursor up to scan limit
• && found < BATCH_LIMIT; i++) - stop when we find batch limit expired vaults
• i++ - increment the loop
• found - Number of expired vaults found
• BATCH_LIMIT - Maximum number of vaults to execute per upkeep (defined as constant = 10)
• SCAN_LIMIT - Maximum number of vaults to scan per upkeep (defined as constant = 25)
• (cursor + i) % n
  • cursor is the index we left off on in the last upkeep and where we'll begin scanning from,
  • i is how far we are in the current loop (0, 1, 2, 3...), up to the SCAN_LIMIT
  • % is the index we are currently on, and n is the number of vaults
  • If we go past the end (>= n), % n "wraps us back" to the beginning.
• Checks three conditions: not executed, has balance, and expired
• Expiration formula: lastHeartbeat + heartbeat + grace
• Stops when we find BATCH_LIMIT expired vaults or scan SCAN_LIMIT total

14. Payout Execution

function _performPayout(uint256 id) internal {
  Vault storage v = vaults[id];
  require(!v.executed, "executed");
  require(block.timestamp >= nextDeadline(id), "not expired");

  v.executed = true;
  uint256 bal = v.balance;
  v.balance = 0;

  if (bal == 0) { emit Executed(id, block.timestamp); return; }

  for (uint256 i = 0; i < v.bens.length; i++) {
    uint256 share = (bal * v.bens[i].bps) / 10000;
    if (share == 0) continue;
    (bool ok, ) = v.bens[i].to.call{value: share}("");
    if (!ok) { owed[id][v.bens[i].to] += share; }
    emit Payout(id, v.bens[i].to, share, ok);
  }
  emit Executed(id, block.timestamp);
}

• Vault storage v = vaults[id]; - storage v is the vault we are working with
• require(!v.executed, "executed"); - checks if the vault has already been executed
• require(block.timestamp >= nextDeadline(id), "not expired"); - checks if the vault has expired
• v.executed = true; - marks the vault as executed
• uint256 bal = v.balance; - gets the balance of the vault
• v.balance = 0; - sets the balance of the vault to 0
• if (bal == 0) { emit Executed(id, block.timestamp); return; } - if the balance is 0, emits the Executed event and returns
• Loops through each beneficiary and calculates their share using basis points
• Uses .call{value: share}("") for gas-efficient ETH transfers:
  • .call - A low-level function in Solidity for sending Ether (or making arbitrary calls)
  • Unlike .transfer() or .send(), it doesn't enforce a fixed gas stipend — it forwards all remaining gas by default
  • {value: share} - This curly-brace syntax means: send share amount of Ether (in wei) along with the call
  • ("") - The parentheses hold the data payload (the function selector + arguments you want to call). Here it's just an empty string "", meaning: no function is called, just send Ether to the recipient's fallback/receive function
  • (bool ok, ) - .call returns two values: A boolean (ok) → whether the call succeeded, and Bytes data (ignored here with _/,). If ok == false, the Ether wasn't received successfully
• Records failed transfers in owed mapping for later claiming
• Emits events for transparency and monitoring

1. License and Version Declaration

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

• // SPDX-License-Identifier: MIT - Standard MIT license for open source contracts
• pragma solidity ^0.8.24; - Specifies Solidity version 0.8.24 or higher

2. Interface Definitions

interface IMySwitch {
  function expired() external view returns (bool);
  function executed() external view returns (bool);
  function performPayout() external;
}

interface AutomationCompatibleInterface {
  function checkUpkeep(bytes calldata) external view returns (bool, bytes memory);
  function performUpkeep(bytes calldata) external;
}

• IMySwitch - Defines the interface that vault contracts must implement
• expired() - Returns true if the vault has passed its deadline
• executed() - Returns true if the vault has already been paid out
• performPayout() - Executes the actual payout to beneficiaries
• AutomationCompatibleInterface - Required interface for Chainlink Automation integration

3. Contract Declaration and Storage

contract SwitchManager is AutomationCompatibleInterface {
  address[] public vaults;
  uint256 public constant SCAN_LIMIT = 25;
  uint256 public constant BATCH_LIMIT = 10;
  uint256 public cursor;

• AutomationCompatibleInterface - Inherits the required automation interface
• vaults[] - Array storing addresses of all registered vault contracts
• SCAN_LIMIT = 25 - Maximum number of vaults to check per upkeep call
• BATCH_LIMIT = 10 - Maximum number of vaults to execute per upkeep call
• cursor - Tracks position for round-robin scanning to ensure fairness

4. Events

event VaultAdded(address vault);
event VaultExecuted(address vault, bool ok);

• VaultAdded - Emitted when a new vault is registered with the manager
• VaultExecuted - Emitted when a vault payout is attempted, with success/failure status

5. Vault Registration Function

function addVault(address vault) external {
  require(vault != address(0), "vault=0");
  vaults.push(vault);
  emit VaultAdded(vault);
}

• addVault - Allows anyone to register a new vault contract
• require(vault != address(0), "vault=0") - Ensures vault address is valid
• vaults.push(vault) - Adds the vault to the registry
• emit VaultAdded(vault) - Logs the registration for transparency

6. Chainlink Automation - checkUpkeep

function checkUpkeep(bytes calldata)
  external
  view
  override
  returns (bool upkeepNeeded, bytes memory performData)
{
  uint256 n = vaults.length;
  if (n == 0) return (false, "");

  address[BATCH_LIMIT] memory dueTmp;
  uint256 found;

• checkUpkeep - Off-chain function that determines if upkeep is needed
• external view override - Implements the automation interface
• returns (bool, bytes) - Returns whether upkeep is needed and data for execution
• address[BATCH_LIMIT] memory dueTmp - Fixed-size array to avoid dynamic allocation
• found - Counter for how many expired vaults we've found

7. Vault Scanning Logic

for (uint256 i = 0; i < SCAN_LIMIT && found < BATCH_LIMIT; i++) {
  uint256 idx = (cursor + i) % n;
  IMySwitch v = IMySwitch(vaults[idx]);
  if (v.expired() && !v.executed()) {
    dueTmp[found++] = vaults[idx];
  }
}

• for (uint256 i = 0; i < SCAN_LIMIT - Loop through up to 25 vaults
• && found < BATCH_LIMIT; i++) - Stop when we find 10 expired vaults
• (cursor + i) % n - Round-robin scanning from last position
• IMySwitch v = IMySwitch(vaults[idx]) - Cast to interface for method calls
• v.expired() && !v.executed() - Check if vault is expired but not yet executed
• dueTmp[found++] = vaults[idx] - Add to list of vaults that need execution

8. Return Data Preparation

if (found == 0) return (false, "");

address[] memory due = new address[](found);
for (uint256 j = 0; j < found; j++) due[j] = dueTmp[j];
return (true, abi.encode(due));

• if (found == 0) return (false, "") - No work needed if no expired vaults found
• address[] memory due = new address[](found) - Create dynamic array of exact size
• for (uint256 j = 0; j < found; j++) - Copy found vaults to dynamic array
• return (true, abi.encode(due)) - Return success and encoded vault addresses

9. Chainlink Automation - performUpkeep

function performUpkeep(bytes calldata performData) external override {
  if (performData.length == 0) return;
  address[] memory due = abi.decode(performData, (address[]));

  uint256 steps = due.length > BATCH_LIMIT ? BATCH_LIMIT : due.length;

• performUpkeep - On-chain function that actually executes the upkeep
• external override - Implements the automation interface
• if (performData.length == 0) return - Safety check for empty data
• abi.decode(performData, (address[])) - Decode vault addresses from checkUpkeep
• steps - Limit execution to BATCH_LIMIT to prevent gas issues

10. Vault Execution with Error Handling

for (uint256 i = 0; i < steps; i++) {
  IMySwitch v = IMySwitch(due[i]);
  if (v.expired() && !v.executed()) {
    try v.performPayout() {
      emit VaultExecuted(due[i], true);
    } catch {
      emit VaultExecuted(due[i], false);
    }
  }
}

• for (uint256 i = 0; i < steps; i++) - Loop through vaults to execute
• IMySwitch v = IMySwitch(due[i]) - Cast to interface for method calls
• if (v.expired() && !v.executed()) - Double-check conditions before execution
• try v.performPayout() - Attempt to execute the payout
• catch - Handle any errors gracefully without stopping other executions
• emit VaultExecuted(due[i], true/false) - Log success or failure for each vault

11. Cursor Update and Utility Function

uint256 n = vaults.length;
cursor = n == 0 ? 0 : (cursor + steps) % n;
}

function vaultCount() external view returns (uint256) { return vaults.length; }

• cursor = n == 0 ? 0 : (cursor + steps) % n - Update cursor for next round-robin scan
• % n - Wrap around to beginning when reaching the end
• vaultCount() - Utility function to get total number of registered vaults