Vestige

Your assets. Your legacy. Your heirs.

Vestige is an immutable inheritance protocol designed for Arc Testnet and Circle-native USDC-first asset flows. It gives users a structured way to define an heir, deposit Circle-native USDC and other ERC20 tokens, maintain liveness through periodic check-ins, and allow inheritance activation only after a configured inactivity window and grace period have both elapsed.

The repository is centered around a production-oriented vault model rather than a single smart contract in isolation. Vestige combines deterministic on-chain state transitions, bounded claim mechanics, explicit accounting, and audit-friendly documentation to support long-term asset continuity without custodians, administrators, or upgradeable control paths. On Arc Testnet, Circle-native USDC is the primary protocol asset, while the underlying contract also retains support for the chain-native gas asset and arbitrary ERC20 balances.

Why Onchain Inheritance Matters

Self-custody solves ownership, but it does not solve succession.

When a wallet owner dies, disappears, loses access, or simply stops managing their keys, their assets can remain permanently stranded. Traditional finance has legal and institutional inheritance rails. Web3 does not. In a self-custodial environment, unplanned inactivity can turn a stable-value treasury such as Circle-native USDC into inaccessible state forever.

Vestige addresses that gap with a dead man switch inheritance protocol that operates entirely onchain:

• no bank or probate intermediary
• no centralized service dependency
• no offchain execution requirement for claims
• no upgradeable admin path controlling user assets

How Vestige Solves It

Each user may create one inheritance vault. That vault stores:

• an owner
• a designated heir
• an inactivity period
• a grace period
• the latest liveness timestamp
• escrowed Circle-native USDC balances
• escrowed ERC20 balances

The owner remains in control during the active lifecycle and can:

• deposit Circle-native USDC
• deposit ERC20 tokens
• withdraw while the vault is not claimable
• update the heir
• update inactivity and grace windows
• refresh liveness through checkIn()

If the owner stops checking in:

1. the vault moves from Active to GracePeriod
2. after grace expires, it becomes Claimable
3. the heir activates inheritance
4. the chain-native asset can be claimed directly if present
5. ERC20 balances are claimed token-by-token through bounded, granular claim calls

Core Features

• Dead man switch vaults with explicit heir designation
• Circle-native USDC-first inheritance on Arc Testnet
• optional support for additional ERC20 assets
• Event-driven transaction journaling for indexing and monitoring
• Deterministic inactivity and grace period state machine
• Granular ERC20 claims that avoid unbounded token loops
• Fee-on-transfer-aware ERC20 accounting
• Immutable contract architecture with no upgrade path
• Emergency pause controls limited to operational containment, not asset seizure

Security Design Highlights

• No upgradeability: Vestige is designed as an immutable vault protocol.
• No unbounded claim loops: ERC20 inheritance is claimed per token to avoid gas-DoS failure modes.
• Reentrancy protection: withdrawal and claim paths are guarded with ReentrancyGuard.
• Checks-effects-interactions discipline: balances and state are updated before external transfers.
• Fee-on-transfer support: ERC20 deposits credit the actual received amount.
• Frozen owner actions after claimability: once a vault becomes claimable, owner-side mutation paths are blocked.
• O(1) empty-vault cleanup checks: active token counts avoid iterating through tracked token lists during disable flows.

Architecture Overview

Vestige is currently implemented as a single immutable core contract:

• contracts/InheritanceVault.sol

Supporting repository components include:

• Hardhat deployment flow in scripts/deploy.ts
• protocol documentation in docs
• test suite in test/InheritanceVault.test.ts

At a high level:

• vaults stores user vault configuration and lifecycle metadata
• ethBalances tracks the chain-native asset balance when the deployment uses it
• tokenBalances tracks vault-scoped ERC20 balances
• activeTokenCounts allows constant-time checks for vault emptiness
• tracked token metadata supports frontend discovery without being part of critical claim execution

Vault Lifecycle

Vestige uses a clear four-state lifecycle:

1. Active The owner is within the configured inactivity window.
2. GracePeriod The inactivity period has elapsed, but the grace period is still active.
3. Claimable Both inactivity and grace windows have elapsed. The heir may activate inheritance.
4. Claimed Inheritance has been activated by the heir. The chain-native asset may already be drained and ERC20 claims may continue token-by-token until balances are exhausted.

Example Flows

Create a vault

await inheritanceVault.createVault(
  heirAddress,
  180 days,
  30 days
);

Check in to refresh liveness

await inheritanceVault.checkIn();

Deposit Circle-native USDC

await usdc.approve(vaultAddress, 2_000_000);
await inheritanceVault.depositToken(
  "0x3600000000000000000000000000000000000000",
  2_000_000
);

Deposit another ERC20

await token.approve(vaultAddress, amount);
await inheritanceVault.depositToken(tokenAddress, amount);

Activate inheritance and claim the chain-native asset if present

await inheritanceVault.connect(heir).claimInheritance(ownerAddress);

Claim a specific ERC20 balance

await inheritanceVault
  .connect(heir)
  .claimToken(ownerAddress, tokenAddress, receiverAddress);

Frontend and Indexing Notes

Frontend clients should typically index:

• VaultCreated
• HeirUpdated
• InactivityPeriodUpdated
• GracePeriodUpdated
• CheckedIn
• EthDeposited
• EthWithdrawn
• TokenDeposited
• TokenWithdrawn
• InheritanceActivated
• InheritanceETHClaimed
• InheritanceTokenClaimed
• VaultDisabled

Recommended frontend reads include:

• getVaultDetails(owner)
• getVaultState(owner)
• getTrackedTokens(owner)
• claimableAt(owner)
• gracePeriodStartsAt(owner)
• timeUntilClaimable(owner)
• activeTokenCounts(owner)

Security Notes

Vestige is intentionally conservative in areas where inheritance systems are most fragile:

• Arc Testnet is the target deployment environment for this repository.
• Circle-native USDC on Arc Testnet is the primary asset profile.
• ERC20 claims are granular by design to keep gas bounded.
• The protocol does not attempt to enumerate and transfer all tokens in one transaction.
• Pausing exists for operational containment, not for asset confiscation or administrator withdrawal.
• The contract does not support NFTs, social recovery, multiple heirs, or guardian arbitration in the current version.
• The contract still exposes chain-native asset handling methods because EVM escrow remains generic, but production usage in this repository is USDC-first.
• Circle docs note that Arc Testnet still uses a separate native gas token for transaction fees even when USDC is the primary protocol asset.
• Users remain responsible for choosing trustworthy heirs and operationally maintaining their check-in schedule.

See docs/SECURITY.md for the full threat model and design rationale.

Deployment

Local and network deployments are handled through Hardhat:

npm run compile
npm run deploy
npm run deploy:localhost
npm run deploy:arc

For full deployment and verification guidance, see docs/DEPLOYMENT.md.

Roadmap

Potential future extensions for Vestige V2 and beyond:

• NFT inheritance support
• multiple heirs and proportional splits
• guardian-assisted recovery layers
• encrypted offchain instructions or messages
• notification and reminder integrations
• richer analytics and monitoring surfaces

These are roadmap ideas only and are not part of the current immutable deployment surface.

License

Vestige is released under the GPL-3.0-only license. See individual source headers for SPDX declarations.