A Deadman Vault is not static — it moves through a well-defined sequence of states from the moment it is created to the moment every beneficiary has been paid. Each state represents a distinct phase of the vault’s life, carries specific rules about what actions are permitted, and determines how the keeper and owner should respond. Understanding this lifecycle is essential for both vault owners who want to ensure their funds reach their beneficiaries, and developers integrating with the protocol.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/natureloved/DeadMan-Vault/llms.txt
Use this file to discover all available pages before exploring further.
The Six States
funding
The vault has been created in the database and a keeper account provisioned, but the owner has not yet deposited USDCx into the FlowVault lock. No deadline is active.
active
The owner’s deposit has been confirmed on-chain and locked in FlowVault. The heartbeat deadline is set. The owner must check in before it expires.
warning
The deadline is approaching — 432 blocks (3 days) or fewer remain. The keeper sends a warning email and marks the vault here until the owner checks in or time runs out.
grace_period
The deadline has passed but the grace window is still open (within 288 blocks / 2 days after the deadline). The owner can still perform a heartbeat to recover the vault.
triggered
The grace period has elapsed. The vault has flatlined. The keeper schedules vesting, initiates payout, and notifies all beneficiaries. Settlement retries on every keeper sweep.
claimed
Every beneficiary has received their share (or their vesting cliff has matured and been paid). The vault is fully settled and no further action is taken.
Block-Based Timing
All timing in Deadman Vault is measured in Stacks blockchain blocks, not wall-clock time. The protocol uses three constants:| Constant | Value | Approximate Duration |
|---|---|---|
BLOCKS_PER_DAY | 144 blocks | 1 day |
WARNING_BLOCKS | 432 blocks | 3 days before deadline |
GRACE_PERIOD_BLOCKS | 288 blocks | 2 days after deadline |
Block times on Stacks are approximately 10 minutes, giving ~144 blocks per day. These approximations are used consistently throughout the protocol, so all timing is deterministic given block height.
State Transition Reference
| Current State | Trigger Condition | Next State | Who Acts |
|---|---|---|---|
funding | Owner deposits USDCx and finalizeVaultFunding confirms | active | Owner |
active | deadline − currentBlock ≤ 432 | warning | Keeper cron |
warning | Owner sends heartbeat (0.01 USDCx check-in) | active | Owner |
warning | currentBlock > deadline | grace_period | Keeper cron |
grace_period | Owner sends heartbeat (0.01 USDCx check-in) | active | Owner |
grace_period | currentBlock > deadline + 288 | triggered | Keeper cron |
triggered | All beneficiary payouts confirmed on-chain | claimed | Keeper cron |
State Details
funding — Awaiting Deposit
When
initVault is called, a vault record is written to the database with status: "funding" and a dedicated custodial keeper keypair is generated and encrypted. At this point no FlowVault interaction has occurred.Available actions: The owner must send depositAmount USDCx to the keeper address, then call finalizeVaultFunding to confirm. Until this happens the vault is invisible to the keeper sweep.Exits to: active once finalizeVaultFunding successfully locks funds on-chain and sets heartbeat_deadline_block.active — Deadman Alive
The vault is live.
last_heartbeat_block and heartbeat_deadline_block are set. The keeper begins monitoring this vault on every sweep.Available actions: The owner should perform regular heartbeats before the deadline. The owner can also update beneficiaries or vault settings while the vault remains active.Exits to: warning when the keeper detects the remaining blocks fall at or below WARNING_BLOCKS (432).warning — Check In Soon
The deadline is 3 days or fewer away. The keeper sends a warning email to the owner (deduplicated — at most once per 24 hours) and advances the status to
warning.Available actions: Performing a heartbeat resets the deadline and returns the vault to active. This is the last routine opportunity to check in before consequences begin.Exits to: active on a successful heartbeat, or grace_period if currentBlock passes the deadline.The warning email is sent only once per 24-hour window. If the keeper cron runs frequently, it will not spam the owner.
grace_period — Last Chance
The deadline has passed but the 2-day grace window (
GRACE_PERIOD_BLOCKS = 288) is still open. The keeper advances status to grace_period and sends a grace period email (deduplicated to once per 48 hours).Available actions: A heartbeat can still recover the vault — the lock is extended and the vault returns to active. This is the final window before an irreversible trigger.Exits to: active on a successful heartbeat, or triggered once currentBlock > deadline + 288.triggered — Deadman Stopped
The grace period elapsed without a check-in. The keeper records
triggered_at, computes each beneficiary’s vesting_release_at timestamp, and immediately attempts settleVaultPayout. Claim-ready notification emails are dispatched to every beneficiary.Available actions: No owner recovery is possible. Beneficiaries with matured vesting cliffs receive their share on the next keeper sweep (or via the manual claim page at /claim/[vaultId]). Beneficiaries still within their vesting window are skipped until the cliff passes.Exits to: claimed once every beneficiary has been paid and confirmed on-chain.Human-Readable Labels
ThegetVaultStatusLabel() function (from src/lib/deadman-vault/beneficiary.ts) maps each VaultStatus to a display-friendly string suitable for use in UIs:
The
VaultStatus type is defined in src/lib/deadman-vault/types.ts as a string union: "funding" | "active" | "warning" | "grace_period" | "triggered" | "claimed". The database schema enforces this constraint via a CHECK clause on the status column.