Quantillon Protocol Architecture

Signed quotes are active on Base since 17 October 2026. See Signed Quotes in Production for verified bindings, transaction wrappers and emergency-mode limits.

Current production controls

See Production Protocol Reference for the dated configuration. The oracle supplies valuation; SignedExecutionPricing verifies exact transaction-bound quotes and signed hedge admission; SignedReferenceSource supplies independently checked valuation reports. Its spread reserve is excluded from backing. A valid oracle mid alone is not an executable mint/redeem quote. Core role administration belongs to the TimelockController; peripheral administration remains with the Safe.

Overview

The Quantillon Protocol is a sophisticated DeFi ecosystem built around a euro-pegged stablecoin (QEURO) with advanced yield management and risk mitigation systems. The architecture is designed for scalability, security, and efficient capital utilization.

The staking layer now supports a multi-vault model through stQEUROFactory: each staking vault has its own non-fungible staking token instance (stQEURO{vaultName}).

Versioning. Every core contract implements IVersioned.version() (a pure semver getter reflecting the deployed implementation); linked libraries expose version() and inlined libraries carry a VERSION constant. Any change to a deployed contract/library must be traced through a semver bump (enforced by make check-version-bump); deployments/{chainId}/versions.json records the live version + commit per contract. See Deployment.md → "Versioning & Provenance".

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        SYSTEM ARCHITECTURE                      │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Layer    │    │ Protocol Layer  │    │  Yield Layer    │
├─────────────────┤    ├─────────────────┤    ├─────────────────┤
│ • Retail Users  │───▶│ • QuantillonVault│    │ • Ext. Vaults   │
│ • Institutional │    │ • QEUROToken    │    │ • YieldShift    │
│ • Liquidity     │    │ • QTIToken      │    └─────────────────┘
│   Providers     │    │ • FeeCollector  │             │
└─────────────────┘    │ • UserPool      │             │
                       │ • HedgerPool    │             │
                       │ • stQEUROToken  │             │
                       └─────────────────┘             │
                                │                      │
                       ┌─────────────────┐             │
                       │Infrastructure   │             │
                       │Layer            │             │
                       ├─────────────────┤             │
                       │ • OracleRouter  │             │
                       │ • TimeProvider  │             │
                       │ • Security Libs │             │
                       └─────────────────┘             │
                                │                      │
                       ┌─────────────────┐             │
                       │External Systems │             │
                       ├─────────────────┤             │
                       │ • Morpho        │◀────────────┘
                       │   (MetaMorpho)  │
                       │ • Hyperliquid   │
                       │ • Chainlink     │
                       │ • Base Network  │
                       └─────────────────┘

Core Components

1. QuantillonVault

Purpose: Central vault managing QEURO minting and redemption against USDC collateral.

Key Responsibilities:

Overcollateralized QEURO minting
USDC collateral management
Oracle price validation
Liquidation-mode redemption when protocol CR is at or below the critical ratio (101%)
Fee collection and distribution

Architecture Patterns:

Proxy Pattern: Upgradeable implementation
Access Control: Role-based permissions
Reentrancy Protection: Secure external calls
Circuit Breaker: Emergency pause mechanisms

2. QEUROToken

Purpose: Euro-pegged stablecoin with compliance and governance features.

Key Features:

ERC-20 compliant with extensions
Mint/burn controls via vault
Compliance features (whitelist/blacklist)
Rate limiting mechanisms
Supply cap management

Architecture Patterns:

Factory Pattern: Controlled token creation
Observer Pattern: Event-driven compliance
State Machine: Pause/unpause states

3. QTIToken

Purpose: Governance token with vote-escrow mechanics for protocol governance.

Status: dormant. No mint path is wired in the deployed contract, so total supply is 0 and lock/vote/propose are inactive until a future activation upgrade mints the cap. The features below describe the intended design.

Key Features:

Vote-escrow token mechanics
Time-weighted voting power
Governance proposal system
Delegation capabilities
Lock period management

Architecture Patterns:

Escrow Pattern: Time-locked voting power; topping up an existing lock recomputes voting power over the full merged position (not just the added amount)
Voting System: On-chain self-execution — the token holds GOVERNANCE_ROLE, so a passed proposal executes its own role-gated calldata after a mandatory post-vote timelock (PROPOSAL_EXECUTION_DELAY, 2 days). Activation requires the applicable core admin controller to grant governance permissions through the timelock, along with a mint/distribution upgrade.
Decay Function: Linear voting power decay

