> For the complete documentation index, see [llms.txt](https://quantillon.gitbook.io/quantillon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantillon.gitbook.io/quantillon/qeuro-first-deployment/quantillon-protocols-tokens/qeuro-token.md).

# QEURO Token

## QEURO Tokenomics: First EUR Deployment Architecture

### 📋 Executive Summary

The Quantillon Euro (QEURO) is the first market-specific asset built on the Quantillon Protocol. It combines euro-denominated exposure with USD liquidity depth, protocol-native FX hedging, and DeFi yield infrastructure. QEURO is therefore the first deployment of the broader architecture, not the full definition of Quantillon.

Our stablecoin architecture incorporates advanced mechanisms including overcollateralized minting/redemption via the QuantillonVault, delta-neutral hedging, and external staking vault yield generation (currently Morpho/MetaMorpho) that delivers superior capital efficiency while maintaining regulatory compliance. The design prioritizes user experience, institutional adoption, and sustainable yield generation across diverse market conditions.

***

### Core Token Specifications

**Technical Architecture**

| Parameter         | Value                                      | Rationale                                              |
| ----------------- | ------------------------------------------ | ------------------------------------------------------ |
| **Name**          | Quantillon Euro                            | Clear utility identification                           |
| **Symbol**        | QEURO                                      | Recognizable euro denomination                         |
| **Standard**      | ERC-20 (UUPS Upgradeable)                  | Future-proof with security                             |
| **Network**       | Base L2 (Primary)                          | L2 efficiency and lower costs                          |
| **Peg Target**    | 1 QEURO = 1 EUR                            | Direct euro denomination                               |
| **Decimals**      | 18                                         | Full ERC-20 compatibility                              |
| **Supply Model**  | No fixed cap - bounded by hedging capacity | Safety ceiling (currently 100M) is governance-raisable |
| **Contract Type** | OpenZeppelin + Custom Logic                | Battle-tested + innovation                             |

**Supply Model**

QEURO has **no fixed tokenomic supply cap** - supply is bounded by the protocol's hedging capacity: minting reverts whenever protocol collateralization would drop below the governance-set minting floor - currently **102.5%** (lowered from 105% on 2 September 2026; hard minimum 101%); 101% is the critical threshold that triggers liquidation mode. The token contract carries two adjustable safety guardrails on top of that economic limit: an **administrative supply ceiling** (currently 100,000,000 QEURO, raisable through the core admin timelock) and a **mint/burn rate limiter** (10M QEURO per 300-block window, \~10 minutes on Base) that contains blast radius if the mint path were ever compromised.

**Implemented Features**

* **Oracle Integration**: the hedge venue's EUR/USD market mid (Hyperliquid) with Chainlink as fallback and USDC/USD validation, all behind circuit breakers - see [Oracle Architecture](/quantillon/qeuro-first-deployment/smart-contract-components/oracle-architecture.md)
* **Quoted Execution**: Minting and normal redemption use execution quotes informed by reference prices and available liquidity
* **Emergency Controls**: Pausable with time-locked upgrades via UUPS pattern
* **Compliance System**: Blacklist/whitelist functionality for regulatory compliance
* **Rate Limiting**: Protection against large-scale manipulation attacks
* **Minting Killswitch**: Emergency minting halt capability

***

### Stablecoin Mechanics & Architecture

**Overcollateralization Model**

**📊 Collateral Framework**

| Collateral Type | Status | Minimum Ratio                                                                                                | Accepted Assets        |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ---------------------- |
| **Primary**     | ✅ Live | Governance-set minting floor - currently 102.5% (105% at launch); 101% is the critical/liquidation threshold | USDC (sole collateral) |

**🔒 Security Mechanisms**

* **Real-time Monitoring**: Oracle staleness checks (Hyperliquid feed: 15-minute default; Chainlink fallback: 2 hours EUR/USD, 25 hours USDC/USD)
* **Price Deviation Protection**: 5% maximum price change tolerance
* **Circuit Breakers**: Automatic pause on oracle failures or extreme conditions
* **Multi-Sig Controls**: Time-locked upgrades for critical parameter changes
* **Compliance Controls**: Blacklist/whitelist address management

**Minting & Redemption Process**

**📥 Minting Workflow**

```
User USDC → QuantillonVault → Price, Capacity and Collateral Checks → QEURO Mint → External Vault Deployment
```

1. **USDC Deposit**: Users deposit USDC to the QuantillonVault
2. **Oracle Price Check**: Real-time EUR/USD rate verification via the oracle router (Hyperliquid mid, Chainlink fallback)
3. **Capacity and Collateral Checks**: The protocol checks published execution capacity and collateralization before admitting the mint
4. **QEURO Issuance**: The vault mints the quoted amount, subject to the user's accepted minimum output and configured minting fee
5. **Yield Deployment**: Collateral can be deployed to external staking vaults (currently Morpho/MetaMorpho)

Minting capacity accounts for usable collateral already assigned to the EUR hedge as well as free USDC. See [minting quotes and capacity](/quantillon/protocol-foundation/mechanisms.md#minting-quotes-and-capacity) for the user flow and [HedgerPool](/quantillon/qeuro-first-deployment/smart-contract-components/hedger-pool.md#minting-capacity-and-hedge-collateral) for how hedge collateral supports it.

> **Important**: Minting occurs via the QuantillonVault contract which holds the MINTER\_ROLE. Users interact through the Vault interface, not directly with the QEURO token contract.

**📤 Redemption Workflow**

```
QEURO Burn → Oracle Verification → Collateral Release → USDC Transfer
```

**Key Benefits**:

* **Execution Quotes**: Users review the expected output and set their accepted minimum before submitting
* **24/7 Operations**: No banking hours or geographic restrictions
* **Instant Settlement**: Single-block transaction finality
* **Open Access**: Any address can deposit/redeem via the Vault

**Yield Generation Strategy**

**💰 Collateral Deployment**

USDC collateral can be deployed to external staking vaults - currently a MetaMorpho (Morpho) USDC vault via a dedicated adapter - to generate yield. Deployment is executed by the vault-operator role, USDC is withdrawn automatically to serve redemptions, and governance can deactivate a vault or pause the protocol. See [External Staking Vaults](/quantillon/qeuro-first-deployment/smart-contract-components/external-staking-vaults.md) for details.

**Revenue Distribution Model**

```
Morpho yield harvested by QuantillonVault
├── Gross staker allocation: harvested yield × harvest-time staking ratio
│   ├── Configured haircut → hedger recipient in USDC
│   └── Remaining allocation → QEURO credit, redeemable as it vests
└── Unstaked allocation → treasury in USDC
```

Holding unstaked QEURO does not earn this yield. Vault 1.5.0 bypasses YieldShift and ignores the legacy staking yield fee. See [Yield Distribution](/quantillon/qeuro-first-deployment/smart-contract-components/yield-distribution.md) for the formula and current settings.

***

### Dual-Pool Architecture

**👥 User Pool Mechanics**

**Primary Functions**:

* **QEURO Minting**: Deposit USDC via Vault to mint QEURO
* **Yield Earning**: Stake QEURO to stQEURO to receive auto-compounding yields
* **Governance Participation**: Vote on protocol parameters via QTI once governance is activated (QTI is dormant; the 2-of-3 Safe sets parameters today)
* **Unstaking Cooldown**: Configurable cooldown period for unstaking

**Participation Requirements**:

* **Minimum Stake**: Configurable via governance (minStakeAmount)
* **Collateral Ratio**: Minting requires the protocol collateralization ratio to stay above the minting floor - currently 102.5% (101% is the critical threshold)
* **Holding Period**: 7-day minimum for yield claims (anti-manipulation)

**🛡️ Hedger Pool Mechanics**

**Current Implementation: Single Hedger Model**

> **Important**: The protocol runs a single designated hedger - Quantillon Labs' hedging engine, executing on Hyperliquid - in the current phase. See [HedgerPool](/quantillon/qeuro-first-deployment/smart-contract-components/hedger-pool.md).

**Hedger Functions**:

* **FX Risk Management**: Delta-neutral EUR/USD exposure via margin positions
* **USDC Provision**: Deposits USDC margin for protocol collateralization
* **Yield compensation**: No base allocation from Morpho; only the configured haircut on gross staker yield, if nonzero
* **Peg Maintenance**: Economic incentives to maintain EUR stability

**Compensation Structure**:

```
Base Compensation: EUR/USD Interest Rate Differential
= Position interest/reward-reserve accounting
Separate: configured staking-yield haircut and authorized-source rewards, if funded
= Total Compensation (configurable via governance)
```

**Risk Management**:

* **Margin Requirements**: Governance-set minimum margin ratio (`minMarginRatio`, currently 250 bps = 2.5%)
* **Leverage Limits**: Maximum leverage configurable by governance (`maxLeverage`, currently 40×)
* **Health Gate**: Margin cannot be withdrawn below the minimum ratio; there is no per-position auto-liquidation - the protocol-level liquidation mode at 0 < CR ≤ 101% is the only liquidation mechanism
* **Entry/Exit Fees**: Configurable fees for position management (currently 0)

***

### Yield allocation

Morpho yield is allocated by the harvest-time staking ratio, with the unstaked share sent to treasury. A configured haircut may reduce gross staker yield; no base allocation is made for hedger margin. See [Yield Distribution](/quantillon/qeuro-first-deployment/smart-contract-components/yield-distribution.md).

[YieldShift](/quantillon/qeuro-first-deployment/smart-contract-components/yield-shift.md) contains a separate dynamic allocation ledger. Its holding-period and TWAP rules do not make the Morpho harvest allocation time-weighted.

***

### Vault Architecture

**🏗️ Current Implementation**

**External Staking Vault (Live)**

| Parameter         | Value                          | Description                                                                    |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| **Backend**       | MetaMorpho (Morpho) USDC vault | Primary yield source, accessed via `MetaMorphoStakingVaultAdapter` (vaultId 2) |
| **Staked series** | stQEUROMORPHO1                 | Per-vault stQEURO series deployed by `stQEUROFactory`                          |
| **Risk Profile**  | Strategy-dependent             | Smart-contract, borrower, curator and liquidity risks remain                   |
| **Target APY**    | Market-dependent               | Variable Morpho lending yield                                                  |

> **🚧 Future Vault Variants** (Roadmap): additional external staking vaults (other lending markets, tokenized T-Bills/RWAs, advanced strategies) can be added by governance via the adapter and factory pattern.

***

### Compliance & Security Features

**🔐 Access Control Roles**

| Role                     | Permission                         | Typical Holder     |
| ------------------------ | ---------------------------------- | ------------------ |
| **DEFAULT\_ADMIN\_ROLE** | Grant/revoke roles, critical admin | Multisig           |
| **MINTER\_ROLE**         | Mint new QEURO                     | QuantillonVault    |
| **BURNER\_ROLE**         | Burn QEURO                         | QuantillonVault    |
| **PAUSER\_ROLE**         | Pause/unpause                      | Emergency multisig |
| **COMPLIANCE\_ROLE**     | Manage blacklist/whitelist         | Compliance team    |

***

### 🚦 Rate Limiting System

The rate limiting system protects the protocol against large-scale manipulation attacks by limiting global mint/burn volume per 300-block window (\~10 minutes on Base). It is a safety guardrail, not a supply policy.

**Technical Implementation**

```
// Rate Limiting (live values)
Mint rate limit: 10,000,000 QEURO per 300-block window (~10 minutes on Base)
```

**Mechanism**

1. **Global tracking**: one mint counter and one burn counter per 300-block window, shared by all minters and burners
2. **Window reset**: The limit resets after each 300-block window (\~10 minutes on Base)
3. **Accumulation**: Operations accumulate within the current window
4. **Blocking**: If cumulative total exceeds the limit, operation fails

**Configuration**

| Parameter         | Live Value                        | Governable                             |
| ----------------- | --------------------------------- | -------------------------------------- |
| Mint rate limit   | 10,000,000 QEURO per window       | ✅ Yes (`updateRateLimits`, admin)      |
| Burn rate limit   | 10,000,000 QEURO per window       | ✅ Yes (`updateRateLimits`, admin)      |
| Rate limit window | 300 blocks (\~10 minutes on Base) | ❌ Constant (`RATE_LIMIT_RESET_PERIOD`) |

**Use Cases**

* **Anti-whale protection**: Prevents an actor from minting/burning massively
* **Operation smoothing**: Distributes load over time
* **Anomaly detection**: Bypass attempts can be monitored

**Associated Functions**

```solidity
// Check and update the global mint rate limit
function _checkAndUpdateMintRateLimit(uint256 amount) internal;

// Check and update the global burn rate limit
function _checkAndUpdateBurnRateLimit(uint256 amount) internal;

// Public getters
function mintRateLimit() external view returns (uint256 limit);
function burnRateLimit() external view returns (uint256 limit);
function rateLimitInfo() external view returns (uint96 currentHourMinted, uint96 currentHourBurned, uint64 lastRateLimitReset);
```

***

### 🔴 Minting Killswitch

The Minting Killswitch is an emergency mechanism that instantly halts all minting operations on the protocol.

**Implementation**

```solidity
// Killswitch state
bool public mintingKillswitch;

// Enable/disable (PAUSER_ROLE)
function setMintingKillswitch(bool enabled) external onlyRole(PAUSER_ROLE);
// emits MintingKillswitchToggled(enabled, caller)
```

**When to Use?**

| Situation                  | Action             | Consequence                      |
| -------------------------- | ------------------ | -------------------------------- |
| **Vulnerability detected** | Enable killswitch  | No more QEURO can be minted      |
| **Oracle compromised**     | Enable killswitch  | Prevents minting at wrong prices |
| **Attack in progress**     | Enable killswitch  | Stops exploitation immediately   |
| **Situation resolved**     | Disable killswitch | Resumes normal operations        |

**Impact**

* ✅ **Burns remain possible**: Users can still exit
* ✅ **Transfers remain possible**: QEURO remains transferable
* ✅ **Redemptions remain possible**: Via the Vault (which burns)
* ❌ **Minting blocked**: No new QEURO issuance

**Difference with Pause**

| Function          | Mint | Burn | Transfer | Redeem |
| ----------------- | ---- | ---- | -------- | ------ |
| **Killswitch ON** | ❌    | ✅    | ✅        | ✅      |
| **Pause ON**      | ❌    | ❌    | ❌        | ❌      |

> **Note**: The killswitch is a less drastic measure than full pause, allowing users to exit the protocol.

***

### 📋 Compliance System (Blacklist/Whitelist)

The QEURO protocol integrates a compliance system to meet regulatory requirements, including MiCA.

**System Architecture**

```
┌─────────────────────────────────────────────────────┐
│                  COMPLIANCE SYSTEM                   │
├─────────────────────────────────────────────────────┤
│  Normal Mode (whitelistEnabled = false)             │
│  ├── Everyone can transfer                          │
│  └── Except blacklisted addresses                   │
├─────────────────────────────────────────────────────┤
│  Whitelist Mode (whitelistEnabled = true)           │
│  ├── Only whitelisted addresses can transfer        │
│  └── Blacklisted remain excluded                    │
└─────────────────────────────────────────────────────┘
```

**Compliance Mappings**

```solidity
mapping(address => bool) public isBlacklisted;   // Blocked addresses
mapping(address => bool) public isWhitelisted;   // Authorized addresses
bool public whitelistEnabled;                     // Whitelist mode active
```

**Management Functions**

| Function                                           | Required Role    | Description                   |
| -------------------------------------------------- | ---------------- | ----------------------------- |
| `blacklistAddress(address account, string reason)` | COMPLIANCE\_ROLE | Block an address              |
| `unblacklistAddress(address account)`              | COMPLIANCE\_ROLE | Unblock an address            |
| `whitelistAddress(address account)`                | COMPLIANCE\_ROLE | Authorize an address          |
| `unwhitelistAddress(address account)`              | COMPLIANCE\_ROLE | Remove authorization          |
| `toggleWhitelistMode(bool enabled)`                | COMPLIANCE\_ROLE | Enable/disable whitelist mode |

**Batch Operations**

For gas efficiency, batch operations are available:

```solidity
function batchBlacklistAddresses(address[] calldata accounts, string[] calldata reasons) external;
function batchUnblacklistAddresses(address[] calldata accounts) external;
function batchWhitelistAddresses(address[] calldata accounts) external;
function batchUnwhitelistAddresses(address[] calldata accounts) external;
```

**Verification Logic**

On each transfer, the `_update` function verifies:

```
1. Sender is not blacklisted
2. Recipient is not blacklisted
3. If whitelistEnabled:
   - Sender must be whitelisted (except for minting)
   - Recipient must be whitelisted (except for burning)
```

**Regulatory Use Cases**

| Scenario           | Configuration                  | Result                                   |
| ------------------ | ------------------------------ | ---------------------------------------- |
| **Open public**    | whitelistEnabled=false         | Everyone can transfer except blacklisted |
| **OFAC sanctions** | Blacklist sanctioned addresses | Sanctions compliance                     |
| **KYC required**   | whitelistEnabled=true          | Only KYC'd users can use                 |
| **Fund freeze**    | Blacklist specific address     | Funds frozen for investigation           |

**Emitted Events**

```solidity
event AddressBlacklisted(address indexed account, string indexed reason);
event AddressUnblacklisted(address indexed account);
event AddressWhitelisted(address indexed account);
event AddressUnwhitelisted(address indexed account);
event WhitelistModeToggled(bool enabled);
```

***

### ⚠️ Emergency Controls

**Emergency Controls Overview**

| Control        | Severity    | Required Role | Reversible   |
| -------------- | ----------- | ------------- | ------------ |
| **Rate Limit** | 🟡 Medium   | Automatic     | ✅ Auto-reset |
| **Killswitch** | 🟠 High     | PAUSER        | ✅ Yes        |
| **Pause**      | 🔴 Critical | PAUSER        | ✅ Yes        |
| **Blacklist**  | 🟡 Targeted | COMPLIANCE    | ✅ Yes        |

**Escalation Procedure**

```
Level 1: Rate Limiting (automatic)
    ↓ If insufficient
Level 2: Minting Killswitch (pauser)
    ↓ If insufficient  
Level 3: Targeted Blacklist (compliance)
    ↓ If insufficient
Level 4: Full Pause (pauser)
```

**Token Recovery**

In case of tokens or ETH sent by mistake to the contract:

```solidity
// Recover ERC20 tokens
function recoverToken(address token, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE);

// Recover ETH
function recoverETH() external onlyRole(DEFAULT_ADMIN_ROLE);
```

> Recovered funds are sent to the configured `treasury` address.

***

### Economic Sustainability Model

**📈 Revenue Streams**

**Primary Revenue Sources**

1. **Mint/Redeem Fees**: currently 0 (governance-settable, capped at 5%); when collected, routed to the FeeCollector (60% treasury / 25% dev fund / 15% community)
2. **Yield Management**: treasury allocation attributable to unstaked QEURO; no additional staking yield fee on vault 1.5.0 credits
3. **Position Fees**: hedger entry/exit/margin fees (currently 0, governance-settable) with separate fee-routing settings; see [Production Deployment Status](/quantillon/qeuro-first-deployment/deployment-status.md). No 20% tax is charged on hedger reward claims

**🎯 Key Performance Indicators**

**Health Metrics**

* **Peg Stability**: Target <2% deviation from EUR
* **Collateral Ratio**: Stay above the minting floor (currently 102.5%) across all conditions; 101% is the critical threshold
* **Yield Consistency**: Dynamic based on external staking vault (Morpho) market conditions
* **Governance Activity**: QTI holder participation (once governance is activated)

***

### Risk Management Framework

**🛡️ Comprehensive Risk Matrix**

**Technical Risks**

| Risk Factor                      | Probability | Impact   | Mitigation Strategy                                                                                                           |
| -------------------------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Smart Contract Bug**           | Medium      | Critical | Internal AI-assisted review, remediated on-chain as they come in; no audit-firm review yet; continuous monitoring             |
| **Oracle Manipulation**          | Low         | High     | Chainlink + circuit breakers, 5% deviation limit                                                                              |
| **External Vault (Morpho) Risk** | Low         | Medium   | Governance can deactivate the vault and pause the protocol; USDC is withdrawn on redemption; loss-aware collateral accounting |
| **Liquidation Cascade**          | Low         | High     | Circuit breakers, emergency pause                                                                                             |

**Market Risks**

| Risk Factor               | Probability | Impact | Mitigation Strategy                      |
| ------------------------- | ----------- | ------ | ---------------------------------------- |
| **EUR/USD Volatility**    | High        | Medium | Delta-neutral hedging, yield shift       |
| **USDC Depeg**            | Low         | High   | 2% tolerance monitoring, circuit breaker |
| **Interest Rate Changes** | Medium      | Low    | Dynamic yield adjustment                 |
| **Regulatory Changes**    | Medium      | High   | MiCA compliance, blacklist capability    |

**Emergency Procedures**

**Crisis Response Protocol**

* **Level 1**: Automatic circuit breakers (oracle pause)
* **Level 2**: Emergency role intervention (pause operations)
* **Level 3**: Admin intervention (parameter changes)
* **Level 4**: Protocol pause (complete system halt)

**Recovery Mechanisms**

* **Token Recovery**: Admin can recover accidentally sent tokens
* **ETH Recovery**: Admin can recover accidentally sent ETH
* **Governance Override**: Emergency parameter adjustments via governance

***

### Technical Reference

**Contract Addresses**

> The protocol contracts are deployed on Base mainnet (chain 8453) since June 2026; the public launch is planned for Q4 2026. QuantillonVault: `0x833E5Ba510a241b21F1C60c987D1c49eB52E4a07`. See [Oracle Architecture](/quantillon/qeuro-first-deployment/smart-contract-components/oracle-architecture.md) for the oracle contract addresses.

**Key Constants**

```solidity
DEFAULT_MAX_SUPPLY = 100_000_000e18   // initial value of the governance-raisable maxSupply ceiling (updateMaxSupply, admin)
// Mint/redeem fees: currently 0, governance-settable, capped at 5%
// Mint rate limit: 10,000,000 QEURO per 300-block window (~10 minutes on Base)
```

**Events**

* `Transfer(from, to, value)` - Standard ERC20 transfer
* `TokensMinted(to, amount, minter)` - QEURO minted
* `TokensBurned(from, amount, burner)` - QEURO burned
* `AddressBlacklisted(account, reason)` / `AddressUnblacklisted(account)` - Compliance update
* `MintingKillswitchToggled(enabled, caller)` - Emergency control toggled
* `SupplyCapUpdated(oldCap, newCap)` / `RateLimitsUpdated(limitType, mintLimit, burnLimit)` - Guardrail changes

The full event list is on [Smart Contract Components](/quantillon/qeuro-first-deployment/smart-contract-components.md#qeurotoken-1).

***

#### Conclusion: QEURO as the First Deployment

QEURO represents more than just another stablecoin: it is the first production deployment of Quantillon's FX-hedged local-currency architecture. Through innovative dual-pool mechanics, snapshot-based staking yield allocation, and robust security controls, QEURO creates a sustainable foundation for EUR-denominated decentralized finance.

The live deployment focuses on core functionality with USDC collateral and external staking vault yield generation (currently Morpho/MetaMorpho); additional external vaults can be registered by governance through the adapter and factory pattern.

The first deployment prioritizes user experience, regulatory compliance, and sustainable yield generation while preserving the broader protocol's flexibility. The result is an EUR asset that bridges local-currency balance-sheet needs with the innovation and accessibility of decentralized protocols.

***

> **Risk Disclaimer**: QEURO is a decentralized financial product that carries inherent risks including smart contract vulnerabilities, market volatility, and regulatory changes. This document is for informational purposes only and should not be considered investment advice. Users should conduct their own research and risk assessment before participating in the protocol.