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

1. Deploy Executor Contract - Implement IExecutor interface for new issuer

2. Register in Executor Registry - Map issuer address to executor

3. Configure Token Registry - Register issuer's tokens with ISSUER_ROLE

4. Integration Testing - Validate end-to-end functionality

Contract Upgrades

1. Implementation Development - Create new contract version

2. Security Audit - Comprehensive security review

3. Staging Validation - Test on staging environment

4. Production Upgrade - Deploy with proper authorization

5. 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.