Protocol Architecture - Multiliquid Protocol

System Overview

The Multiliquid Protocol is built on a modular, upgradeable architecture that enables atomic swaps between multiple permissioned Real World Asset (RWA) tokens and multiple stablecoins. The system is designed for institutional-grade operations with comprehensive risk management, transparent fee structures, and extensible integration patterns.

Design Principles

Modularity: Asset-specific logic isolated in delegate contracts
Upgradeability: UUPS proxy pattern enables secure evolution
Atomicity: All operations either fully succeed or fully revert
Transparency: All state changes emit comprehensive events
Extensibility: New assets can be integrated without modifying core logic

Core Contract System

The protocol consists of four primary contract categories that work together to enable secure, atomic swaps between RWAs and stablecoins.

How the Contracts Work Together

At the heart of the system, MultiliquidSwap acts as the central orchestrator that coordinates all swap operations. When a user initiates a swap, MultiliquidSwap queries Price Adapters to obtain real-time USD valuations for the assets involved, then calculates the exact amounts using WAD mathematics and applies the appropriate protocol fees. For added security, it calls RWA Delegates (if configured) to enforce volume limits and compliance checks before any tokens move. Finally, it delegates the actual token transfers to Stablecoin Delegates, which handle the asset-specific logic—whether minting new stablecoins, transferring from custody, or burning tokens. This separation of concerns ensures that each contract focuses on its specialized responsibility while maintaining atomic execution, meaning every swap either completes entirely or reverts with no partial state changes.

1. MultiliquidSwap Contract

Location: MultiliquidSwap.sol The central orchestrator managing all swap operations, fee calculations, and asset interactions.

Core Responsibilities

Swap Orchestration: Coordinates six types of swaps (RWA↔Stablecoin, RWA↔RWA, Stablecoin↔Stablecoin) with ExactIn and ExactOut variants
Fee Management: Calculates protocol fees using volume-based tiers
Price Calculation: Integrates with price adapters for USD-denominated valuation
Access Control: Enforces role-based permissions for all operations
Quote Generation: Provides view functions for off-chain quote calculation

View MultiliquidSwap Contract Details

Complete function signatures and implementation details

2. Stablecoin Delegate System

Base Contract: StablecoinDelegateBase.sol Stablecoin delegates handle asset-specific integration logic for each supported stablecoin.

Core Responsibilities

Stablecoin Operations: Mint, burn, or transfer stablecoins based on delegate type
RWA Whitelist Management: Maintain per-stablecoin RWA whitelists controlled by issuer admins
Fee Configuration: Set discount rates, redemption fees, and acceptance fees per RWA
Risk Controls: Pause mechanisms and compliance hooks for metadata validation
Custody Management: Manage RWA token custody addresses (for balance sheet delegates)

Delegate Types

Mint/Burn Delegates: Direct integration with stablecoins supporting native minting
Balance Sheet Delegates: Custody-based model for existing stablecoin liquidity balances without mint/burn integration

View Stablecoin Delegate Details

Complete interface and implementation details

3. RWA Delegate System

Base Contract: RWADelegate.sol RWA delegates provide optional risk management and compliance controls for specific RWA tokens. Only deployed when custom controls beyond token-native functionality are needed.

Core Responsibilities

Volume Limits: Enforce daily swap limits per wallet with configurable reset windows
Risk Validation: Validate RWA transfers with checkRWAIn() and checkRWAOut() hooks
Pause Controls: Issuer-controlled pause mechanism independent from protocol-wide pause
Compliance Metadata: Validate and pass through metadata for regulatory tracking

When to Use

RWA delegates are only required when additional risk management is needed beyond the RWA token’s native controls (e.g., built-in KYC, transfer restrictions).

View RWA Delegate Details

Complete interface and implementation details

4. Price Adapter System

Interface: IPriceAdapter.sol Price adapters provide USD-denominated pricing for all assets in the protocol.

Core Responsibilities

Price Provision: Return USD price in 18-decimal WAD format (1e18 = $1.00 USD)
Asset-Specific Integration: Query published NAV of the RWA
Standardization: Normalize pricing across different RWA token architectures

View Price Adapter Details

Complete adapter implementations and integration patterns

Operational Flow

Swap Execution Flow

Data Structures

RWA Information

struct RWAInfo {
    bool accepted;                    // Whether RWA is accepted for swaps
    uint8 decimals;                   // Token decimals (e.g., 6, 18)
    address rwaDelegate;              // Optional delegate address (address(0) if none)
    address priceAdapter;             // Price oracle adapter
    bool riskControlsActive;          // Whether delegate risk checks are enabled
}

Stablecoin Information

