Skip to main content
Resets the vault’s last-heartbeat to stacks-block-time, restarting the inactivity countdown. The vault must exist and must not be distributed. This function is only callable by the vault owner (the address that created the vault), because it uses tx-sender to look up the vault.

​
Function signature

(define-public (heartbeat) -> (response bool uint))

​
Parameters

This function takes no arguments. The vault owner is identified by tx-sender.

​
Return value

​
ok
bool
Returns (ok true) on success. The vault’s last-heartbeat is updated to the current stacks-block-time.
​
err
uint
Returns (err uint) on failure. See error codes below.

​
Error codes

CodeConstantWhen returned
u103ERR-VAULT-NOT-FOUNDThe calling address has no vault
u110ERR-VAULT-DISTRIBUTEDThe vault has been distributed or cancelled

​
How the heartbeat works

The function merges stacks-block-time into the vault’s last-heartbeat field: 
;; From heirloom-vault.clar
(define-public (heartbeat)
  (let ((vault (unwrap! (map-get? vaults tx-sender) ERR-VAULT-NOT-FOUND)))
    (asserts! (not (get is-distributed vault)) ERR-VAULT-DISTRIBUTED)

    ;; Reset the heartbeat timer
    (map-set vaults tx-sender (merge vault { last-heartbeat: stacks-block-time }))

    (ok true)
  )
)
stacks-block-time is a Clarity 4 consensus-level keyword — it returns the timestamp of the current Stacks block and cannot be manipulated by the caller.

​
Vault states where heartbeat works

The function only blocks if is-distributed is true. It succeeds in all other states:
Vault stateHeartbeat allowed?Effect
activeYesResets timer, vault stays active
graceYesResets timer, vault returns to active
claimableYesResets timer, vault returns to active — heirs can no longer claim
distributedNoReturns ERR-VAULT-DISTRIBUTED
Sending a heartbeat while the vault is in claimable state will pull the vault back to active and prevent heirs from claiming until the countdown expires again. This is intentional — it allows an owner who regains access to recover their vault at any point before distribution.

​
JavaScript example

import { sendHeartbeat } from './lib/contracts';

// Called by the vault owner to prove they are still active
await sendHeartbeat();
Automate heartbeats using a scheduled job or a browser-based reminder. The vault does not send notifications — it is the owner’s responsibility to send heartbeats before the interval expires. A missed heartbeat starts the grace period immediately.

Build docs developers (and LLMs) love

Get started for freeTalk to us