Time-Locked Recovery System

A secure Clarity smart contract for Stacks blockchain that enables account recovery through trusted guardians with time-delayed execution.

Overview

This contract provides a robust account recovery mechanism that protects users from lost private keys while preventing unauthorized takeovers through mandatory time-lock periods.

Core Concepts

Guardian

A trusted individual or entity designated by the account owner who can initiate recovery on their behalf.

Time-Lock Period

A mandatory waiting period (1-30 days by default) between recovery initiation and execution, giving the legitimate owner time to cancel fraudulent recovery attempts.

Recovery Process

1. Account owner sets up recovery configuration with a guardian
2. If access is lost, guardian initiates recovery
3. Time-lock period begins
4. After time-lock expires, guardian executes recovery
5. Account ownership transfers to the new address

Key Features

• Configurable Time-Locks: Set custom waiting periods within admin-defined boundaries
• Guardian Management: Designate and update trusted recovery agents
• Recovery History: Complete audit trail of all recovery events
• Cancel Protection: Original owner can cancel pending recoveries
• Activation Controls: Enable/disable recovery without removing configuration
• Fee-Based Spam Prevention: Recovery initiation requires STX payment
• Multi-Recovery Support: Track multiple recovery events per account

Functions

User Functions

setup-recovery

(setup-recovery (guardian principal) (time-lock-period uint))

Initialize recovery configuration for your account.

• guardian: Principal address of trusted recovery agent
• time-lock-period: Waiting period in blocks (144-4320 blocks)

update-recovery-config

(update-recovery-config (guardian principal) (time-lock-period uint))

Modify existing recovery settings. Requires no pending recoveries.

initiate-recovery

(initiate-recovery (account principal) (new-owner principal))

Guardian-only function to start recovery process. Requires recovery fee payment.

execute-recovery

(execute-recovery (account principal))

Guardian completes recovery after time-lock expires. Transfers ownership and configuration.

cancel-recovery

(cancel-recovery)

Account owner cancels their pending recovery immediately.

deactivate-recovery / reactivate-recovery

Temporarily disable or re-enable recovery capability without deleting configuration.

Read-Only Functions

• get-recovery-config: View account's recovery settings
• get-pending-recovery: Check active recovery attempts
• get-recovery-history: Retrieve past recovery records
• get-recovery-count: Total recoveries performed on account
• is-recovery-ready: Verify if time-lock has elapsed
• get-min-time-lock / get-max-time-lock: View time-lock boundaries
• get-recovery-fee: Check current recovery initiation cost

Admin Functions

• set-min-time-lock: Adjust minimum time-lock period
• set-max-time-lock: Adjust maximum time-lock period
• set-recovery-fee: Update recovery initiation fee

Security Features

Protection Against Attacks

• Self-Recovery Prevention: Cannot set yourself as guardian or recovery address
• Time-Lock Enforcement: Mandatory waiting period prevents instant takeovers
• Single Recovery Limit: One pending recovery at a time
• Guardian Authorization: Only designated guardian can initiate/execute
• Cancellation Rights: Original owner maintains control during time-lock

Error Handling

The contract includes comprehensive error codes:

• u100: Owner-only operation
• u101: Configuration not found
• u102: Unauthorized access
• u103: Configuration already exists
• u104: Time-lock still active
• u105: No pending recovery
• u106: Invalid time-lock period
• u107: Self-recovery attempt
• u108: Recovery already executed

Usage Example

Setting Up Recovery

;; Alice sets up recovery with Bob as guardian, 1-day time-lock
(contract-call? .time-locked-recovery setup-recovery 'SP2BOB... u144)

Initiating Recovery

;; Bob initiates recovery to new address for Alice
(contract-call? .time-locked-recovery initiate-recovery 'SP2ALICE... 'SP2ALICE-NEW...)

Executing Recovery

;; After 144 blocks, Bob completes the recovery
(contract-call? .time-locked-recovery execute-recovery 'SP2ALICE...)

Canceling Fraudulent Recovery

;; Alice detects unauthorized recovery and cancels it
(contract-call? .time-locked-recovery cancel-recovery)

Configuration Defaults

• Minimum Time-Lock: 144 blocks (~1 day)
• Maximum Time-Lock: 4,320 blocks (~30 days)
• Recovery Fee: 1,000,000 microSTX (1 STX)

Best Practices

1. Choose Trusted Guardians: Select someone reliable who won't collude against you
2. Set Appropriate Time-Locks: Balance security (longer) vs. accessibility (shorter)
3. Monitor Your Account: Regularly check for pending recoveries
4. Secure Guardian's Keys: Guardian compromise can lead to account takeover
5. Update Contact Info: Ensure guardian can reach you during time-lock period
6. Test the Process: Consider test runs with minimal-value accounts first

Limitations

• Guardian must maintain access to their keys
• No built-in dispute resolution mechanism
• Recovery fee is non-refundable
• Time-lock cannot be bypassed even in emergencies
• Contract owner has administrative privileges