Digital Will and Testament Vault

A secure, decentralized smart contract on the Stacks blockchain for managing digital wills, inheritances, and automated asset distribution.

Overview

This smart contract enables users to create legally-binding digital wills, designate beneficiaries, deposit assets into secure vaults, and automate inheritance distribution upon death or prolonged inactivity.

Key Features

🔐 Will Management

• Create Digital Wills: Store testament text (up to 500 characters) on-chain
• Executor Assignment: Designate trusted executors to manage your estate
• Will Locking: Prevent unauthorized modifications once finalized
• Activity Tracking: Automatic heartbeat monitoring system

👥 Beneficiary System

• Multiple Beneficiaries: Add unlimited beneficiaries with custom allocations
• Percentage-Based Distribution: Allocate assets by percentage (1-100%)
• Asset Descriptions: Document specific asset details for each beneficiary
• Claim Protection: Prevents double-claiming and fraud

💰 Vault System

• STX Token Deposits: Securely store STX tokens in contract-managed vaults
• Automatic Balance Tracking: Real-time vault balance monitoring
• Fee Management: 1% platform fee on distributions (configurable)
• Secure Withdrawals: Only authorized beneficiaries can claim after death declaration

⏰ Inactivity Detection

• Automated Monitoring: Tracks last activity timestamp
• Inactivity Threshold: Default 1 year (~5.184M blocks)
• Auto-Declaration: Allows death declaration after prolonged inactivity
• Heartbeat Function: Users can record activity to reset timer

✅ Witness Verification

• Multi-Witness Support: Multiple parties can confirm will validity
• Timestamp Recording: Captures confirmation time for legal records
• Independent Verification: Witnesses must be different from testator

Functions

Public Functions

create-will

(create-will (testament (string-ascii 500)) (executor (optional principal)))

Creates a new digital will with testament text and optional executor.

update-testament

(update-testament (new-testament (string-ascii 500)))

Updates will testament (only if not locked or deceased).

add-beneficiary

(add-beneficiary (beneficiary principal) (allocation uint) (description (string-ascii 200)))

Adds a beneficiary with percentage allocation (1-100%) and asset description.

deposit-to-vault

(deposit-to-vault (amount uint))

Deposits STX tokens into your secure vault for future distribution.

record-activity

(record-activity)

Records activity to reset inactivity timer (heartbeat function).

declare-deceased

(declare-deceased (testator principal))

Declares a testator deceased (only by executor or after inactivity period).

claim-inheritance

(claim-inheritance (testator principal))

Allows beneficiaries to claim their allocated inheritance after death declaration.

lock-will

(lock-will)

Permanently locks will to prevent future modifications.

add-witness-confirmation

(add-witness-confirmation (testator principal))

Records witness confirmation of a will's validity.

Read-Only Functions

• get-will: Retrieve complete will information
• get-beneficiary-info: Get specific beneficiary details
• get-vault-balance: Check current vault balance
• get-platform-fee: View current platform fee
• get-inactivity-period: Check inactivity threshold
• check-inactivity-threshold: Verify if inactivity period has been met
• get-executor-assignments: List all wills managed by an executor

Admin Functions

set-platform-fee

(set-platform-fee (new-fee uint))

Updates platform fee (max 10%, in basis points). Owner only.

set-inactivity-period

(set-inactivity-period (new-period uint))

Updates inactivity threshold (min 1 day, max ~100 years). Owner only.

Error Codes

Code	Constant	Description
u100	err-owner-only	Action restricted to contract owner
u101	err-not-found	Will or beneficiary not found
u102	err-unauthorized	Unauthorized access attempt
u103	err-already-exists	Will already exists for this user
u104	err-not-deceased	Testator must be declared deceased
u105	err-already-claimed	Inheritance already claimed
u106	err-invalid-beneficiary	Invalid beneficiary designation
u107	err-will-locked	Will is locked and cannot be modified
u108	err-inactivity-not-met	Inactivity period not yet reached
u109	err-invalid-amount	Invalid amount or allocation

Usage Example

Creating a Will

;; Create will with executor
(contract-call? .digital-will create-will 
  "I leave my assets to my family. Distribute according to beneficiary allocations." 
  (some 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7))

Adding Beneficiaries

;; Add spouse with 50% allocation
(contract-call? .digital-will add-beneficiary 
  'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7
  u50
  "Primary residence and investment accounts")

;; Add child with 50% allocation
(contract-call? .digital-will add-beneficiary 
  'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159
  u50
  "Educational trust and personal items")

Depositing Assets

;; Deposit 1000 STX to vault
(contract-call? .digital-will deposit-to-vault u1000000000)

Recording Activity

;; Reset inactivity timer (recommended monthly)
(contract-call? .digital-will record-activity)

Claiming Inheritance

;; Beneficiary claims their share after death declaration
(contract-call? .digital-will claim-inheritance 
  'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7)

Security Features

• ✅ Authorization Checks: All critical functions verify caller identity
• ✅ Will Locking: Prevents unauthorized modifications
• ✅ Single-Claim Protection: Beneficiaries can only claim once
• ✅ Executor Verification: Only designated executors can declare death
• ✅ Input Validation: All user inputs are validated
• ✅ Inactivity Safeguards: Automatic death declaration after prolonged absence
• ✅ Fee Caps: Platform fees limited to maximum 10%

Best Practices

1. Regular Activity Recording: Record activity monthly to prevent premature death declaration
2. Choose Trusted Executors: Select reliable individuals as executors
3. Verify Allocations: Ensure beneficiary percentages total 100%
4. Lock When Final: Lock your will once satisfied with all provisions
5. Add Witnesses: Have multiple witnesses confirm your will
6. Keep Descriptions Clear: Use detailed asset descriptions for beneficiaries
7. Test Small Deposits First: Start with small amounts before large deposits

Technical Specifications

• Blockchain: Stacks (Bitcoin-anchored)
• Language: Clarity
• Token Support: STX (native token)
• Max Testament Length: 500 characters
• Max Asset Description: 200 characters
• Default Inactivity Period: ~1 year (5,184,000 blocks)
• Default Platform Fee: 1% (100 basis points)