struct StablecoinInfo {
    bool accepted;                    // Whether stablecoin is accepted
    uint8 decimals;                   // Token decimals
    address stablecoinDelegate;       // Required delegate address
    address priceAdapter;             // Price oracle adapter
}

Fee Tier Structure

struct FeeTier {
    uint128 maxVolume;                // Maximum volume for this tier (WAD)
    uint128 fee;                      // Fee rate at this tier (WAD, where 1e18 = 100%)
}

Protocol fee tiers (volume-based):

Volume From	Volume To	Fee Rate	Basis Points
$0	$100,000	0.10%	10 bps
$100,000	$1,000,000	0.05%	5 bps
$1,000,000	$10,000,000	0.03%	3 bps
$10,000,000	$100,000,000	0.02%	2 bps
$100,000,000	∞	0.01%	1 bps

Discount and Redemption Fees

Discount Rate: Reduction applied to swap costs, set by stablecoin issuer per RWA

Stored as WAD percentage (1e18 = 100%)
Example: 5% discount = 5e16

Redemption Fee: Additional fee when swapping stablecoin → RWA

Charged by stablecoin issuer to discourage RWA redemptions
Stored as WAD percentage
Example: 0.5% redemption fee = 5e15

Permission Model

The protocol implements a comprehensive role-based access control system:

Global Roles

DEFAULT_ADMIN_ROLE

Full system control
Can upgrade contracts via UUPS
Can grant/revoke all other roles
Intended for multi-sig governance

OPERATOR_ROLE

Day-to-day operational control
Can accept new RWAs and stablecoins
Can update price adapters
Can set fee tiers
Cannot upgrade contracts

PAUSE_ROLE

Emergency pause capabilities
Can pause the entire MultiliquidSwap contract
Prevents all swap operations
Intended for security incidents

Asset-Specific Roles

Issuer Admin (Stablecoin) Each stablecoin delegate has its own issuer admin who can:

Set RWA discount rates for their stablecoin
Set RWA redemption fees for their stablecoin
Manage the RWA whitelist for their stablecoin
Pause their specific delegate
Configure custody addresses

Issuer Admin (RWA) Each RWA delegate has its own issuer admin who can:

Configure volume limits
Adjust risk parameters
Pause their specific delegate
Update compliance metadata requirements

Special Role

MULTILIQUID_SWAP_CONTRACT

Granted to the MultiliquidSwap contract address
Allows the swap contract to call delegate functions
Ensures only the central orchestrator can trigger swaps

Upgrade Mechanism

All core contracts use the UUPS (Universal Upgradeable Proxy Standard) pattern:

Upgrade Process

Preparation: New implementation contract is deployed
Testing: Comprehensive testing on testnet with identical configuration
Proposal: DEFAULT_ADMIN_ROLE proposes upgrade
Execution: Multi-sig approval and upgrade execution
Verification: Post-upgrade validation and monitoring

Upgrade Safety

Storage Gaps: All upgradeable contracts include storage gaps for future variables
Initialization Guards: Prevents re-initialization of upgraded contracts
Access Control: Only DEFAULT_ADMIN_ROLE can execute upgrades
Event Emission: All upgrades emit events for transparency

Storage Layout Preservation

When upgrading contracts, the storage layout must be preserved:

New variables can only be added at the end
Existing variables cannot be removed or reordered
Storage gaps provide buffer for new variables

Event System

The protocol emits comprehensive events for all state changes:

Swap Events

event SwapIntoRWA(
    bytes32 indexed rwaID,
    bytes32 indexed stablecoinID,
    address indexed user,
    uint256 rwaAmt,
    uint256 stablecoinAmt,
    uint256 feeAmt,
    uint256 redemptionFeeAmt,
    bytes stablecoinMetadata,
    bytes rwaMetadata
);

event SwapIntoRWAExactOut(
    bytes32 indexed rwaID,
    bytes32 indexed stablecoinID,
    address indexed user,
    uint256 rwaAmt,
    uint256 stablecoinAmt,
    uint256 feeAmt,
    uint256 redemptionFeeAmt,
    bytes stablecoinMetadata,
    bytes rwaMetadata
);

event SwapIntoStablecoin(
    bytes32 indexed stablecoinID,
    bytes32 indexed rwaID,
    address indexed user,
    uint256 stablecoinAmt,
    uint256 rwaAmt,
    uint256 feeAmt,
    bytes stablecoinMetadata,
    bytes rwaMetadata
);

event SwapIntoStablecoinExactOut(
    bytes32 indexed stablecoinID,
    bytes32 indexed rwaID,
    address indexed user,
    uint256 stablecoinAmt,
    uint256 rwaAmt,
    uint256 feeAmt,
    bytes stablecoinMetadata,
    bytes rwaMetadata
);

