Overview

Architecture Overview

Aqua's smart contract infrastructure consists of five core components that work together to enable multi-issuer tokenized asset aggregation. The system implements a hub-and-spoke architecture with the Manager Contract as the central coordinator and specialized registry and executor contracts handling specific responsibilities.

Contract Architecture Diagram

graph TB
    User[User/Frontend] 
    Manager[Manager Contract<br/>AggregatorManager]
    TokenReg[Token Registry<br/>TokenRegistry]
    ExecReg[Executor Registry<br/>ExecutorRegistry]
    Exec1[Executor A<br/>IssuerA_Executor]
    Exec2[Executor B<br/>IssuerB_Executor]
    Token1[Token A<br/>AAPL_IssuerA]
    Token2[Token B<br/>AAPL_IssuerB]
    
    User -->|1. Submit Quote| Manager
    Manager -->|2. Verify Token| TokenReg
    TokenReg -->|3. Return Issuer| Manager
    Manager -->|4. Get Executor| ExecReg
    ExecReg -->|5. Return Executor| Manager
    Manager -->|6. Execute Trade| Exec1
    Manager -->|6. Execute Trade| Exec2
    Exec1 -->|7. Interact with| Token1
    Exec2 -->|7. Interact with| Token2
    
    subgraph "Registry Layer"
        TokenReg
        ExecReg
    end
    
    subgraph "Execution Layer"
        Exec1
        Exec2
    end
    
    subgraph "Token Layer"
        Token1
        Token2
    end
    
    style Manager fill:#e1f5fe
    style TokenReg fill:#f3e5f5
    style ExecReg fill:#f3e5f5
    style Exec1 fill:#e8f5e8
    style Exec2 fill:#e8f5e8

Contract Relationships

Central Coordination

Manager Contract (Hub)

Serves as the single entry point for all trade execution
Coordinates between registries and executors
Implements EIP-712 signature verification for quotes
Maintains upgradeability through UUPS pattern

Registry Layer

Token Registry

Maps token symbols to contract addresses and issuers
Implements role-based access control (ISSUER_ROLE)
Supports multi-issuer tokens for the same underlying asset
Provides token validation and issuer lookup services

Executor Registry

Maps issuer addresses to their executor contracts
Maintains simple address-to-address mapping
Enables dynamic executor updates and hot-swapping
Supports system expansion with new issuers

Execution Layer

Executor Contracts

Implement standardized IExecutor interface
Adapt between Manager Contract and issuer-specific protocols
Handle issuer-specific business logic and authentication
Enable support for diverse issuer architectures

Data Flow Architecture

Trade Execution Flow

sequenceDiagram
    participant U as User
    participant M as Manager
    participant TR as Token Registry
    participant ER as Executor Registry
    participant E as Executor
    participant T as Token Contract

    U->>M: executeQuote(signedQuote)
    
    Note over M: Verify EIP-712 signature
    Note over M: Check nonce and expiry
    
    M->>TR: getIssuerForToken(tokenAddress)
    TR-->>M: issuerAddress
    
    M->>ER: getExecutor(issuerAddress)
    ER-->>M: executorAddress
    
    alt Buy Operation
        M->>E: executeBuy(user, token, amount, payment)
        E->>T: mint(user, amount)
        Note over E: Handle payment processing
    else Sell Operation
        M->>E: executeSell(user, token, amount, payout)
        E->>T: burn(user, amount)
        Note over E: Handle payout processing
    end
    
    E-->>M: execution result
    M-->>U: transaction complete
    
    Note over M: Emit TradeExecuted event

Security and Upgrade Framework

Access Control Matrix

Contract

Upgrade Authorization

Admin Functions

Special Roles

Manager

Owner only

Signer updates, registry addresses

Owner

Token Registry

DEFAULT_ADMIN_ROLE

Token management

ISSUER_ROLE

Executor Registry

Owner only

Executor registration

Owner

Executors

Varies by implementation

Issuer-specific

Implementation-dependent

UUPS Upgradeability

Consistent Pattern Across All Core Contracts

function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}

Upgrade Safety Measures

Storage layout preservation requirements
Initialize pattern for proxy compatibility
Version control and rollback capabilities
Emergency upgrade procedures for security incidents

Contract Interactions

Manager ↔ Registry Integration

Token Registry Queries

getIssuerForToken(address) - Resolve token to issuer
isTokenActive(address) - Verify token availability

Executor Registry Queries

getExecutor(address) - Resolve issuer to executor contract

Manager ↔ Executor Integration

Standardized Interface Calls

executeBuy(address, address, uint256, uint256) - Process buy orders
executeSell(address, address, uint256, uint256) - Process sell orders

Parameter Flow

User address for token delivery/collection
Token contract for asset identification
Amount for quantity specification
Payment/payout for value transfer

System Evolution

Adding New Issuers

Deploy Executor Contract - Implement IExecutor interface for new issuer
Register in Executor Registry - Map issuer address to executor
Configure Token Registry - Register issuer's tokens with ISSUER_ROLE
Integration Testing - Validate end-to-end functionality

Contract Upgrades

Implementation Development - Create new contract version
Security Audit - Comprehensive security review
Staging Validation - Test on staging environment
Production Upgrade - Deploy with proper authorization
Post-Upgrade Monitoring - Verify successful operation

Gas Optimization Strategy

Efficient Query Patterns

Single external calls for registry lookups
Minimal state changes during execution
Optimized storage layouts across contracts
Event indexing for off-chain efficiency

Transaction Cost Management

Batch operations where possible
Storage slot packing for related variables
Reduced validation logic in hot paths
Pre-computed values for frequent operations

This smart contract architecture provides a robust, scalable, and secure foundation for Aqua's multi-issuer tokenized asset aggregation platform, enabling efficient trade execution while maintaining operational flexibility and system evolution capabilities.

Last updated 25 days ago