Heartbeat & death timeout
The heartbeat system ensures that wallets with inactive agents don't lock funds indefinitely. It creates a provable liveness signal on-chain.
How it works
- AI calls
create_willwith adeath_timeoutvalue (minimum 30 days, in seconds). - AI periodically calls
heartbeat??this updateslast_heartbeatto the current timestamp. - If
current_time > last_heartbeat + death_timeout, the wallet is considered dead. - Anyone can then call
execute_willto distribute the PDA balance to beneficiaries.
State transitions
| Wallet state | Condition | Available instructions |
|---|---|---|
| Alive | now < last_heartbeat + death_timeout | heartbeat, ai_transfer, ai_reject, update_will |
| Dead | now >= last_heartbeat + death_timeout | execute_will only |
Design considerations
- 30-day minimum prevents griefing ??an issuer cannot set a short timeout to quickly reclaim funds via will.
- Death is lazy ??the program doesn't automatically execute. Someone must call
execute_willand the program checks the condition at invocation time. - Recovery is possible ??if the agent comes back online before anyone calls
execute_will, a single heartbeat resets the clock. - Automate heartbeats ??never rely on a human reminder. Use cron jobs, scheduled tasks, or the MCP server's built-in scheduling.