ChainGuard Vault System

Version: 1.0.0
Last Updated: 18-11-2025
Status: Production Ready

Table of Contents

Overview

The ChainGuard Vault System provides non-custodial smart wallet infrastructure that enables users to securely manage digital assets across multiple blockchain networks. The system is built on smart contracts deployed on Base, Arbitrum, and Optimism, with guardian-mediated gasless transactions and comprehensive security controls.

Component Map

Smart Contracts

1. ChainFiVault

Purpose: User-owned smart wallet contract
Features:

  • Multi-asset support (ETH, ERC20, ERC721, ERC1155)
  • Dual-signature enforcement (owner + auth addresses)
  • Guardian-mediated gasless transactions
  • Emergency fallback paths (direct gas payment)
  • Deterministic vault addresses

2. ChainFiVaultFactory

Purpose: Deterministic vault deployment
Features:

  • Clones pattern for gas-efficient deployment
  • Guardian protection mechanisms
  • Version management
  • Integration with Registry and Whitelist

3. ChainFiVaultRegistry

Purpose: Canonical vault registry
Features:

  • Owner ↔ vault mapping
  • Version tracking
  • Single-vault-per-user policy
  • Vault metadata storage

4. WhitelistRegistry

Purpose: Contract and token whitelisting
Features:

  • Guardian address management
  • Whitelisted contract addresses
  • Token metadata storage
  • Category-based whitelisting

5. ChainFiMarketPlace

Purpose: On-chain NFT marketplace
Features:

  • Guardian-verified listings
  • ERC721 and ERC1155 support
  • Emergency unlisting capabilities
  • Integration with vault system

Guardian Workflow

Guardian Workflow Diagram

Guardian Role

The Guardian (Forwarder Server / Payment Service) acts as a trusted intermediary that:

  • Verifies transaction signatures (owner + auth)
  • Submits meta-transactions (gasless)
  • Pays gas fees on behalf of users
  • Validates transactions against whitelist
  • Provides emergency pause capabilities

Important: The guardian role is the "payment server" in the vault context. This terminology clarifies the guardian's function as a transaction facilitator, not a custodian.

Guardian Protection

Guardian State Management:

  • Guardian address can be updated via multi-signature
  • Guardian protection can be enabled/disabled
  • Emergency pause capabilities
  • Guardian verification for critical operations

Security:

  • Guardian cannot access user funds
  • Guardian cannot bypass signature requirements
  • Guardian only facilitates approved transactions
  • Users can bypass guardian by paying gas directly

Lifecycle Flows

Vault Creation Flow

Text Flow:

1. User initiates vault creation
   ↓
2. User signs vault creation message (EIP-712)
   - Owner address signature
   - Auth address signature
   ↓
3. Forwarder Server (Guardian) verifies signatures
   ↓
4. Guardian signs creation message
   ↓
5. ChainFiVaultFactory creates vault (deterministic address)
   ↓
6. ChainFiVaultRegistry registers vault
   ↓
7. Vault address returned to user

Key Features:

  • Deterministic vault addresses (same address across chains)
  • Multi-signature required (owner + auth + guardian)
  • Gasless creation (guardian pays gas)
  • Single vault per user policy

Asset Deposit Flow

1. User transfers assets to vault address
   ↓
2. Assets received by ChainFiVault contract
   ↓
3. Vault balance updated
   ↓
4. Event emitted for tracking
   ↓
5. Blockchain Listener detects deposit
   ↓
6. User balance updated in system

Supported Assets:

  • ETH (native)
  • ERC20 tokens
  • ERC721 NFTs
  • ERC1155 multi-token

Asset Withdrawal Flow (Gasless)

Text Flow:

1. User initiates withdrawal via OAuth Portal
   ↓
2. User signs withdrawal message (EIP-712)
   - Owner address signature
   - Auth address signature
   ↓
3. OAuth Portal sends request to Forwarder Server
   ↓
4. Forwarder Server (Guardian) verifies signatures
   ↓
5. Guardian checks whitelist (if applicable)
   ↓
