System Components

Architecture Overview

Aqua's hybrid architecture consists of six core components that work together to provide seamless liquidity aggregation for tokenized assets. The system combines off-chain price discovery with on-chain execution to optimize both performance and security.

Aqua Flow

Off-Chain Components

Off-Chain Backend

Purpose: Handles quote aggregation and price discovery Technology: API server with RFQ (Request for Quote) engine

The off-chain backend serves as the intelligence layer of Aqua:

  • Quote Aggregation: Collects prices from multiple issuers and market makers

  • Best Price Selection: Analyzes all available quotes to determine optimal execution

  • Signed Quote Generation: Creates cryptographically signed quotes using EIP-712 standard

  • Trade Initiation: Provides endpoints for users to request quotes and initiate trades

Key Features:

  • Real-time price aggregation from multiple sources

  • EIP-712 signature generation for on-chain verification

  • RESTful API interface for seamless integration

  • High-performance quote processing and caching

On-Chain Components

Manager Contract

Type: Upgradeable Solidity contract Role: Primary entry point for all trade execution

The Manager Contract orchestrates the entire on-chain execution flow:

  • Quote Verification: Validates EIP-712 signatures from the off-chain backend

  • Routing Logic: Determines which executor contract to use for each trade

  • Trade Coordination: Manages the complete trade execution process

  • Security Enforcement: Implements access controls and safety checks

Core Functions:

function executeQuote(SignedQuote quote) external
function verifyQuoteSignature(SignedQuote quote) internal
function routeToExecutor(address issuer, TradeParams params) internal

Token Registry

Type: Upgradeable on-chain registry contract Purpose: Central repository of all supported tokenized assets

The Token Registry maintains a comprehensive mapping of available assets:

  • Asset Mapping: Links stock symbols to token contract addresses

  • Issuer Association: Associates each token with its respective issuer

  • Multi-Issuer Support: Enables multiple issuers to list the same asset

  • Access Control: Role-based permissions for token registration

Registry Structure:

struct TokenInfo {
    address tokenContract;
    address issuer;
    string symbol;
    bool isActive;
}

mapping(string => TokenInfo[]) public tokensBySymbol;
mapping(address => TokenInfo) public tokensByContract;

Access Controls:

  • Issuers can register their own tokens

  • System admin can manage registry settings

  • Users have read-only access for price discovery

Executor Registry

Type: Upgradeable registry contract Purpose: Maps issuers to their specific executor contracts

The Executor Registry enables modular integration of different issuer protocols:

  • Issuer-Executor Mapping: Links each issuer to their custom executor contract

  • Protocol Adaptation: Enables support for different token standards and trading interfaces

  • Administrative Control: Only system owner can register or update executors

  • Upgrade Safety: Supports safe upgrades of executor implementations

Registry Functions:

function registerExecutor(address issuer, address executor) external onlyOwner
function getExecutor(address issuer) external view returns (address)
function updateExecutor(address issuer, address newExecutor) external onlyOwner

Executor Contracts

Type: Issuer-specific adaptor contracts Purpose: Handle actual token transfers and payments

Executor contracts serve as protocol adaptors for each issuer:

  • Protocol Abstraction: Standardizes interaction with diverse issuer protocols

  • Trade Execution: Performs actual token transfers and payment processing

  • Custom Logic: Implements issuer-specific trading rules and requirements

  • Safety Mechanisms: Includes validation and error handling for each issuer's protocol

Standard Interface:

interface IExecutor {
    function executeBuy(address user, string symbol, uint256 amount, uint256 price) external;
    function executeSell(address user, string symbol, uint256 amount, uint256 price) external;
    function validateTrade(TradeParams params) external view returns (bool);
}

Executor Types:

  • Mint/Burn Executors: For issuers using mint/burn mechanisms

  • Transfer Executors: For issuers using token transfer models

  • Marketplace Executors: For issuers with marketplace-based trading

Issuer Token Contracts

Type: External contracts owned by individual issuers Purpose: Actual tokenized asset implementation

These are the external contracts that Aqua integrates with:

  • Token Implementation: The actual tokenized stock contracts

  • Payment Handling: Processes payments for token purchases/sales

  • Compliance Logic: Implements issuer-specific compliance requirements

  • Asset Backing: Manages the underlying asset representation

Integration Patterns:

  • Direct Token Contracts: Simple ERC-20 style tokenized stocks

  • Marketplace Contracts: Full trading platforms with order books

  • Custodial Contracts: Contracts managing underlying asset custody

Component Interactions

Trade Execution Flow

  1. User Request: User requests quote through frontend or API

  2. Quote Aggregation: Off-chain backend queries all registered issuers

  3. Best Quote Selection: Backend selects optimal quote and signs it

  4. On-Chain Execution: User submits signed quote to Manager Contract

  5. Verification: Manager Contract verifies quote signature and validity

  6. Routing: Manager queries Executor Registry to find appropriate executor

  7. Execution: Executor contract interacts with issuer's token contract

  8. Settlement: Tokens and payments are transferred according to trade terms

Registry Management

  • Token Registration: Issuers register their tokens in Token Registry

  • Executor Deployment: System admin deploys and registers executor contracts

  • Updates: Registries support upgrades for new features and improvements

Security Model

Access Controls

  • Registry Permissions: Role-based access for different registry operations

  • Executor Authorization: Only authorized executors can perform trades

  • Signature Verification: All quotes must be cryptographically signed

Safety Mechanisms

  • Quote Expiration: Time-limited quotes prevent stale price execution

  • Trade Validation: Multiple validation layers before execution

  • Circuit Breakers: Emergency stops for unusual market conditions

Scalability Considerations

Off-Chain Optimization

  • Parallel Quote Processing: Simultaneous requests to multiple issuers

  • Caching Mechanisms: Efficient price data caching and updates

  • Load Balancing: Distributed backend infrastructure

On-Chain Efficiency

  • Gas Optimization: Minimal on-chain computation and storage

  • Batch Processing: Support for multiple trade execution in single transaction

  • Upgradeable Contracts: Future improvements without migration costs

Last updated