> For the complete documentation index, see [llms.txt](https://block-street.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://block-street.gitbook.io/docs/architecture/system-components.md).

# 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](/files/XBgVT0EAvqbrCaBIVDNb)

## 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**:

```solidity
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**:

```solidity
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**:

```solidity
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**:

```solidity
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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://block-street.gitbook.io/docs/architecture/system-components.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.