Verification Wallet Smart Contract

An Ethereum smart contract that protects funds in a "primary" wallet by requiring a separate "verification" wallet for large transfers and offering a failover "secondary" wallet.

🚀 Quick Commands

# Start local blockchain
npm run anvil

# Deploy contract
npm run deploy

# Run tests
npm run test

# Start with funded contract
npm run start

🔐 Security Model

The VerificationVault implements a three-wallet security model:

• Primary Wallet: Initiates regular withdrawals up to daily limits
• Verification Wallet: Controls limits, emergency functions, and security parameters (⚠️ NEVER stores funds)
• Secondary Wallet: Emergency backup that receives extracted funds with time-limited forwarding capabilities

Critical Security Feature: No Funds to Verifier

The verification wallet is designed to NEVER receive funds from the contract. This is enforced through:

• Constructor validation preventing verifier from being primary or secondary
• Runtime checks in all transfer functions (require(to != verifier))
• Emergency extraction only sends to secondary wallet

🏗️ Architecture

Daily Limit System

• Primary wallet can withdraw up to a configurable daily limit
• Rolling 24-hour window based on block.timestamp / 1 days
• Verifier can temporarily bypass limits with allowAnyAmountNextTransaction

Emergency Extraction

1. Verifier blocks primary wallet
2. Verifier triggers extractAllToSecondary() - sends all funds to secondary
3. Secondary has 1-2 hours (configurable) to forward funds
4. After deadline, secondary is automatically blocked

Access Control

• Primary: primaryWithdraw(to, amount)
• Verifier: setDailyLimit(), blockPrimary(), extractAllToSecondary(), etc.
• Secondary: secondaryForward(to, amount) (time-limited)

🛠️ Technical Details

• Solidity Version: ^0.8.20
• Dependencies: OpenZeppelin ReentrancyGuard
• Gas Optimized: Uses immutable addresses, efficient storage patterns
• Reentrancy Protected: All external calls protected

📦 Installation

# Clone and install dependencies
git clone <repository-url>
cd verification-wallet
npm install

# Install Foundry (if not already installed)
curl -L https://foundry.paradigm.xyz | bash
foundryup

🚀 Quick Start

Compile Contracts

npm run compile
# or
forge build

Run Tests

npm run test
# or
forge test -vvv

Gas Analysis

npm run test-gas
# or
forge test --gas-report

🧪 Testing

The test suite includes comprehensive coverage:

• ✅ Constructor validation and access controls
• ✅ Daily limit enforcement and bypass mechanisms
• ✅ Emergency extraction and secondary forwarding
• ✅ Critical security: No funds to verifier validation
• ✅ Reentrancy attack protection
• ✅ Edge cases and failure scenarios

Key Test Scenarios

// Daily limit enforcement
testPrimaryCanWithdrawBelowDailyLimit()
testPrimaryCannotExceedDailyLimit()

// Emergency procedures
testExtractAllToSecondary()
testSecondaryCannotForwardToVerifier()

// Security validations
testCannotSendToVerifierInAnyContext()
testReentrancyProtection()

🔧 Usage

Deployment

VerificationVault vault = new VerificationVault(
    primaryAddress,    // EOA or multisig for regular use
    verifierAddress,   // Multisig for governance (NEVER receives funds)
    secondaryAddress,  // EOA or multisig for emergency backup
    dailyLimitWei     // Initial daily limit in wei
);

Daily Operations

// Deposit funds (anyone can deposit)
vault.deposit{value: amount}();

// Primary wallet withdraws (up to daily limit)
vault.primaryWithdraw(recipient, amount);

// Verifier adjusts security parameters
vault.setDailyLimit(newLimit);
vault.setAllowAnyAmountNextTransaction(true); // One-time bypass

Emergency Procedures

// 1. Verifier blocks compromised primary
vault.blockPrimary(true);

// 2. Extract all funds to secondary
vault.extractAllToSecondary();

// 3. Secondary forwards funds within deadline
vault.secondaryForward(safeAddress, amount);

⚠️ Security Considerations

Address Generation

• Smart contracts cannot generate private keys
• Use externally generated addresses (EOAs, hardware wallets, multisigs)
• Recommended: Gnosis Safe multisig for verifier wallet

Time-based Operations

• Uses block.timestamp for daily limits and deadlines
• Minor miner manipulation possible (~15 seconds)
• Choose extraction windows conservatively (1-2 hours)

Wallet Recommendations

• Primary: Hardware wallet or EOA for regular access
• Verifier: Multisig (2-of-3 or 3-of-5) for governance only
• Secondary: Hardware wallet or multisig for emergency recovery

Critical Rules

1. Never send funds to the verifier address
2. Verifier is governance-only, not a funds-holding wallet
3. Use multisig for verifier to prevent single points of failure
4. Test on testnets before mainnet deployment

📊 Contract API

Core Functions

Function	Caller	Description
primaryWithdraw(to, amount)	Primary	Withdraw up to daily limit
setDailyLimit(newLimit)	Verifier	Update withdrawal limit
blockPrimary(blocked)	Verifier	Emergency block/unblock
extractAllToSecondary()	Verifier	Emergency fund extraction
secondaryForward(to, amount)	Secondary	Time-limited forwarding

View Functions

Function	Returns	Description
getDailySpent()	uint256	Amount spent today
remainingDailyLimitToday()	uint256	Remaining daily allowance
getSecondaryStatus()	(bool,bool,uint256)	Active, blocked, deadline
getBalance()	uint256	Contract ETH balance

🔍 Events

event Deposit(address indexed sender, uint256 amount);
event PrimaryWithdrawal(address indexed to, uint256 amount);
event DailyLimitChanged(uint256 oldLimit, uint256 newLimit);
event AllowAnyToggled(bool enabled);
event PrimaryBlocked(bool blocked);
event ExtractedToSecondary(uint256 amount);
event SecondaryForwarded(address indexed to, uint256 amount);
event SecondaryFinalized(bool blocked);

🗂️ Project Structure

verification-wallet/
├── src/
│   └── Contract.sol          # VerificationVault implementation
├── test/
│   └── Contract.t.sol        # Comprehensive test suite
├── lib/
│   ├── forge-std/           # Foundry testing framework
│   └── openzeppelin-contracts/
├── foundry.toml             # Foundry configuration
├── package.json             # npm scripts and dependencies
└── README.md               # This file

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: npm run test
5. Submit a pull request

⚖️ License

MIT License - see LICENSE file for details.

🚨 Disclaimer

This smart contract is for educational and experimental purposes. Audit thoroughly before deploying real funds. The authors assume no responsibility for lost funds or security vulnerabilities. Always test on testnets first and consider professional security audits for production use.