Skip to main content

Architecture

This page provides an overview of the rwapool.xyz protocol's technical architecture, including its components, interactions, and design principles.

System Overview​

The rwapool.xyz protocol is built on a modular architecture that combines on-chain and off-chain components to create a secure, scalable, and efficient system for managing real-world assets on the blockchain.

High-Level Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                        User Interfaces                          │
│  (Web App, API, SDK, Command Line Interface)                    │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                      Protocol Core Layer                        │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐            │
│  │  Pool       │   │  Asset      │   │  Governance │            │
│  │  Management │   │  Management │   │  System    │            │
│  └─────────────┘   └─────────────┘   └─────────────┘            │
│                                                                 │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐            │
│  │  Yield      │   │  Risk       │   │  Treasury   │            │
│  │  Generation │   │  Management │   │  Management │            │
│  └─────────────┘   └─────────────┘   └─────────────┘            │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                    Blockchain Infrastructure                     │
│  (Smart Contracts, Oracles, Cross-Chain Bridges)                │
└───────────────────────────────┬─────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                     Off-Chain Components                         │
│  (Legal Framework, Asset Custody, Compliance, Analytics)         │
└─────────────────────────────────────────────────────────────────┘

Detailed Architecture Diagram​

The following diagram provides a more detailed view of the rwapool.xyz architecture, showing the specific layers and components that make up the system:

Layered Architecture​

As illustrated in the detailed architecture diagram above, the rwapool.xyz protocol is built on a seven-layer architecture. Each layer serves a specific purpose and interacts with other layers to create a comprehensive system for managing real-world assets on the blockchain.

1. User Layer​

This layer represents the entry point for users interacting with the rwapool.xyz protocol:

  • Wallet (EVM-Compatible): Standard Ethereum wallets that users connect to access the protocol
  • Session Keys (AA): Account Abstraction implementation allowing for improved UX with session-based authentication
  • KYC Verification: User identity verification process required for regulatory compliance

2. Access & Interface Layer​

This layer provides the interfaces through which users interact with the protocol:

  • DApp Frontend: The web application interface for users to interact with the protocol
  • Paymaster (Gasless Onboarding): Enables gas-free transactions for new users to reduce onboarding friction
  • Token/Badge Claim UI: Interface for claiming tokens, badges, or other credentials

3. Vault Layer​

At the core of the rwapool.xyz protocol is the Vault Layer, which implements the ERC-4626 standard:

  • ERC-4626 Vaults: Standardized tokenized vault implementation that provides a unified API for deposit/withdrawal and yield-bearing functions. The ERC-4626 standard offers several key advantages:

    • Composability: Easily integrates with other DeFi protocols
    • Standardization: Consistent interface for all vaults regardless of underlying assets
    • Accounting: Built-in accounting for shares and assets
    • Yield Accrual: Automatic handling of yield distribution
    • Interoperability: Seamless integration with existing ERC-20 tokens

  • RWA Asset Tokenization: Process of converting real-world assets into on-chain tokens that can be managed by the vaults

  • Share/NFT Issuance: Mechanism for issuing shares or NFTs representing ownership in the vaults

4. Compliance Engine​

This layer ensures the protocol adheres to regulatory requirements:

  • Access Controls (ACLs): Granular permission system controlling who can access which parts of the protocol
  • Sumsub / IDfy Integration: Third-party KYC/AML service integrations for identity verification
  • Blacklist / Freeze Hooks: Mechanisms to restrict or freeze addresses based on compliance requirements

5. Bridge & Settlement Layer​

This layer handles cross-chain operations and asset transfers:

  • Stablecoin Bridge (USDC/USDT): Facilitates the movement of stablecoins across different blockchain networks
  • Arbitrary Messaging (LayerZero, Lumia): Cross-chain messaging protocols for communication between different blockchains
  • Vault State Sync: Ensures vault states are synchronized across different chains

6. Liquidity & Routing Layer​

This layer manages liquidity and cross-chain participation:

  • OFT-Based Liquidity Pools: Omnichain Fungible Token standard for cross-chain liquidity provision
  • Cross-Chain Vault Participation: Allows users to participate in vaults across different blockchain networks
  • Optional Staking Layer: Provides additional yield opportunities through staking mechanisms

7. Governance & Security Layer​

This layer handles protocol governance and security measures:

  • Multisig Governance: Multi-signature wallet governance for protocol decisions
  • Time-Locked Upgrades: Delayed implementation of protocol upgrades for security
  • Emergency Pause Switch: Mechanism to pause protocol operations in case of emergencies

