Vestige Docs

OverviewProtocol modelFAQVault lifecycleAssets and balancesSecurity modelContract overviewFunction referenceDeployed contractsdApp integrationDeploymentLocal developmentOperational runbookEvents and indexingTroubleshooting
Protocol

Vault lifecycle

The vault lifecycle is a small state machine computed from existence, claimed status, and timestamps. Most UX decisions in the dApp come from this state machine.

State table

getVaultState(owner) returns the computed lifecycle state for a vault.

Active
Vault exists, is not claimed, and current time is before lastCheckIn + inactivityPeriod.
GracePeriod
Inactivity period has passed, but grace period has not fully expired yet.
Claimable
current time >= lastCheckIn + inactivityPeriod + gracePeriod and inheritance has not been activated.
Claimed
Inheritance was activated by the heir. Native USDC may be claimed, and token balances may still be claimed one by one.

Creation

createVault initializes the owner's vault. The owner is always msg.sender. The heir must be non-zero and must not equal the owner. Timing windows must fit the protocol limits.

Min inactivity
1 day
Max inactivity
3650 days
Min grace
1 day
Max grace
365 days
createVault(address heir, uint256 inactivityPeriod, uint256 gracePeriod)

Owner window

While the vault is active or still recoverable by check-in, the owner can refresh liveness, change the heir, change timing, deposit assets, and withdraw assets. These actions are blocked once the vault is claimable or claimed.

  • checkIn refreshes lastCheckIn to block.timestamp.
  • updateHeir changes the configured claimant wallet.
  • updateInactivityPeriod and updateGracePeriod change future timing windows.
  • depositUSDC/depositToken add value to the vault.
  • withdrawUSDC/withdrawToken remove value while owner control is valid.

Claim window

When the claimable timestamp matures, the heir can activate inheritance. From a user's perspective this is the moment where the vault opens. From the contract perspective, it is a strict timestamp and caller authorization check.

block.timestamp >= vault.lastCheckIn + vault.inactivityPeriod + vault.gracePeriod

Cleanup and new vaults

A claimed or empty vault is not automatically removed from storage. It must be disabled after all native USDC and active token balances are zero. Cleanup matters because the protocol allows one vault lifecycle per owner at a time.

The dApp should show completed-vault UX instead of normal owner controls after inheritance has been activated. Once the vault is drained, it should guide the owner or heir to disable it.