4. UserPool

Purpose: Optional batch front-end for deposits (USDC → QEURO through the vault) and QEURO staking with an unstaking cooldown.

Key Features:

Batched USDC deposit / QEURO withdrawal routed through QuantillonVault
QEURO staking with requestUnstake → 7-day cooldown → unstake
Pending-withdrawal escrow when a USDC transfer to the user fails
User position tracking (getUserInfo)
No reward claim: user yield accrues through stQEURO (ERC-4626 share price)

Architecture Patterns:

Pool Pattern: Centralized escrow of staked QEURO
Cooldown Gate: Time-locked unstaking
State Tracking: User position management

5. HedgerPool

Purpose: Manages leveraged hedging positions for risk management.

Key Features:

EUR/USD hedging positions
Margin management system
Liquidation mechanisms
Position tracking and PnL calculation
Risk parameter management

Architecture Patterns:

Position Management: Individual position tracking
Margin System: Collateral and leverage management
Liquidation Engine: Automated risk management
Oracle Integration: Price feed validation

6. stQEUROToken

Purpose: Yield-bearing wrapper for QEURO with automatic yield accrual.

Key Features:

Automatic yield distribution via exchange rate
Exchange rate = totalAssets() / totalSupply(); totalAssets() includes principal plus linearly vested QEURO yield, while newly credited yield remains excluded until syncVesting() advances the schedule
No lock-up period — unstake at any time
Virtual protection against donation attacks

Architecture Patterns:

Wrapper Pattern: Enhanced token functionality
Yield Distribution: Exchange rate increases as yield accrues
Virtual Protection: Attack prevention mechanisms

6b. stQEUROFactory (Multi-Vault Extension)

Purpose: Factory/orchestrator that deploys one stQEUROToken proxy per staking vault.

Key Features:

Per-vault token deployment using ERC1967Proxy and shared stQEUROToken implementation
Deterministic registry and lookup mappings:
- vaultId -> stQEURO token
- vault -> stQEURO token
- stQEURO token -> vaultId
Strict vault self-registration model (msg.sender is the registered vault)
Validation and uniqueness guarantees for vaultId and vaultName (uppercase alphanumeric)
Governance-controlled factory config (implementation/yieldShift/treasury/token admin)

Architecture Patterns:

Factory Pattern: Dynamic deployment of homogeneous staking-token proxies
Registry Pattern: Bi-directional mapping between vaults and staking tokens
Role-Gated Self-Registration: Vault onboarding constrained by governance-granted role + on-chain self-call

7. FeeCollector

Purpose: Centralized fee collection and distribution across the protocol.

Key Features:

Collects fees from QuantillonVault (mint/redeem fees)
Distributes to three beneficiaries: treasury (60%), dev fund (25%), community (15%)
Governance-controlled ratio updates
Per-token fee accounting

Architecture Patterns:

Pull Pattern: Beneficiaries withdraw collected fees
Split Pattern: Configurable fee ratio distribution

8. OracleRouter

Purpose: Oracle-agnostic price routing — all protocol contracts interact with OracleRouter via IOracle.

Key Features:

Holds two EUR/USD oracle slots and routes all IOracle reads to the active one
Slot 0 = ChainlinkOracle (fallback); slot 1 = HyperliquidEurUsdOracle (active since the governance switch of 2026-06-25)
Governance switches sources at runtime via switchOracle — no protocol-contract changes
updateOracleAddresses repoints a slot; OracleSwitched event on switch

9. EUR/USD Oracles (HyperliquidEurUsdOracle · ChainlinkOracle · StorkOracle)

Purpose: EUR/USD pricing with freshness checks, price bounds, and deviation circuit breakers. All implement IOracle, so the router (and thus the protocol) is source-agnostic.

Key Features:

HyperliquidEurUsdOracle (active): mirrors the Hyperliquid xyz:EUR perpetual mid — the venue where the protocol's EUR/USD hedge executes — so QEURO mint/redeem aligns with the hedge. Reads signed valuation from SignedReferenceSource (reports delivered with transactions) and delegates USDC/USD to the ChainlinkOracle. Configurable staleness (default 900s), bounds (0.80–1.40e18), 5% deviation circuit breaker, last-valid fallback.
ChainlinkOracle (fallback): Chainlink AggregatorV3 EUR/USD + USDC/USD; 2-hour EUR/USD staleness (25h for USDC/USD, matching its daily heartbeat), 5% deviation circuit breaker. Also the protocol's USDC/USD validation source.
StorkOracle: Stork Network TemporalNumericValue feeds (legacy/parked; the slot-1 position is now occupied by HyperliquidEurUsdOracle).
Mock versions available (MockChainlinkOracle, MockStorkOracle) for local/testnet.
Full design: Oracle Architecture.

9b. Signed reference and execution modules

SignedReferenceSource 1.0.0 accepts authenticated reports with their original observation time and an independent-reference check. SignedExecutionPricing 1.1.0 validates exact execution authorizations and cumulative hedge-capacity reports. The production maximum quote lifetime is 45 seconds; the separate normal report-age limit is 60 seconds.

SlippageStorage and publication batchers remain historical deployments. The recurring publisher is retired. See Signed Quotes in Production for binding addresses and the zero emergency budget.

10. TimeProvider

Purpose: Centralized block.timestamp wrapper for consistent time management across all contracts.

Yield Management Architecture

YieldShift System

Purpose: Intelligent yield distribution between user and hedger pools.

Components:

Yield Sources: external staking vaults (MetaMorpho live via MetaMorphoStakingVaultAdapter; Morpho/Aave adapters for localhost), protocol fees, interest differentials
Distribution Engine: Dynamic allocation between pools
Performance Metrics: Yield tracking and optimization
Rebalancing Logic: Automatic pool rebalancing

Architecture Patterns:

Strategy Pattern: Multiple yield source strategies
Observer Pattern: Performance monitoring
Factory-Routed Distribution: Yield routed by vaultId through stQEUROFactory to the correct staking token

External Staking Vault Integration

Purpose: Yield generation by deploying protocol USDC into external yield vaults (MetaMorpho live in production; Morpho/Aave adapters available).

Features:

USDC deployment per vaultId via QuantillonVault.deployUsdcToVault
Yield harvesting and distribution via harvestAndDistributeVaultYield
One stQEURO series per vault (isolated yield accounting)
Governance-gated exposure decisions per vault

Architecture Patterns:

Adapter Pattern: thin IExternalStakingVault adapters wrap each external vault
Factory Registry: stQEUROFactory maps vaultId to adapter + stQEURO series
Yield Optimization: Dynamic allocation strategies
Vault-Aware Routing: harvested external-vault yield is split by QuantillonVault.harvestAndDistributeVaultYield (staked allocation after haircut / unstaked allocation to treasury / haircut only to hedger); YieldShift.addYield(vaultId, ...) stays available for other authorized sources

Security Architecture

Access Control System

Role-Based Access Control (RBAC):

MINTER_ROLE / BURNER_ROLE: QEUROToken — vault-only mint/burn
PAUSER_ROLE: QEUROToken emergency pause and minting killswitch
COMPLIANCE_ROLE: QEUROToken blacklist/whitelist management
GOVERNANCE_ROLE: Parameter updates and contract wiring across all core contracts (on FeeCollector it also gates upgrades)
EMERGENCY_ROLE: Emergency pause and withdrawal across all core contracts; oracle circuit breakers
VAULT_OPERATOR_ROLE: QuantillonVault — deployUsdcToVault (USDC deployment into any registered external vault adapter)
YIELD_DISTRIBUTOR_ROLE: QuantillonVault — harvestAndDistributeVaultYield / creditVaultYield
Hedging: no dedicated role — HedgerPool uses a single-hedger allowlist (setSingleHedger)
VAULT_FACTORY_ROLE: stQEUROFactory — vault self-registration
TREASURY_ROLE / FEE_SOURCE_ROLE: FeeCollector — fee distribution / authorized fee sources
ORACLE_MANAGER_ROLE: OracleRouter / ChainlinkOracle / HyperliquidEurUsdOracle / StorkOracle / LighterEurUsdOracle (inert) — feed updates, oracle switching
MANAGER_ROLE / WRITER_ROLE: SlippageStorage — store configuration / on-chain mid publishing
UPGRADER_ROLE: the plain-UUPS proxies (oracles, SlippageStorage) — direct Safe upgrades; the SecureUpgradeable core proxies are gated by the 12 h TimelockController instead