6. Guardian submits meta-transaction (gasless)
   ↓
7. Smart contract verifies signatures on-chain
   ↓
8. Assets transferred to recipient
   ↓
9. Transaction logged and broadcast

Asset Withdrawal Flow (Direct Gas Payment)

Text Flow:

1. User initiates withdrawal directly
   ↓
2. User signs withdrawal message (EIP-712)
   ↓
3. User submits transaction with gas payment
   ↓
4. Smart contract verifies signatures
   ↓
5. Assets transferred to recipient

Emergency Fallback:

  • Users can always bypass guardian
  • Direct gas payment option available
  • No dependency on guardian for access
  • Full user control maintained

Emergency Fallback & Recovery

Emergency Withdrawal Functions

ChainGuard Vault provides always-accessible emergency withdrawal functions that allow users to directly withdraw their assets by paying gas fees, completely bypassing the guardian (payment server). These functions are critical safety features that ensure users maintain full control over their assets at all times.

Available Emergency Functions

1. emergencyWithdrawEther(uint256 amount, bytes memory signature)

  • Access: Owner address only (onlyOwnerDirect modifier)
  • Purpose: Direct ETH withdrawal to owner's wallet
  • Requirements: Owner signature (EIP-712), gas payment
  • Bypasses: Guardian mediation, subscription requirements

2. emergencyWithdrawERC20(address token, uint256 amount, bytes memory signature)

  • Access: Owner address only (onlyOwnerDirect modifier)
  • Purpose: Direct ERC20 token withdrawal to owner's wallet
  • Requirements: Owner signature (EIP-712), gas payment
  • Bypasses: Guardian mediation, subscription requirements

3. emergencyWithdrawERC721(address nftContract, uint256 tokenId, bytes memory signature)

  • Access: Owner address only (onlyOwnerDirect modifier)
  • Purpose: Direct ERC721 NFT withdrawal to owner's wallet
  • Requirements: Owner signature (EIP-712), gas payment
  • Bypasses: Guardian mediation, subscription requirements
  • Additional: Automatically unlists NFT from marketplace if listed

4. emergencyWithdrawERC1155(address nftContract, uint256 id, uint256 amount, bytes memory signature)

  • Access: Owner address only (onlyOwnerDirect modifier)
  • Purpose: Direct ERC1155 multi-token withdrawal to owner's wallet
  • Requirements: Owner signature (EIP-712), gas payment
  • Bypasses: Guardian mediation, subscription requirements
  • Additional: Automatically unlists NFT from marketplace if listed

Key Characteristics

Always Accessible:

  • ✅ Available to all users regardless of subscription tier
  • ✅ Works even in free mode (no subscription required)
  • ✅ No dependency on guardian service availability
  • ✅ No dependency on ChainGuard infrastructure
  • ✅ Direct on-chain execution

Security Features:

  • Owner signature required (EIP-712 typed data)
  • Nonce-based replay protection
  • Reentrancy guards
  • Automatic marketplace unlisting (for NFTs)
  • On-chain signature verification

Use Cases:

  • Guardian service unavailable
  • Subscription expired or cancelled
  • User prefers direct control
  • Emergency situations
  • Recovery scenarios

Fallback Address Recovery

The vault system includes a fallback address mechanism that provides an additional recovery path for users.

Fallback Address Purpose

Recovery Mechanism:

  • Secondary address for recovery operations
  • Can be used for emergency access
  • Separate from owner and auth addresses
  • User-controlled and configurable

Fallback Address Management:

  • Set during vault creation
  • Can be modified via modifyFallbackAddress() (requires owner + auth signatures)
  • Stored in vault state and registry
  • 24-hour cooldown period for changes

Security:

  • Fallback address changes require dual signatures (owner + auth)
  • Cooldown period prevents rapid changes
  • Guardian-mediated updates (or direct owner control)
  • Registry tracking for audit trail

Free Mode Access

Critical Feature: Emergency withdrawal functions are always accessible, even when users are in free mode or have no active subscription.

