ChainGuard System Architecture Overview

Version: 2.0.0
Last Updated: 18-11-2025
Status: Production System Architecture - ISO 27001 Ready

Table of Contents

Executive Summary

The ChainGuard System is a comprehensive Web3 security ecosystem providing non-custodial identity, authentication, and vault management services. The system consists of 7 core components (6 off-chain services + 1 on-chain vault stack) working together to deliver:

  • Identity & Authentication: OAuth 2.0 provider with wallet-based 2FA
  • Vault Management: Non-custodial smart wallets with dual-signature enforcement and guardian-mediated gasless transactions
  • On-Chain Infrastructure: Vault Factory, Registry, Whitelist, and Marketplace contracts deployed on Base, Arbitrum, and Optimism
  • Payment Processing: Stripe integration for subscriptions and vault creation
  • Blockchain Monitoring: Real-time transaction tracking and analytics
  • User Portal: Private workspace for account and application management
  • Mobile 2FA: Secure mobile authenticator for transaction signing
  • Public Documentation: Marketing site, compliance center, and technical docs

The architecture follows a microservices pattern with clear separation of concerns, horizontal scalability, and comprehensive security controls.

System Components

Application Components

1. ChainGuard DApp (Frontend) 🌐

Type: Public Marketing & Documentation Website
Technology: Next.js 15, TypeScript, SSR
Port: 3000 (production)
Status: ✅ Production Ready

Features:

  • Homepage & Product Pages
  • Compliance Center (11 jurisdictions)
  • Documentation Hub
  • FAQ System
  • Geo-Targeting System
  • Multi-Language Support (15+ languages)

2. ChainGuard Backend Server 🔐

Type: Core Authentication & Authorization Service
Technology: Node.js, Express, PostgreSQL, Redis
Port: 3001
Status: ✅ Production Ready

Services:

  • Authentication Service (JWT + 2FA)
  • OAuth 2.0 Provider
  • WebSocket Server (Socket.IO)
  • User Management
  • Wallet Management
  • Vault Coordination
  • Compliance Logging
  • Session Management

3. OAuth Portal (module.chain-fi.io) 🔒

Type: Private User Workspace
Technology: Next.js 15, TypeScript
Port: Internal deployment
Status: ✅ Production Ready

Features:

  • User Dashboard
  • OAuth Consent Screens
  • 2FA Setup & Verification
  • Wallet & Vault Management
  • Application Access Control
  • Activity History
  • Billing Integration

4. Forwarder Server (Payment Service) 💳

Type: Blockchain Transaction Relay & Payment Gateway
Technology: Node.js, Express, Ethers.js, Stripe
Port: 3000 (separate instance)
Status: ✅ Production Ready

Services:

  • Vault Creation Service
  • Meta-Transaction Relay
  • Stripe Payment Processing
  • Multi-Chain Support (Base, Arbitrum, Optimism)
  • Signature Verification
  • Wallet Validation

5. Blockchain Listener ⚡

Type: Real-Time Blockchain Monitor
Technology: Node.js, Express, Ethers.js, Redis, WebSocket
Port: 3005
Status: ✅ Production Ready

Services:

  • Block Listener Service
  • Transaction Analyzer
  • Transaction Decoder
  • Balance Service
  • Balance Checker
  • Provider Management
  • Registry Service
  • WebSocket Broadcasting

6. ChainGuard Mobile App 📱

Type: Mobile 2FA Authenticator
Technology: React Native, Expo, Socket.IO Client
Platform: iOS & Android
Status: ✅ Production Ready

Features:

  • QR Code Scanner
  • Wallet Generator & Manager
  • Transaction Signer
  • Secure Storage
  • Socket.IO Client
  • Transaction Renderer

7. ChainGuard Vault Stack 🔗

Type: Smart Contract Infrastructure (On-Chain)
Technology: Solidity 0.8.23, EIP-712, Deterministic Clones
Deployment: Base Sepolia (84532), Arbitrum Sepolia (421614), Optimism Sepolia (11155420)
Status: ✅ Production Ready

Smart Contracts:

  • ChainFiVault - User-owned smart wallets (ETH, ERC20, ERC721, ERC1155)
  • ChainFiVaultFactory - Deterministic vault deployment with guardian protection
  • ChainFiVaultRegistry - Canonical owner ↔ vault mapping and version tracking
  • WhitelistRegistry - Guardian address, whitelisted contracts, token metadata
  • ChainFiMarketPlace - On-chain NFT marketplace with guardian-verified listings

Key Features:

  • Non-custodial design (users control owner/auth keys)
  • Dual-signature enforcement (owner + auth addresses)
  • Guardian-mediated gasless transactions (guardian = payment server role)
  • Emergency fallback paths (direct gas payment)
  • Multi-asset support (ETH, ERC20, ERC721, ERC1155)
  • Deterministic vault addresses per user
  • Single-vault-per-user policy

Infrastructure Components

PostgreSQL Database 💾

Type: Primary Database
Port: 5432 (5433 in Docker)
Purpose: User data, OAuth clients, compliance events, file metadata

Redis Cache 💾

Type: Cache & Session Store
Port: 6379
Purpose: Sessions, rate limiting, real-time data, transaction cache

MinIO (S3-Compatible) 💾

Type: Object Storage
Ports: 9000 (API), 9001 (Console)
Purpose: Encrypted file storage

Hashicorp Vault 🔐

Type: Key Management
Port: 8200
Purpose: Secret management, encryption keys

High-Level Architecture

System Boundaries

ChainGuard Scope:

  • Backend Server (CG-BE)
  • OAuth Portal (module.chain-fi.io)
  • ChainGuard 2FA App
  • OAuth authorization and token issuance
  • API key tracking
  • User session JWTs
  • Vault smart contracts

