Programmable Bitcoin Vault Smart Contract

A secure, feature-rich Clarity smart contract for creating programmable Bitcoin vaults on Stacks blockchain with time-locks, multi-signature support, and configurable withdrawal limits.

Overview

This smart contract enables users to create secure vaults for storing STX tokens with advanced security features including time-locked withdrawals, daily spending limits, multi-signature approval mechanisms, and guardian-based access control.

Key Features

🔐 Security Features

• Time-Lock Protection: Set unlock dates to prevent premature withdrawals
• Daily Withdrawal Limits: Automatic spending caps that reset every ~144 blocks (~24 hours)
• Multi-Signature Support: Require multiple approvals for withdrawals
• Guardian System: Add trusted parties to co-manage vault access
• Emergency Mode: Global freeze capability for security incidents

💰 Vault Management

• Unlimited Vaults: Create up to 50 vaults per user
• Flexible Configuration: Update time-locks and limits after creation
• Active/Inactive Toggle: Pause vault operations without destroying the vault
• Balance Tracking: Real-time balance and withdrawal monitoring

🤝 Multi-Signature Workflow

1. Propose: Owner or guardian proposes a withdrawal
2. Approve: Required number of guardians approve the proposal
3. Execute: Once threshold met, withdrawal executes automatically

Core Functions

Vault Operations

create-vault

(create-vault (timelock-blocks uint) (daily-limit uint) (required-sigs uint))

Creates a new vault with specified parameters.

• timelock-blocks: Number of blocks before vault unlocks
• daily-limit: Maximum STX withdrawable per day
• required-sigs: Number of signatures needed for multi-sig withdrawals

deposit

(deposit (vault-id uint) (amount uint))

Deposits STX into a vault. Anyone can deposit into any active vault.

withdraw

(withdraw (vault-id uint) (amount uint))

Withdraws STX from vault (subject to time-lock, daily limits, and owner verification).

Guardian Management

add-guardian

(add-guardian (vault-id uint) (guardian principal))

Adds a trusted guardian to the vault. Only vault owner can add guardians.

remove-guardian

(remove-guardian (vault-id uint) (guardian principal))

Removes a guardian from the vault.

Multi-Signature Withdrawals

propose-withdrawal

(propose-withdrawal (vault-id uint) (withdrawal-id uint) (amount uint) (recipient principal))

Creates a withdrawal proposal requiring guardian approval.

approve-withdrawal

(approve-withdrawal (vault-id uint) (withdrawal-id uint))

Guardian approves a pending withdrawal proposal.

execute-withdrawal

(execute-withdrawal (vault-id uint) (withdrawal-id uint))

Executes approved withdrawal once signature threshold is met.

Configuration

update-timelock

(update-timelock (vault-id uint) (new-timelock uint))

Updates the vault's time-lock (must be future block height).

update-daily-limit

(update-daily-limit (vault-id uint) (new-limit uint))

Changes the daily withdrawal limit.

toggle-vault-status

(toggle-vault-status (vault-id uint))

Activates or deactivates the vault.

Read-Only Functions

get-vault-info

Returns complete vault information including balance, time-lock, limits, and settings.

get-vault-balance

Returns current vault balance.

get-user-vaults

Lists all vault IDs owned by a user.

is-vault-unlocked

Checks if vault has passed its time-lock period.

get-remaining-daily-limit

Returns how much can still be withdrawn today.

get-withdrawal-info

Returns details of a pending multi-sig withdrawal.

get-emergency-status

Checks if emergency mode is active.

Error Codes

Code	Error	Description
u100	err-owner-only	Action requires contract owner
u101	err-not-authorized	Caller lacks permission
u102	err-vault-locked	Vault is locked or inactive
u103	err-insufficient-balance	Not enough funds in vault
u104	err-invalid-amount	Amount must be greater than 0
u105	err-vault-exists	Vault limit reached
u106	err-vault-not-found	Vault ID doesn't exist
u107	err-withdrawal-limit	Daily limit exceeded
u108	err-cooldown-active	Cooldown period active
u109	err-invalid-timelock	Invalid time-lock value
u110	err-guardian-exists	Guardian already added
u111	err-not-guardian	Caller is not a guardian

Use Cases

1. Long-Term Savings Vault

Create a vault with a 1-year time-lock to prevent impulsive spending:

(create-vault u52560 u1000000 u1) ;; ~1 year, 1M STX daily limit

2. Business Treasury

Multi-signature vault requiring 3 of 5 executives to approve withdrawals:

(create-vault u144 u5000000 u3) ;; 1 day unlock, 5M daily limit, 3 sigs required

3. Estate Planning

Time-locked vault with family members as guardians:

(create-vault u262800 u10000000 u2) ;; ~5 years, 10M limit, 2 family approvals

4. Dollar-Cost Averaging

Short-term vault with strict daily limits for disciplined investing:

(create-vault u144 u100000 u1) ;; 1 day unlock, 100K daily limit

Security Considerations

• Time-Lock Immutability: Once set, time-locks can only be extended, not shortened
• Daily Limit Reset: Limits reset automatically every ~144 blocks
• Emergency Mode: Contract owner can freeze all vaults in case of security threat
• No Storage APIs: Contract uses in-memory state only (no localStorage/sessionStorage)
• Guardian Trust: Choose guardians carefully as they have withdrawal proposal powers

Deployment

1. Deploy contract to Stacks blockchain
2. Initialize with desired global parameters
3. Users create individual vaults with custom settings
4. Add guardians for multi-sig protection
5. Deposit funds and configure time-locks