Free Mode Guarantees:

  • ✅ Emergency withdrawals work without subscription
  • ✅ No guardian service required
  • ✅ Direct on-chain execution
  • ✅ Users pay gas fees directly
  • ✅ Full asset control maintained

Why This Matters:

  • Users never lose access to their assets
  • No lock-in based on subscription status
  • True non-custodial design
  • User sovereignty preserved
  • Recovery always possible

Always-Accessible Withdrawal

The emergency withdrawal functions provide a guaranteed path for users to withdraw their assets to their wallet, regardless of:

  • Subscription status (free mode, paid, expired)
  • Guardian service availability
  • ChainGuard infrastructure status
  • Payment processing issues
  • Service outages

Withdrawal Flow (Emergency Path):

1. User signs withdrawal message (EIP-712)
   - Owner signature only (no auth signature required)
   ↓
2. User submits transaction directly to blockchain
   - Pays gas fees from their wallet
   ↓
3. Smart contract verifies owner signature
   ↓
4. Assets transferred to owner's wallet
   ↓
5. Transaction complete (no guardian involvement)

Comparison: Standard vs Emergency Withdrawal

FeatureStandard Withdrawal (Gasless)Emergency Withdrawal (Direct)
Guardian RequiredYes (for gasless execution)No (bypasses guardian)
Subscription RequiredYes (for guardian service)No (works in free mode)
Gas FeesPaid by guardianPaid by user
Signatures RequiredOwner + AuthOwner only
Access LevelPremium featureAlways available
Use CaseNormal operationsEmergency/recovery

Important Notes:

  • Emergency withdrawals are always available as a safety mechanism
  • Users maintain full control regardless of service status
  • No dependency on ChainGuard infrastructure for emergency access
  • True non-custodial design ensures user sovereignty

Security Controls

Dual-Signature Enforcement

Signature Requirements:

  • Owner Address: Primary wallet address (user-controlled)
  • Auth Address: Secondary wallet address (user-controlled, often 2FA wallet)
  • Both Required: All transactions require signatures from both addresses

Security Benefits:

  • Prevents single-point-of-failure
  • Requires explicit approval from both wallets
  • Reduces risk of unauthorized transactions
  • Maintains user control

On-Chain Signature Verification

EIP-712 Typed Data Signing:

  • Structured data signing standard
  • Prevents signature replay attacks
  • Clear transaction intent
  • Cryptographic proof of authorization

Verification Process:

  1. User signs message off-chain (Mobile App or desktop wallet)
  2. Signature included in transaction
  3. Smart contract verifies signature on-chain
  4. Transaction executed only if signature valid

Guardian Verification

Guardian Role:

  • Verifies signatures before submission
  • Validates against whitelist
  • Submits meta-transactions
  • Pays gas fees

Guardian Security:

  • Cannot access user funds
  • Cannot bypass signature requirements
  • Only facilitates approved transactions
  • Emergency pause capabilities

Whitelist Enforcement

WhitelistRegistry:

  • Manages whitelisted contract addresses
  • Token metadata storage
  • Category-based whitelisting
  • Guardian address management

Whitelist Checks:

  • External contract interactions validated
  • Token transfers checked against whitelist
  • Marketplace operations verified
  • Emergency unlisting capabilities

Emergency Controls

Emergency Pause:

  • Multi-signature team pause
  • Guardian pause capabilities
  • Emergency withdrawal paths
  • System-wide pause (if needed)

Fallback Mechanisms:

  • Direct gas payment option
  • Emergency withdrawal functions
  • User-controlled fallback address
  • No dependency on guardian

Multi-Chain Support

Supported Networks

Base Sepolia (Chain ID: 84532)

  • ✅ Vault contracts deployed
  • ✅ Production ready

Arbitrum Sepolia (Chain ID: 421614)

  • ✅ Vault contracts deployed
  • ✅ Production ready

Optimism Sepolia (Chain ID: 11155420)

  • ✅ Vault contracts deployed
  • ✅ Production ready