Smart Contract Implementation​

The rwapool.xyz protocol's smart contract system implements these layers through several interconnected modules:

ERC-4626 Vault Contracts​

  • VaultFactory: Creates and initializes new ERC-4626 compliant vaults
  • VaultRegistry: Maintains a registry of all deployed vaults
  • VaultController: Manages vault operations and parameters
  • VaultToken: ERC-20 token representing vault shares, compliant with ERC-4626

Asset Contracts​

  • AssetRegistry: Tracks all tokenized real-world assets
  • AssetVault: Securely holds tokenized assets using ERC-4626 standard
  • AssetTokenizer: Converts real-world assets to on-chain tokens
  • AssetOracle: Provides price and valuation data for assets

Compliance Contracts​

  • AccessController: Manages access controls and permissions
  • IdentityVerifier: Interfaces with KYC/AML providers
  • ComplianceRegistry: Maintains compliance status of users and assets

Off-Chain Infrastructure​

rwapool.xyz relies on several off-chain components that support the on-chain layers:

  • Asset Management System: Tracks and manages real-world assets
  • Legal Framework: Ensures legal compliance and asset ownership
  • Analytics Engine: Provides insights and performance metrics
  • Risk Management System: Monitors and manages protocol risks
  • Compliance System: Ensures regulatory compliance

Investment Flow​

Data Flow​

The layered architecture of rwapool.xyz facilitates several key data flows that enable the protocol's functionality. Understanding these flows helps illustrate how the different layers interact with each other.

Asset Onboarding Flow​

This flow demonstrates how real-world assets are brought on-chain and made available in the rwapool.xyz protocol:

  1. Asset Documentation: Asset owners submit legal documentation through the User Layer
  2. KYC Verification: Identity verification occurs in the Compliance Engine
  3. Asset Validation: Legal and compliance checks are performed
  4. Tokenization: The asset is tokenized in the Vault Layer using the ERC-4626 standard
  5. Registration: The tokenized asset is registered in the protocol
  6. Availability: The asset becomes available for investment in vaults

Cross-Chain Investment Flow​

This flow shows how users can invest in vaults across different blockchain networks:

  1. User Connection: User connects wallet through the User Layer
  2. Interface Interaction: User selects investment options in the Access & Interface Layer
  3. Bridge Utilization: Funds are bridged through the Bridge & Settlement Layer if cross-chain investment is needed
  4. Vault Deposit: Funds are deposited into ERC-4626 vaults in the Vault Layer
  5. Share Issuance: Vault shares are issued to the user according to the ERC-4626 standard
  6. State Synchronization: Vault state is synchronized across chains via the Bridge & Settlement Layer

Yield Distribution Flow​

This flow illustrates how yield is generated and distributed to vault participants:

  1. Yield Generation: Real-world assets generate yield (e.g., rental income, interest)
  2. Yield Capture: The yield is captured by the Vault Layer
  3. Accounting: The ERC-4626 vault automatically accounts for the yield
  4. Distribution: Yield is distributed to vault share holders according to their proportional ownership
  5. Cross-Chain Distribution: For cross-chain participants, yield is distributed via the Bridge & Settlement Layer

Governance Decision Flow​

This flow demonstrates how governance decisions are made and implemented:

  1. Proposal Creation: Governance proposals are created in the Governance & Security Layer
  2. Voting: Stakeholders vote on proposals
  3. Approval: Approved proposals are queued in the Time-Locked Upgrades system
  4. Execution: After the timelock period, changes are implemented across relevant layers
  5. Cross-Chain Synchronization: Governance decisions affecting multiple chains are synchronized via the Bridge & Settlement Layer

Cross-Chain Architecture​

rwapool.xyz's cross-chain architecture leverages the Bridge & Settlement Layer and Liquidity & Routing Layer to enable seamless operations across multiple blockchain networks. The ERC-4626 standard plays a crucial role in this architecture by providing a consistent interface for vaults across all supported chains.

Primary Networks​

  • Ethereum: Core governance and high-value assets, hosting the primary ERC-4626 vaults
  • Polygon: Main user operations and medium-value assets, with optimized gas costs for frequent interactions
  • Arbitrum: Yield optimization and specialized pools, leveraging L2 scalability for complex strategies
  • Optimism: Fast operations and experimental features, with quick transaction finality

Cross-Chain Vault System​