Security Patterns

Reentrancy Protection:

nonReentrant modifier on all state-changing functions
Checks-effects-interactions pattern
External call isolation

Oracle Security:

Multiple price feed validation
Staleness checks
Circuit breaker mechanisms
Price bound validation

Emergency Systems:

Pause/unpause mechanisms
Emergency withdrawal functions
Circuit breaker activation
Recovery procedures

Data Flow Architecture

QEURO Minting Flow

User approves USDC to the chosen Vault or UserPool target
  -> quote service returns exact execution + reference + capacity authorizations
  -> user reviews amount, output and expiry
  -> executeWithQuote(callData, authorization)
  -> signature, call binding, nonce, epoch and freshness checks
  -> reference delivery and current collateral/capacity checks
  -> USDC transfer, backing/spread accounting and QEURO mint
  -> receipt confirms Base settlement
  -> hedge engine reconciles and executes the separate venue hedge

All Base-side effects revert together if a settlement check fails. The later Hyperliquid operation is not atomic with Base. OracleRouter forwards valuation reads to HyperliquidEurUsdOracle and its signed reference source. A rejected price with isValid = false blocks the operation. The non-view oracle read can update its deviation baseline; simulations do not persist that update.

Yield Distribution Flow

Yield Distribution Flow (QuantillonVault.harvestAndDistributeVaultYield):
┌──────────┐  ┌───────────────┐  ┌──────────────┐  ┌───────────┐  ┌───────────────┐
│  Keeper  │  │QuantillonVault│  │ Ext. adapter │  │  stQEURO  │  │ hedger recip. │
│ (YIELD_  │  │               │  │ (MetaMorpho) │  │(per vault)│  │  / treasury   │
│DISTRIB.) │  │               │  │              │  │           │  │               │
└────┬─────┘  └───────┬───────┘  └──────┬───────┘  └─────┬─────┘  └───────┬───────┘
     │ harvestAndDistributeVaultYield(vaultId)      │              │
     ├─────────────▶│                  │            │              │
     │              │ harvestYieldToVault()         │              │
     │              ├─────────────────▶│            │              │
     │              │ realizedYield (USDC above tracked principal) │
     │              │◀─────────────────┤            │              │
     │              │ grossStaker = floor(realizedYield × rawStakedQEURO / totalQEURO)
     │              │ hedgerShare = floor(grossStaker × haircutBps / 10000)
     │              ├──────────────────────────────────────────────▶│
     │              │ userShare = grossStaker - hedgerShare → QEURO credit (share price rises as yield vests)
     │              ├───────────────────────────────▶│              │
     │              │ treasuryShare = realizedYield - grossStaker (USDC) │              │
     │              ├──────────────────────────────────────────────▶│
     │              │ emit VaultYieldDistributed(vaultId, realizedYield, hedgerShare, userShare, treasuryShare)

See the Staking Yield Distribution guide for the split formula and parameters. YieldShift.addYield(vaultId, ...) remains the entrypoint for other authorized yield sources; external-vault yield no longer routes through it.

Governance Flow

Live governance on Base mainnet is the 2-of-3 Safe plus an OpenZeppelin TimelockController (12 h minDelay, Safe = sole proposer/executor). The QTI on-chain governance path (lock → createProposal → vote → self-execution after PROPOSAL_EXECUTION_DELAY) is coded but dormant: QTI supply is 0 and the token holds no GOVERNANCE_ROLE.

Governance Flow (live):
┌────────────┐    ┌───────────────────┐    ┌───────────────────────────┐
│ Safe (2/3) │    │ TimelockController│    │ SecureUpgradeable proxy   │
└─────┬──────┘    └─────────┬─────────┘    └─────────────┬─────────────┘
      │ schedule(upgradeToAndCall)           │
      ├────────────────────▶│                │
      │      ... 12 h minDelay ...           │
      │ execute()           │                │
      ├────────────────────▶│ upgradeToAndCall(newImpl)
      │                     ├───────────────▶│  _authorizeUpgrade: msg.sender == timelock
      │
      │ Parameter changes on every contract, and upgrades of the plain-UUPS proxies
      │ (FeeCollector, oracles, SlippageStorage): one direct Safe transaction on the
      │ target (GOVERNANCE_ROLE / ORACLE_MANAGER_ROLE / UPGRADER_ROLE), no delay
      ├──────────────────────────────────────────────────▶ target contract