Polygon (Future)

  • 🔄 Cross-chain compatibility planned

Cross-Chain Features

Deterministic Vault Addresses:

  • Same vault address across all chains
  • Salt-based deterministic deployment
  • Single vault per user across all chains
  • Unified user experience

Multi-Chain Asset Management:

  • Assets managed per chain
  • Cross-chain balance tracking
  • Unified dashboard view
  • Chain-specific operations

Transaction Types

ETH Transfers

Deposit:

  • Direct transfer to vault address
  • Automatic balance update
  • Event emission for tracking

Withdrawal:

  • Signature-based authorization
  • Guardian-mediated (gasless) or direct
  • On-chain verification
  • Balance update

ERC20 Token Transfers

Deposit:

  • Standard ERC20 transfer to vault
  • Token balance tracked
  • Event emission

Withdrawal:

  • Signature-based authorization
  • Whitelist validation (if enabled)
  • Guardian-mediated or direct
  • On-chain execution

ERC721 NFT Transfers

Deposit:

  • NFT transfer to vault
  • Token ownership tracked
  • Event emission

Withdrawal:

  • Signature-based authorization
  • Whitelist validation
  • Guardian-mediated or direct
  • On-chain execution

ERC1155 Multi-Token Transfers

Deposit:

  • Multi-token transfer to vault
  • Token balances tracked
  • Event emission

Withdrawal:

  • Signature-based authorization
  • Whitelist validation
  • Guardian-mediated or direct
  • On-chain execution

Gasless Transaction Architecture

Meta-Transaction Pattern

How It Works:

  1. User signs transaction message (EIP-712)
  2. Guardian verifies signature
  3. Guardian submits transaction as meta-transaction
  4. Guardian pays gas fees
  5. Smart contract verifies user signature
  6. Transaction executed

Benefits:

  • Users don't pay gas fees
  • Seamless user experience
  • Guardian covers transaction costs
  • Maintains non-custodial design

Direct Gas Payment Option

Emergency Fallback:

  • Users can always pay gas directly
  • Bypass guardian if needed
  • Full user control maintained
  • No dependency on guardian

Use Cases:

  • Guardian unavailable
  • User prefers direct control
  • Emergency situations
  • Testing and development

Audit & Compliance Features

Comprehensive Logging

Transaction Logging:

  • All vault operations logged
  • Signature verification events
  • Guardian actions tracked
  • Balance changes recorded

Event Categories:

  • Vault creation events
  • Deposit events
  • Withdrawal events
  • Transfer events
  • Emergency actions

Compliance-Ready

Audit Trail:

  • Complete transaction history
  • Signature verification records
  • Guardian action logs
  • User activity tracking

Regulatory Support:

  • ISO 27001 compliance
  • GDPR audit requirements
  • AML/CTF audit trails
  • Regulatory reporting capabilities

Key Principles

Non-Custodial Design

User Control:

  • Users control owner and auth addresses
  • Private keys never leave user devices
  • Users can bypass guardian anytime
  • Full asset control maintained

No Custody:

  • ChainGuard never holds user assets
  • Guardian facilitates but doesn't control
  • Smart contracts are user-owned
  • No custodial risk

Security by Design

Multi-Layer Security:

  • Dual-signature enforcement
  • On-chain verification
  • Guardian validation
  • Whitelist enforcement

Defense in Depth:

  • Multiple security layers
  • No single point of failure
  • Redundant verification
  • Emergency fallback paths

User Sovereignty

User Control:

  • Users own their vaults
  • Users control their keys
  • Users approve all transactions
  • Users can revoke guardian access

Transparency:

  • All operations on-chain
  • Verifiable transactions
  • Public audit trail
  • User visibility

Related Documentation

Document Version: 1.0.0
Last Updated: 18-11-2025
Status: Production Ready

Note: ChainGuard Core is a future feature not currently deployed. This document focuses on the current vault stack implementation.

ChevronLeft iconCompliance CenterProject ArchitectureChevronRight icon
ChainGuard Vault System | Technical Documentation | ChainGuard