The ERC-4626 standard enables a unified vault system across all chains:

  • Standardized Interface: The same deposit/withdraw functions and accounting system on all chains
  • Chain-Specific Optimizations: Each chain's implementation can be optimized for its specific characteristics
  • Consistent Yield Calculation: Standardized yield calculation and distribution across all chains
  • Unified Share Representation: Vault shares maintain consistent meaning and value across chains

Cross-Chain Communication​

  • Arbitrary Messaging: Using protocols like LayerZero and Lumia for secure cross-chain communication
  • Stablecoin Bridges: Dedicated bridges for USDC/USDT to ensure liquidity across chains
  • Vault State Sync: Synchronization of vault states to maintain consistency across networks
  • OFT-Based Liquidity: Omnichain Fungible Token standard for cross-chain liquidity provision
  • Unified Governance: Coordinated decision-making across chains through the Governance & Security Layer

Scalability Design​

rwapool.xyz's scalability is built into the seven-layer architecture, with each layer designed to scale independently and collectively:

Vault Layer Scalability​

  • ERC-4626 Efficiency: The ERC-4626 standard provides gas-efficient operations for deposits, withdrawals, and yield distribution
  • Batched Operations: Support for batched transactions to reduce gas costs for multiple operations
  • Optimized Asset Management: Efficient asset management within vaults to minimize transaction costs

Cross-Chain Scalability​

  • Layer 2 Integration: Leveraging L2 solutions like Arbitrum and Optimism for cost-effective operations
  • Sharded Operations: Distributing workload across multiple chains based on specific use cases
  • Chain-Specific Optimization: Tailoring implementations to each chain's strengths and fee structures

Technical Scalability​

  • Modular Architecture: Independent components that can be upgraded separately across all seven layers
  • Optimized Gas Usage: Efficient contract design to minimize costs, especially in the Vault Layer
  • Stateless Design Patterns: Minimizing on-chain state to reduce gas costs and improve throughput
  • Event-Driven Architecture: Using events for off-chain indexing and processing to reduce on-chain computation

Security Architecture​

Security is integrated into each of the seven layers of the rwapool.xyz architecture:

User Layer Security​

  • Account Abstraction: Enhanced security through session keys and improved user experience
  • KYC Verification: Identity verification to prevent unauthorized access and ensure compliance

Vault Layer Security​

  • ERC-4626 Implementation: The standardized ERC-4626 interface has been extensively tested and follows best practices
  • Formal Verification: Mathematical proof of correctness for core vault contracts
  • Invariant Testing: Comprehensive testing of vault accounting invariants

Compliance Engine Security​

  • Access Control Matrix: Granular permissions for all system operations
  • Blacklist/Freeze Mechanisms: Ability to restrict or freeze addresses based on compliance requirements

Governance & Security Layer​

  • Multisig Governance: Multi-signature wallet governance for critical protocol decisions
  • Time-Locked Upgrades: Delayed implementation of protocol upgrades for security
  • Emergency Pause Switch: Circuit breakers to pause protocol operations in case of emergencies

Cross-Layer Security​

  • Defense in Depth: Multiple security layers protecting critical functions across all seven layers
  • Secure Cross-Chain Communication: Robust security for cross-chain messaging and asset transfers
  • Rate Limiting: Protection against flash loan attacks and other rapid exploitation attempts

Future Architecture​

The rwapool.xyz architecture roadmap builds upon the current seven-layer design with enhanced capabilities:

Enhanced ERC-4626 Implementation​

  • Extended ERC-4626 Features: Additional extensions to the ERC-4626 standard for specialized RWA use cases
  • Multi-Asset Vaults: Support for multiple assets within a single ERC-4626 vault
  • Programmable Yield Distribution: Advanced yield distribution mechanisms based on user parameters

Advanced Cross-Chain Capabilities​

  • ZK-Rollup Integration: Enhanced privacy and scalability for vault operations
  • Unified Liquidity: Seamless liquidity sharing across all supported chains
  • Cross-Chain Governance: Enhanced governance mechanisms that operate consistently across all chains

Next-Generation Features​

  • Mobile Application: Native mobile app for iOS and Android providing on-the-go access to the rwapool.xyz protocol
  • Decentralized Identity: Improved compliance with privacy-preserving identity verification
  • AI-Powered Risk Management: Advanced risk assessment and mitigation for real-world assets
  • DAO-Based Governance: Fully decentralized protocol management across all layers
  • Real-Time Settlement: Instant cross-chain settlement for improved capital efficiency