event RWAToRWASwap(
    bytes32 indexed rwaInID,
    bytes32 indexed rwaOutID,
    bytes32 indexed stablecoinID,
    address user,
    uint256 rwaInAmount,
    uint256 rwaOutAmount,
    uint256 protocolFeeAmt,
    uint256 redemptionFeeAmt,
    bytes rwaInMetadata,
    bytes rwaOutMetadata
);

event StablecoinToStablecoinSwap(
    bytes32 indexed stablecoinInID,
    bytes32 indexed stablecoinOutID,
    address indexed user,
    uint256 stablecoinInAmount,
    uint256 stablecoinOutAmount,
    uint256 protocolFeeAmt,
    uint256 acceptanceFeeAmt,
    uint256 redemptionFeeAmt,
    bytes stablecoinInMetadata,
    bytes stablecoinOutMetadata
);

Administrative Events

event RWAAcceptanceSet(
    bytes32 indexed rwaID,
    address indexed delegate,
    address indexed assetAddress,
    uint8 decimals,
    bool accepted
);

event StablecoinAcceptanceSet(
    bytes32 indexed stablecoinID,
    address indexed delegate,
    address indexed assetAddress,
    uint8 decimals,
    bool accepted,
    bool externalSwapper
);

event UpdateRWAUSDValue(
    bytes32 indexed rwaID,
    address priceAdapter
);

event UpdateStablecoinUSDValue(
    bytes32 indexed stablecoinID,
    uint256 value
);

event MultiliquidFeeTiersSet(FeeTier[] feeTiers);

event DiscountRateSet(
    bytes32 indexed stablecoinID,
    bytes32 indexed rwaID,
    uint256 rate
);

event RedemptionFeeSet(
    bytes32 indexed stablecoinID,
    bytes32 indexed rwaID,
    uint256 rate
);

event StablecoinAcceptanceFeeSet(
    bytes32 indexed stablecoinOutID,
    address indexed stablecoinIn,
    uint256 rate
);

event StablecoinRedemptionFeeSet(
    bytes32 indexed stablecoinOutID,
    address indexed stablecoinIn,
    uint256 rate
);

Extensibility

The protocol’s modular architecture enables straightforward extension:

Adding a New Stablecoin

Deploy Delegate: Create stablecoin delegate (mint/burn or balance sheet)
Configure Delegate: Set custody addresses, initial whitelists
Deploy Price Adapter: If custom pricing is needed
Register with MultiliquidSwap: Operator calls acceptStablecoin()
Test Integration: Validate swaps on testnet
Production Deployment: Enable on mainnet

Adding a New RWA

Technical Analysis: Review RWA token contract for compatibility
Deploy Delegate (optional): Only if custom risk controls needed
Deploy Price Adapter: Create adapter for USD pricing
Register with MultiliquidSwap: Operator calls acceptRWA()
Whitelist Configuration: Stablecoin issuers whitelist the new RWA
Test Integration: Validate swaps on testnet
Production Deployment: Enable on mainnet

Next: Security & Risk Management

Review the comprehensive security measures, access controls, and risk management framework

Overview

Core Components

Integration

​System Overview

​Design Principles

​Core Contract System

​How the Contracts Work Together

​1. MultiliquidSwap Contract

​Core Responsibilities

View MultiliquidSwap Contract Details

​2. Stablecoin Delegate System

​Core Responsibilities

​Delegate Types

View Stablecoin Delegate Details

​3. RWA Delegate System

​Core Responsibilities

​When to Use

View RWA Delegate Details

​4. Price Adapter System

​Core Responsibilities

View Price Adapter Details

​Operational Flow

​Swap Execution Flow

​Data Structures

​RWA Information

​Stablecoin Information

​Fee Tier Structure

​Discount and Redemption Fees

​Permission Model

​Global Roles

​Asset-Specific Roles

​Special Role

​Upgrade Mechanism

​Upgrade Process

​Upgrade Safety

​Storage Layout Preservation

​Event System

​Swap Events

​Administrative Events

​Extensibility

​Adding a New Stablecoin

​Adding a New RWA

Next: Security & Risk Management

System Overview

Design Principles

Core Contract System

How the Contracts Work Together

1. MultiliquidSwap Contract

Core Responsibilities

2. Stablecoin Delegate System

Core Responsibilities

Delegate Types

3. RWA Delegate System

Core Responsibilities

When to Use

4. Price Adapter System

Core Responsibilities

Operational Flow

Swap Execution Flow

Data Structures

RWA Information

Stablecoin Information

Fee Tier Structure

Discount and Redemption Fees

Permission Model

Global Roles

Asset-Specific Roles

Special Role

Upgrade Mechanism

Upgrade Process

Upgrade Safety

Storage Layout Preservation

Event System

Swap Events

Administrative Events

Extensibility

Adding a New Stablecoin

Adding a New RWA