Scalability Architecture

Gas Optimization

Storage Optimization:

Packed structs for efficient storage
Batch operations for multiple updates
Event-based logging instead of storage
Minimal state variables

Computation Optimization:

Cached values for repeated calculations
Efficient algorithms for complex operations
Minimal external calls
Optimized loops and iterations

Upgradeability

Proxy Pattern Implementation:

ERC1967 + UUPS proxies for every upgradeable contract (no transparent proxies)
Core contracts inherit SecureUpgradeable: _authorizeUpgrade requires the call to come from the configured timelock — on Base mainnet the 12 h OpenZeppelin TimelockController
Oracles, SlippageStorage and FeeCollector are plain UUPS proxies upgraded directly by the governance Safe (no timelock)
Storage-layout compatibility and ABI additivity are enforced by make check-upgrade-safety

Upgrade Process:

Deploy and verify the new implementation (run make check-verifiable-bytecode CONTRACT=<Name> first)
Validate compatibility (make check-upgrade-safety: size, storage layout, ABI, version bump)
SecureUpgradeable proxies: the Safe schedules upgradeToAndCall on the TimelockController, waits 12 h, then executes; plain-UUPS proxies: the Safe calls upgradeToAndCall directly
Verify version() on the proxy and record it in deployments/{chainId}/versions.json

Integration Architecture

External Integrations

Oracle System (OracleRouter + HyperliquidEurUsdOracle + ChainlinkOracle):

OracleRouter implements IOracle — all protocol contracts use this interface
Active oracle is switchable by governance (switchOracle: Hyperliquid ↔ Chainlink) without contract changes; HyperliquidEurUsdOracle has been the active slot since 2026-06-25
HyperliquidEurUsdOracle: signed Hyperliquid reference read from SignedReferenceSource; normal signed age and additional adapter checks; independent Chainlink reference and USDC/USD validation
ChainlinkOracle: EUR/USD + USDC/USD via Chainlink AggregatorV3; 2 h EUR/USD staleness check (25 h USDC/USD); 5% deviation circuit breaker; Base L2 sequencer-uptime feed check
StorkOracle: parked (former slot-1 oracle, still deployed). LighterEurUsdOracle: deployed 2026-07-17 and inert — the Lighter venue was not adopted (2026-09-01)
MockChainlinkOracle + MockStorkOracle available for local/testnet development

External Yield Vaults (Morpho / Aave):

USDC deployment through IExternalStakingVault adapters (MetaMorpho live, vaultId 2)
Yield harvesting and distribution via QuantillonVault.harvestAndDistributeVaultYield
Governance-gated exposure per vaultId
Emergency withdrawal mechanisms

ERC-20 Standards:

Full ERC-20 compliance
Extended functionality
Metadata support

API Architecture

Contract Interfaces:

Standardized function signatures
Consistent error handling
Event emission patterns
Access control integration

Integration Patterns:

Factory pattern for contract creation
Registry pattern for contract discovery
Proxy pattern for upgrades
Adapter pattern for external integrations

Monitoring and Observability

Event Architecture

Core Events:

Token transfers and approvals
Vault operations (mint/redeem)
Staking and unstaking
Yield distribution
Governance actions

Monitoring Events:

System health indicators
Performance metrics
Error conditions
Security events

Analytics Architecture

On-Chain Analytics:

Transaction volume tracking
Yield performance metrics
User behavior analysis
Risk metrics monitoring

Off-Chain Analytics:

Protocol health dashboards
Performance reporting
Risk assessment
Compliance monitoring

Architecture Principles

Design Principles

Security First: All components designed with security as the primary concern
Modularity: Clear separation of concerns and modular design
Upgradeability: Future-proof design with upgrade capabilities
Gas Efficiency: Optimized for cost-effective operations
Transparency: Open and auditable code and processes

Development Principles

Test-Driven Development: Comprehensive test coverage
Documentation: Complete documentation for all components
Code Review: Rigorous review process for all changes
Continuous Integration: Automated testing and deployment
Security Audits: Regular security assessments

This architecture document is maintained by Quantillon Labs and updated with each protocol version.