Client Scope (External):

  • Client Backend (CL-BE) - Third-party client backend
  • Client Frontend (CL-FE) - Third-party client frontend
  • Client session management
  • Client data storage

Communication Patterns

Synchronous REST API Calls:

  • Request-Response pattern
  • User authentication, data retrieval, OAuth token exchange
  • All services use REST for standard CRUD operations

Asynchronous WebSocket Communication:

  • Event-driven, bidirectional
  • 2FA session coordination, real-time transaction updates
  • Components: Backend Server, Mobile App, OAuth Portal, Blockchain Listener

Message Queue (Redis Pub/Sub):

  • Publish-Subscribe pattern
  • Real-time event broadcasting, cross-service notifications
  • Blockchain Listener → Backend Server, Backend Server → Portal

Blockchain RPC Calls:

  • Request-Response (JSON-RPC)
  • Smart contract interactions, transaction submission, balance queries
  • Forwarder Server, Blockchain Listener

Smart Contract Interactions:

  • Meta-transactions with EIP-712 signatures
  • Vault creation, asset transfers, marketplace operations
  • Dual-signature enforcement (owner + auth), guardian verification, whitelist checks

Data Flow Overview

Data Flow Diagram

Authentication Flow

  1. User authenticates via OAuth Portal
  2. Backend Server validates credentials
  3. 2FA verification via Mobile App (wallet-based signature)
  4. JWT tokens issued for session management
  5. OAuth authorization for third-party applications

Vault Transaction Flow

  1. Application initiates transaction request
  2. OAuth Portal displays transaction for user approval
  3. User approves via Mobile App (2FA signature)
  4. Forwarder Server (Guardian) verifies signatures
  5. Guardian submits meta-transaction (gasless)
  6. Smart contract verifies signatures on-chain
  7. Transaction executed, logged, and broadcast

OAuth Flow

  1. Client Frontend redirects to OAuth Portal
  2. User authenticates and approves scopes
  3. Authorization code issued
  4. Client Backend exchanges code for tokens
  5. Client Backend uses tokens to fetch user data
  6. Tokens refreshed as needed

Security Architecture

Network Security Zones

Public Zone:

  • ChainGuard DApp (Public Website)
  • DDoS protection, WAF, rate limiting, SSL/TLS termination

DMZ / Edge Zone:

  • OAuth Portal (Authenticated user workspace)
  • Authentication required, no-index robots, session validation

Internal Services Zone:

  • Backend Server, Forwarder Server, Blockchain Listener
  • Internal network only, service-to-service authentication

Data Zone:

  • PostgreSQL, Redis, MinIO, Hashicorp Vault
  • No direct internet access, encrypted at rest, network segmentation

Authentication Layers

Layer 1: User Authentication

  • Email/password with bcrypt hashing
  • JWT tokens in HttpOnly cookies

Layer 2: Two-Factor Authentication (2FA)

  • Wallet-based cryptographic signatures (EIP-712)
  • Mobile device storage (keys never leave device)

Layer 3: OAuth 2.0 Authorization

  • Authorization code flow
  • Access tokens (short-lived), refresh tokens (long-lived, server-side only)

Authorization Mechanisms

  • Role-Based Access Control (RBAC): Backend Server, OAuth Portal
  • Scope-Based Access (OAuth): OAuth Service
  • Wallet Ownership Validation: Signature verification
  • Vault Access Control: Dual-signature enforcement (owner + auth), guardian verification

Storage Architecture

PostgreSQL Database

  • User accounts and profiles
  • OAuth clients and tokens
  • Compliance event logs
  • File metadata
  • Session data

Redis Cache

  • User sessions
  • Rate limiting counters
  • Real-time transaction cache
  • Pub/Sub messaging
  • Temporary data storage

MinIO Object Storage

  • Encrypted file storage
  • User-uploaded files
  • Encrypted file names
  • Version history

Hashicorp Vault

  • JWT secrets
  • Database credentials
  • Stripe API keys
  • Blockchain private keys (payment server)
  • Encryption keys

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 across chains
  • Multi-chain transaction monitoring
  • Cross-chain asset support
  • Unified user experience

Integration Points

External Services

Stripe API:

  • Payment processing
  • Subscription management
  • VAT calculation
  • Invoice generation

Sumsub API:

  • KYC/AML verification
  • Identity verification
  • Document verification
  • Ongoing monitoring (optional)

Blockchain RPC Providers:

  • Base, Arbitrum, Optimism RPC endpoints
  • Transaction submission
  • Block monitoring
  • Balance queries

System Status

Production Ready Components:

  • ✅ ChainGuard DApp (Frontend)
  • ✅ ChainGuard Backend Server
  • ✅ OAuth Portal
  • ✅ Forwarder Server (Payment Service)
  • ✅ Blockchain Listener
  • ✅ ChainGuard Mobile App
  • ✅ ChainGuard Vault Stack (5 smart contracts)

Infrastructure:

  • ✅ PostgreSQL Database
  • ✅ Redis Cache
  • ✅ MinIO Object Storage
  • ✅ Hashicorp Vault

Deployment:

  • ✅ Multi-region capable (UK/EU/US)
  • ✅ Docker containerization
  • ✅ Kubernetes orchestration ready
  • ✅ Production monitoring and alerting

Related Documentation

Document Version: 2.0.0
Last Updated: 18-11-2025
Status: Production System Architecture - ISO 27001 Ready

ChevronLeft iconCompliance CenterProject ArchitectureChevronRight icon
ChainGuard System Architecture Overview | Technical Documentation | ChainGuard