Quantillon Protocol Smart Contracts

Production update, 17 October 2026: Signed Quotes in Production. Signed execution is active on Base; the periodic publisher is retired and the emergency-redemption budget is zero.

Current production behavior and settings: Production Protocol Reference.

Base deployment addresses and active versions (17 October 2026): Deployment guide · API address reference.

Euro-pegged stablecoin protocol with dual-pool architecture, yield generation, and governance mechanisms

📖 Overview

Quantillon Protocol is a comprehensive DeFi ecosystem built around QEURO, a Euro-pegged stablecoin. The protocol features a dual-pool architecture that separates user deposits from hedging operations, enabling efficient yield generation while maintaining stability. The codebase ships an extensive Foundry test suite (unit, fuzz, integration, invariants), custom errors and centralized validation libraries, and role-based access control.

📚 Documentation

• API Reference - Complete API reference for all smart contracts
• Architecture Overview - Components, flows, roles and the upgrade model
• Oracle Architecture - Hedge-aligned EUR/USD pricing (Hyperliquid active, Chainlink fallback)
• Quick Start Guide - Get started quickly with integration examples
• Integration Examples - Comprehensive integration examples and patterns
• Deployment Guide - Complete deployment instructions and procedures
• Security Guide - Security practices and considerations
• stQEUROFactory Technical Upgrade - Multi-vault staking refactor details and runbook
• Multi-Vault Staking Runtime Flow - Contract-level mint/redeem/hedger routing behavior after the vaultId refactor
• Yield Distribution 1.5.0 - Harvest-time staking ratio, haircut-only hedger payout and vesting
• External Vault Onboarding Runbook - Operator guide for setup-external-vaults.sh
• Documentation Hub - Comprehensive documentation overview

🎯 Key Features

• Euro-Pegged Stablecoin: QEURO maintains 1:1 peg with Euro through sophisticated mechanisms
• Dual-Pool Architecture: Separates user deposits from hedging operations for optimal risk management
• Yield Generation: Multiple yield sources including protocol fees, interest differentials, and yield farming
• Governance Token: QTI token with vote-escrow mechanics for decentralized governance (not yet activated — token supply not minted, governance dormant until launch)
• Advanced Hedging: EUR/USD hedging positions with margin management and liquidation systems
• Yield-Bearing Wrapper: stQEURO token that automatically accrues yield for holders
• External Adapter Integration: Multi-vault adapter model with post-deploy onboarding
• Comprehensive Security: Role-based access control, reentrancy protection, and emergency pause mechanisms
• Gas-Optimized Design: Custom errors, centralized validation, and consolidated error libraries

🏗️ Architecture

Core Contracts

🚀 Quick Start

Prerequisites

• Foundry (latest version)
• Node.js (v18 or later)
• Anvil for local development

1. Clone and Setup

git clone https://github.com/Quantillon-Labs/smart-contracts.git
cd smart-contracts/quantillon-protocol
npm install

Note: scripts/deployment/ (deployment and upgrade scripts), the .env* templates and CLAUDE.private.md are git-crypt encrypted; the rest of scripts/ is plaintext so CI can run it. Building and testing does not need the key — contact the maintainers only if you need the deployment tooling.

2. Environment Configuration

# Copy an environment template for your target network
cp .env.localhost .env        # for local Anvil development
cp .env.base-sepolia .env     # for Base Sepolia testnet
cp .env.base .env             # for Base mainnet

3. Build and Test

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

Testing conventions: Run make test before pushing; run make ci for full checks (build, test, Slither, NatSpec, gas and size analysis). CI (GitHub Actions, .github/workflows/quantillon-protocol-tests.yml at the repository root) splits all test files across four runners on push and pull requests to main. Reproduce one shard with bash scripts/ci-test-shard.sh 0 4 (indices 0–3); each uses the normal test profile and fuzz/invariant settings. The gating job requires every shard to pass, then runs make build and the upgrade-safety gate (make analyze-contract-sizes check-storage-layout check-abi check-version-bump). Nightly and manually dispatched runs execute the same four shards with --gas-report, then run make ci-base using the combined reports through FORGE_GAS_REPORT_FILE; the analysis job requires all shards to pass and does not rerun the full test suite. Reproduce a gas-report shard with bash scripts/ci-test-shard.sh 0 4 --gas-report. Use test_*, testFuzz_*, and invariant_* naming; avoid new assertTrue(true, ...) placeholders—convert or explicitly skip with rationale. See the test/ directory for test structure and coverage.

🚀 Deployment

🔐 Unified Deployment

Core contracts are deployed in a single forge script invocation via DeployQuantillon.s.sol. Deployed addresses are written to deployments/{chainId}/addresses.json.

# Deploy to localhost with mock contracts
./scripts/deployment/deploy.sh localhost --with-mocks

# Deploy to Base Sepolia testnet
./scripts/deployment/deploy.sh base-sepolia --verify

# Deploy to Base mainnet (production)
./scripts/deployment/deploy.sh base --verify --production

# Then onboard external vault adapters (post-core step)
./scripts/deployment/setup-external-vaults.sh --help

📋 Deployment Options

🔧 Deployment Features

• 🔐 Secure Environment Variables: .env* templates are tracked git-crypt encrypted — never commit them in plaintext
• 🌐 Multi-Network Support: Localhost (31337), Base Sepolia (84532), Base Mainnet (8453)
• 🎭 Granular Mock Control: Choose which contracts to mock (--with-mocks, --with-mock-usdc, --with-mock-oracle)
• ✅ Contract Verification: Automatic verification on block explorers via --verify
• 🧪 Dry-Run Capability: Test deployments without broadcasting via --dry-run
• ⚡ Smart Caching: Compilation cache preserved by default for faster deployments (use --clean-cache to force full rebuild)
• 📝 Post-Deployment Tasks: Automatic ABI copying and address updates

🛡️ Security Features

• Environment Variables: .env* templates are tracked git-crypt encrypted — never commit them in plaintext, never disable the filter
• Secret Management: Prefer a secret manager for production (e.g., AWS Secrets Manager)

🧪 Testing

Run All Tests

make test

Run Specific Test Suites

# Core protocol tests
forge test --match-contract QuantillonVault

# Integration tests
forge test --match-contract IntegrationTests

# Reentrancy and security-oriented tests
forge test --match-contract ReentrancyTests

Gas Analysis

make gas-analysis

🔍 Security

Automated Security Analysis

# Run Slither static analysis
make slither

# Run Mythril analysis
make mythril

# Validate NatSpec documentation
make validate-natspec

# Check contract bytecode size limits (EIP-170)
make analyze-contract-sizes

# Enforce a personal EIP-170 budget (example: 97%)
EIP170_PERSONAL_LIMIT_PERCENT=97 make analyze-contract-sizes

Security And Quality Reports

Analysis outputs are written under scripts/results/:

• scripts/results/slither/slither-report.txt - Slither executive summary and unresolved/suppressed/excluded sections
• scripts/results/mythril-reports/ - Mythril per-contract JSON and timestamped text summaries
• scripts/results/natspec-validation-report.txt - NatSpec validation coverage report
• scripts/results/contract-sizes/contract-sizes-summary.txt - EIP-170 size compliance summary
• scripts/results/gas-analysis/ - Gas analysis outputs

Security Features

• Role-Based Access Control: Granular permissions for different operations
• Reentrancy Protection: Comprehensive reentrancy guards
• Emergency Pause: Circuit breakers for critical functions
• Input Validation: Extensive parameter validation with centralized libraries
• Overflow Protection: Safe math operations throughout
• Flash Loan Protection: Balance checks to prevent flash loan attacks
• Custom Errors: Gas-efficient error handling with clear error messages
• Secret Handling: Environment variables loaded from .env during development
• 🔐 Encrypted Paths: scripts/deployment/, .env* and CLAUDE.private.md are git-crypt encrypted (see .gitattributes); everything else is plaintext

📊 Development

Available Commands

# Build contracts
make build

# Run tests
make test

# Run security analysis
make slither

# Generate documentation
make docs

# Clean build artifacts
make clean

# Gas analysis
make gas-analysis

Code Quality

• NatSpec Documentation: Comprehensive documentation for all functions
• Test Coverage: Extensive test suite (unit, fuzz, integration, invariants) — make test
• Security Analysis: Regular security audits and static analysis
• Gas Optimization: Optimized for deployment size and execution cost
• Error Handling: Custom errors for gas efficiency and better error messages
• Code Deduplication: Consolidated validation functions and error libraries
• Stack Optimization: Fixed stack too deep issues through struct-based refactoring

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Solidity style guide
• Write comprehensive tests (aim for 100% coverage)
• Update documentation
• Ensure security best practices
• Protect secrets: .env* files are tracked but git-crypt encrypted — never commit them in plaintext, never disable the filter
• Use custom errors instead of require() strings for gas efficiency
• Consolidate duplicate code into libraries
• Follow the centralized error library pattern (CommonErrorLibrary)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Website: https://quantillon.money
• Documentation: https://docs.quantillon.money
• Discord: discord.gg/uk8T9GqdE5
• X (Twitter): @QuantillonLabs
• Telegram: @QuantillonLabs

🙏 Acknowledgments

• OpenZeppelin for secure contract libraries
• Chainlink for reliable price feeds
• Morpho (MetaMorpho vaults) for the live external yield venue and Hyperliquid for the hedge venue and EUR/USD market price
• Foundry for development framework
• Standard .env files for environment variable management

Yield crediting uses an independent solvency gate above max(101%, criticalCollateralizationRatio) and a projected 100% floor; public minting continues to use the live configured mint floor.

Staking yield distribution 1.5.0

Production QuantillonVault 1.5.0 was activated on 30 September 2026. Vault 1.6.0, activated on 17 October, preserves that policy and allocates harvested yield by the staked/total QEURO ratio, with haircut-only hedger compensation and no separate staking yield fee. Yield credit vests through the share price; allocation remains snapshot-weighted. See the economics and confirmed activation record. The capital-weighted 1.4 guide is historical.

Production Deployment Status

Signed quotes are active on Base since 17 October 2026. Versions, signed-module bindings, oracle routing, zero mint/redemption fees, the 102.5% mint floor, the 101% critical threshold and zero QTI supply were rechecked at finalized Base block 52,727,379. The signed module is in NORMAL mode with an emergency budget of 0 QEURO. See Signed Quotes and the confirmed activation.

The broader parameter, role and availability review below was performed on 30 September 2026, using finalized Base block 51,985,907. Settings not listed in the October recheck retain that earlier verification date. These are dated observations, not immutable defaults; read current state and obtain a fresh quote before transacting.

Deployment and availability

Contracts are deployed on Base mainnet (8453). The public application is at app.quantillon.money; the public launch remains a Q4 2026 target, not a confirmed opening date. There is no Ethereum-mainnet deployment. Development and preproduction use separate Base forks; the former public testnet is retired.

QTI is deployed but has zero supply. Its vote-escrow and proposal machinery is dormant. Quantillon Rewards is deployed, but the public program state is off and enrollment is not open. QP points promise neither monetary value nor a token allocation.

User flows and backing

• Users mint QEURO with USDC through QuantillonVault. Normal mint/redeem amounts use transaction-specific signed execution quotes, valid for at most 45 seconds from the market observation, including depth, spread and buffer constraints, rather than simply multiplying by the oracle mid. Zero protocol fees do not mean zero execution cost.
• The dapp stakes QEURO directly into an ERC-4626 stQEURO series. The optional UserPool batch contract has separate accounting and a cooldown; these are not the direct stQEURO staking rules.
• The current external strategy is the MetaMorpho USDC vault, registered as vaultId 2. QEURO backing can be deployed there; hedger margin is not part of its yield-bearing principal. External backing is counted conservatively, capped by tracked principal and current underlying value; the execution-spread reserve is excluded from backing.
• Minting has a 102.5% collateralization floor, plus oracle, execution-capacity, token, pause and liquidity checks. Protocol liquidation mode applies when the computed ratio is positive and at or below 101%. A zero ratio is not an automatic liquidation signal. Redemptions remain subject to validation and available liquidity.

See Execution Pricing, Liquidation Mode and External Staking Vaults.

Yield and fees

UserPool's configured accounting rates are not Morpho's realized return or the direct stQEURO APY. The displayed Morpho rate is an underlying provider metric, not a guaranteed QEURO return. See Yield Distribution for the allocation formula and conversion costs. YieldShift remains a separate authorized-source ledger.

Hedge and oracle

The single designated hedger maintains a Base HedgerPool position and a Hyperliquid xyz:EUR position. HedgerPool's minimum margin is 2.5% and its configured maximum leverage is 40x. Configured EUR/USD annual interest inputs are 3.5% / 4.5%; they are not promises of realized hedger profit. Order preparation inside Hyperliquid and movement of capital between venues are distinct operations.

OracleRouter slot 1 uses HyperliquidEurUsdOracle; slot 0 is the manually selected Chainlink fallback. HyperliquidEurUsdOracle 1.0.7 reads SignedReferenceSource, which accepts authenticated reference reports delivered with transactions and checks an independent Chainlink reference. The periodic publisher is retired. A stale reference can block operations even when the venue is trading. Switching to Chainlink does not by itself restore minting: execution pricing also checks source compatibility and admitted hedge capacity.

Governance and security

The governance Safe requires 2 of 3 signers. The 12-hour TimelockController holds DEFAULT_ADMIN_ROLE on the eight core contracts, including the stQEURO series. Core role grants and revocations therefore use that controller. The Safe retains direct operational, governance and emergency permissions according to each contract's roles; it holds the peripheral admin roles.

Core upgrades use the timelock while secure upgrades are enabled. SecureUpgradeable also contains a separate emergency-disable procedure with a 24-hour delay and two distinct admin approvals; it is not an ordinary pause operation. Peripheral upgrades can be executed directly by the Safe. See Quantillon DAO for the control boundaries.

No professional security audit has been performed. Review to date is internal and AI-assisted. This does not establish that the contracts are free of defects. See Risks and Mitigation.

Token guardrails and references

QEURO has an adjustable administrative supply ceiling of 100 million, and global mint and burn limits of 10 million per 300-block window. These are controls, not a fixed tokenomic issuance promise. Whitelist mode and the minting killswitch were off at the verification block.

The contract inventory records addresses and versions. Core Mechanisms explains the flows. The roadmap and planned QTI allocations describe future intentions, not current issuance or guaranteed dates.

Evidence and maintenance

This reference describes the current deployment, not an audit certification. The broader settings and role review used finalized Base block 51,985,907; the October versions and signed bindings listed above were independently read at finalized block 52,727,379. User flows were checked against contract source and deployed ABIs. Runtime routing and Rewards availability were checked separately on 30 September 2026. Future launch, distribution and entity plans remain organizational intentions.

Deployment manifests record upgrade history and can lag live state; use version(), role reads and the active vault bindings for current integration. Do not infer the active implementation from a historical release section alone.

Quantillon Protocol API Reference

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

Technical API Reference

This document provides detailed technical specifications for all Quantillon Protocol smart contract interfaces.

Contract Addresses

Deployed addresses for Base Mainnet (chain ID 8453). The machine-readable registry deployments/8453/addresses.json is a local deployment artifact (gitignored, not published); the tracked deployments/8453/versions.json carries the proxy and implementation address plus versions recorded by deployment tooling; these records can lag subsequent upgrades, so read live version() values. All core contracts are UUPS proxies — the addresses below are the stable proxy addresses that integrators should use.

Core protocol

Oracles

Protocol contracts depend only on OracleRouter (which implements IOracle). The router has two slots — enum OracleType { CHAINLINK, MARKET } (slot 1 was named STORK before router v1.1.0; the live router is v1.1.2) — switchable in one governance transaction via switchOracle. Slot 1 currently hosts HyperliquidEurUsdOracle, the active production oracle (activeOracle = 1); read it via marketOracle() (the pre-1.1.0 storkOracle() getter remains as a deprecated alias). Slot 0 (ChainlinkOracle) is the fallback and remains the USDC/USD source.

Signed execution and reference (Base, 17 October 2026)

Verified at finalized block 52,727,379. Both modules are deployed directly and are non-upgradeable. Resolve QuantillonVault.executionPricing() and the module's referenceSource() before integration.

QuantillonVault is 1.6.0, UserPool 1.3.0, HedgerPool 1.6.0, HyperliquidEurUsdOracle 1.0.7 and vaultId-2 stQEUROToken 1.3.0. The production integration guide records the activation and binding checks.

Normal conversions use QuantillonVault.executeWithQuote(bytes,bytes) or UserPool.executeWithQuote(bytes,bytes). Existing conversion selectors below describe the inner operations; bare unquoted calls are rejected while signed execution is enabled. Hedger reference operations use executeWithReference(bytes,bytes) or the typed removeMarginWithReference(uint256,uint256,bytes) and retain caller permissions. Add-margin remains directly available to authorized callers.

The previous ExecutionPricing module (0x4338c6C9A912d51487cc0bf3b20162fdb25eFc03), PublicationBatcher (0x0E7a3df68D527249fB3A2e66dC307ed1F119172d) and ReportPublicationBatcher (0x2efA498B9Fa9903A371A9fbE561555AD10589EeA) are historical. The periodic publication route is retired.

Governance & infrastructure

External vault adapters (onboarded post-core)

External staking adapters are onboarded after core deployment via setup-external-vaults.sh and are tracked per vaultId, not in addresses.json. Currently live:

The previous vaultId-2 adapter (0xb2f253Cd74ebfa16894339438B467396De9e8EA3) was migrated to the version-2.1.1 address above on 2026-09-23. Per-vault adapter records (deployments/8453/*-adapter.json) are local deployment artifacts and are not tracked in this repository; the live binding is readable on-chain via QuantillonVault.getVaultExposure(2).

Per-vault stQEURO tokens

addresses.json intentionally lists stQEUROToken as the zero address: stQEURO is deployed per external vault by stQEUROFactory and must be resolved at runtime via getStQEUROByVaultId(vaultId). Currently live:

External dependencies

QuantillonVault

Contract: QuantillonVault.sol
Interface: IQuantillonVault.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

initialize(address admin, address _qeuro, address _usdc, address _oracle, address _hedgerPool, address _userPool, address _timelock, address _feeCollector)

function initialize(
    address admin,
    address _qeuro,
    address _usdc,
    address _oracle,
    address _hedgerPool,
    address _userPool,
    address _timelock,
    address _feeCollector
) external

Modifiers: initializer
Notes:

• _hedgerPool and _userPool can be wired later through governance setters.
• _timelock is also used as treasury destination for recovery flows.

mintQEURO(uint256 usdcAmount, uint256 minQeuroOut)

function mintQEURO(
    uint256 usdcAmount,
    uint256 minQeuroOut
) external

Modifiers: whenNotPaused, nonReentrant
Events: QEUROminted(address indexed user, uint256 usdcAmount, uint256 qeuroAmount)
Requirements:

• usdcAmount > 0
• Price cache initialized (initializePriceCache)
• Active hedger configured (hedgerPool.hasActiveHedger())
• Sufficient USDC balance and allowance
• Projected post-mint collateralization ratio must remain above threshold

redeemQEURO(uint256 qeuroAmount, uint256 minUsdcOut)

function redeemQEURO(
    uint256 qeuroAmount,
    uint256 minUsdcOut
) external

Modifiers: whenNotPaused, nonReentrant
Events: QEURORedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcAmount)
Requirements:

• qeuroAmount > 0
• Sufficient QEURO balance and allowance
• Automatically routes to liquidation mode when protocol CR is positive and at or below the critical threshold
• Pulls liquidity from external vault adapters when needed (tracked principal only; unharvested adapter yield is not used as redemption collateral)

Execution previews

The former calculateMintAmount and calculateRedeemAmount helpers are absent from the current vault ABI. Resolve vault.executionPricing() and use ExecutionPricing.previewMint(usdcInput) or previewRedeem(qeuroInput) for normal execution.

Both return a Quote tuple: amountOut, executionRate, referenceRate, capacityQeuro, observedAt, sequence (all uint256). Mint output is QEURO in 18 decimals; redeem output is USDC in 6 decimals. Preview outputs include the configured protocol fee. Prices are 18-decimal USD/EUR and capacity is 18-decimal QEURO. Quotes can revert and do not reserve capacity.

The redemption preview can use the module's degraded quote path. It is not a liquidation-mode payout preview. Simulate the actual vault call with a user-selected minimum output and the user's account before submitting. See Integration Examples.

Vault balance getters (public state)

uint256 public totalUsdcHeld;              // USDC held directly by the vault
uint256 public totalMinted;                // QEURO minted by vault tracker
uint256 public totalUsdcInExternalVaults;  // Principal tracked across external vault adapters

Notes:

• The aggregated getVaultMetrics() helper was retired in the external multi-vault refactor (EIP-170 headroom); read the three public trackers directly, and use getProtocolCollateralizationRatio() for debt/collateral ratio math (1e20 = 100%). Do not sum the trackers as proof of redeemable backing: external strategy losses and the excluded execution-spread reserve matter. Use getTotalUsdcAvailable() and the collateralization getter; unharvested yield is not backing.

getProtocolCollateralizationRatio() → (uint256)

function getProtocolCollateralizationRatio() public view returns (uint256 ratio)

Returns: Current protocol collateralization ratio in 18-decimal percentage format (100% = 1e20)

Description: Calculates CR = (TotalCollateral / BackingRequirement) * 1e20 where:

• TotalCollateral = totalUsdcHeld + tracked external-vault principal (unharvested adapter yield is excluded; it accrues to stQEURO holders via harvestAndDistributeVaultYield/creditVaultYield)
• BackingRequirement = QEUROSupply * cachedEurUsdPrice / 1e30

Note: This function uses cached price and returns 0 when required wiring/cache prerequisites are not met.

Requirements:

• Both HedgerPool and UserPool must be set
• Initialized cached price
• QEURO supply > 0

canMint() → (bool)

function canMint() public view returns (bool)

Returns: true if minting is allowed, false otherwise

Description: Checks if minting is allowed under current safeguards:

• Cached price must be initialized.
• Active hedger must exist.
• Collateralization ratio must be >= minCollateralizationRatioForMinting.

initializePriceCache()

Governance-only bootstrap step required after deployment and before first user mint.

updateHedgerRewardFeeSplit(uint256 newSplit)

Governance setter for fee routing share to HedgerPool reserve (1e18 = 100%).

mintQEUROToVault(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId)

User entrypoint for minting QEURO and routing collateral to a specific external vault adapter.

mintAndStakeQEURO(uint256 usdcAmount, uint256 minQeuroOut, uint256 vaultId, uint256 minStQEUROOut) → (uint256 qeuroMinted, uint256 stQEUROMinted)

One-step user entrypoint to mint QEURO and stake into the vault-specific stQEURO token.

deployUsdcToVault(uint256 vaultId, uint256 usdcAmount)

Vault-operator entrypoint for manual collateral deployment to a specific adapter.

harvestAndDistributeVaultYield(uint256 vaultId)

Keeper entrypoint (YIELD_DISTRIBUTOR_ROLE). In live vault 1.5.0, gross staker yield is harvested USDC multiplied by the harvest-time ratio of raw staked QEURO to total QEURO supply. Stakers receive that allocation after the configured haircut; treasury receives the unstaked allocation; the hedger receives only the haircut (currently zero). Conversion execution costs remain. Emits VaultYieldDistributed(vaultId, realizedYield, hedgerShare, userShare, treasuryShare) and VaultYieldBreakdown with hedgerBase = 0. See the 1.5.0 distribution guide.

creditVaultYield(uint256 vaultId, uint256 usdcAmount) → (uint256 qeuroMinted)

YIELD_DISTRIBUTOR_ROLE entrypoint crediting externally realized USDC yield into a vault's stQEURO backing.

harvestConfig(uint256 vaultId) → (uint256 fundingRateBps, address hedgerRecipient, uint256 lastHarvest)

Compatibility view: the retired funding-rate result is always zero. Use yieldDistributionConfig(vaultId) for (haircutBps, hedgerRecipient, lastHarvest).

setFundingRateAnnualBps(uint256 newRateBps) / setHedgerYieldRecipient(address newRecipient)

setFundingRateAnnualBps is retired and reverts. Governance configures the haircut with setHedgerStakingYieldHaircutBps(uint256 newBps) (0–10,000 bps), and its recipient with setHedgerYieldRecipient. These emit HedgerStakingYieldHaircutUpdated and HedgerYieldRecipientUpdated.

Events

event QEUROminted(address indexed user, uint256 usdcAmount, uint256 qeuroAmount);
event QEURORedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcAmount);
event LiquidationRedeemed(address indexed user, uint256 qeuroAmount, uint256 usdcPayout, uint256 collateralizationRatioBps, bool isPremium);
event ProtocolFeeRouted(string sourceType, uint256 totalFee, uint256 hedgerReserveShare, uint256 collectorShare);
event StakingVaultConfigured(uint256 indexed vaultId, address indexed adapter, bool active);
event UsdcDeployedToExternalVault(uint256 indexed vaultId, uint256 indexed usdcAmount, uint256 principalInVault);
event UsdcWithdrawnFromExternalVault(uint256 indexed vaultId, uint256 indexed usdcAmount, uint256 principalInVault);
event VaultYieldDistributed(uint256 indexed vaultId, uint256 realizedYield, uint256 hedgerShare, uint256 userShare, uint256 treasuryShare);

QEUROToken

Contract: QEUROToken.sol
Interface: IQEUROToken.sol
Inherits: ERC20Upgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable (timelock-gated upgrades)

Function Signatures

mint(address to, uint256 amount)

function mint(address to, uint256 amount) external

Modifiers: onlyRole(MINTER_ROLE) (held by QuantillonVault), whenNotPaused Events: TokensMinted(address indexed to, uint256 indexed amount, address indexed minter) Requirements:

• Minting killswitch off (mintingKillswitch() == false, else MintingDisabled)
• amount > 0; to passes the compliance checks (BlacklistedAddress; NotWhitelisted while whitelist mode is on)
• totalSupply() + amount <= maxSupply() (WouldExceedLimit)
• Within the mint rate limit (rateLimitCaps().mint per 300-block window, else RateLimitExceeded)

burn(address from, uint256 amount)

function burn(address from, uint256 amount) external

Modifiers: onlyRole(BURNER_ROLE) (held by QuantillonVault), whenNotPaused Events: TokensBurned(address indexed from, uint256 indexed amount, address indexed burner) Requirements:

• amount > 0 and balanceOf(from) >= amount
• Within the burn rate limit (rateLimitCaps().burn per 300-block window, else RateLimitExceeded)

batchMint(address[] recipients, uint256[] amounts) / batchBurn(address[] froms, uint256[] amounts)

Batched variants of mint / burn (same roles and checks; at most MAX_BATCH_SIZE = 100 entries).

whitelistAddress(address account) / unwhitelistAddress(address account)

Modifiers: onlyRole(COMPLIANCE_ROLE) Events: AddressWhitelisted(address indexed account) / AddressUnwhitelisted(address indexed account)

blacklistAddress(address account, string reason) / unblacklistAddress(address account)

Modifiers: onlyRole(COMPLIANCE_ROLE) Events: AddressBlacklisted(address indexed account, string indexed reason) / AddressUnblacklisted(address indexed account)

Batched variants: batchWhitelistAddresses, batchUnwhitelistAddresses, batchBlacklistAddresses(address[] accounts, string[] reasons), batchUnblacklistAddresses (MAX_COMPLIANCE_BATCH_SIZE = 50). toggleWhitelistMode(bool enabled) (COMPLIANCE_ROLE) emits WhitelistModeToggled(bool enabled).

updateMaxSupply(uint256 newMaxSupply)

function updateMaxSupply(uint256 newMaxSupply) external

Modifiers: onlyRole(DEFAULT_ADMIN_ROLE) Events: SupplyCapUpdated(uint256 oldCap, uint256 newCap) Requirements: newMaxSupply >= totalSupply() (otherwise NewCapBelowCurrentSupply)

updateRateLimits(uint256 newMintLimit, uint256 newBurnLimit)

Modifiers: onlyRole(DEFAULT_ADMIN_ROLE) — each limit must be <= MAX_RATE_LIMIT (10M QEURO), else RateLimitTooHigh Events: RateLimitsUpdated(string indexed limitType, uint256 mintLimit, uint256 burnLimit)

setMintingKillswitch(bool enabled)

Modifiers: onlyRole(PAUSER_ROLE) Events: MintingKillswitchToggled(bool enabled, address indexed caller)

getTokenInfo() → (string, string, uint8, uint256, uint256, bool, bool, uint256, uint256)

function getTokenInfo() external view returns (
    string memory name_,
    string memory symbol_,
    uint8 decimals_,
    uint256 totalSupply_,
    uint256 maxSupply_,
    bool isPaused_,
    bool whitelistEnabled_,
    uint256 mintRateLimit_,
    uint256 burnRateLimit_
)

State getters

maxSupply(), getSupplyUtilization(), rateLimitCaps() → (uint128 mint, uint128 burn), mintRateLimit(), burnRateLimit(), rateLimitInfo() → (uint96 currentHourMinted, uint96 currentHourBurned, uint64 lastRateLimitReset), mintingKillswitch(), whitelistEnabled(), isWhitelisted(address), isBlacklisted(address), isMinter(address), isBurner(address).

Events

event TokensMinted(address indexed to, uint256 indexed amount, address indexed minter);
event TokensBurned(address indexed from, uint256 indexed amount, address indexed burner);
event AddressWhitelisted(address indexed account);
event AddressUnwhitelisted(address indexed account);
event AddressBlacklisted(address indexed account, string indexed reason);
event AddressUnblacklisted(address indexed account);
event WhitelistModeToggled(bool enabled);
event SupplyCapUpdated(uint256 oldCap, uint256 newCap);
event RateLimitsUpdated(string indexed limitType, uint256 mintLimit, uint256 burnLimit);
event RateLimitReset(uint256 indexed blockNumber);
event MintingKillswitchToggled(bool enabled, address indexed caller);

QTIToken

Contract: QTIToken.sol
Inherits: ERC20Upgradeable, AccessControlUpgradeable, PausableUpgradeable, SecureUpgradeable (timelock-gated upgrades)

Function Signatures

lock(uint256 amount, uint256 lockTime) → (uint256)

function lock(uint256 amount, uint256 lockTime) external returns (uint256 veQTI)

Modifiers: whenNotPaused, nonReentrant
Events: TokensLocked(address indexed user, uint256 amount, uint256 lockTime, uint256 votingPower)
Requirements:

• amount > 0
• lockTime >= MIN_LOCK_TIME && lockTime <= MAX_LOCK_TIME
• Sufficient QTI balance

unlock() → (uint256)

function unlock() external returns (uint256 amount)

Modifiers: whenNotPaused, nonReentrant
Events: TokensUnlocked(address indexed user, uint256 amount)
Requirements: Lock period has expired

getVotingPower(address user) → (uint256)

function getVotingPower(address user) external view returns (uint256 votingPower)

getLockInfo(address user) → (uint256, uint256, uint256, uint256)

function getLockInfo(address user) external view returns (
    uint256 lockedAmount,
    uint256 lockTime,
    uint256 unlockTime,
    uint256 currentVotingPower
)

createProposal(string memory description, uint256 startTime, uint256 endTime) → (uint256)

function createProposal(
    string memory description,
    uint256 startTime,
    uint256 endTime
) external returns (uint256 proposalId)

Modifiers: whenNotPaused
Events: ProposalCreated(uint256 indexed proposalId, string description, uint256 startTime, uint256 endTime)
Requirements:

• Sufficient voting power
• Valid time parameters

vote(uint256 proposalId, bool support)

function vote(uint256 proposalId, bool support) external

Modifiers: whenNotPaused
Events: VoteCast(address indexed voter, uint256 indexed proposalId, bool support, uint256 votingPower)
Requirements:

• Voting period active
• Sufficient voting power
• Not already voted

Events

event TokensLocked(address indexed user, uint256 amount, uint256 lockTime, uint256 votingPower);
event TokensUnlocked(address indexed user, uint256 amount);
event ProposalCreated(uint256 indexed proposalId, string description, uint256 startTime, uint256 endTime);
event VoteCast(address indexed voter, uint256 indexed proposalId, bool support, uint256 votingPower);

UserPool

Contract: UserPool.sol Interface: IUserPool.sol Inherits: SecureUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable

Optional batch front-end over the vault: deposit mints QEURO through QuantillonVault.mintQEURO and sends it to the caller's wallet, withdraw pulls QEURO from the caller's wallet and redeems it through QuantillonVault.redeemQEURO, and stake / requestUnstake / unstake escrow QEURO behind a cooldown. User yield does not accrue here — it accrues through the per-vault stQEURO ERC-4626 token (see stQEUROToken); the former staking-reward claim path was removed. Every user-facing amount function takes arrays (use a one-element array for a single operation); batches are capped at MAX_BATCH_SIZE = 100.

Function Signatures

deposit(uint256[] usdcAmounts, uint256[] minQeuroOuts) → (uint256[] qeuroMintedAmounts)

function deposit(uint256[] calldata usdcAmounts, uint256[] calldata minQeuroOuts)
    external returns (uint256[] memory qeuroMintedAmounts)

Modifiers: nonReentrant, whenNotPaused Events: UserDeposit(address indexed user, uint256 usdcAmount, uint256 qeuroMinted, uint256 timestamp) and UserDepositTracked(...) per entry Requirements:

• usdcAmounts.length == minQeuroOuts.length, non-empty, at most MAX_BATCH_SIZE (ArrayLengthMismatch / EmptyArray / BatchSizeTooLarge)
• each usdcAmounts[i] > 0 (6 decimals); minQeuroOuts[i] is the per-entry slippage floor (18 decimals)
• Sufficient USDC balance and allowance to the UserPool; the vault must accept the mint (QuantillonVault.canMint())

withdraw(uint256[] qeuroAmounts, uint256[] minUsdcOuts) → (uint256[] usdcReceivedAmounts)

function withdraw(uint256[] calldata qeuroAmounts, uint256[] calldata minUsdcOuts)
    external returns (uint256[] memory usdcReceivedAmounts)

Modifiers: nonReentrant, whenNotPaused Events: UserWithdrawal(address indexed user, uint256 qeuroBurned, uint256 usdcReceived, uint256 timestamp) and UserWithdrawalTracked(...) per entry; WithdrawalPending(user, amount) when the USDC transfer to the user fails (e.g. USDC blacklist) Requirements:

• array lengths match, non-empty, at most MAX_BATCH_SIZE; each qeuroAmounts[i] > 0 (18 decimals)
• Sufficient QEURO balance in the caller's wallet and allowance to the UserPool; minUsdcOuts[i] is the per-entry slippage floor (6 decimals)

claimPendingWithdrawal()

Pulls USDC that was queued in pendingUsdcWithdrawals(user) after a failed transfer during withdraw. nonReentrant, whenNotPaused; emits PendingWithdrawalClaimed(address indexed user, uint256 amount); reverts InsufficientBalance when nothing is pending.

stake(uint256[] qeuroAmounts)

function stake(uint256[] calldata qeuroAmounts) external

Modifiers: nonReentrant, whenNotPaused Events: QEUROStaked(address indexed user, uint256 qeuroAmount, uint256 timestamp) per entry Requirements:

• non-empty, at most MAX_BATCH_SIZE entries; each qeuroAmounts[i] >= minStakeAmount() (settable; 100 QEURO live)
• Sufficient QEURO balance and allowance to the UserPool

requestUnstake(uint256 qeuroAmount)

function requestUnstake(uint256 qeuroAmount) external

Modifiers: nonReentrant Starts the unstaking cooldown (unstakingCooldown(), 7 days live) for qeuroAmount of the caller's staked balance; recorded in getUserInfo(user).unstakeAmount / .unstakeRequestTime.

unstake()

function unstake() external

Modifiers: nonReentrant, whenNotPaused Events: QEUROUnstaked(address indexed user, uint256 qeuroAmount, uint256 timestamp) Requirements: a pending requestUnstake whose cooldown has elapsed. Transfers the requested QEURO back to the caller.

getUserInfo(address user) → (uint256 × 7)

function getUserInfo(address user) external view returns (
    uint256 qeuroBalance,        // legacy field, never written: deposited QEURO goes to the user's wallet
    uint256 stakedAmount,        // QEURO currently staked (18 decimals)
    uint256 pendingRewards,      // always 0: the staking-reward path was removed
    uint256 depositHistory,      // cumulative USDC deposited (6 decimals)
    uint256 lastStakeTime,
    uint256 unstakeAmount,       // QEURO in a pending unstake request
    uint256 unstakeRequestTime
)

Pool views

function getPoolTotals() external view returns (uint256 totalDeposits, uint256 totalWithdrawals, uint256 totalStakes_, uint256 totalUsers_);
function getPoolMetrics() external view returns (uint256 totalUsers_, uint256 averageDeposit, uint256 stakingRatio, uint256 poolTVL);
function getPoolConfiguration() external view returns (uint256 stakingAPY_, uint256 depositAPY_, uint256 minStakeAmount_, uint256 unstakingCooldown_, uint256 performanceFee_);
function getTotalDeposits() external view returns (uint256);
function getTotalStakes() external view returns (uint256);
function isPoolActive() external view returns (bool);
function getUserDepositHistory(address user) external view returns (UserDepositInfo[] memory);
function getUserWithdrawals(address user) external view returns (UserWithdrawalInfo[] memory);

Public state getters: stakingAPY(), depositAPY(), minStakeAmount(), unstakingCooldown(), performanceFee(), totalStakes(), totalUsers(), totalUserDeposits(), totalUserWithdrawals(), pendingUsdcWithdrawals(address), hasDeposited(address), userInfo(address).

Governance / emergency

• updateStakingParameters(uint256 newStakingAPY, uint256 newMinStakeAmount, uint256 newUnstakingCooldown) — GOVERNANCE_ROLE; APY capped at 5000 bps. Emits PoolParameterUpdated(string indexed parameter, uint256 oldValue, uint256 newValue) for each field.
• setPerformanceFee(uint256 _performanceFee) — GOVERNANCE_ROLE; max 2000 bps. Mint / redemption fees live in QuantillonVault, not here.
• emergencyUnstake(address user, address recipient) — EMERGENCY_ROLE; force-unstakes a user's full staked balance to recipient (defaults to user).

Events

event UserDeposit(address indexed user, uint256 usdcAmount, uint256 qeuroMinted, uint256 timestamp);
event UserWithdrawal(address indexed user, uint256 qeuroBurned, uint256 usdcReceived, uint256 timestamp);
event UserDepositTracked(address indexed user, uint256 usdcAmount, uint256 qeuroReceived, uint256 oracleRatio, uint256 timestamp, uint256 blockNumber);
event UserWithdrawalTracked(address indexed user, uint256 qeuroAmount, uint256 usdcReceived, uint256 oracleRatio, uint256 timestamp, uint256 blockNumber);
event WithdrawalPending(address indexed user, uint256 amount);
event PendingWithdrawalClaimed(address indexed user, uint256 amount);
event QEUROStaked(address indexed user, uint256 qeuroAmount, uint256 timestamp);
event QEUROUnstaked(address indexed user, uint256 qeuroAmount, uint256 timestamp);
event PoolParameterUpdated(string indexed parameter, uint256 oldValue, uint256 newValue);

HedgerPool

Contract: HedgerPool.sol
Interface: IHedgerPool.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

enterHedgePosition(uint256 usdcAmount, uint256 leverage) → (uint256)

function enterHedgePosition(
    uint256 usdcAmount,
    uint256 leverage
) external returns (uint256 positionId)

Modifiers: whenNotPaused, nonReentrant
Events: HedgePositionOpened(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• usdcAmount > 0
• leverage >= 1 && leverage <= maxLeverage
• Caller must be configured singleHedger
• Fresh oracle price
• Sufficient USDC balance and allowance

exitHedgePosition(uint256 positionId) → (int256)

function exitHedgePosition(uint256 positionId) external returns (int256 pnl)

Modifiers: whenNotPaused, nonReentrant
Events: HedgePositionClosed(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position

addMargin(uint256 positionId, uint256 usdcAmount)

function addMargin(uint256 positionId, uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position
• usdcAmount > 0
• Margin fee is split between local reward reserve and FeeCollector

removeMargin(uint256 positionId, uint256 usdcAmount)

function removeMargin(uint256 positionId, uint256 usdcAmount) external

Modifiers: whenNotPaused, nonReentrant
Events: MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData)
Requirements:

• Position exists and is active
• Caller owns the position
• Maintains minimum margin ratio

claimHedgingRewards() → (uint256, uint256, uint256)

function claimHedgingRewards() external returns (uint256 interestDifferential, uint256 yieldShiftRewards, uint256 totalRewards)

Modifiers: nonReentrant Events: none (the former HedgingRewardsClaimed event was removed in v1.0.1; watch RewardReserveFunded and USDC transfers instead) Requirements:

• Caller must be configured singleHedger
• YieldShift reward component is settled once through YieldShift

withdrawPendingRewards(address recipient)

function withdrawPendingRewards(address recipient) external

Pull-based fallback for pending reward escrow after failed push-transfer.

hasActiveHedger() → (bool)

function hasActiveHedger() external view returns (bool)

Returns true when the configured single hedger has an active position.

getTotalEffectiveHedgerCollateral(uint256 currentPrice) → (uint256)

function getTotalEffectiveHedgerCollateral(uint256 currentPrice) external view returns (uint256 totalEffectiveCollateral)

Returns: Total effective hedger collateral in USDC (6 decimals)
Requirements:

• currentPrice > 0

setSingleHedger(address hedger)

Governance entrypoint for bootstrap/reassignment. Assignment is synchronous: it succeeds only while the backing position (positionId 1) is inactive, and reverts otherwise. (The former delayed applySingleHedgerRotation path was removed as dead code — it could overwrite a live backing position.)

fundRewardReserve(uint256 amount)

Permissionless reserve top-up path for hedger rewards.

configureRiskAndFees(HedgerRiskConfig cfg)

Batch governance setter for risk + fee parameters:

• minMarginRatio
• maxLeverage
• minPositionHoldBlocks
• minMarginAmount
• eurInterestRate
• usdInterestRate
• entryFee
• exitFee
• marginFee
• rewardFeeSplit (1e18 = 100%)

configureDependencies(HedgerDependencyConfig cfg)

Batch governance setter for:

• treasury
• vault
• oracle
• yieldShift
• feeCollector

Events

event HedgePositionOpened(address indexed hedger, uint256 indexed positionId, bytes32 packedData);
event HedgePositionClosed(address indexed hedger, uint256 indexed positionId, bytes32 packedData);
event MarginUpdated(address indexed hedger, uint256 indexed positionId, bytes32 packedData);
event RewardReserveFunded(address indexed funder, uint256 amount);
event SingleHedgerRotationApplied(address indexed previousHedger, address indexed newHedger);
event EmergencyPositionClosed(address indexed hedger, uint256 indexed positionId, uint256 marginReturned, uint256 exposureRemoved);

stQEUROFactory

Contract: stQEUROFactory.sol
Interface: IStQEUROFactory.sol
Inherits: AccessControlUpgradeable, SecureUpgradeable

Function Signatures

registerVault(uint256 vaultId, string vaultName) -> (address stQEUROToken_)

function registerVault(uint256 vaultId, string calldata vaultName) external returns (address stQEUROToken_);

Modifiers: onlyRole(VAULT_FACTORY_ROLE)
Events: VaultRegistered(uint256 indexed vaultId, address indexed vault, address indexed stQEUROToken, string vaultName)
Requirements:

• vaultId > 0
• vaultName uppercase alphanumeric with length 1..12
• unique vaultId, unique caller vault, unique vaultName
• strict self-registration semantics: caller vault is inferred from msg.sender

getStQEUROByVaultId(uint256 vaultId) -> (address)

function getStQEUROByVaultId(uint256 vaultId) external view returns (address stQEUROToken_);

The address-keyed getStQEUROByVault helper was removed. Resolve each series by numeric vaultId.

getVaultById(uint256 vaultId) -> (address)

function getVaultById(uint256 vaultId) external view returns (address vault);

getVaultIdByStQEURO(address stQEUROToken_) -> (uint256)

function getVaultIdByStQEURO(address stQEUROToken_) external view returns (uint256 vaultId);

getVaultName(uint256 vaultId) -> (string)

function getVaultName(uint256 vaultId) external view returns (string memory vaultName);

updateYieldShift(address) / updateTokenImplementation(address) / updateOracle(address) / updateTreasury(address) / updateTokenAdmin(address)

Governance configuration setters affecting future vault token deployments and defaults.

Events

event VaultRegistered(uint256 indexed vaultId, address indexed vault, address indexed stQEUROToken, string vaultName);
event FactoryConfigUpdated(string indexed key, address oldValue, address newValue);

stQEUROToken

Contract: stQEUROToken.sol Interface: IstQEURO.sol Inherits: ERC4626Upgradeable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable, SecureUpgradeable

Per-vault, yield-bearing ERC-4626 vault whose underlying asset() is QEURO. One proxy is deployed per staking vault by stQEUROFactory (live: stQEUROMORPHO1, vaultId = 2). There is no rebasing and no claim call: the share price totalAssets() / totalSupply() rises as credited QEURO yield vests (see the Staking Yield Distribution guide). Roles are GOVERNANCE_ROLE and EMERGENCY_ROLE (plus DEFAULT_ADMIN_ROLE and the SecureUpgradeable upgrade gate); there is no yield-manager role on this contract.

Function Signatures

Standard OpenZeppelin ERC-4626 surface; the four mutators are nonReentrant and whenNotPaused:

function deposit(uint256 assets, address receiver) external returns (uint256 shares);            // stake QEURO
function mint(uint256 shares, address receiver) external returns (uint256 assets);
function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets); // unstake
function totalAssets() external view returns (uint256);                                             // principal + vested QEURO
function convertToAssets(uint256 shares) external view returns (uint256);
function convertToShares(uint256 assets) external view returns (uint256);
function previewDeposit(uint256 assets) / previewMint(uint256 shares) / previewWithdraw(uint256 assets) / previewRedeem(uint256 shares)
function maxDeposit(address) / maxMint(address) / maxWithdraw(address owner) / maxRedeem(address owner)
function asset() external view returns (address);                                                   // QEURO
function syncVesting() external;                                                                      // advance lazy yield vesting

Notes:

• deposit needs a prior QEURO approval to the stQEURO proxy; withdraw / redeem by a third party need share allowance from owner.
• Redeeming the last outstanding shares also sweeps the rounding residual left by ERC-4626 round-down to that final exiter (ResidualSwept).
• totalAssets() excludes unvested QEURO yield and includes principal plus the linearly vested portion. syncVesting() advances the schedule; it is permissionless while unpaused and may be called by governance while the token is paused for a post-upgrade initialization snapshot.
• Current share price: convertToAssets(1e18). A holder's redeemable QEURO: previewRedeem(balanceOf(holder)).

yieldFee() / updateYieldParameters(uint256 _yieldFee)

The legacy yieldFee setting remains on the staking token for compatibility, but vault 1.5.0 ignores it for harvested and directly credited yield. The dapp retires this control for 1.5.0. Existing conversion execution costs still apply. The token setter remains GOVERNANCE_ROLE and emits YieldParametersUpdated(uint256 yieldFee).

updateTreasury(address _treasury)

GOVERNANCE_ROLE; emits TreasuryUpdated(address indexed oldTreasury, address indexed newTreasury, address indexed caller).

emergencyWithdraw(address user)

EMERGENCY_ROLE, nonReentrant: burns all of user's shares and transfers the redeemable QEURO to that user.

Metadata / wiring views

vaultName() (e.g. "MORPHO1"), qeuro(), treasury(), TIME_PROVIDER(), version().

initialize(...)

Two initializers exist:

• initialize(address admin, address _qeuro, address _treasury, address _timelock, string _vaultName) — used by stQEUROFactory; name / symbol become Staked Quantillon Euro {vaultName} / stQEURO{vaultName}.
• initialize(address admin, address _qeuro, address, address, address _treasury, address _timelock) — legacy default-metadata initializer ("Staked Quantillon Euro" / "stQEURO").

Events

event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares);                              // ERC-4626
event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares);  // ERC-4626
event YieldParametersUpdated(uint256 yieldFee);
event TreasuryUpdated(address indexed oldTreasury, address indexed newTreasury, address indexed caller);
event ResidualSwept(address indexed receiver, uint256 amount);

External Vault Adapters

The monolithic AaveVault contract was retired in the multi-vault refactor. External yield is provided by lightweight, non-upgradeable adapters that all implement the same IExternalStakingVault interface and are onboarded per vaultId via setup-external-vaults.sh. Adapters in src/core/vaults/: MetaMorphoStakingVaultAdapter (the live mainnet adapter, vaultId 2 — see Contract Addresses); AaveStakingVaultAdapter and MorphoStakingVaultAdapter wrap the MockAaveVault / MockMorphoVault mocks and exist for localhost / testnet only.

Interface: IExternalStakingVault.sol

Function Signatures

depositUnderlying(uint256 usdcAmount) → (uint256)

function depositUnderlying(uint256 usdcAmount) external returns (uint256 sharesReceived)

Deposits USDC into the wrapped third-party vault. Called by QuantillonVault.deployUsdcToVault(vaultId, usdcAmount).

withdrawUnderlying(uint256 usdcAmount) → (uint256)

function withdrawUnderlying(uint256 usdcAmount) external returns (uint256 usdcWithdrawn)

Withdraws USDC from the wrapped vault back to the protocol.

harvestYieldToVault() → (uint256)

function harvestYieldToVault() external returns (uint256 realizedYield)

Realizes accrued yield and transfers it to the calling vault (VAULT_MANAGER_ROLE). Invoked by QuantillonVault.harvestAndDistributeVaultYield(vaultId), which then splits the realized USDC by the staking ratio between stakers and treasury, paying the hedger only the configured haircut from gross staker yield.

totalUnderlying() → (uint256)

function totalUnderlying() external view returns (uint256 underlyingBalance)

Returns the adapter's current USDC-equivalent balance held in the wrapped vault.

YieldShift

Contract: YieldShift.sol
Interface: IYieldShift.sol
Inherits: SecureUpgradeable, PausableUpgradeable

Function Signatures

addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source)

function addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source) external

Modifiers: nonReentrant; the caller must be authorized for source via setYieldSourceAuthorization (otherwise NotAuthorized), and with strict binding enabled sourceToVaultId(msg.sender) must equal vaultId
Events: YieldAdded(uint256 yieldAmount, string indexed source, uint256 indexed timestamp)
Requirements:

• vaultId > 0 and vault must be registered in stQEUROFactory
• yieldAmount > 0
• Sufficient USDC balance and allowance

updateYieldDistribution()

function updateYieldDistribution() external

Modifiers: whenNotPaused, nonReentrant
Events: YieldDistributionUpdated(uint256 newYieldShift, uint256 userYieldAllocation, uint256 hedgerYieldAllocation, uint256 indexed timestamp)

claimUserYield(address user) — ⚠️ REMOVED

This function has been removed. User yield accrues automatically through the stQEURO wrapper (the user share routes via creditVaultYield → stQEURO). (Hedger yield via claimHedgerYield is unaffected.)

claimHedgerYield(address hedger) → (uint256)

function claimHedgerYield(address hedger) external returns (uint256 yieldAmount)

Modifiers: whenNotPaused, nonReentrant
Events: HedgerYieldClaimed(address indexed hedger, uint256 yieldAmount, uint256 timestamp)

getPoolMetrics() → (uint256, uint256, uint256, uint256)

function getPoolMetrics() external view returns (
    uint256 userPoolSize,
    uint256 hedgerPoolSize,
    uint256 poolRatio,
    uint256 targetRatio
)

calculateOptimalYieldShift() → (uint256, uint256)

function calculateOptimalYieldShift() external view returns (
    uint256 optimalShift,
    uint256 currentDeviation
)

configureYieldModel(YieldModelConfig cfg)

Batch governance setter for:

• baseYieldShift
• maxYieldShift
• adjustmentSpeed
• targetPoolRatio

configureDependencies(YieldDependencyConfig cfg)

Batch governance setter for:

• userPool
• hedgerPool
• mockAaveVault (vestigial: never read by YieldShift; pass address(0))
• stQEUROFactory
• treasury

setYieldSourceAuthorization(address source, bytes32 yieldType, bool authorized)

Governance setter to authorize/revoke a yield source and bind source type.

currentYieldShift(), userPendingYield(address), hedgerPendingYield(address), paused()

Direct state getters used by integrations and indexers.

Events

event YieldDistributionUpdated(uint256 newYieldShift, uint256 userYieldAllocation, uint256 hedgerYieldAllocation, uint256 indexed timestamp);
event YieldAdded(uint256 yieldAmount, string indexed source, uint256 indexed timestamp);
event HedgerYieldClaimed(address indexed hedger, uint256 yieldAmount, uint256 timestamp);
event SourceVaultBindingUpdated(address indexed source, uint256 indexed vaultId);
event SourceVaultBindingModeUpdated(bool enabled);

OracleRouter

Contract: OracleRouter.sol Interface: IOracle.sol Inherits: UUPSUpgradeable, AccessControlUpgradeable, PausableUpgradeable — plain UUPS proxy (not SecureUpgradeable): _authorizeUpgrade is gated by UPGRADER_ROLE, held by the governance Safe, so upgrades execute in one Safe transaction with no timelock

Single oracle entry point for the protocol. All protocol contracts read prices only through OracleRouter; the underlying source can be switched by governance without touching consumers.

Routing slots (enum OracleType { CHAINLINK, MARKET }; live router version 1.1.2):

• Slot 0 (CHAINLINK) — ChainlinkOracle, the fallback.
• Slot 1 (MARKET) — the swappable market-price oracle: StorkOracle historically, currently HyperliquidEurUsdOracle, the active production oracle (activeOracle = 1). Named STORK before v1.1.0; the old storkOracle() getter is a deprecated alias of marketOracle().

Function Signatures

getEurUsdPrice() → (uint256, bool)

function getEurUsdPrice() external returns (uint256 price, bool isValid)

Proxies to the active oracle. Non-view by design — a fresh valid read commits the price into the deviation-baseline cache and emits PriceUpdated; integrators that only need a cheap read should use the cached getters.

Returns:

• price: EUR/USD price (18 decimals)
• isValid: Whether price is fresh and valid

getUsdcUsdPrice() → (uint256, bool)

function getUsdcUsdPrice() external view returns (uint256 price, bool isValid)

getActiveOracle() → (OracleType)

Returns the currently active slot (1 on Base mainnet).

getOracleAddresses() → (address chainlinkAddress, address marketAddress)

Returns both slot addresses (the market slot currently returns the HyperliquidEurUsdOracle address).

marketOracle() → (IOracle) / storkOracle() → (IStorkOracle)

marketOracle() is the slot-1 getter (v1.1.0+). storkOracle() is the pre-1.1.0 name, kept as a deprecated ABI-compatible alias returning the same address.

switchOracle(OracleType newOracle)

function switchOracle(OracleType newOracle) external

Modifiers: onlyRole(ORACLE_MANAGER_ROLE) Events: OracleSwitched(uint8 oldOracle, uint8 newOracle, address caller)

One-transaction failover between slot 0 and slot 1 (e.g. switchOracle(0) falls back to Chainlink).

updateOracleAddresses(address _chainlinkOracle, address _marketOracle)

Modifiers: onlyRole(ORACLE_MANAGER_ROLE) Events: OracleAddressesUpdated

Points a slot at a new oracle contract — this is how HyperliquidEurUsdOracle was installed into slot 1.

Health and config views (getOracleHealth, getEurUsdDetails, getOracleConfig, getPriceFeedAddresses, checkPriceFeedConnectivity) and manager passthroughs (updatePriceBounds, updateUsdcTolerance, updatePriceFeeds, triggerCircuitBreaker, resetCircuitBreaker) forward to the active oracle.

ChainlinkOracle

Contract: ChainlinkOracle.sol Interface: IChainlinkOracle.sol Inherits: UUPSUpgradeable, AccessControlUpgradeable, PausableUpgradeable — plain UUPS proxy (not SecureUpgradeable): _authorizeUpgrade is gated by UPGRADER_ROLE, held by the governance Safe, so upgrades execute in one Safe transaction with no timelock

Fallback EUR/USD oracle (router slot 0) and the protocol's USDC/USD source, reading Chainlink AggregatorV3 feeds.

Validation rules:

• MAX_PRICE_STALENESS (EUR/USD): 2 hours
• MAX_USDC_PRICE_STALENESS: 25 hours
• MAX_PRICE_DEVIATION: 500 basis points (5%) circuit breaker
• MAX_TIMESTAMP_DRIFT: 900 seconds (15 minutes)
• EUR/USD price bounds: 0.80 – 1.40 (18 decimals)
• USDC tolerance: 200 bps (2%), falls back to $1.00 outside tolerance

Function Signatures

getEurUsdPrice() → (uint256, bool)

function getEurUsdPrice() external view returns (uint256 price, bool isValid)

Returns:

• price: EUR/USD price (18 decimals, normalized from the 8-decimal feed)
• isValid: Whether price is fresh and valid

getUsdcUsdPrice() → (uint256, bool)

function getUsdcUsdPrice() external view returns (uint256 price, bool isValid)

Returns:

• price: USDC/USD price (18 decimals, normalized from the 8-decimal feed)
• isValid: Whether price is fresh and valid

updatePriceFeeds(address eurUsdFeed, address usdcUsdFeed)

function updatePriceFeeds(address eurUsdFeed, address usdcUsdFeed) external

Modifiers: onlyRole(ORACLE_MANAGER_ROLE)
Events: PriceFeedsUpdated(address eurUsdFeed, address usdcUsdFeed)
Requirements:

• eurUsdFeed != address(0)
• usdcUsdFeed != address(0)

updatePriceBounds(uint256 minPrice, uint256 maxPrice)

function updatePriceBounds(uint256 minPrice, uint256 maxPrice) external

Modifiers: onlyRole(ORACLE_MANAGER_ROLE)
Events: PriceBoundsUpdated(uint256 minPrice, uint256 maxPrice)
Requirements:

• minPrice < maxPrice

triggerCircuitBreaker()

function triggerCircuitBreaker() external

Modifiers: onlyRole(EMERGENCY_ROLE)
Events: CircuitBreakerTriggered(uint256 timestamp)

resetCircuitBreaker()

function resetCircuitBreaker() external

Modifiers: onlyRole(EMERGENCY_ROLE)
Events: CircuitBreakerReset(uint256 timestamp)

HyperliquidEurUsdOracle

Contract: HyperliquidEurUsdOracle.sol Interface: IHyperliquidOracle.sol (IOracle-compatible) Inherits: UUPSUpgradeable, AccessControlUpgradeable, PausableUpgradeable — plain UUPS proxy (not SecureUpgradeable): _authorizeUpgrade is gated by UPGRADER_ROLE, held by the governance Safe, so upgrades execute in one Safe transaction with no timelock

The ACTIVE production EUR/USD oracle (router slot 1, live since 2026-06-25). EUR/USD is the Hyperliquid EUR perpetual mid-price, published on-chain into SlippageStorage by the off-chain publisher and read via getSlippageBySource(sourceId).midPrice (18 decimals). USDC/USD is delegated to ChainlinkOracle.

Validation rules:

• maxPriceStaleness: 900 seconds default (15 min), hard-capped by HARD_MAX_STALENESS = 3600 seconds
• EUR/USD price bounds: 0.80 – 1.40 (18 decimals)
• MAX_PRICE_DEVIATION: 500 basis points (5%) circuit breaker vs last valid price
• USDC tolerance: 200 bps (2%), falls back to $1.00
• Stale or out-of-bounds price → isValid = false → dependent mint/redeem revert

Function Signatures

getEurUsdPrice() → (uint256, bool)

function getEurUsdPrice() external returns (uint256 price, bool isValid)

Non-view: a fresh valid read updates the deviation-baseline cache and emits PriceUpdated.

getUsdcUsdPrice() → (uint256, bool)

function getUsdcUsdPrice() external view returns (uint256 price, bool isValid)

Delegated to the configured USDC source (ChainlinkOracle).

setMaxPriceStaleness(uint256 newMaxStaleness)

Modifiers: onlyRole(ORACLE_MANAGER_ROLE) — must be ≤ 3600 seconds. Events: MaxStalenessUpdated(uint256 oldStaleness, uint256 newStaleness)

updateSlippageSource(address _slippageStorage, uint8 _sourceId) / updateUsdcSource(address _usdcSource)

Modifiers: onlyRole(ORACLE_MANAGER_ROLE)

updatePriceBounds(uint256 minPrice, uint256 maxPrice) / updateUsdcTolerance(uint256 newToleranceBps)

Modifiers: onlyRole(ORACLE_MANAGER_ROLE)

triggerCircuitBreaker() / resetCircuitBreaker()

Modifiers: onlyRole(EMERGENCY_ROLE)

Health and config views: getOracleHealth, getEurUsdDetails, getOracleConfig, getPriceFeedAddresses, checkPriceFeedConnectivity.

Events

event PriceUpdated(uint256 eurUsdPrice, uint256 usdcUsdPrice, uint256 indexed timestamp);
event CircuitBreakerTriggered(uint256 attemptedPrice, uint256 lastValidPrice, string indexed reason);
event CircuitBreakerReset(address indexed admin);
event PriceBoundsUpdated(string indexed boundType, uint256 newMinPrice, uint256 newMaxPrice);
event SlippageSourceUpdated(address indexed newSlippageStorage, uint8 newSourceId);
event UsdcSourceUpdated(address indexed newUsdcSource);
event MaxStalenessUpdated(uint256 oldStaleness, uint256 newStaleness);

StorkOracle

Contract: StorkOracle.sol Inherits: UUPSUpgradeable, AccessControlUpgradeable, PausableUpgradeable — plain UUPS proxy (not SecureUpgradeable): _authorizeUpgrade is gated by UPGRADER_ROLE, held by the governance Safe, so upgrades execute in one Safe transaction with no timelock

EUR/USD and USDC/USD feeds via the Stork Network, exposing the same IOracle surface as ChainlinkOracle. Parked: it previously occupied router slot 1 and was replaced there by HyperliquidEurUsdOracle on 2026-06-25. The contract remains deployed and can be re-installed via OracleRouter.updateOracleAddresses if needed.

FeeCollector

Contract: FeeCollector.sol Inherits: UUPSUpgradeable, AccessControlUpgradeable, ReentrancyGuardUpgradeable, PausableUpgradeable — plain UUPS proxy (not SecureUpgradeable): _authorizeUpgrade is gated by GOVERNANCE_ROLE, held by the governance Safe, so upgrades execute in one Safe transaction with no timelock

Centralized protocol fee collection and distribution. Distribution ratios (initializer defaults, governance-adjustable, must sum to 10000 bps): treasury 60% / dev fund 25% / community 15%.

Function Signatures

collectFees(address token, uint256 amount, string sourceType)

Records fees pulled from an authorized protocol contract.

Modifiers: onlyFeeSource, whenNotPaused, nonReentrant

collectETHFees(string sourceType)

Payable ETH-fee variant.

Modifiers: onlyFeeSource, whenNotPaused, nonReentrant

distributeFees(address token)

Distributes collected fees to treasury, dev fund, and community fund according to configured ratios.

Modifiers: onlyRole(TREASURY_ROLE), whenNotPaused, nonReentrant

updateFeeRatios(uint256 _treasuryRatio, uint256 _devFundRatio, uint256 _communityRatio)

Modifiers: onlyRole(GOVERNANCE_ROLE) Requirements: _treasuryRatio + _devFundRatio + _communityRatio == 10000

updateFundAddresses(...)

Updates treasury / dev fund / community fund destinations.

Modifiers: onlyRole(GOVERNANCE_ROLE)

authorizeFeeSource(address feeSource) / revokeFeeSource(address feeSource)

Modifiers: onlyRole(GOVERNANCE_ROLE)

Events

event FeesCollected(address indexed token, uint256 amount, address indexed source, string indexed sourceType);
event FeesDistributed(address indexed token, uint256 totalAmount, uint256 treasuryAmount, uint256 devFundAmount, uint256 communityAmount);
event FeeRatiosUpdated(uint256 treasuryRatio, uint256 devFundRatio, uint256 communityRatio);
event FundAddressesUpdated(address treasury, address devFund, address communityFund);

TimeProvider

Contract: TimeProvider (in src/libraries/TimeProviderLibrary.sol) — deployed directly, not behind a proxy

Centralized block.timestamp wrapper used across core contracts, with governance-controlled offset support for test environments.

Function Signatures

currentTime() → (uint256) / rawTimestamp() → (uint256)

Public views: offset-adjusted time and raw block timestamp.

setTimeOffset(int256 newOffset, string reason)

Modifiers: onlyRole(GOVERNANCE_ROLE) — offset bounded (max 7 days) to prevent abuse.

advanceTime(uint256 amount) / resetTime()

Modifiers: onlyRole(GOVERNANCE_ROLE)

setEmergencyMode(bool enabled) / emergencyResetTime()

Modifiers: onlyRole(EMERGENCY_ROLE)

getTimeInfo() / timeDiff(uint256 t1, uint256 t2)

Public views.

Events

event TimeOffsetChanged(address indexed changer, int256 oldOffset, int256 newOffset, string reason, uint256 timestamp);
event EmergencyModeChanged(bool enabled, address indexed changer, uint256 timestamp);
event TimeReset(address indexed resetter, uint256 timestamp);

Access Control Roles

On Base mainnet the governance Safe holds operational governance, upgrade, emergency and oracle-manager roles as configured per contract. The 23 September 2026 activation transferred core default-admin roles to the controller while retaining Safe operational roles; direct-Safe oracle/fee administration is unchanged. Read live hasRole values to verify current authority. Operational roles are delegated to dedicated service wallets: VAULT_OPERATOR_ROLE and YIELD_DISTRIBUTOR_ROLE to keeper wallets, an additional EMERGENCY_ROLE grant on the vault to the hedging watchdog, and SlippageStorage WRITER_ROLE to the off-chain price publisher (currently also held by the deployer EOA). OracleRouter itself holds ORACLE_MANAGER_ROLE and EMERGENCY_ROLE on the market oracle so that its admin passthroughs work. There is no liquidator role — liquidation mode is a protocol-level state (0 < vault CR <= critical ratio (currently 101%)), not a per-position keeper action.

Constants and Limits

Configuration checked against finalized Base block 51,985,907 on 30 September 2026; see Production Protocol Reference. Values marked settable are current live values that governance can change, not immutable constants.

QuantillonVault

• mintFee: 0 (settable, max 5% = 5e16)
• redemptionFee: 0 (settable, max 5%; also applied to liquidation-mode redemptions)
• minCollateralizationRatioForMinting: 102.5% live (1.025e20, since 2026-09-02) — governance-settable (initializer default 105% = 105e18; hard floor 101%)
• criticalCollateralizationRatio: 101% (101e18) — liquidation mode at or below this protocol CR
• MAX_PRICE_DEVIATION: 200 bps (2%) between cached and live oracle price
• hedgerStakingYieldHaircutBps: 0 live on 30 September 2026; governance-settable from 0 to 10,000 bps of gross staker yield. The annual-funding model is retired.

QEUROToken

• Supply model: no fixed tokenomic supply cap — supply is economically bounded by hedging capacity (minting requires the protocol CR to stay above the governance-set minting floor)
• maxSupply: administrative safety ceiling, currently 100,000,000 QEURO (DEFAULT_MAX_SUPPLY; governance-raisable at any time via updateMaxSupply, only constrained to ≥ current supply)
• Decimals: 18
• Mint and burn rate limiting (supply-abuse guardrail, global): each capped at 10,000,000 QEURO per 300-block window (~10 min on Base) — rateLimitCaps() returns (mint, burn), both initialised to MAX_RATE_LIMIT and live at 10M / 10M; adjustable downward by updateRateLimits (DEFAULT_ADMIN_ROLE). RATE_LIMIT_RESET_PERIOD = 300 blocks.

QTIToken

• TOTAL_SUPPLY_CAP: 100,000,000 QTI — current supply is 0 (dormant: no mint path is wired)
• MIN_LOCK_TIME: 7 days · MAX_LOCK_TIME: 365 days
• MAX_VE_QTI_MULTIPLIER: 4× voting power
• proposalThreshold: 100,000 QTI · quorumVotes: 1,000,000 QTI (settable)
• Voting period: 3 days minimum, 14 days maximum · PROPOSAL_EXECUTION_DELAY: 2 days

UserPool

• stakingAPY: 800 bps (8%) · depositAPY: 400 bps (4%) (settable)
• minStakeAmount: 100 QEURO (settable)
• unstakingCooldown: 7 days (settable)
• performanceFee: 0 (settable)

HedgerPool

• coreParams().maxLeverage: 40× (settable via configureRiskAndFees; the MAX_LEVERAGE constant = 65535 is a storage bound; MAX_CONFIGURABLE_LEVERAGE caps configuration at 40) · coreParams().minMarginRatio: 250 bps (2.5%) live since 2026-09-02 — governance-set via configureRiskAndFees: 500 bps at launch, hard floor DEFAULT_MIN_MARGIN_RATIO_BPS = 250 bps since v1.0.8
• MAX_MARGIN_RATIO: 5000 bps (50%, i.e. 2× minimum leverage)
• minMarginAmount: 0 live (settable; initializer default 100 USDC) · minPositionHoldBlocks: 0 live (settable; initializer default 5 blocks)
• entryFee / exitFee / marginFee: 0 (settable)
• eurInterestRate / usdInterestRate: 350 / 450 bps (settable)
• HedgerPool rewardFeeSplit: 0 of its operation fees routed to the reserve (settable). The separate vault hedgerRewardFeeSplit is 20% of collected vault fees; neither is a reward-claim tax.
• Single-hedger model (setSingleHedger; the delayed rotation path was removed, see setSingleHedger above); liquidation is driven by the vault-level critical CR (<= 101%), not a per-position threshold constant

stQEURO

• yieldFee: legacy token setting, ignored by QuantillonVault 1.5.0.

YieldShift

• baseYieldShift: 50% · maxYieldShift: 90% (settable)
• MIN_HOLDING_PERIOD: 7 days · TWAP_PERIOD: 24 hours · MAX_HISTORY_LENGTH: 1000

Oracles

• ChainlinkOracle: EUR/USD staleness 2 h · USDC/USD staleness 25 h · 5% deviation breaker · bounds 0.80–1.40 · USDC tolerance 2%
• HyperliquidEurUsdOracle: staleness 900 s (hard cap 3600 s) · same bounds, breaker, and tolerance

External Vault Adapters

• No fixed exposure/rebalance constants — adapters are thin pass-throughs to the wrapped vault.
• USDC is deployed/withdrawn per vaultId under governance control via QuantillonVault.deployUsdcToVault / harvestAndDistributeVaultYield.

Error Handling

All functions revert with custom errors (no require strings). Errors are declared in the domain error libraries under src/libraries/ and are part of each contract's ABI, so they decode with the contract ABI or with the library ABI. OpenZeppelin errors (AccessControlUnauthorizedAccount, EnforcedPause, ReentrancyGuardReentrantCall, ERC20Insufficient*, ERC4626ExceededMax*, UUPSUnauthorizedCallContext, ...) surface unchanged.

// Revert with a library error
if (amount == 0) revert CommonErrorLibrary.InvalidAmount();

Error Catalogue (from src/libraries/*ErrorLibrary.sol)

CommonErrorLibrary (shared by all contracts)

TokenErrorLibrary (QEUROToken / QTIToken): MintingDisabled, BlacklistedAddress, NewCapBelowCurrentSupply, LockNotExpired, NothingToUnlock, RateLimitExceeded, AlreadyBlacklisted, NotBlacklisted, AlreadyWhitelisted, PrecisionTooHigh, TooManyDecimals

HedgerPoolErrorLibrary (HedgerPool): FlashLoanAttackDetected, InvalidPosition, InvalidHedger, OnlyVault, RewardOverflow, InsufficientMargin, MarginExceedsMaximum, PositionSizeExceedsMaximum, EntryPriceExceedsMaximum, LeverageExceedsMaximum, TimestampOverflow, TotalMarginExceedsMaximum, TotalExposureExceedsMaximum, NewMarginExceedsMaximum, InvalidLeverage, LeverageTooHigh, MarginRatioTooLow, MarginRatioTooHigh, PositionOwnerMismatch, PositionClosureRestricted, InsufficientHedgerCapacity, NoActiveHedgerLiquidity, HedgerHasActivePosition, MinHoldPeriodNotElapsed

VaultErrorLibrary (QuantillonVault): FeeTooHigh

All of these are parameterless (error Name();), so matching on the 4-byte selector (keccak256("Name()")[:4]) is sufficient. Pausing surfaces as OpenZeppelin EnforcedPause().

Gas Optimization

Best Practices

1. Use view functions for read-only operations
2. Batch operations when possible
3. Cache storage reads in loops
4. Use events instead of storage for logging
5. Implement proper access control to prevent unauthorized calls

Gas Figures

No static gas table is maintained here: figures drift with every implementation upgrade. Generate them from the current source with make gas-analysis (outputs under scripts/results/gas-analysis/) or forge test --gas-report.

Integration Patterns

Frontend Integration

// Web3.js example
const contract = new web3.eth.Contract(abi, address);

// Call view function
const result = await contract.methods.getProtocolCollateralizationRatio().call();

// Send transaction
const tx = await contract.methods.mintQEURO(usdcAmount, minQeuroOut)
    .send({ from: userAddress });

Backend Integration

# Web3.py example
from web3 import Web3

w3 = Web3(Web3.HTTPProvider(rpc_url))
contract = w3.eth.contract(address=contract_address, abi=abi)

# Call view function
result = contract.functions.getProtocolCollateralizationRatio().call()  # 1e20 == 100%

# Send transaction
tx_hash = contract.functions.mintQEURO(usdc_amount, min_qeuro_out).transact({
    'from': user_address
})

Solidity Integration Examples

Basic QEURO Minting

// 1. Approve USDC spending
usdc.approve(vaultAddress, usdcAmount);

// 2. Quote the mint (QEURO is 18 decimals, USDC is 6 — never derive the floor from usdcAmount)
ExecutionPricing.Quote memory quote = ExecutionPricing(vault.executionPricing()).previewMint(usdcAmount);
uint256 expectedQeuro = quote.amountOut;
uint256 minQeuroOut = (expectedQeuro * 95) / 100; // 5% slippage tolerance

// 3. Mint QEURO with slippage protection
vault.mintQEURO(usdcAmount, minQeuroOut);

Staking QEURO

// 1. Approve QEURO spending
qeuro.approve(userPoolAddress, qeuroAmount);

// 2. Stake QEURO — UserPool functions take arrays (one element for a single stake)
uint256[] memory amounts = new uint256[] (1);
amounts[0] = qeuroAmount; // must be >= userPool.minStakeAmount()
userPool.stake(amounts);

// There is no staking-reward claim. Protocol yield for users accrues automatically
// through the stQEURO ERC-4626 token (rising share price) — deposit QEURO into the
// per-vault stQEURO (stQEUROFactory.getStQEUROByVaultId(vaultId)) to earn it.

Opening a Hedge Position

// 1. Approve USDC spending (caller must be the configured single hedger)
usdc.approve(hedgerPoolAddress, marginAmount);

// 2. Open position with 5x leverage (max leverage: 40x)
uint256 positionId = hedgerPool.enterHedgePosition(marginAmount, 5);

// 3. Monitor hedger activity / claim rewards
bool hedgerActive = hedgerPool.hasActiveHedger();
(uint256 interestDiff, uint256 ysRewards, uint256 total) = hedgerPool.claimHedgingRewards();

Governance Participation

Note: QTI is currently dormant (supply 0, no mint path wired) — these calls become functional after the activation upgrade.

// 1. Lock QTI for voting power
qti.lock(lockAmount, lockDuration);

// 2. Create proposal
uint256 proposalId = qti.createProposal(
    "Update protocol parameters",
    block.timestamp + 1 days,
    block.timestamp + 7 days
);

// 3. Vote on proposal
qti.vote(proposalId, true); // Vote yes

Security Considerations

1. Always validate return values from view functions
2. Check contract state before making transactions
3. Use slippage protection for all swaps
4. Monitor oracle prices for freshness
5. Implement proper error handling for all interactions
6. Use events for transaction monitoring
7. Follow access control patterns for role-based operations

Support

For technical support and questions:

• Email: team@quantillon.money
• Documentation: Quantillon Protocol Docs
• GitHub: Quantillon Labs

This technical reference is maintained by Quantillon Labs and updated with each protocol version.

Yield and collateralization gates

The public mint floor remains the governance value read from minCollateralizationRatioForMinting; clients must read this value on-chain rather than use a frontend default. Yield crediting uses a separate gate: current collateralization must be strictly greater than max(101%, criticalCollateralizationRatio), projected collateralization must remain at least 100%, and the cached oracle, active hedger, execution book, QEURO token state, and hedger capacity must all pass. A failed harvest reverts the entire transaction so adapter yield remains available for a later retry.

Quantillon Protocol Quick Start

Signed quotes are active on Base since 17 October 2026. Normal mint and redemption must use executeWithQuote(bytes,bytes) on the authorized Vault or UserPool target. Bare conversion calls and the legacy pricing module's previews are not the current integration path.

This ethers v6 example uses the UserPool conversion route. It does not use UserPool's optional staking accounting. The later staking example deposits QEURO directly into the ERC-4626 series. Use the address inventory and production guide, and test with an isolated fork before integration.

Connect and pin the intended deployment

import { BrowserProvider, Contract, Interface, keccak256, parseUnits, ZeroAddress } from 'ethers';

const provider = new BrowserProvider(window.ethereum);
if ((await provider.getNetwork()).chainId !== 8453n) throw new Error('Select Base');
const signer = await provider.getSigner();
const owner = await signer.getAddress();
const vaultAddress = '0x833E5Ba510a241b21F1C60c987D1c49eB52E4a07';
const poolAddress = '0x712bCc77e7aa53C79870A40d044D440Ad2901bF2';
const moduleAddress = '0x076F86a591258957665b65c04F04B706D00EaEBa';
const qeuroAddress = '0x69aD4e6c49d6275D0e11b5515D98a89f029869AA';
const usdcAddress = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const factoryAddress = '0x0382B0b9FB6Ff737209C3B31D727BB9d2E2bcb53';
const tokenAbi = [
  'function approve(address spender,uint256 amount) returns (bool)',
  'function balanceOf(address owner) view returns (uint256)',
];
const usdc = new Contract(usdcAddress, tokenAbi, signer);
const qeuro = new Contract(qeuroAddress, tokenAbi, signer);
const vault = new Contract(vaultAddress, [
  'function executionPricing() view returns (address)',
  'function signedExecutionEnabled() view returns (bool)',
], provider);
const pool = new Contract(poolAddress, [
  'function executeWithQuote(bytes callData,bytes authorization) returns (bytes)',
], signer);
const route = new Interface([
  'function deposit(uint256[] amounts,uint256[] minimums)',
  'function withdraw(uint256[] amounts,uint256[] minimums)',
]);

Approval, quote and review

For a mint, approve USDC to the selected target before requesting an executable quote:

const inputUsdc = parseUnits('100', 6); // illustrative user-selected amount
await (await usdc.approve(poolAddress, inputUsdc)).wait();

The dapp's authenticated gateway accepts POST /api/quotes with a JSON body such as {"action":"MINT","amountIn":"100000000","chainId":8453,"route":"USER_POOL"} and the wallet identity associated with the authenticated session. The frontend supplies credentials: 'include' and x-wallet-address; a header alone does not establish a login session. Integrators must arrange access to the quote service. POST /api/quotes/preview returns a preview, not an executable authorization.

An executable envelope contains chainId, module, target, callData, authorization and a quote with wallet/caller, action, exact input/output, observation time, validity times, nonce, epoch and hashes. Display the output and deadline for user review. Use integer base units: USDC has 6 decimals and QEURO has 18.

Submit the reviewed UserPool quote

The function below accepts an envelope already obtained from the quote service, plus the exact action, input and output reviewed by the user. It checks the deployment and allowed inner call before sending anything. The contract validates the signatures and remaining protocol guards.

async function settleReviewedPoolQuote(envelope, reviewed) {
  const same = (a, b) => a.toLowerCase() === b.toLowerCase();
  if (!['MINT', 'REDEEM'].includes(reviewed.action)) throw new Error('Invalid action');
  if (reviewed.amountIn <= 0n || reviewed.amountOut <= 0n) throw new Error('Invalid amount');
  if ((await provider.getNetwork()).chainId !== 8453n ||
      !same(await signer.getAddress(), owner)) throw new Error('Wallet or chain changed');
  if (!await vault.signedExecutionEnabled() ||
      !same(await vault.executionPricing(), moduleAddress)) throw new Error('Deployment changed');
  const q = envelope.quote;
  const action = reviewed.action === 'MINT' ? 0 : 1;
  const functionName = action === 0 ? 'deposit' : 'withdraw';
  const expectedCall = route.encodeFunctionData(functionName, [
    [reviewed.amountIn], [reviewed.amountOut],
  ]);
  if (envelope.chainId !== 8453 || !same(envelope.target, poolAddress) ||
      !same(envelope.module, moduleAddress) || !same(q.user, owner) ||
      !same(q.caller, poolAddress) || q.action !== action ||
      BigInt(q.amountIn) !== reviewed.amountIn || BigInt(q.amountOut) !== reviewed.amountOut ||
      envelope.callData.toLowerCase() !== expectedCall.toLowerCase() ||
      q.callHash.toLowerCase() !== keccak256(envelope.callData).toLowerCase()) {
    throw new Error('Quote differs from the reviewed operation');
  }
  const checkTime = () => {
    const now = BigInt(Math.floor(Date.now() / 1000));
    if (BigInt(q.validAfter) > now || BigInt(q.observedAt) > now ||
        BigInt(q.validUntil) < now + 10n ||
        BigInt(q.validUntil) - BigInt(q.observedAt) > 45n) {
      throw new Error('Request and review a fresh quote');
    }
  };
  checkTime();
  await pool.executeWithQuote.staticCall(envelope.callData, envelope.authorization);
  checkTime();
  const tx = await pool.executeWithQuote(envelope.callData, envelope.authorization);
  // Persist tx.hash immediately; reconcile its receipt before any retry.
  return tx;
}

The 10-second remaining-time check is a client convenience, not an inclusion guarantee. The onchain maximum is 45 seconds from the market observation. Simulation does not reserve public liquidity, and state changes or wallet delays can still cause a revert. Never modify the signed calldata or silently refresh the user's accepted output.

Stake QEURO directly

const factory = new Contract(factoryAddress, [
  'function getStQEUROByVaultId(uint256 vaultId) view returns (address)',
], provider);
const seriesAddress = await factory.getStQEUROByVaultId(2n);
if (seriesAddress === ZeroAddress) throw new Error('No staking series');
const series = new Contract(seriesAddress, [
  'function asset() view returns (address)',
  'function previewDeposit(uint256 assets) view returns (uint256)',
  'function deposit(uint256 assets,address receiver) returns (uint256)',
  'function balanceOf(address owner) view returns (uint256)',
  'function convertToAssets(uint256 shares) view returns (uint256)',
  'function redeem(uint256 shares,address receiver,address owner) returns (uint256)',
], signer);
if ((await series.asset()).toLowerCase() !== qeuroAddress.toLowerCase()) {
  throw new Error('Unexpected staking asset');
}
const assets = parseUnits('10', 18); // user-selected amount, must be available
if (await qeuro.balanceOf(owner) < assets) throw new Error('Insufficient QEURO');
await (await qeuro.approve(seriesAddress, assets)).wait();
const expectedShares = await series.previewDeposit(assets);
if (expectedShares === 0n) throw new Error('Deposit would produce no shares');
await series.deposit.staticCall(assets, owner);
await (await series.deposit(assets, owner)).wait();
const shares = await series.balanceOf(owner);
const vestedAssets = await series.convertToAssets(shares);

Standard ERC-4626 deposit does not accept a minimum-share argument: a preview is informational, not slippage protection. The vault's signed mintAndStakeQEURO inner operation has an explicit minimum-share parameter for a combined mint/stake. Yield increases the assets represented by shares as it vests; no separate staking-reward claim is needed. See Yield Distribution 1.5.0.

Next steps

Integration Examples covers redemption, unstaking and transaction recovery. Dapp Compatibility lists release checks. Use the compiled ABI matching each active implementation, including library errors.

Integration Examples

Use the ethers v6 setup and contract objects from Quick Start. These examples illustrate client integration; simulate and test them on an isolated fork before use. They are not a guarantee of current liquidity or transaction success.

Normal redemption

Approve the input QEURO to the same UserPool target used in Quick Start:

const inputQeuro = parseUnits('10', 18);
await (await qeuro.approve(poolAddress, inputQeuro)).wait();

Then request an executable quote with action: 'REDEEM', amountIn: inputQeuro.toString(), chainId: 8453 and route: 'USER_POOL'. Display its exact USDC output and expiry. After review, pass the envelope and the reviewed values to settleReviewedPoolQuote from Quick Start, record the returned transaction hash and await its receipt. The function validates that the inner call is precisely withdraw([inputQeuro], [reviewedUsdcOutput]).

Normal signed redemption does not use the retired module's degraded-reference fallback. The current emergency-redemption budget is 0 QEURO, so missing quotes do not automatically open an alternative exit. Protocol liquidation mode uses a separate proportional-backing payout rule, still subject to signed settlement and current contract guards. Never set a zero minimum to bypass an unavailable quote.

Unstake shares into QEURO

const sharesToRedeem = parseUnits('1', 18); // share units, not QEURO assets
const receivedQeuro = await series.redeem.staticCall(sharesToRedeem, owner, owner);
if (receivedQeuro === 0n) throw new Error('Redemption produces no QEURO');
await (await series.redeem(sharesToRedeem, owner, owner)).wait();

This returns QEURO, not USDC. A later QEURO-to-USDC redemption is a separate operation with its own quote and approval. Standard ERC-4626 redemption has no minimum-assets argument; simulations do not protect against all intervening state changes. Direct stQEURO redemption is separate from UserPool's unstaking cooldown.

Portfolio reads

Use qeuro.balanceOf(owner) for unstaked QEURO, series.balanceOf(owner) for shares and series.convertToAssets(shares) for currently recognized assets. Raw assets used in the harvest allocation include unvested credit and can differ from vested ERC-4626 assets.

The provider's APY, UserPool's configured accounting APY, a realized share-price return and future yield are different metrics. Do not label one as a guarantee of another.

Optional and privileged interfaces

• UserPool: deposit and withdrawal inner methods accept arrays and must use the signed wrapper for conversion; optional staking methods have their own accounting. Its bookkeeping and unstaking cooldown are not the direct stQEURO flow.
• HedgerPool: reference-dependent position operations use executeWithReference or scoped removeMarginWithReference, retaining their existing ownership and role checks. Client-side visibility does not grant that authority. HedgerPool and Hyperliquid margin are separate balances.
• Yield keeper: harvest conversion uses its bounded signed authorization as well as the configured distributor role and valid strategy/liquidity/collateral conditions. Daily scheduling is an operated service, not an autonomous Solidity timer.
• QTI: supply is zero and governance is dormant. Examples of lock/propose/vote are API descriptions, not currently usable public governance.
• Administration: core default-admin operations require the controller; retained Safe roles and peripheral administration have different paths. Resolve current roles before constructing calls.

Transaction recovery

Record a submitted transaction hash and check its receipt before retrying. A network timeout does not prove a transaction failed. Reconcile pending/confirmed state and the wallet nonce, then obtain a fresh quote and ask the user to review any changed output. Do not automatically resubmit a deposit or mint after an ambiguous response.

For revert decoding use the ABI matching the active implementation, including relevant library errors. Report stale/invalid pricing, insufficient capacity, pauses, allowances and minimum-output failures separately where the decoded error supports that distinction. Never silently widen a user's tolerance.

See Production Protocol Reference, API Reference and Security Guide.

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:

1. Deploy and verify the new implementation (run make check-verifiable-bytecode CONTRACT=<Name> first)
2. Validate compatibility (make check-upgrade-safety: size, storage layout, ABI, version bump)
3. SecureUpgradeable proxies: the Safe schedules upgradeToAndCall on the TimelockController, waits 12 h, then executes; plain-UUPS proxies: the Safe calls upgradeToAndCall directly
4. 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

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

Development Principles

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

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

Oracle Architecture

Valuation and execution

Since 17 October 2026, signed reference reports supply the EUR/USD valuation path. SignedReferenceSource 1.0.0 checks the report signature, original observation time, sequence, epoch and independent Chainlink reference. HyperliquidEurUsdOracle 1.0.7 consumes that source in OracleRouter's active market slot 1. ChainlinkOracle in slot 0 remains a manual governance fallback and the USDC/USD source.

Reference valuation is separate from an exact execution quote. SignedExecutionPricing 1.1.0 validates transaction-specific execution authorization and signed hedge-capacity reports. A trade's size-dependent price does not change the valuation of all outstanding QEURO.

Data flow

Hyperliquid observation -> reference signer -> signed reference report
                                                | delivered with a transaction
                                                v
Chainlink independent reference ----------> SignedReferenceSource
                                                |
                                                v
                                      HyperliquidEurUsdOracle
                                                |
                                                v
                                           OracleRouter
                                                |
                                    Vault / HedgerPool accounting

Exact execution quote + capacity report -> SignedExecutionPricing -> settlement

SlippageStorage and the publication batchers are historical deployments; they no longer feed the active signed reference path. The adapter's slippageStorage() getter retains its legacy name but now returns SignedReferenceSource. The periodic publisher is retired.

Freshness and validity

Normal reference and capacity reports have a 60-second maximum age in the verified configuration. Execution quotes have a separate 45-second maximum measured from the original market observation. The adapter's 900-second market snapshot limit is an additional check, not permission to use an expired signed report or quote.

Report delivery preserves the original observation timestamp. Replaying an identical report cannot refresh it; an older report cannot overwrite a newer cached reference. Price bounds, independent-reference comparison, USDC validation and circuit breakers remain applicable. A rejected price is not made usable by returning a cached value with isValid = false.

The adapter supports the signed source's explicit emergency reference policy, with a configured age ceiling of 8100 seconds and the independent oracle's own validity checks. Emergency redemption has zero budget and is disabled in the current production configuration. Ordinary signed quotes cannot use this emergency age window.

Readiness during inactivity

A stored observation may age while no transaction needs it. Dashboards, keepers and the watchdog can obtain fresh signed reports and simulate their delivery with the relevant read or operation. Those simulations do not persist state and do not spend publication gas. An idle cache alone does not establish that signed delivery is unavailable.

The watchdog monitors fresh delivery and hedge health. Slow but successful probes are distinct from failed readiness checks. A valid signature establishes authorization, not economic accuracy or a completed Hyperliquid fill. Current state can still change between simulation and settlement.

Fallback and governance

OracleRouter selects one source; it does not automatically fail over. Switching to Chainlink is a governance action and does not, by itself, restore execution quotes, hedge capacity or a paused vault. Normal signed settlement fails closed when required data or authorization is unavailable.

Oracle proxies retain their peripheral administration and upgrade paths. The core controller and Safe have different responsibilities; a signed report grants no administrative role. Confirm live roles before constructing governance calls.

See Signed Quotes, Execution Pricing and Deployment Status for the verified release and user-facing behavior.

Signed Quotes in Production

Signed quotes were activated on Base mainnet (8453) on 17 October 2026. The confirmed governance execution is recorded at block 52,720,621. The production dapp reopened at 10:08 UTC after the coordinated contract and service cutover. The recurring market publisher is retired.

Versions and active bindings below were read at finalized Base block 52,727,379 on 17 October. These are dated observations; read the live contracts before integration.

QuantillonVault.executionPricing() points to SignedExecutionPricing and signedExecutionEnabled() is true. The pricing module's referenceSource() and the market adapter's legacy-named slippageStorage() getter both point to SignedReferenceSource. OracleRouter still selects market slot 1. The pricing mode is NORMAL and the non-renewing emergency budget is 0 QEURO. The pricing module's active() getter describes a temporary settlement context, not whether signed execution is enabled.

See Production Protocol Reference for dated economic settings and Quick Start for the current integration path.

Three separate responsibilities

A trade's size-dependent execution rate must never revalue all outstanding QEURO. Signing amountOut does not bypass collateralization, protocol fees, execution spread, route validation or hedge-capacity limits.

Normal minting buys EUR exposure using asks. Redemption reduces that exposure using bids. The quote engine retains the reference clamps, walks the book with integer arithmetic and includes the configured execution buffer. The venue hedge follows Base settlement and remains non-atomic.

Contracts and entrypoints

SignedExecutionPricing and SignedReferenceSource are new non-upgradeable modules. QuantillonVault, UserPool and HedgerPool received governed implementation upgrades in this release. Linked settlement libraries must be included in deployment verification and bytecode-size checks.

The vault's existing configureExecutionPricing(address) detects the signed module. It still requires a paused vault, correct vault binding and no outstanding exposure in the previous module. The appended signedExecutionEnabled flag closes the old unquoted conversion paths. UserPool adds an appended route guard; existing deposit and withdrawal accounting runs with the original user.

The HedgerPool wrapper does not change ownership or roles. Add-margin stays available directly without a quote or reference signer. Delegated Safe/Zodiac callers use the typed removeMarginWithReference(uint256,uint256,bytes) route with scoped permissions. A signature does not grant caller authority.

Signature and calldata binding

Execution EIP-712 uses name Quantillon Execution, version 1, the deployment chain ID and the execution module as verifying contract. The quote includes:

address user;
address caller;
uint8 action;
uint256 amountIn;
uint256 amountOut;
uint256 observedAt;
uint256 validAfter;
uint256 validUntil;
uint256 nonce;
uint256 epoch;
bytes32 callHash;
bytes32 referenceHash;

callHash binds the complete inner calldata, including the route, vault ID and minimum shares when staking. Pool settlement binds caller to UserPool and user to the original wallet. Nonces are consumed per original user. Epoch changes invalidate outstanding execution authorizations; revoking a signer invalidates its signatures at settlement.

The authorization is ABI-encoded as (Quote,bytes,ReferenceReport,bytes,CapacityReport,bytes) inside the shared Authorization struct. Reference-only authorization is abi.encode(ReferenceReport, signature). The fixed wire vector is tested in both Node and Solidity for exact tuple encoding, signature recovery and chain-domain separation.

Reference signatures use domain name Quantillon Reference and the reference-source address. They carry price, original observation time, sequence and source epoch. Exact replay is idempotent; it cannot refresh the observation timestamp. An authenticated older report may accompany a still-valid quote, but it cannot replace a newer cached reference. Capacity reports carry cumulative acknowledged buys and sells, margin capacity, observation time, sequence, execution epoch and the canonical Base block/hash inspected by the signer.

Accounting and concurrency

For a mint, received USDC is split into protocol fees, reference-valued backing and execution spread. Token transfers, hedger synchronization, quote consumption and admission occur atomically. Failure rolls back all of them, including UserPool tracking and any report updates.

Out-of-order capacity delivery retains the latest accepted margin limit, original observation time and cumulative acknowledgments. All delivered signatures still require the authorized signer, current epoch, valid age and canonical block. Conflicting reports with the same sequence revert.

Exact output stays signed, while backing and reference-valued fees use the latest accepted reference. A quote can therefore fail current collateral or impact checks before its deadline; the deadline is an expiry bound, not an unconditional execution guarantee.

The signed module counts unresolved buys plus unresolved sells toward its gross admission limit. They do not cancel each other merely because their net exposure is zero. This is more conservative than the previous directional policy and must be included in capacity calibration.

Offchain reservations serialize all quote workers sharing a deployment. Reserved public order-book depth represents Quantillon's risk budget; it does not reserve liquidity on Hyperliquid. Release requires canonical nonce, epoch, time and settlement evidence. Unknown consumed nonces and reorganized settlements retain their budget.

Expiration and failure behavior

SignedExecutionPricing 1.1.0 enforces a forty-five-second maximum, measured from the original market observation. The matching API defaults to forty-five seconds. Production uses this forty-five-second limit. The module and reference source separately enforce a 60-second report-age limit; that does not extend a quote deadline. Issue age is bounded; the interface requires enough remaining time before opening the wallet. A quote can still expire during wallet interaction or inclusion. Approval precedes executable quote issuance.

Normal signed settlement fails closed on stale market data, invalid reference, exhausted capacity, bad signatures, expired authorization or pause. Emergency redemption is a separate mode, with a non-renewing budget and independent-reference checks. Switching modes alone does not replenish that budget. The existing market adapter's freshness policy also applies; emergency behavior must be rehearsed against the actual router and adapter.

Keeper yield conversion uses a distinct bounded-rate authorization because the exact harvested amount is known only during the transaction. The signed maximum must not be exceeded. Zero-harvest behavior, role checks, staking allocation and vesting must remain unchanged. Public quote issuance does not grant keeper authority.

Operations after activation

The paired dapp, quote/reference/capacity services, hedging engine, watchdog, dashboard and keeper consumers use the signed deployment. Required backend migrations and the reconciliation baseline were applied during maintenance before reopening. Fresh signed delivery is checked with read-only simulations; an idle cache alone does not require a paid publication transaction.

For a future upgrade, stage against actual deployed addresses, respect the controller's 12-hour delay and pause admission for binding changes and reconciliation. Timelock expiry does not execute an upgrade automatically. Keep admission closed if versions, signer authorization, references or hedge readiness do not match the reviewed release.

After signed settlements, a rollback must preserve transaction journals and reconcile real venue fills, consumed quotes and cumulative onchain admission. Restoring an old database or pointing to a legacy pricing module does not undo settlement.

Eliminating idle periodic publication removes its recurring gas expense. User settlement, governance, emergency actions and necessary operational acknowledgments still require transactions. No cross-chain fill guarantee is created by a signature.

Deploying a future inactive module

scripts/deployment/DeploySignedQuoteModules.s.sol deploys the reference and execution modules without changing any proxy, oracle binding or active pricing module. It requires the explicit environment/chain pair (dev/31337, preprod/31338, prod/8453), existing vault and independent-reference contracts, governance, reserve recipient and all risk bounds. Both modules are owned by governance from construction; the broadcaster receives no role. Execution remains paused and there are no authorized signing keys until governance configures them.

Before activation, governance must grant the reference signer on the source, grant the execution module the source's emergency-controller role, and grant separate execution and capacity signers on the pricing module. Bind the oracle adapter to the new reference source, upgrade the required vault/UserPool/HedgerPool implementations with their verified linked libraries, and check all bindings and roles against the release receipt. These operations belong to the governed cutover after old exposure is reconciled; module deployment alone does not satisfy that cutover.

The deployment script logs module addresses, not public Safe import payloads. Keep broadcaster receipts and any governed transaction staging artifacts in private operator storage. Do not run --broadcast as part of unit tests or documentation builds.

Historical preproduction validation (12 October 2026)

The integration passed direct mint/redemption, UserPool deposit/withdrawal, mint-and-stake share issuance, replay rejection, expiry rejection, signed keeper harvesting and a coordinated reset with fresh quote domains. Reference-backed dashboard and keeper previews use read-only simulation. A 70-second idle check confirmed no publisher transaction and no persistent reference update while valuation remained available. Hedge capacity remains simulated; no real Hyperliquid fill or production risk calibration is implied. Private installation receipts and keys are not published.

Historical production rehearsal and authority

The dedicated production candidate was rehearsed on a private Base fork pinned to block 52,554,188. The deployed TimelockController requires 43,200 seconds; execution before this delay was rejected. Vault 1.6.0, UserPool 1.3.0 and HedgerPool 1.6.0 were activated with their linked libraries, the signed reference source and signed pricing module. This is a migration rehearsal, not live deployment or a real Hyperliquid execution test.

The existing proxies assign operational GOVERNANCE_ROLE and EMERGENCY_ROLE to the Safe, while the timelock executes upgrades. Keep that division in the transaction plan. Initialize UserPool pending liabilities only when its explicit initialization flag is false. Preserve hedger cost-basis accounting.

The typed production Roles permission restricts removeMarginWithReference to position 1, a positive amount and CALL with no ETH. Dynamic reference bytes still require the pool's normal authorization checks. The paired backend verifies the exact permission event, storage and condition runtime; no generic reference-call permission is granted.

Before reopening admission, install the paired Dapp/services/watchdog release, initialize the immutable real-venue reconciliation baseline during the pause, and check the active module, source, signing authorities and signed readiness. There is no mandatory seven-day shadow window or completed-hedge quota. After activation, a software rollback must not silently replace contract bindings or discard signed settlements, journaled transactions or executed venue fills.

Public CI and private deployment entrypoint

The encrypted scripts/deployment/DeploySignedQuoteModules.s.sol entrypoint inherits the secret-free implementation in scripts/utils/SignedQuoteDeployment.s.sol. Tests import that implementation so an ordinary GitHub checkout can compile and validate environment guards and inactive deployments without the git-crypt key. No deployment credentials or transaction payloads are published.

Emergency freshness compatibility

The production release includes HyperliquidEurUsdOracle 1.0.7. Its ordinary market snapshot window is unchanged. In the governed signed source's explicit emergency mode it accepts that source's independent-reference age policy up to 8100 seconds. Original observation timestamps are preserved. Invalid or expired independent rounds still fail at the source; adapter bounds, reference comparison, USDC checks and circuit breakers still apply. A legacy source lacking the signed emergency getters cannot extend its snapshot window.

The configured emergency reference-age ceiling is 8100 seconds, subject to the independent oracle's own validity checks. This does not enable emergency redemption: the current emergency budget is zero. Any future activation requires governed configuration and validation through the source, adapter, router and vault. Normal quotes do not use this extended emergency window.

Signed Quotes: Historical Consolidation Record

Production activation completed on 17 October 2026. See Signed Quotes in Production. The dated candidate and rehearsal evidence below describes the preparation stage, not current deployment status.

Historical branch promotion — 13 October 2026

feat/signed-quotes-migration now contains the source and test changes validated on preprod through 08387433. The promotion preserves the original candidate history. It does not upgrade Base, change deployment manifests, send governance transactions or publish the production documentation site. Paired Dapp evidence is in docs/migrations/signed-quotes-production-sync-2026-10-13.md in the frontend repository.

Candidate versions are Vault 1.6.0, UserPool 1.3.0, HedgerPool 1.6.0 and ReferenceSettlementLibrary 1.1.0. The typed margin withdrawal and normal, paused, capacity-constrained, emergency and liquidation settlement tests are included. The six newly declared interface functions now have complete NatSpec. This documentation completion changes no runtime bytecode: canonical artifacts were compared before and after, and only matching-version dependency hashes were refreshed. No interface selector or storage field was changed by that completion.

Fresh validation: 186 tests across seven signed/reference suites; EIP-170, append-only storage, additive ABI, version tracing, 100% NatSpec and generated documentation checks. These are candidate checks, not production activation evidence.

Production preparation subsequently added live fill evidence/allocation, typed Roles permission support and private service/Dapp staging in the paired Dapp branch. An isolated Base fork at block 52,554,188 repeated deployment, the actual TimelockController's 43,200-second delay, refusal before eligibility and activation of these three proxy versions. The Safe performs operational pause and configuration; the timelock performs the upgrades. Existing UserPool pending liability initialization must be preserved rather than run a second time. No extra Solidity runtime change was needed for this backend preparation.

Before production activation, validate preprod, complete independent review and initial parameter/signer selection, deploy inactive production modules, stage artifacts against their actual addresses and submit the reviewed permissions and upgrade proposals. User decision on 13 October: no mandatory shadow duration or completed-hedge quota. Cut over services, Dapp and contracts with the explicit activation after the 12-hour governance delay, keeping admission closed until bindings and readiness are verified. Timelock expiry alone does not execute the upgrade. See docs/migrations/signed-quotes-production-preparation.md in the Dapp repository for the executable rehearsal and staged cutover sequence. Fork keys, mock feeds and fixture transaction artifacts must never be used on Base.

The historical preprod evidence below retains its original scope.

Signed quotes: preprod consolidation (2026-10-13)

Scope: the dedicated feat/signed-quotes-preprod branch. This change does not authorize a production or dev deployment.

Contract changes

HedgerPool 1.6.0 adds removeMarginWithReference(positionId, amount, authorization). It returns the underlying operation's ABI-encoded return data (empty for a successful withdrawal). The linked ReferenceSettlementLibrary 1.1.0 submits the governed signed reference and delegates the existing withdrawal in the same transaction. A failed withdrawal rolls back the reference update. The original caller, ownership, pause, reentrancy, margin and collateral checks remain in force. No storage field or namespace is added.

The typed selector exposes position and amount to Zodiac Roles conditions without granting the generic executeWithReference(bytes,bytes) wrapper. Existing generic reference operations remain supported for hedgers signing directly.

IHedgerPool and IQuantillonVault now declare their existing signed settlement entrypoints, in addition to the new typed withdrawal. The interfaces do not remove legacy selectors or economic guards. Removing the Dapp's legacy deviation input does not remove onchain reference bounds or execution impact limits.

Permissions and rollout

Preprod uses a local fork (chain 31338), with external capital execution disabled. Its governance impersonation is strictly local. Upgrade only HedgerPool; preserve pricing modules, signers, capacity counters, positions, and pause state. Record the implementation, library addresses, source commit and runtime hash privately. Keep the previous implementation for rollback; storage compatibility is unchanged.

Before enabling a Safe operator on any environment, governance must explicitly scope the typed selector to the correct pool and position, zero ETH value and CALL operation, retaining the reviewed amount policy. The authorization bytes contain only a reference report verified by the governed source. Do not grant arbitrary delegatecall or generic envelope permissions. Full Roles simulation must succeed before signing. The current production policy-history allowlist has not been migrated by this preprod change; it intentionally rejects unreviewed permission transitions.

Tests exercise the actual HedgerPool proxy against the reference source, including caller preservation, rejected callers, economic failure rollback, expired reports, and the preexisting margin-accounting suite. Safe client unit tests are not evidence that a live Safe permission upgrade has executed.

Verification

• HedgerPool runtime: 24,534 bytes (EIP-170 limit: 24,576). There is little remaining headroom; future additions should use linked libraries.
• Storage layout compared with the previous preprod artifact: identical after ignoring compiler AST identifiers.
• Scoped upgrade rehearsed on an isolated fork of preprod (port 18550), retaining margin, exposure, oracle, pricing module, owner, time provider and pause state.
• A real typed withdrawal of one USDC base unit succeeded on that isolated fork: total margin decreased by one and the owner's USDC balance increased by one. No test withdrawal was sent to the served preprod instance.
• Three source-closure baselines (QuantillonRebalancerModule, YieldShift, YieldShiftOptimizationLibrary) were refreshed only after verifying their deployed bytecode was identical to the previous preprod artifacts. Interface additions changed dependency hashes without changing their runtime. The reference settlement library is now explicitly covered by the version gate.

Stateful preprod simulation (13 October, subsequent delivery)

The dedicated preprod branch now runs the normal hedging engine against a durable local venue. Orders, fills, fees, margin nonces and allocation to signed or emergency settlements survive worker restarts. The fork uses a sealed historical-origin cache; initialization may read the approved Base proxy, but ordinary sealed execution cannot. All transactions are on chain 31338. External orders and bridges remain disabled.

The served local Safe has a dedicated Roles module. Browser tests exercised a USDC collateral addition and the typed reference withdrawal, with exact Safe balance checks. This supersedes the earlier served-instance testing limitation above; it is not a production permission migration.

SignedProtocolSettlement.t.sol additionally covers pause/resume without nonce consumption, concurrent quotes against admitted capacity, emergency budget rollback, and pro-rata liquidation against the real router. Browser tests exercise emergency redemption with the quote signer stopped, liquidation redemption, stake/unstake and positive fixture-yield conversion followed by a simulated hedge and reconciliation. No contract bytecode was changed for these additional simulation tests, so the previously deployed versions remain Vault 1.6.0, UserPool 1.3.0 and HedgerPool 1.6.0.

Operational scenarios and reset instructions are in the Dapp repository at docs/migrations/preprod-isolated-simulation.md. Synthetic funding/APY data does not model Hyperliquid funding cashflows or exchange liquidations. Real-fill integration, initial parameter review and governed production activation remain separate release gates; no timed calibration window is required.

Shared candidate alignment — 14 October 2026

The preprod and production signed-quotes branches now share the same contract source, documented interfaces, deployment helper, version assertions and test CI. The synchronization changes no core implementation, storage layout or contract version. The eight signed/reference/version suites passed all 198 tests locally. The deployment entrypoint remains encrypted; the helper is testable in a locked checkout. This source synchronization does not upgrade either running instance.

Quantillon Protocol Security Guide

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

Overview

The Quantillon Protocol implements comprehensive security measures to protect user funds and ensure protocol integrity. This document outlines security best practices, the vulnerability disclosure process, and risk management guidelines.

Security Architecture

Multi-Layer Security Model

graph TB
    subgraph "Application Layer"
        AC[Access Control]
        RB[Role-Based Permissions]
        EM[Emergency Mechanisms]
    end
    
    subgraph "Smart Contract Layer"
        RP[Reentrancy Protection]
        OV[Overflow Protection]
        PA[Pause Mechanisms]
    end
    
    subgraph "Oracle Layer"
        CB[Circuit Breakers]
        PV[Price Validation]
        SF[Staleness Checks]
    end
    
    subgraph "Infrastructure Layer"
        UP[Upgradeable Proxies]
        TL[Timelock Controls]
        AU[Audit Trails]
    end
    
    subgraph "External Layer"
        AE[Internal AI-assisted Security Reviews]
        BB[Responsible Disclosure]
        MC[Monitoring & Alerting]
    end

Security Features

1. Access Control

Role-Based Access Control (RBAC):

• Hierarchical permission system
• Principle of least privilege
• Time-locked upgrades: the eight SecureUpgradeable core proxies (QuantillonVault, QEUROToken, QTIToken, UserPool, HedgerPool, YieldShift, stQEUROFactory, stQEUROToken) can only be upgraded through the 12 h OpenZeppelin TimelockController
• Multi-signature control: every privileged role is held by the 2-of-3 governance Safe. Parameter changes, and upgrades of the plain-UUPS FeeCollector / oracle / SlippageStorage proxies, execute as direct Safe transactions with no delay (see the governance-flow column of the 2026-08-26 bundle runbook)

Key Roles per contract:

// QEUROToken
MINTER_ROLE       = keccak256("MINTER_ROLE");      // Vault: mint QEURO
BURNER_ROLE       = keccak256("BURNER_ROLE");      // Vault: burn QEURO
PAUSER_ROLE       = keccak256("PAUSER_ROLE");      // Emergency: pause token, minting killswitch
COMPLIANCE_ROLE   = keccak256("COMPLIANCE_ROLE");  // Blacklist/whitelist management

// QuantillonVault / QTIToken / UserPool / HedgerPool / YieldShift / stQEUROFactory / stQEUROToken
GOVERNANCE_ROLE         = keccak256("GOVERNANCE_ROLE");         // Parameter updates, wiring
EMERGENCY_ROLE          = keccak256("EMERGENCY_ROLE");          // Emergency pause/withdraw
VAULT_OPERATOR_ROLE     = keccak256("VAULT_OPERATOR_ROLE");     // Vault: external-vault USDC deployment
YIELD_DISTRIBUTOR_ROLE  = keccak256("YIELD_DISTRIBUTOR_ROLE");  // Vault: harvestAndDistributeVaultYield / creditVaultYield
VAULT_FACTORY_ROLE      = keccak256("VAULT_FACTORY_ROLE");      // stQEUROFactory: vault self-registration
// HedgerPool has no hedger role: it uses a single-hedger allowlist (setSingleHedger)

// FeeCollector
GOVERNANCE_ROLE   = keccak256("GOVERNANCE_ROLE");  // Ratios, fund addresses, fee sources, upgrades (plain UUPS)
TREASURY_ROLE     = keccak256("TREASURY_ROLE");    // distributeFees
FEE_SOURCE_ROLE   = keccak256("FEE_SOURCE_ROLE");  // Contracts allowed to push fees

// OracleRouter / ChainlinkOracle / HyperliquidEurUsdOracle / StorkOracle / LighterEurUsdOracle (inert)
ORACLE_MANAGER_ROLE = keccak256("ORACLE_MANAGER_ROLE"); // Feed/source updates, bounds, staleness, oracle switching
EMERGENCY_ROLE      = keccak256("EMERGENCY_ROLE");      // Circuit breakers, pause
UPGRADER_ROLE       = keccak256("UPGRADER_ROLE");       // Plain-UUPS upgrades (Safe direct, no timelock)

// SlippageStorage
MANAGER_ROLE        = keccak256("MANAGER_ROLE");        // Store configuration (sources, thresholds, intervals)
WRITER_ROLE         = keccak256("WRITER_ROLE");         // Publishing the venue mid on-chain

2. Reentrancy Protection

Implementation:

• nonReentrant modifier on all state-changing functions
• Checks-effects-interactions pattern
• External call isolation
• State variable protection

Example:

// OpenZeppelin ReentrancyGuardUpgradeable: a re-entrant call reverts with ReentrancyGuardReentrantCall()
function redeemQEURO(uint256 qeuroAmount, uint256 minUsdcOut) external nonReentrant whenNotPaused {
    // ... function logic
}

3. Oracle Security

Price Feed Validation:

• Multiple price feed sources
• Staleness checks (Hyperliquid: 15 min; Chainlink EUR/USD: 2 h; USDC/USD: 25 h)
• Price bound validation
• Circuit breaker mechanisms

The active deployment enforces a strict independent Chainlink EUR/USD reference check (enabled on 23 September 2026). Invalid, unavailable, stale or excessively divergent reference data blocks minting and normal redemption, including on weekends. The release must verify both successful operation with valid prices and rejection with an invalid reference. Configuration targets and live-state checks are documented in Oracle Architecture.

Implementation:

// QuantillonVault: an invalid oracle read is a hard stop for mint / redeem
(uint256 price, bool isValid) = oracle.getEurUsdPrice();
if (!isValid) revert CommonErrorLibrary.InvalidOraclePrice();

// Oracles: staleness, bounds and deviation checks return isValid = false instead of
// reverting; governance setters validate inputs with CommonErrorLibrary.InvalidPrice()

4. Emergency Mechanisms

Pause System:

• Global pause functionality
• Role-based pause controls
• Contract-specific emergency controls; the vault has no generic emergency withdrawal from an external strategy
• Circuit breaker activation

Implementation:

// OpenZeppelin PausableUpgradeable: `whenNotPaused` reverts with EnforcedPause()
function pause() external onlyRole(EMERGENCY_ROLE) {   // PAUSER_ROLE on QEUROToken
    _pause();                                          // emits Paused(msg.sender)
}

Responsible Disclosure

Reporting a vulnerability

Report suspected vulnerabilities privately to team@quantillon.money before any public disclosure. Include the affected contract(s) and addresses, a reproduction (preferably a Foundry test against a local fork) and your assessment of impact. The team acknowledges reports, works with the reporter on validation and remediation, and coordinates a reasonable disclosure date.

In scope: Quantillon-written contracts under src/ as deployed on Base mainnet (see the API Reference), including the oracle stack and external-vault integration logic. A defect in third-party code is outside this programme, but an exploitable impact caused by Quantillon's configuration or integration remains in scope.

Do not execute exploit or disruptive transactions on Base mainnet without prior written authorization. Do not access or move data or funds that are not yours, and do not perform denial of service, abusive automated traffic, oracle or market manipulation, governance interference, phishing, or social engineering.

The canonical, current terms and programme status are maintained at security.quantillon.money/disclosure. The disclosure programme is active and unpaid.

Audits

No professional security audit has been performed. Review to date is internal and AI-assisted; findings and corrections are ongoing work, not a completed audit milestone. Internal review does not establish that deployed contracts are free of defects. No external audit report is promised.

Risk Management

Risk Categories

1. Smart Contract Risks

Oracle Manipulation:

• Risk: Price feed manipulation
• Mitigation: Multiple price sources, circuit breakers
• Monitoring: Price deviation alerts

Reentrancy Attacks:

• Risk: State manipulation during external calls
• Mitigation: Reentrancy guards, CEI pattern
• Monitoring: Function call analysis

Access Control Bypass:

• Risk: Unauthorized function execution
• Mitigation: Role-based access control, multi-sig
• Monitoring: Permission change alerts

2. Economic Risks

Liquidity Risk:

• Risk: Insufficient liquidity for operations
• Mitigation: Liquidity requirements, emergency procedures
• Monitoring: Liquidity ratio tracking

Interest Rate Risk:

• Risk: Adverse interest rate movements
• Mitigation: Hedging mechanisms, rate limits
• Monitoring: Rate change alerts

Market Risk:

• Risk: Extreme market volatility
• Mitigation: Circuit breakers, position limits
• Monitoring: Volatility tracking

3. Operational Risks

Key Management:

• Risk: Private key compromise
• Mitigation: Hardware security modules, multi-sig
• Monitoring: Access pattern analysis

Upgrade Risk:

• Risk: Malicious or faulty upgrades
• Mitigation: Timelock controls, governance
• Monitoring: Upgrade proposal tracking
• Version traceability: every core contract exposes IVersioned.version() and any change is traced through a semver bump (CI-enforced via make check-version-bump); deployments/{chainId}/versions.json records the live implementation + commit per contract, so an auditor can confirm exactly which source version is deployed (cast call <proxy> "version()(string)").
• Controller authority: after bootstrap, setTimelock requires the current controller. The 23 September 2026 activation transferred core DEFAULT_ADMIN_ROLE to that controller and removed the Safe's direct default-admin role. Operational governance, pause and emergency roles remain with their existing holders. The handover is complete; read hasRole to confirm current authority.

Integration Risk:

• Risk: Third-party protocol failures
• Mitigation: Risk limits, emergency procedures
• Monitoring: External protocol health

Security Best Practices

For Developers

1. Code Security

Input Validation:

function deposit(uint256 amount) external {
    if (amount == 0) revert CommonErrorLibrary.InvalidAmount();
    if (amount > MAX_DEPOSIT) revert CommonErrorLibrary.AboveLimit();
    // ... function logic
}

Access Control:

// Role checks use OpenZeppelin AccessControl (`onlyRole`) or the shared library helpers,
// which revert with custom errors (e.g. CommonErrorLibrary.NotGovernance / NotAuthorized)
function setParameter(uint256 value) external onlyRole(GOVERNANCE_ROLE) {
    // ... function logic
}

Reentrancy Protection:

function withdraw(uint256 amount) external nonReentrant {
    // ... function logic
}

2. Testing

Unit Testing:

• Test all function paths
• Test edge cases and boundary conditions
• Test access control mechanisms
• Test error conditions

Integration Testing:

• Test contract interactions
• Test external integrations
• Test upgrade scenarios
• Test emergency procedures

Fuzz Testing:

• Random input generation
• Property-based testing
• Stress testing
• Gas limit testing

3. Code Review

Review Checklist:

• Access control implementation
• Input validation
• Reentrancy protection
• Error handling
• Gas optimization
• Event emission
• Documentation

For Integrators

1. Integration Security

Contract Verification:

// Verify contract addresses
const VAULT_ADDRESS = "0x..."; // Verified on Etherscan
const QEURO_ADDRESS = "0x..."; // Verified on Etherscan

// Verify contract state
const isPaused = await vault.paused();
if (isPaused) {
    throw new Error("Contract is paused");
}

Transaction Security:

// Use slippage protection
const slippage = 0.05; // 5%
const minOutput = expectedOutput * (1 - slippage);

// Validate transaction parameters
const gasEstimate = await contract.estimateGas.function(params);
const gasLimit = gasEstimate.mul(120).div(100); // 20% buffer

Error Handling:

try {
    await contract.function();
} catch (error) {
    const msg = error.reason || error.message;
    if (msg.includes('InsufficientBalance') || msg.includes('ERC20InsufficientBalance')) {
        // Handle insufficient balance
    } else if (msg.includes('InvalidOraclePrice')) {
        // Handle stale / invalid oracle price
    } else if (msg.includes('EnforcedPause')) {
        // Handle paused contract
    } else {
        // Handle other errors
    }
}

2. Monitoring

Event Monitoring:

// Monitor important events (QEUROminted: lowercase m, 3 arguments)
vault.on('QEUROminted', (user, usdcAmount, qeuroAmount) => {
    console.log(`User ${user} minted ${qeuroAmount} QEURO`);
});

// Pause is the OpenZeppelin Pausable event
vault.on('Paused', (account) => {
    console.log(`Contract paused by ${account}`);
});

Health Checks:

async function healthCheck() {
    const [isPaused, [price, isValid], collateralizationRatio, mintFloor, criticalRatio] = await Promise.all([
        vault.paused(),
        oracleRouter.callStatic.getEurUsdPrice(),   // non-view: simulate instead of sending a tx
        vault.getProtocolCollateralizationRatio(),   // 18-decimal percent, 1e20 == 100% (0 while nothing is minted)
        vault.minCollateralizationRatioForMinting(), // 1.025e20 live (102.5%)
        vault.criticalCollateralizationRatio()       // 1.01e20 (101%)
    ]);

    if (isPaused) {
        console.warn("Vault is paused");
    }

    if (!isValid) {
        console.warn("Oracle price is stale or invalid");
    }

    if (collateralizationRatio.lt(mintFloor)) {
        console.warn("Protocol CR below the minting floor: mints are refused");
    }

    if (collateralizationRatio.lte(criticalRatio)) {
        console.error("Protocol CR at or below the critical ratio: liquidation-mode redemptions");
    }
}

Incident Response

Response Procedures

1. Detection

Automated Monitoring:

• Price deviation alerts
• Liquidity threshold alerts
• Access control violation alerts
• Unusual transaction pattern alerts

Manual Monitoring:

• Community reports
• Security researcher reports
• Internal security reviews
• External audit findings

2. Assessment

Severity Classification:

• Critical: Immediate threat to user funds
• High: Significant risk to protocol integrity
• Medium: Moderate risk with workarounds
• Low: Minor issues with minimal impact

Impact Analysis:

• Affected contracts and functions
• Potential financial impact
• User impact assessment
• Recovery time estimation

3. Response

Immediate Actions:

• Activate emergency pause if necessary
• Notify security team and stakeholders
• Assess and contain the issue
• Implement temporary mitigations

Recovery Actions:

• Develop and test fixes
• Deploy fixes through governance
• Monitor system recovery
• Conduct post-incident review

4. Communication

Stakeholder Notification:

• Internal team notification
• Community announcement
• Partner notification
• Regulatory notification (if required)

Transparency:

• Incident timeline
• Root cause analysis
• Remediation steps
• Prevention measures

Security Monitoring

Real-Time Monitoring

Key Metrics:

• Contract pause status
• Oracle price staleness
• Liquidity ratios
• Access control changes
• Unusual transaction patterns

Alerting:

• Price deviation > 5%
• Protocol collateralization ratio below the governance-set minting floor (minCollateralizationRatioForMinting: 105% at launch, 102.5% under the September 2026 margin policy; liquidation mode at <= 101%)
• Emergency role activation
• Large transaction volumes
• Failed transaction spikes

Security Dashboards

Operational Dashboard:

• System health indicators
• Performance metrics
• Error rates
• Gas usage patterns

Security Dashboard:

• Access control events
• Emergency activations
• Oracle health status
• Risk metrics

Security Contacts

Primary Contacts

Security contact: team@quantillon.money — vulnerability reports and responsible disclosure (see Responsible Disclosure)

Security Resources

Documentation

• Smart Contract Security Best Practices
• OpenZeppelin Security Guidelines
• Ethereum Security Considerations

Tools

• Slither Static Analysis
• Mythril Symbolic Execution
• Echidna Fuzzing

Security Analysis Results

Use generated artifacts from each run instead of hardcoded snapshots:

• scripts/results/slither/slither-report.txt
• scripts/results/slither/slither-report.json
• scripts/results/mythril-reports/
• scripts/results/natspec-validation-report.txt
• scripts/results/contract-sizes/contract-sizes-summary.txt

Running Mythril Analysis:

# Run Mythril analysis
make mythril

# Or run directly
./scripts/run-mythril.sh

# Run Slither static analysis
make slither

# Validate NatSpec coverage
make validate-natspec

# Run EIP-170 contract size checks
make analyze-contract-sizes

# Run comprehensive security analysis (Slither + Mythril)
make security

This security guide is maintained by Quantillon Labs and updated regularly.

Operational invariants for minting and yield

Public minting continues to use the configured mint floor. Yield conversion is independent and is permitted only when current collateralization is strictly above max(101%, criticalCollateralizationRatio) and projected collateralization is at least 100%. The final QEURO token mint remains authoritative for pause, killswitch, cap, whitelist, blacklist, and rate-limit checks; failed token or hedger checks revert atomically, preserving the harvest for retry.

Accepted operational-scope risks

This remediation release preserves the current publisher and Safe Roles assignments, including the existing shared publisher/reporting identity, operational FeeCollector recipients, and Zodiac Roles module permissions. It does not rotate the publisher key, split those identities, replace recipients, or remove the existing Zodiac permissions. These remain separately governed operational risks; the contract safeguards and monitoring in this release do not change those assignments.

Quantillon Protocol — Deployment Guide

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

For the current deployed behavior, versions and role ownership, use Production Protocol Reference. Dated release sections below describe their respective upgrade bundles, not the latest state after subsequent upgrades.

Current Base release: 17 October 2026

The signed-quote migration is active. The confirmed governance execution upgraded the core implementations and configured the signed deployment. At finalized block 52,727,379, the live versions are Vault 1.6.0, UserPool 1.3.0, HedgerPool 1.6.0, HyperliquidEurUsdOracle 1.0.7, SignedExecutionPricing 1.1.0 and SignedReferenceSource 1.0.0. The current emergency budget is 0 QEURO.

The production dapp and affected services were cut over during maintenance and reopened at 10:08 UTC. The periodic publisher is retired. See Signed Quotes in Production for active addresses, bindings and integration requirements. September release sections below are historical records; their publisher commands and addresses do not describe the current signed deployment.

Overview

This guide covers deploying and configuring the Quantillon Protocol smart contracts using Foundry. Core contracts are deployed in a single forge script invocation via DeployQuantillon.s.sol, which writes the deployed addresses to deployments/{chainId}/addresses.json.

Versioning & Provenance

Every core contract implements IVersioned.version() — a pure semver getter that, read through the proxy, reflects the deployed implementation. Linked libraries expose version(); inlined libraries carry a VERSION constant.

Golden rule — every change is traced through a version bump. Any change to a deployed contract or library (correction, bug fix, update, or upgrade) MUST bump its version() per semver:

• PATCH (1.0.0 → 1.0.1): bug fix or internal-logic change.
• MINOR (1.0.0 → 1.1.0): new function or externally-observable behavior (ABI-additive).
• MAJOR: reserved — storage-layout / ABI breaks are disallowed by the upgrade-safety gates.

This is enforced in CI by make check-version-bump: it hashes each versioned unit's import closure (deterministic, build-independent) and fails if a source dependency changed without a version() bump — comment and NatSpec edits count as changes. After an intentional bump, re-baseline with scripts/check-version-bump.sh --update (commits the new hash+version to version-baseline/).

Deployed-version manifest. deployments/{chainId}/versions.json records verified deployments. Upgrade scripts write receipt-backed entries after a completed proxy upgrade; a later reconciliation can record finalized implementations, versions and runtime hashes without claiming an unverified deployment timestamp. Live implementation slots, version() values and bindings are authoritative. Candidate-only actions (deploy-only, propose, and approve) leave it unchanged. Pass GIT_COMMIT=$(git rev-parse HEAD) to the upgrade scripts so the commit is recorded.

Answering "what is deployed / what needs upgrading?"

# On-chain: read the live implementation's version directly
cast call <proxy> "version()(string)" --rpc-url $RPC_URL

# Report deployed-vs-source for every contract (flags which need an upgrade)
make check-deployed-versions

# One-time seed of versions.json for contracts deployed before versioning existed
RPC_URL=$RPC_URL GIT_COMMIT=<sha> scripts/deployment/backfill-versions.sh 8453

Basescan verifiability — check BEFORE every implementation deploy. Under via_ir, a contract's optimized bytecode can depend on the full compilation unit, while forge verify-contract submits a standard-json pruned to the contract's dependency closure — if the two compiles diverge, the deployed implementation can never be verified (QuantillonVault v1.1.1, 2026-07-04; ~67 bytes of drift). Whether a given contract/version diverges is per-compile luck, so gate every impl:

# ok  -> deploy normally (UpgradeBase deploy-only); standard verification will match
# FAIL-> deploy the pruned-unit bytecode instead, so verification matches by construction
make check-verifiable-bytecode CONTRACT=QuantillonVault

# On FAIL: same sources & settings, equally valid compile — but reproducible by the verifier.
# Requires CAST_ACCOUNT, RPC_URL, RELEASE_MANIFEST and private VERIFIABLE_OUTDIR.
# Uses a Foundry keystore; raw keys never enter cast arguments. Continue the
# Safe/timelock flow with the verified implementation address.
scripts/deployment/build-verifiable-impl.sh QuantillonVault \
  --lib src/libraries/StakingYieldLibrary.sol:StakingYieldLibrary=<addr> \
  --lib src/libraries/TreasuryRecoveryLibrary.sol:TreasuryRecoveryLibrary=<addr> \
  --deploy

Base deployment reconciliation — September 20, 2026

HedgerPool 1.3.0 is active at proxy 0xff5D7cE5c7671B2EA805Ee752B4f8eC9Ecf2975A, using implementation 0x8d83F7463CbFfd188Df7bC4302900151e273435a and HedgerPoolAccountingLibrary 1.1.0 at 0x4FDA47d379f00f849808500DD52b5106825ce5f1. Both implementations were deployed at Base block 51,522,127. The pool upgrade and one-time legacy correction executed together at block 51,548,748, September 20 at 06:47:23 UTC, in the completed Safe transaction.

The correction assigned 0.388448 USDC of existing unallocated backing to the current Safe hedger position's margin without transferring tokens or minting QEURO. The correction marker is already set; this is a record of completed execution, not a pending operation. The reconciled source and regression tests are recorded in commit 37d2381fbe0ed73bc28160fa46d335f6a73de265 (committed after deployment).

The same reconciliation corrected the stale QuantillonVault manifest entry to 1.2.1, implementation 0xdA2eF3B9CCD2b819806b29A5Ac65abCf689E2227, activated at block 51,202,101 on September 12 at 06:12:29 UTC in its existing upgrade transaction. The source is commit 03d8120181ea919dddc3ea7cd203b4793e0999cf; no new vault upgrade was performed.

For all three units, a fresh Solidity 0.8.24 verification-unit build (via_ir, optimizer runs 0) reproduced the complete deployed runtime after applying the live library addresses and constructor immutables, checked at block 51,571,753. The manifest records the runtime code hashes and separates implementation deployment from proxy activation. All 31 hedger accounting/correction regression tests passed, including the pinned Base fork; ABI, storage layout, contract size, and version checks passed.

HedgerPool remaining-cost accounting activation

HedgerPool v1.1.0 values filledVolume as the original USDC cost of the remaining QEURO backing. Deploy its implementation with HedgerPoolLogicLibrary v1.0.1 and HedgerPoolRedeemMathLibrary v1.0.1. Fresh proxies activate this model in initialize. Build and verify with FOUNDRY_PROFILE=production (optimizer_runs = 0), using an isolated output/cache directory when test builds are running concurrently.

An existing proxy requires settlement before upgrading: position 1 must be inactive, totalMargin, totalExposure, and totalFilledExposure must be zero, and the vault's totalMinted() must be at most QEURO_DUST_THRESHOLD. Reconcile the position and vault balances before closure; this upgrade does not convert an active position's balances.

After settlement, pause the pool through EMERGENCY_ROLE, execute the implementation upgrade through the configured timelock, and call initializeCostBasisAccounting() through GOVERNANCE_ROLE while the pool remains paused. Verify costBasisAccountingInitialized() == true before unpausing. Installing the implementation alone leaves mint/redeem accounting, margin changes, normal exits, and effective-collateral queries blocked until activation. The generic upgrade script does not perform this governance activation call.

Base release (23 September 2026, historical)

The live versions and runtime hashes are recorded in deployments/8453/versions.json. Proxy addresses are unchanged. The coordinated activation completed on Base at block 51,685,734 on 23 September 2026, 10:53:35 UTC. The controller operation is complete. Versions at that activation were QEUROToken 1.0.9, QTIToken 1.0.5, UserPool 1.0.6, HedgerPool 1.4.1, stQEUROFactory 1.0.4, YieldShift 1.1.1, ChainlinkOracle 1.0.5, OracleRouter 1.1.2, SlippageStorage 1.0.3, LighterEurUsdOracle 1.0.2 (inert), and FeeCollector 1.0.3. QuantillonVault 1.3.4, per-vault stQEUROToken 1.2.4, HyperliquidEurUsdOracle 1.0.5, and ExecutionPricing 1.3.2 retain their existing implementations. The factory now uses the 1.2.4 staking-token template for future series. The vault links ExecutionPricingLibrary 1.1.1, StakingYieldLibrary 1.3.2, TreasuryRecoveryLibrary 1.0.1, and SecureUpgradeLibrary 1.0.1.

VaultId 2 now uses MetaMorphoStakingVaultAdapter 2.1.1 at 0x4c9B8b09214d37D5310b8E6768cF28E0dDcEDC30; principal and uncredited yield were transferred atomically, and temporary migration permissions were revoked. The eight existing secure proxies have controller default-admin authority with Safe operational roles preserved. Strict reference limits are 200/300 bps with 8,100 seconds maximum age; cumulative price drift is 100 bps / 3,600 seconds. The public mint floor remains 102.5%. Yield conversion has its own CR gate and still requires token eligibility, execution liquidity and hedger capacity; an unsuccessful harvest rolls back for retry.

QuantillonVault.executionPricing() is authoritative for the active module. The local, gitignored deployments/8453/addresses.json and dapp src/config/addresses.json must agree with it. Preserve the zero-address stQEUROToken placeholder in those registries: resolve each live token through the factory; the manifest records the vaultId-2 proxy explicitly.

Before switching publisher configuration, verify writer(), priceStore(), and depthStore() on the selected batcher. The active ReportPublicationBatcher needs all three grants: SlippageStorage WRITER_ROLE, ExecutionPricing WRITER_ROLE, and ExecutionPricing REPORTER_ROLE. A grant to PublicationBatcher or the publisher EOA does not confer permission on ReportPublicationBatcher. Set EXECUTION_PRICING_ADDRESS, PUBLICATION_BATCHER_ADDRESS, and REPORT_PUBLICATION_BATCHER_ADDRESS to the same deployment generation. Append both new batcher-to-module mappings to the indexer's PUBLICATION_BATCHERS; retain historical mappings for decoding older events.

Verify accepted price, book and capacity events on chain, fresh observations, usable mint/redeem previews, token state and hedger reconciliation before opening the vault. Execution depth and capacity expire after 60 seconds on this module; the batch heartbeat is min(PUBLISHER_INTERVAL_S, maxAge / 2) (30 seconds with the 60-second publisher interval). Partial price/depth reports may restore oracle health before capacity can be certified. Health endpoints alone do not prove that all reports were accepted. If the watchdog owns a pause, let its configured recovery checks complete before resuming operation.

Coordinated core implementation release

Treat a coordinated release as one reviewed package with two mandatory governance steps: schedule the complete timelocked batch, then activate all components in one atomic Safe transaction after the controller's live minimum delay. Direct-Safe oracle and fee upgrades can share that activation transaction with the timelock execution, configuration calls and adapter migration. Scheduling must not change runtime addresses or pause production. Execution time is measured from the confirmed scheduling block, not proposal submission.

The active release includes the strict Chainlink EUR/USD cross-check: setReferenceCheck(200, 300, 8100), after upgrading the independent reference probe. Verify all three values after execution and test that stale, unavailable and divergent references reject minting and normal redemption. This applies on weekends too; there is no stale-reference bypass. See Oracle Architecture.

Inventory factory implementation templates and every registered staking series separately from the factory proxy. Update the template even when existing series already use the desired token implementation. Include funded non-upgradeable adapters using the atomic migration procedure. The retired Stork proxy, standalone production time provider and OpenZeppelin controller are not automatically upgrade targets for similarly named source contracts; verify their actual deployment type and active consumers first.

Rehearse the exact Safe hashes, all implementation slots and runtime hashes, library links, temporary role revocation, retained yield and unchanged supply, collateral and hedger accounting. Test the dapp's mint, redeem, stake and withdrawal paths plus keeper harvesting against the upgraded state. An isolated time-warped governance rehearsal proves delay enforcement; it cannot certify live report freshness. Repeat fresh-price integration checks separately and recheck production readiness before executing the queued package.

Deploy the coordinated core implementations from the release manifest. Read target versions from version-baseline/ and live versions.json; do not reuse the historical version list in older runbooks. Link the vault using the library addresses recorded for its selected implementation in versions.json; preserve the pool library links recorded for that release. Preserve each implementation's existing TimeProvider constructor argument. Check the factory registry for all token proxies; the zero stQEUROToken entry in addresses.json is not an upgrade target.

The base timing helper uses block.timestamp; contracts with a TimeProvider read that provider directly. Before upgrading, check the provider's offset and ensure no emergency-disable proposal spans a change of clock.

For the Base controller, schedule all implementation upgrades with TimelockController.scheduleBatch from the governance Safe. Read getMinDelay() and wait for readiness. The Safe's execution batch must pause vault and pool, execute the timelocked implementation upgrades, perform explicitly listed governance activation, and unpause only after post-upgrade checks pass. For every existing stQEURO proxy, keep the vault paused and call syncVesting() immediately after the implementation upgrade. Verify the YieldVestingSynced event, totalAssets() <= asset balance, and the expected accounted/unvested balances from the implementation state before allowing deposits or unpausing. A plain upgradeToAndCall(newImpl, "") does not run the token initializer, so omitting this sync exposes historical donations through the first read path.

Installing QuantillonVault v1.2.0 leaves executionPricing() at zero on an existing proxy. This installs pricing support while retaining reference-price settlement. Pricing can be activated in the same release by deploying a vault-bound module with explicit writer/reporter addresses, reserve recipient and risk limits. Configure the publisher and hedge reporter against that module before execution. Align report freshness, hedge tolerance and execution-impact limits with the hedge engine. Both depth and capacity reports must remain fresh through the upgrade window.

For coordinated pricing activation, add the Safe's call to QuantillonVault.configureExecutionPricing(module) after P&L activation and before unpausing. Check that the module has fresh depth, reconciled hedge exposure, positive executable capacity and usable previews before enabling settlement. An implementation upgrade alone does not activate the pricing module.

Rehearse the exact staged bytecode and controller calls on a pinned Base fork with scripts/deployment/DryRunCombinedRelease.s.sol. Its deployment input contains library link offsets, constructor arguments and the seven proxy addresses; the script never broadcasts. Independently validate storage, ABI, versions, runtime size and reproducible verification inputs before deploying implementations.

Execution-pricing launch configuration

The combined Base release activated on 11 September 2026 at 06:54:31 UTC in the Safe execution transaction. That launch used 0x57fBdf17a55D8F1d89E244D8D88937a867FfD063; the current module is listed in Current Base release. The following launch configuration is recorded in deployments/8453/execution-pricing-candidate.json; the active module's getters remain the source of truth for current values. Verified deployed versions are recorded in deployments/8453/versions.json.

The reporter permits at most one wei of difference between the engine's indexed target and confirmed QEURO supply to accommodate the residue after full redemption. This bookkeeping tolerance is separate from the EUR 1 actual hedge-exposure check.

At selection, the unified Hyperliquid account held approximately 108.43 USDC. EUR 1,000 at the observed 1.16355 reference price requires approximately 23.27 USDC of margin at the engine's existing 50x leverage, before its 1 USDC cushion. This is a launch ceiling, not an assertion that this capacity is always available. The reporter reduces admission as available funding decreases; no additional leverage is enabled by this configuration.

The observed xyz:EUR market had growth mode enabled and deployer fee scale 1. With the account's 0.045% base taker rate and no referral discount, the documented fee formula gives approximately 0.009% (0.9 bps), before any aligned-collateral discount. Fees and market conditions can change; the buffer does not guarantee a hedge fill. See Hyperliquid's fee formula.

ExecutionPricing v1.1.0 lets governance update age, impact, buffer and the exposure ceiling through updateRiskLimits(age, impact, buffer, outstandingLimit). The vault must be paused and outstanding admission must be zero. The update invalidates both depth and capacity; new reports must carry source timestamps strictly after the update. Keep settlement paused until those reports restore usable quotes.

The admin Parameters tab provides editable inputs, validates contract bounds and generates the governance Safe transaction. It displays release settings separately from live on-chain values and quote status. The reserve recipient remains fixed; changing that address requires replacing the module. Publisher confirmations and hedge tolerance are service configuration, separate from the four contract limits.

LighterEurUsdOracle (historical — venue not adopted)

LighterEurUsdOracle was deployed on 2026-07-17 as the candidate market oracle for a second hedge venue and most recently upgraded to 1.0.2 on 2026-09-23; on 2026-09-01 the Lighter venue was ruled out for good, so the proxy stays deployed and inert (no router slot, no consumer) as a historical record and no activation is planned. Like the other oracle proxies it is plain UUPS controlled by UPGRADER_ROLE (Safe direct, no timelock), and its upgrade script (scripts/deployment/UpgradeLighterOracle.s.sol, UPGRADE_ACTION=deploy-only then record) follows the pattern described above — kept only so the inert deployment can be maintained if ever required.

Prerequisites

Required Tools

• Foundry (forge, cast, anvil): curl -L https://foundry.paradigm.xyz | bash && foundryup
• jq: for post-deployment address parsing (sudo apt install jq or brew install jq)
• Node.js 18+ (for NatSpec validation and size analysis scripts)

Environment File

Copy the appropriate template and fill in your values:

# Localhost development
cp .env.localhost .env

# Base Sepolia testnet
cp .env.base-sepolia .env

# Base mainnet production
cp .env.base .env

Required variables:

Optional variables (default to deployer address if not set):

Deployment Architecture

DeployQuantillon.s.sol deploys all contracts in this dependency order within a single broadcast session:

TimeProvider
    └── ChainlinkOracle (or MockChainlinkOracle) + ERC1967Proxy
    └── StorkOracle (or MockStorkOracle) + ERC1967Proxy
    └── OracleRouter + ERC1967Proxy
            │
            ├── FeeCollector + ERC1967Proxy
            │       └── QEUROToken + ERC1967Proxy
            │               └── QuantillonVault + ERC1967Proxy
            │
            ├── QTIToken + ERC1967Proxy
            │
            ├── UserPool + ERC1967Proxy
            ├── HedgerPool + ERC1967Proxy
            ├── YieldShift + ERC1967Proxy
            ├── stQEUROToken (implementation)
            └── stQEUROFactory + ERC1967Proxy
                    └── _wireContracts() — configures dependencies/roles and enforces required post-deploy wiring (no vault registration)

After deployment, addresses are written to deployments/{chainId}/addresses.json.

Required post-deploy wiring now enforced in-script (deployment reverts if any check fails):

• quantillonVault.initializePriceCache()
• yieldShift.configureDependencies(...)
• yieldShift.bootstrapDefaults()
• hedgerPool.configureDependencies(...) (includes feeCollector)
• feeCollector.authorizeFeeSource(quantillonVault)
• feeCollector.authorizeFeeSource(hedgerPool)

Vault registration is intentionally deferred: DeployQuantillon.s.sol does not register any stQEURO vault token or adapter on initialization. Use scripts/deployment/setup-external-vaults.sh for post-core onboarding.

Network Configuration

Production oracle stack. DeployQuantillon.s.sol deploys ChainlinkOracle, StorkOracle and OracleRouter. The market oracle originally used SlippageStorage + HyperliquidEurUsdOracle (router slot 1, active since 2026-06-25); since 17 October 2026 its source is SignedReferenceSource. The original components were deployed by dedicated scripts under scripts/deployment/ (DeployHyperliquidOracle.s.sol for the oracle) and wired into the router by the Safe (updateOracleAddresses, then switchOracle(1)). StorkOracle is parked on mainnet. See Oracle Architecture.

Localhost Deployment

Start Anvil

# Plain local node (all mocks required)
anvil --host 127.0.0.1 --port 8545 --accounts 10 --balance 10000

# Or fork Base mainnet (allows using real oracle feeds without mocks)
anvil --host 127.0.0.1 --port 8545 --fork-url https://app.quantillon.money/api/rpc/base --chain-id 31337

Deploy

# All mocks (MockUSDC + MockChainlinkOracle + MockStorkOracle)
./scripts/deployment/deploy.sh localhost --with-mocks

# Mock oracle only (real USDC from fork)
./scripts/deployment/deploy.sh localhost --with-mock-oracle

# No mocks (assumes Base mainnet fork with real contracts)
./scripts/deployment/deploy.sh localhost

Output

deployments/31337/addresses.json

Testnet Deployment (Base Sepolia)

# With mock contracts (recommended for testing)
./scripts/deployment/deploy.sh base-sepolia --with-mocks --verify

# With real Chainlink feeds + real USDC
./scripts/deployment/deploy.sh base-sepolia --verify

The script automatically:

• Sets gas price to 2 gwei
• Uses --slow to send transactions one-at-a-time (avoids nonce desync with public RPCs)
• Polls for stable nonce before broadcasting

Output

deployments/84532/addresses.json

Mainnet Deployment (Base)

Pre-Deployment Checklist

Before deploying to Base mainnet:

• Set TREASURY, DEV_FUND, COMMUNITY_FUND to governance-controlled multisig addresses in .env.base
• Set SINGLE_HEDGER to the authorized hedger address
• Verify PRIVATE_KEY belongs to a dedicated deployment wallet with sufficient ETH
• Set ETHERSCAN_API_KEY for contract verification
• Run a dry-run first: ./scripts/deployment/deploy.sh base --dry-run
• Test on Base Sepolia with the same configuration

Deploy

# Production deployment with verification and the size-minimising production profile
./scripts/deployment/deploy.sh base --verify --production

The --production flag sets FOUNDRY_PROFILE=production, which compiles with optimizer_runs = 0 (defined in foundry.toml): runtime bytecode is minimised to stay under the EIP-170 limit (via_ir is on in every profile; the test/coverage profiles use 200 runs).

Output

deployments/8453/addresses.json

Dry Run

Test the deployment without broadcasting any transactions:

./scripts/deployment/deploy.sh localhost --dry-run
./scripts/deployment/deploy.sh base-sepolia --dry-run
./scripts/deployment/deploy.sh base --dry-run

Post-Deployment

deploy.sh automatically runs these after a successful deployment:

1. Copy ABIs to Frontend

./scripts/deployment/copy-abis.sh localhost

Copies all contract JSON artifacts from out/ to the path specified in FRONTEND_ABI_DIR.

2. Update Frontend Addresses

./scripts/deployment/update-frontend-addresses.sh localhost

Reads deployments/{chainId}/addresses.json and writes the frontend addresses.json to FRONTEND_ADDRESSES_FILE.

3. Onboard External Vaults (Required for Multi-Vault Staking)

Core deploy does not set adapter routing/defaults. Onboard vaults with:

./scripts/deployment/setup-external-vaults.sh \
  --rpc-url http://localhost:8545 \
  --private-key "$PRIVATE_KEY" \
  --quantillon-vault 0xQuantillonVault \
  --factory 0xStQEUROFactory \
  --yield-shift 0xYieldShift \
  --vault 1:AAVE1:0xMockAaveAdapter \
  --vault 2:MORPHO1:0xMorphoAdapter \
  --default-vault-id 2 \
  --enforce-source-bindings

See the dedicated runbook: docs/External-Vault-Onboarding-Runbook.md.

4. Seed the Version Manifest (one-time, per chain)

deployments/{chainId}/versions.json is the source of truth for what version is deployed. After upgrades it is maintained automatically by the UpgradeBase scripts, but it must be seeded once for contracts that were deployed before version() existed. This step reads each proxy's current implementation from its EIP-1967 slot on-chain.

Read-only — no private key required. It only issues eth_getStorageAt reads via cast; it sends no transactions and spends no gas. It needs only a Base RPC URL.

# chainId defaults to 8453 (Base mainnet). GIT_COMMIT tags the pre-versioning baseline.
RPC_URL="$BASE_RPC_URL" GIT_COMMIT=f1c55ad \
  ./scripts/deployment/backfill-versions.sh 8453

versions.json is committed (a .gitignore exception re-includes deployments/*/versions.json while the rest of deployments/ stays ignored), so deployed-version provenance syncs across workstations via git pull. Seed it once with the backfill above; thereafter the UpgradeBase scripts keep it current on each upgrade — commit the updated manifest so other machines pick it up.

After seeding, verify and inspect drift vs source:

make check-deployed-versions          # lists contracts whose deployed version != source version()
cast call <proxy> "version()(string)" --rpc-url "$BASE_RPC_URL"   # once a version()-bearing impl is live

Before the July 2026 implementation upgrades the manifest showed every contract as 0.0.0-unversioned (deployed) vs 1.0.0 (source) — i.e. "needs upgrade" — because no live implementation carried version() yet. Today every proxy except StorkOracle (parked) and TimeProvider (not a proxy) reports a live version(); each UpgradeBase run overwrites that contract's entry with the real deployed version + commit.

Accessing Deployed Addresses

deployments/{chainId}/addresses.json is a flat map keyed by PascalCase contract name (plus the external dependencies). On Base mainnet the key set is:

QuantillonVault, QEUROToken, QTIToken, UserPool, HedgerPool, FeeCollector, YieldShift,
stQEUROFactory, stQEUROToken (zero address: resolved per vault via stQEUROFactory),
OracleRouter, ChainlinkOracle, HyperliquidEurUsdOracle, LighterEurUsdOracle (inert), StorkOracle,
SlippageStorage, TimeProvider, Timelock, Multisig, USDC, EURUSD, USDCUSD

The file is a local deployment artifact (gitignored — only versions.json is tracked); the API Reference mirrors the mainnet values.

Programmatically (shell)

jq -r '.QEUROToken' deployments/8453/addresses.json
# "0x69aD4e6c49d6275D0e11b5515D98a89f029869AA"

Frontend format

update-frontend-addresses.sh writes the frontend addresses.json (FRONTEND_ADDRESSES_FILE) with the same PascalCase keys, nested per chain id:

{
  "8453": {
    "name": "Base",
    "isTestnet": false,
    "contracts": {
      "QuantillonVault": "0x...",
      "QEUROToken": "0x...",
      "QTIToken": "0x...",
      "UserPool": "0x...",
      "HedgerPool": "0x...",
      "FeeCollector": "0x...",
      "YieldShift": "0x...",
      "stQEUROFactory": "0x...",
      "stQEUROToken": "0x0000000000000000000000000000000000000000",
      "OracleRouter": "0x...",
      "ChainlinkOracle": "0x...",
      "HyperliquidEurUsdOracle": "0x...",
      "StorkOracle": "0x...",
      "TimeProvider": "0x...",
      "USDC": "0x..."
    }
  }
}

Contract Verification

Contracts are verified automatically when --verify is passed. For manual re-verification:

# Example: re-verify QEUROToken proxy on Base Sepolia
forge verify-contract \
  <PROXY_ADDRESS> \
  lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy \
  --chain-id 84532 \
  --etherscan-api-key $ETHERSCAN_API_KEY

Troubleshooting

Anvil not running

anvil --host 127.0.0.1 --port 8545 --accounts 10 --balance 10000

Missing environment file

cp .env.localhost .env
# or
cp .env.base-sepolia .env

Nonce desync on testnet

The deploy script polls for a stable nonce before broadcasting. If it keeps failing, try a different RPC URL (the default https://sepolia.base.org can occasionally lag). You can override by editing the NETWORKS map in deploy.sh.

Verification failed

Ensure ETHERSCAN_API_KEY is set and valid. If automatic verification fails, contracts can be re-verified using forge verify-contract after deployment.

USDC address is zero on localhost

Set USDC=<mock_address> in .env.localhost after deploying MockUSDC, or let deploy.sh handle it automatically with --with-mock-usdc.

Security Considerations

Private Key Management

• Use a dedicated deployment wallet — never your main wallet
• For production, use a hardware wallet or a cloud HSM
• Rotate deployment keys after production deployment

Production Role Configuration

• TREASURY, DEV_FUND, and COMMUNITY_FUND should be multisig wallets (e.g., Safe)
• SINGLE_HEDGER should be an audited, authorized hedger address
• After deployment, transfer core default-admin roles to the configured controller and operational governance/emergency roles to the multisig; verify the handover before enabling deposits

Never Commit Secrets

• .env, .env.base, .env.base-sepolia and .env.localhost are tracked but git-crypt encrypted (.gitattributes): never commit them in plaintext and never disable the git-crypt filter
• Use a secret manager (AWS Secrets Manager, HashiCorp Vault) for production CI/CD

Maintained by Quantillon Labs.

Reviewed release bindings and controller administration

build-upgrade-safe-txs.sh <implementation> <version> requires RPC_URL, RELEASE_MANIFEST and SAFE_TX_OUT_DIR. Both staging directories must be private (mode 0700), outside repositories and web roots. Never publish generated payloads. The manifest is a reviewed local JSON object containing chainId, sourceCommit (full Git SHA), safe, timelock, minimumDelay, contracts, and libraries. Each contract entry contains name, address (candidate), version, runtimeCodeHash, proxy, and currentImplementation. Each library entry contains name, fqn, address, version, and runtimeCodeHash. Derive expected hashes from the reproducible, reviewed build and verified library links; do not blindly bless whatever code an address currently returns.

For QuantillonVault 1.4.0 and later, its contract entry also requires a nonzero hedgerYieldRecipient equal to singleHedger() on the vault's configured HedgerPool. The builder validates that binding and the Safe's governance role. Its execute package contains an ordered, atomic Safe batch: configure the vault recipient to the hedger itself, then execute the scheduled controller upgrade. The schedule and cancel packages do not change the recipient. Revalidate the manifest immediately before execution; regenerate/review it if the hedger changes. The recipient setting does not automatically track subsequent hedger rotations.

The builder checks chain, runtime hashes, versions, UUPS identity, current implementation, controller, Safe permissions and the live delay. It creates a unique salt and matching schedule, execute and cancel payloads. Rehearse the exact payload on a pinned fork before proposing it. build-verifiable-impl.sh requires the same reviewed library bindings for every --lib; an address alone is insufficient. UpgradeBase and the vault upgrade script detect OZ controllers and direct operators to this Safe builder instead of the legacy proposal-registry interface.

The coordinated core activation grants the controller default-admin authority on all seven core proxies and every registered staking token, checks that authority through the scheduled batch, and renounces the Safe's default-admin role in the same atomic transaction. Preserve all operational roles and verify immediate Safe pause/resume plus delayed role grants/revocations in the rehearsal. The dapp reads current authority and produces matched schedule/execute actions when a controller is required. New staking series must complete the same admin handover before users can deposit; retain Safe governance/emergency roles separately.

After the confirmed activation, reconcile each proxy and linked library against the reviewed runtime hashes, read versions from live storage, and run the upgrade scripts' record action with the release commit, or the release manifest tool's record-live mode. The latter requires RELEASE_ACTIVATION_TX, plus executionSafeTxHash and operationId in the reviewed manifest; it checks the successful canonical Safe receipt, completed controller operation, and every live implementation/library binding before atomically updating versions.json. This is a required release-close step, not a candidate-deployment step. Update adapter inventory and all affected address/documentation entries only after their bindings change on chain. Re-run make check-deployed-versions and the dapp contract-drift check; verify production publisher, watchdog and rebalancer health before closing the release.

Storage gates recursively compare mappings, arrays and struct members and keep an append-only registry of assembly storage anchors and schemas. --update cannot approve an incompatible existing recursive layout. Run the gate's Python regression tests as well as Solidity tests. Static analysis includes every installed High/Medium detector and fails on unreviewed production results; stage reports privately.

Technical Upgrade: stQEURO Multi-Vault with stQEUROFactory

Historical technical record. This document describes the multi-vault refactor as designed at the time; the factory / vaultId model it introduces is the one live in production, but three things have changed since: the AaveVault contract referenced in sections 5-7 was retired — external yield flows through IExternalStakingVault adapters (see Architecture); stQEUROToken was rewritten as a standard ERC-4626 vault in v1.0.3, so the YIELD_MANAGER_ROLE grants and the distributeYield call described in sections 2, 4 and 11 no longer exist (yield reaches stakers through QuantillonVault.creditVaultYield, see Staking Yield Distribution); and on Base mainnet only vaultId = 2 (MORPHO1, MetaMorphoStakingVaultAdapter) is registered. Sections 2, 4, 5, 6 and 11 are kept as the historical design record.

Context

The protocol originally used a single stQEURO staking token for a single staking vault.
The architecture has been extended to support multiple vaults (identified by vaultId), with one dedicated token per vault:

• vaultId = 1 -> stQEURO<VAULT_NAME_1>
• vaultId = 2 -> stQEURO<VAULT_NAME_2>
• ...

These tokens are not fungible with each other (distinct ERC20 addresses, distinct metadata, and distinct yield accounting).

Upgrade objective

1. Replace the "single stQEURO token" model with an upgradeable factory.
2. Keep stQEUROToken as the vault-level staking token implementation.
3. Route yield (YieldShift) through vaultId.
4. Enforce strict vault registration through an on-chain self-call.
5. Update deployment flows, interfaces, and tests.

Updated components

1) New contract: stQEUROFactory

This contract introduces an orchestration layer to deploy and register one stQEURO token per vault dynamically.

Responsibilities

• Deploy one ERC1967Proxy per vault pointing to the stQEUROToken implementation.
• Keep resolution indexes vaultId <-> vault <-> token.
• Store vault metadata (vaultName).
• Provide resolution getters for YieldShift, scripts, and indexers.

Upgradeability and access control

• Pattern: Initializable + AccessControlUpgradeable + SecureUpgradeable (UUPS via SecureUpgradeable).
• Roles:
  • GOVERNANCE_ROLE: factory reconfiguration (implementation, yieldShift, treasury, etc.)
  • VAULT_FACTORY_ROLE: permission to register vaults

Main storage

• stQEUROByVaultId[vaultId] -> token
• stQEUROByVault[vault] -> token
• vaultById[vaultId] -> vault
• vaultIdByStQEURO[token] -> vaultId
• _vaultNamesById[vaultId] -> vaultName
• _vaultNameHashUsed[keccak256(vaultName)] -> bool

Strict registration: registerVault(uint256 vaultId, string vaultName)

Applied constraints:

• onlyRole(VAULT_FACTORY_ROLE)
• caller vault derived from msg.sender (no vault parameter): strict self-register
• vaultId > 0
• uniqueness:
  • vaultId not already used
  • vault not already registered
  • vaultName not already used
• vaultName format:
  • length 1..12
  • allowed characters: A-Z, 0-9

Token creation:

• Name: Staked Quantillon Euro {vaultName}
• Symbol: stQEURO{vaultName}
• Deploy an ERC1967Proxy pointing to the stQEUROToken implementation
• Initialize the proxy with dynamic metadata (tokenName, tokenSymbol, vaultName)

Events

• VaultRegistered(vaultId, vault, stQEUROToken, vaultName)
• FactoryConfigUpdated(key, oldValue, newValue)

Governance reconfiguration

• updateYieldShift(address)
• updateTokenImplementation(address)
• updateOracle(address)
• updateTreasury(address)
• updateTokenAdmin(address)

2) stQEUROToken evolution

stQEUROToken remains the vault-level token (stake/unstake/yield logic preserved), but can now be initialized with dynamic metadata.

Key changes

• Added string public vaultName.
• Added an overloaded initialize(...) supporting:
  • _tokenName
  • _tokenSymbol
  • _vaultName
• Kept the legacy initializer (default metadata).
• Centralized initialization in _initializeStQEURO(InitConfig memory cfg).

Roles

At initialization:

• At initialization, DEFAULT_ADMIN_ROLE, GOVERNANCE_ROLE, EMERGENCY_ROLE -> admin. Before production activation, hand default-admin authority to the configured controller while preserving Safe governance/emergency roles; see the onboarding runbook.
• YIELD_MANAGER_ROLE -> admin
• YIELD_MANAGER_ROLE -> yieldShift (explicit grant)

3) QuantillonVault evolution (self-registration)

Additions:

• stQEUROFactory (linked factory address)
• stQEUROToken (token deployed for this vault)
• stQEUROVaultId (registered vault id)
• event StQEURORegistered(...)

New function:

• selfRegisterStQEURO(address factory, uint256 vaultId, string vaultName)
  • onlyRole(GOVERNANCE_ROLE)
  • local anti double-registration (stQEUROToken == address(0))
  • factory call originates from the vault itself, enforcing msg.sender == vault on the factory side
  • persists local references for factory/token/vaultId

4) YieldShift evolution (multi-vault routing)

Dependency change

• Old model: direct reference to a single stQEURO.
• New model: reference to stQEUROFactory.

YieldDependencyConfig field replacement:

• stQEURO -> stQEUROFactory

New signature

• addYield(uint256 vaultId, uint256 yieldAmount, bytes32 source)

Routing flow

1. Verify global source authorization (authorizedYieldSources + sourceToYieldType).
2. Pull USDC from source to YieldShift.
3. Compute userAllocation / hedgerAllocation.
4. Resolve target token through stQEUROFactory.getStQEUROByVaultId(vaultId).
5. Revert if vault is not registered (address(0)).
6. Keep coherent pull flow toward token:
   • safeIncreaseAllowance(stQEURO, userAllocation)
   • IstQEURO(stQEURO).distributeYield(userAllocation)

Source policy:

• default remains global (no strict source -> vaultId binding).
• optional strict mode is available through:
  • setSourceVaultBinding(source, vaultId)
  • clearSourceVaultBinding(source)
  • setSourceVaultBindingEnforcement(enabled)
• when strict mode is enabled, addYield(vaultId, ...) reverts unless sourceToVaultId[msg.sender] == vaultId.

5) AaveVault evolution

Additions:

• uint256 public yieldVaultId (governance config)
• setYieldVaultId(uint256) (reverts if 0)
• updateYieldShift(address) (explicit rewiring)

Change in harvestAaveYield():

• validate yieldVaultId != 0
• routing call:
  • yieldShift.addYield(yieldVaultId, netYield, bytes32("aave"))

6) Impacted interfaces

• New: IStQEUROFactory
  • registerVault(vaultId, vaultName)
  • resolution getters (vaultId -> token, token -> vaultId, etc.)
• IYieldShift
  • addYield becomes addYield(vaultId, yieldAmount, source)
  • dependency config: stQEUROFactory
  • optional strict source routing:
    • setSourceVaultBinding(source, vaultId)
    • clearSourceVaultBinding(source)
    • setSourceVaultBindingEnforcement(bool)
• IAaveVault
  • setYieldVaultId(uint256)
  • updateYieldShift(address)
  • yieldVaultId()
• IQuantillonVault
  • selfRegisterStQEURO(...)
  • getters stQEUROFactory, stQEUROToken, stQEUROVaultId
• IstQEURO
  • overloaded initialize(...) with dynamic metadata

7) Deployment scripts and wiring

DeployQuantillon.s.sol is updated to:

1. Deploy YieldShift.
2. Deploy stQEUROToken implementation.
3. Deploy stQEUROFactory (proxy) while injecting token implementation.
4. Configure YieldShift with stQEUROFactory.
5. Rewire AaveVault to YieldShift.
6. Leave AaveVault.yieldVaultId unset until governance/core-team vault decision.
7. Do not register any stQEURO vault token during bootstrap deployment.
8. Register vaults later via explicit core-team governance flow.

At bootstrap, no vault-name environment variable is consumed by DeployQuantillon.s.sol.

Exports:

• addresses and ABIs now include stQEUROFactory.

8) Breaking changes

Breaking changes assumed for this iteration:

1. YieldShift.addYield(...) now requires vaultId.
2. YieldShift dependency points to the factory instead of a single token.
3. Deployment flows must explicitly register vaults.
4. Integrations calling the old API addYield(yieldAmount, source) must be updated.

No on-chain legacy migration is included in this pass.

9) Validation and test coverage

New test

• test/stQEUROFactory.t.sol
  • registration OK
  • multi-vault registration (2 active vaults)
  • duplicate vaultId
  • duplicate vault address
  • invalid/duplicate vaultName
  • unauthorized caller

Updated tests

• YieldShift.t.sol (vaultId routing, factory dependency, strict source -> vaultId policy, multi-vault routing assertions)
• AaveVault.t.sol (yieldVaultId, new addYield signature)
• DeploymentSmoke.t.sol, IntegrationTests.t.sol, QuantillonInvariants.t.sol, LiquidationScenarios.t.sol, stQEUROToken.t.sol (initializer/signature alignment)

Result

• forge build --skip test passes
• targeted suites pass
• forge test -q passes

10) Runbook: adding a new staking vault

To onboard vaultId = N:

1. Deploy/configure the new vault (including governance roles).
2. From governance, grant VAULT_FACTORY_ROLE to the vault address.
3. Call vault.selfRegisterStQEURO(factory, N, VAULT_NAME).
4. Verify:
   • factory.getStQEUROByVaultId(N) != 0
   • factory.getVaultById(N) == vault
   • factory.getVaultName(N) == VAULT_NAME
5. If the vault receives yield through YieldShift, route addYield(N, ...) calls from the relevant source.
6. Update address/ABI exports and the off-chain integration layer.

11) Attention points for next steps

Rotation runbook: updateTokenImplementation

Use this for future vault deployments only (already-deployed vault tokens are unchanged).

1. Deploy the new stQEUROToken implementation contract.
2. Smoke-test initialization compatibility off-chain:
   • verify the 9-argument initializer used by the factory still succeeds.
   • verify role wiring still grants YIELD_MANAGER_ROLE to YieldShift.
3. From governance, execute:
   • stQEUROFactory.updateTokenImplementation(newImplementation).
4. Register a canary vault and verify:
   • metadata (name, symbol, vaultName) is correct.
   • factory.getStQEUROByVaultId(canaryId) resolves as expected.
   • yield routing still works through YieldShift.addYield(canaryId, ...).
5. If canary checks fail, roll back by re-pointing:
   • stQEUROFactory.updateTokenImplementation(previousImplementation).

Monitoring runbook: VaultRegistered and indexer consistency

Use scripts/deployment/monitor-stqeuro-factory.sh:

./scripts/deployment/monitor-stqeuro-factory.sh \
  --rpc-url <RPC_URL> \
  --factory <STQEURO_FACTORY_ADDRESS> \
  --from-block <START_BLOCK>

What it validates:

1. Streams/parses VaultRegistered logs in the selected block range.
2. For each event, checks on-chain registry consistency:
   • getStQEUROByVaultId(vaultId) == event.stQEUROToken
   • getVaultById(vaultId) == event.vault
   • getVaultIdByStQEURO(event.stQEUROToken) == vaultId
3. Optionally compares against an indexer snapshot:
   • --indexer-snapshot <path-to-json>

Status of prior follow-ups

1. Multi-vault integration tests: implemented.
2. Optional strict source -> vaultId policy: implemented.
3. updateTokenImplementation rotation procedure: documented.
4. VaultRegistered + indexer consistency monitoring: implemented.

12) Executive summary

This upgrade introduces a robust factory layer that enables QEURO staking to scale across multiple vaults without mixing staking positions.

• One vault = one dedicated stQEURO token.
• Yield routing becomes explicitly keyed by vaultId.
• Self-registration guarantees strict and auditable registration semantics.
• Core deployment registers no vault; each vault is onboarded post-core with setup-external-vaults.sh (see the External Vault Onboarding Runbook). On Base mainnet only vaultId = 2 (MORPHO1) is registered.

Multi-Vault Staking Runtime Flow

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

This note describes the current vaultId-based runtime behavior for staking, minting, redemption, and hedger liquidity flows.

Core Runtime State

QuantillonVault tracks:

• defaultStakingVaultId
• stakingVaultAdapterById[vaultId]
• stakingVaultActiveById[vaultId]
• redemptionPriorityVaultIds[]
• stQEUROTokenByVaultId[vaultId]
• principalUsdcByVaultId[vaultId]
• totalUsdcHeld
• totalUsdcInExternalVaults

Mint and Stake Flows

The conversion selectors below are inner operations. In production signed mode, submit the permitted operation through executeWithQuote(bytes,bytes) with its exact authorization; bare unquoted conversion calls are rejected.

1) Mint (default routing)

• mintQEURO(usdcAmount, minQeuroOut) calls internal mint flow with defaultStakingVaultId.
• If default vault id is non-zero and valid, net USDC is auto-deployed to that vault adapter.
• If default vault id is 0, net USDC remains in totalUsdcHeld.

2) Mint (explicit vault)

• mintQEUROToVault(usdcAmount, minQeuroOut, vaultId) uses provided vaultId.

3) Mint + Stake (one-step)

• mintAndStakeQEURO(usdcAmount, minQeuroOut, vaultId, minStQEUROOut):
  • Mints QEURO via the same vault-aware mint flow.
  • Resolves stQEUROTokenByVaultId[vaultId].
  • Stakes and transfers stQ token to caller.

Auto-deploy implementation

• _mintQEUROCommit moves net amount from held balance to per-vault principal accounting when targetVaultId != 0.
• _autoDeployToVault(vaultId, usdcAmount) deposits through configured adapter and emits UsdcDeployedToExternalVault.

Yield Distribution to Stakers

QuantillonVault 1.6.0 preserves the allocation introduced in 1.5.0 and allocates realized strategy yield by the harvest-time ratio of raw staked QEURO to total QEURO supply. Stakers receive their gross allocation after the configured haircut; treasury receives the unstaked allocation. The hedger receives only that haircut, with no base allocation for hedger collateral. There is no additional staking yield fee on vault credits; conversion costs and admission checks remain.

The release accepts one funded strategy and one outstanding staking series; registered empty strategies are allowed. It rejects unsupported simultaneous allocation. Raw staked QEURO includes unvested credit, while totalAssets() excludes yield not yet redeemable. Shareholders participate pro rata as yield vests; this does not make allocation time-weighted.

The keeper reads yieldDistributionConfig and the on-chain preview. hedgerBase remains zero for ABI compatibility. Older 1.4.x and legacy deployments retain their own models. See Yield Distribution 1.5.0.

Redemption Flow

redeemQEURO(qeuroAmount, minUsdcOut) (normal mode):

• Computes required USDC and checks total collateral availability.
• Uses _planExternalVaultWithdrawal(requiredUsdc) to compute deficit vs totalUsdcHeld.
• Commit phase withdraws deficit through _withdrawUsdcFromExternalVaults when needed.

Withdrawal source order:

• First: redemptionPriorityVaultIds (if configured).
• Fallback: single-item array with defaultStakingVaultId.
• If neither exists and held balance is insufficient, redemption reverts (InsufficientBalance).

Liquidation-mode redemption uses the same external-withdraw planning pattern.

Hedger Flow

Hedger opens / adds margin

• HedgerPool transfers USDC into QuantillonVault.
• vault.addHedgerDeposit(...) increases totalUsdcHeld.

Hedger closes / removes margin / liquidation payout

• HedgerPool calls vault.withdrawHedgerDeposit(...).
• Vault uses held USDC first; if needed, it withdraws from external vaults using the same priority logic as redemptions.

Governance and Operator Controls

QuantillonVault controls:

• setStakingVault(vaultId, adapter, active) (GOVERNANCE_ROLE)
• setDefaultStakingVaultId(vaultId) (GOVERNANCE_ROLE)
• setRedemptionPriority(vaultIds[]) (GOVERNANCE_ROLE)
• harvestAndDistributeVaultYield(vaultId) (YIELD_DISTRIBUTOR_ROLE) — harvest + 3-way split to stakers/hedger/treasury
• creditVaultYield(vaultId, usdcAmount) (YIELD_DISTRIBUTOR_ROLE) — credit USDC into stQEURO as QEURO backing
• setHedgerStakingYieldHaircutBps(bps) / setHedgerYieldRecipient(addr) (GOVERNANCE_ROLE)
• deployUsdcToVault(vaultId, usdcAmount) (VAULT_OPERATOR_ROLE)

Factory binding:

• selfRegisterStQEURO(factory, vaultId, vaultName) links vault id to stQ token (GOVERNANCE_ROLE).

Automatic vs Operational Actions

Automatic:

• Mint routing to default/explicit vault (if configured).
• Redemption and hedger withdrawals sourcing liquidity from external vaults when needed.

Operational:

• Adapter configuration and activation.
• Default vault and redemption-priority policy.
• Deploying idle held USDC (deployUsdcToVault).
• Harvesting + distributing adapter yield (harvestAndDistributeVaultYield).

Key Events for Indexer and Admin Read Models

• VaultRegistered (factory)
• StakingVaultConfigured
• DefaultStakingVaultUpdated
• RedemptionPriorityUpdated
• UsdcDeployedToExternalVault
• UsdcWithdrawnFromExternalVault
• VaultYieldDistributed (harvest + 3-way split)

Practical Ops Notes

• If vaultId config is missing/inactive, vault-aware actions revert (InvalidVault / config errors).
• If held + external principal cannot satisfy required payouts, flows revert (InsufficientBalance).
• Correct default and priority setup is critical to predictable redemption behavior.

Source Files

• src/core/QuantillonVault.sol
• src/core/HedgerPool.sol
• src/core/stQEUROFactory.sol

Staking-ratio yield distribution — 1.5.0 release

This policy was introduced in vault 1.5.0 and is preserved by the signed-quote production release, vault 1.6.0, activated on 17 October 2026. Harvest conversion uses its bounded signed authorization. See Signed Quotes in Production.

The Base candidate contracts were deployed and source-verified on 29 September 2026. The production proxy was upgraded to 1.5.0 on 30 September 2026 at 09:21:13 UTC (11:21:13 Paris time), in Base block 51,985,363. QuantillonVault and its linked StakingYieldLibrary change from capital-weighted allocation to harvest-time staking-ratio allocation. The Morpho adapter and staking-token implementation do not change. The existing single-funded-strategy guard remains.

Economics

Let Y be actual harvested USDC, Q total QEURO supply, S the registered staking token's raw QEURO balance when it has outstanding shares (including credited, unvested yield), and h the haircut in basis points. Clamp S to Q. Snapshot S and Q before harvesting or minting.

• Gross staker yield G = floor(Y × S / Q); G = 0 if Q is zero or no staking shares exist.
• Hedger payout H = floor(G × h / 10,000).
• Staker allocation = G − H; treasury allocation = Y − G.
• Hedger collateral, unrealized P&L and reference exchange rates do not weight the allocation.
• Zero haircut means no hedger payment, including the first harvest. Principal is never deducted.
• Staking-ratio rounding remains with treasury; haircut rounding remains with stakers.

The strategy's harvested yield is assigned to QEURO backing under this policy. Before activation, review the actual funded strategy and the provenance of its principal; separately owned hedger strategy deposits or multiple funded strategies require explicit accounting outside this release.

This remains snapshot-weighted, not time-weighted: staking duration is not accumulated. The staker allocation is converted into QEURO and vests using the token's existing schedule, currently 24 hours. Existing conversion costs, oracle checks, execution admission, collateralization and mint eligibility remain enforced. The token's legacy yieldFee value is ignored for both harvested and directly credited yield. Direct creditVaultYield credits an already allocated amount and does not apply the harvest haircut again. Public mint/redeem fees are unchanged.

Compatibility

Storage layout and public selectors are unchanged. previewVaultYieldDistribution and VaultYieldBreakdown retain hedgerBase, now always zero. Preview estimates accrued yield; execution uses the adapter's actual liquid payout, so a liquidity limit may reduce all allocations. A successful allocation preview is not a guarantee that conversion admission will succeed. Conversion failure rolls back the entire harvest, USDC transfers and lastHarvest timestamp.

Deploy the version-aware dapp/backend/keeper release before activating the contract. It recognizes 1.4.x as capital and 1.5.x as staking-ratio, keeps older funding semantics, and disables the legacy staking-yield-fee control only for the new model (unknown versions cannot enable that control). The displayed provider APY remains an underlying historical rate, explicitly before deductions and conversion costs, not a guaranteed QEURO return. No new net-APY estimator is included.

Required release evidence

1. Preserve unrelated local changes; build from the reviewed release commit and installed pinned dependencies. Run contract tests, keeper tests/typecheck, dapp typecheck and targeted UI/backend tests.

2. Run ABI, storage-layout, size and version-bump gates. Bump versions for dependency-closure changes; do not overwrite the deployed-version manifest with candidate addresses.

3. Rehearse the upgrade and zero/nonzero-haircut harvests on Base block 51,942,142 (deployed 1.4.0):

   REQUIRE_BASE_FORK=true FOUNDRY_PROFILE=production forge test \
     --match-contract StakingYieldUpgradeForkTest \
     --fork-url https://app.quantillon.money/api/rpc/base \
     --fork-block-number 51942142 -vv
   

   The tests upgrade only the local fork and check balances, private token vesting storage, configuration, timestamps, conservation, recipient balance deltas and subsequent vesting.

4. Reconcile the live proxy version, EIP-1967 implementation and linked libraries against on-chain evidence. Record the current haircut, recipient, strategy binding and funding. The tracked version manifest may lag live state; do not infer the predecessor from that manifest alone.

5. Run reproducible-bytecode checks for the library and vault. If the ordinary full-unit build differs from the verifier's pruned unit, use the existing build-verifiable-impl.sh workflow and rehearse the exact candidate runtime before deploying. Never deploy an unverified variant.

Activation

After release review, deploy the new library and the implementation linked to that exact library and the verified existing dependencies. Prepare the Safe schedule/execute operations using the live controller's delay and roles; the documented current delay is 12 hours. Keep transaction JSON and Safe payloads private, outside repositories and public hosting. The implementation is inert until the proxy upgrade executes. No initializer or storage migration is required.

Preserve the haircut (currently zero), hedger recipient, staking shares, existing vesting and keeper journal. Coordinate activation away from a keeper run in flight. The first harvest after activation uses the new policy for all pending yield, including yield accrued before activation. Historical payouts are not recomputed. Preserve the daily 03:00 UTC schedule.

After activation, verify version 1.5.0 and the exact implementation/library runtime hashes; update deployment provenance only from confirmed transactions. Invalidate/refresh version and fee snapshots. Confirm the preview has hedgerBase = 0 and haircut-only payout. Observe the first actual harvest: USDC allocations reconcile, the recipient receives no payout at zero haircut, QEURO is credited to stakers, syncVesting confirms, and the keeper reports a healthy served slot without duplicate harvests.

If these checks fail, stop further keeper attempts and investigate with the writer journal intact. Corrective upgrades follow governance; completed payouts cannot be rolled back automatically.

Base deployment and governance handoff — 29 September 2026

Source commit: d0232f8e3d5a072e18447345380d753ae91089cb.

Both deployed runtimes match the independently reproduced build. The vault keeps the live ExecutionPricingLibrary, SecureUpgradeLibrary and TreasuryRecoveryLibrary bindings. The proxy address is unchanged: 0x833E5Ba510a241b21F1C60c987D1c49eB52E4a07.

The generated private schedule, execute and cancel package was rehearsed against Base block 51,944,104 using the actual Safe (two-owner threshold), controller and deployed candidates. The rehearsal proved early execution fails, cancellation works, the operation becomes ready only after 43,200 seconds, and the ordered recipient configuration plus upgrade succeeds through Safe MultiSend. Accounting, configuration, staking shares and vesting storage were preserved. At zero haircut, the post-upgrade preview paid no yield to the hedger.

Confirmed production activation — 30 September 2026

Safe transaction #78 completed the reviewed operation in Base transaction 0xc41087be…d3255b3. The Safe success event, completed controller operation, proxy implementation and all linked runtime hashes were verified. Accounting, QEURO supply, staking shares and token vesting storage were preserved across the activation block. The haircut remains zero and the preview pays no hedger yield. The dapp reports staking-ratio; the keeper remains healthy on its 03:00 UTC schedule.

The 30 September 03:00 UTC harvest occurred before activation and used the previous model. The first scheduled harvest under 1.5.0 is 1 October 2026 at 03:00 UTC (05:00 Paris time). Its actual allocation and vesting synchronization still need to be observed after that run. Deployment provenance is recorded in deployments/8453/versions.json; transaction payloads and execution evidence remain private.

Historical staking yield distribution — 1.4.0

Production uses 1.5.0 from 30 September 2026. See the current staking-ratio allocation and activation record. The capital-weighted model below is retained only as historical documentation.

Capital-based distribution (QuantillonVault 1.4.0)

This source describes the proposed 1.4.0 implementation. Deploying application changes alone does not activate it. Confirm version() on the target proxy; earlier versions retain the annual-funding model until upgraded.

Yield from the single funded external strategy belongs to three economic allocations:

• Hedgers receive yield attributable to their effective collateral.
• Stakers receive yield attributable to the backing of staked QEURO.
• Treasury receives yield attributable to unstaked QEURO backing and existing protocol fees.

Governance may additionally redirect a percentage of gross earned staking yield to the configured hedger recipient. hedgerStakingYieldHaircutBps defaults to zero; 100 is 1%, 200 is 2%, and the maximum is 10,000 (100%). This is never an annual rate or a deduction from principal. The haircut applies before the existing staking yield fee.

Calculation

Immediately before harvesting, snapshot:

• H: HedgerPool.getTotalEffectiveHedgerCollateral(price), including its existing P&L treatment.
• U: QEURO total supply valued in USDC at a fresh validated EUR/USD reference price (supply * price / 1e30).
• S: QEURO balance of the selected stQEURO token, capped at QEURO supply, or zero if there are no shareholders. This includes credited but unvested QEURO: vesting affects redemption, not economic ownership.
• Q: QEURO total supply.
• Y: USDC yield actually realized by the adapter, excluding tracked principal.

hedgerBase   = floor(Y * H / (H + U))
userPool     = Y - hedgerBase
stakerGross  = Q == 0 ? 0 : floor(userPool * S / Q)
treasuryBase = userPool - stakerGross
haircut      = floor(stakerGross * haircutBps / 10000)
hedgerShare  = hedgerBase + haircut
userShare    = stakerGross - haircut

If H + U == 0, orphaned yield goes to treasury. All amounts conserve realized yield; floor rounding remains in the residual allocations. A nonzero hedger payment requires a configured nonzero recipient: there is no implicit treasury fallback.

The snapshot uses economic ownership at harvest, including changes to balances or exchange rates before the transaction. It is not time-weighted participation accounting. Idle and deployed capital use the same pooled ownership weights; only strategy yield that is actually harvested is paid out.

Example

At 1 QEURO = 1 USDC, take 1,000 USDC of effective hedger collateral, 100 QEURO outstanding, 50 staked, and 110 USDC harvested:

Staker allocations above are before the existing staking fee and execution conversion into QEURO.

Credit, fees and vesting

harvestAndDistributeVaultYield(vaultId) remains role-gated, paused with the vault, and non-reentrant. The staker allocation goes through the existing _creditVaultYield path: staking yield fee, execution-pricing admission, collateralization validation and QEURO minting into stQEURO. The public mint fee is not additionally charged. Zero staker allocations skip crediting entirely.

There is no claim call. Credited QEURO vests under the token's existing schedule and increases redeemable value per share. Including unvested QEURO in the ownership snapshot does not make it immediately withdrawable. A failed admission, mint, transfer or oracle validation reverts the entire harvest, including its timestamp and transfers.

The initial release supports one funded strategy. Distribution rejects other deployed strategy principal, other registered strategies with underlying assets, or another registered series with outstanding shares. Registered empty series remain allowed. Factory registration must retain the existing factory so its registry remains complete. Multiple-strategy capital attribution requires a later extension.

Interfaces and compatibility

• setHedgerStakingYieldHaircutBps(uint256): governance-only, accepts 0–10,000; emits HedgerStakingYieldHaircutUpdated.
• hedgerStakingYieldHaircutBps(): public getter.
• yieldDistributionConfig(vaultId): (haircutBps, hedgerRecipient, lastHarvest).
• previewVaultYieldDistribution(vaultId): returns (realizedYield, hedgerBase, haircut, hedgerShare, userShare, treasuryShare) as a struct. Invoke using eth_call/simulateContract; the oracle's stateful interface means this is not a Solidity view. Shares calculation and validation with execution; realized yield and balances may change before mining.
• VaultYieldDistributed: existing conserved aggregate event; userShare is after haircut but before existing staking fees.
• VaultYieldBreakdown: supplemental event exposing hedger base and haircut separately.
• harvestConfig: deprecated read; the first value is always zero after upgrade. Recipient and timestamp remain available.
• setFundingRateAnnualBps: retained selector, explicitly reverts. The old storage slot stays in place and cannot initialize the new haircut.

Keepers continue to use lastHarvest for idempotency. There is no funding clock, time prorating, or first-harvest funding exemption. Clients identify contract semantics by version and do not relabel old funding data as a haircut.

Upgrade procedure

1. Validate storage layout, ABI compatibility, semantic versions, runtime size and verification reproducibility. Deploy only the reviewed library/implementation artifacts through the normal authorized release process.
2. Rehearse on a pinned Base fork through the protocol RPC API. Preserve balances, shares, vesting, execution configuration and harvest timestamps; prove a nonzero old funding rate becomes a zero new haircut.
3. Stop recurring harvests. Settle accrued yield under the old implementation immediately before coordinated activation. If that cannot succeed, stop activation and resolve it rather than silently change the allocation of pending yield.
4. Confirm one funded strategy. Resolve HedgerPool from the vault, read its nonzero singleHedger(), and use that account itself as hedgerYieldRecipient in the reviewed release manifest. The private Safe execute package sets that recipient through the Safe's governance role before executing the controller upgrade; execute those calls together as one atomic Safe batch. Revalidate the hedger immediately before execution; a hedger change invalidates the prepared recipient binding. Haircut starts at zero, but hedger capital yield still requires this recipient.
5. Deploy compatible API, keeper and UI changes before resuming. Confirm configuration and the first distribution against the preview and events.
6. Any later haircut change is a separate governance action.

Transaction proposals and review artifacts remain private. Never publish transaction JSON or Safe payloads in docs, public assets or releases.

Tests: StQEUROYieldDistribution.t.sol covers allocation, fees, vesting ownership, rollback and boundary cases; StakingYieldUpgradeFork.t.sol rehearses the UUPS upgrade and payment to singleHedger() in a local Base fork. Release rehearsals must set REQUIRE_BASE_FORK=true so an absent or incorrect fork fails instead of skipping. Use production compiler settings and an explicitly pinned block:

REQUIRE_BASE_FORK=true FOUNDRY_PROFILE=production forge test \
  --match-path test/StakingYieldUpgradeFork.t.sol \
  --fork-url "$RPC_URL" --fork-block-number "$FORK_BLOCK" -vv

Confirm the activated yieldDistributionConfig(vaultId) recipient equals HedgerPool.singleHedger() before resuming harvests. Repeat that configuration check when rotating the hedger; the recipient is an explicit governance setting and does not automatically follow a rotation.

External Vault Onboarding Runbook (setup-external-vaults.sh)

Why This Exists

Core deployment (DeployQuantillon) intentionally does not bootstrap external adapters. After core deploy:

• defaultStakingVaultId = 0
• redemption priority is empty
• no adapter is registered via setStakingVault

Use this runbook to onboard staking vault adapters post-deploy.

Script

./scripts/deployment/setup-external-vaults.sh

The script performs, for each --vault entry:

1. Grant VAULT_FACTORY_ROLE to QuantillonVault on stQEUROFactory.
2. Register the vault token via selfRegisterStQEURO(factory, vaultId, vaultName).
3. Configure adapter binding via setStakingVault(vaultId, adapter, true).
4. Grant VAULT_MANAGER_ROLE to QuantillonVault on the adapter (adapter.grantRole(VAULT_MANAGER_ROLE, vault)).

Adapter yield is distributed via QuantillonVault.harvestAndDistributeVaultYield — grant YIELD_DISTRIBUTOR_ROLE to the yield keeper separately (yield distribution no longer routes through YieldShift).

Required — do not skip. The vault calls adapter.depositUnderlying / withdrawUnderlying / harvestYieldToVault, all gated by VAULT_MANAGER_ROLE on the adapter. The adapter constructor grants that role only to its admin, so without step 4 every external-vault deploy / redeem-sourcing / harvest reverts. Step 4's signer must hold the adapter's DEFAULT_ADMIN_ROLE.

Recommended — seed each new stQEURO series. To avoid the well-known first-depositor donation/rounding edge case, the operator should make the first stake into each newly registered stQEURO vault (a small deposit) so it is never bootstrapped by an arbitrary first external user.

Then it sets:

• setDefaultStakingVaultId(...)
• setRedemptionPriority(...)

Prerequisites

• Foundry installed (cast available in PATH)
• Core deployment completed (QuantillonVault, stQEUROFactory, and optionally YieldShift addresses)
• Deployer/admin key with required governance/role permissions
• RPC URL for target chain

Parameters

• --rpc-url <url>: chain RPC endpoint
• --private-key <hex>: signer private key
• --quantillon-vault <address>: deployed QuantillonVault
• --factory <address>: deployed stQEUROFactory
• --vault <vaultId:vaultName:adapterAddress>: repeatable vault definition
  • vaultId: positive integer
  • vaultName: uppercase/digits token label (factory validation applies)
  • adapterAddress: external strategy adapter for that vault id
• --default-vault-id <vaultId>: optional, defaults to first --vault item

Ready-To-Run Examples

The AAVE1 entries below are localhost / testnet examples over mock adapters. On Base mainnet only vaultId = 2 (MORPHO1, MetaMorphoStakingVaultAdapter) is registered; there is no Aave vault in production.

Localhost (31337)

./scripts/deployment/setup-external-vaults.sh \
  --rpc-url http://localhost:8545 \
  --private-key "$PRIVATE_KEY" \
  --quantillon-vault 0xQuantillonVault \
  --factory 0xStQEUROFactory \
  --vault 1:AAVE1:0xMockAaveAdapter \
  --vault 2:MORPHO1:0xMorphoAdapter \
  --default-vault-id 2

Base Sepolia (84532)

./scripts/deployment/setup-external-vaults.sh \
  --rpc-url https://sepolia.base.org \
  --private-key "$PRIVATE_KEY" \
  --quantillon-vault 0xQuantillonVault \
  --factory 0xStQEUROFactory \
  --vault 1:AAVE1:0xAdapterA \
  --vault 2:MORPHO1:0xAdapterB

Verification Commands

Export addresses once:

export RPC_URL=http://localhost:8545
export QUANTILLON_VAULT=0xQuantillonVault
export FACTORY=0xStQEUROFactory
export YIELD_SHIFT=0xYieldShift

Check default vault:

cast call "$QUANTILLON_VAULT" "defaultStakingVaultId()(uint256)" --rpc-url "$RPC_URL"

Check per-vault token + adapter exposure:

cast call "$FACTORY" "getStQEUROByVaultId(uint256)(address)" 1 --rpc-url "$RPC_URL"
cast call "$QUANTILLON_VAULT" "getVaultExposure(uint256)(address,bool,uint256,uint256)" 1 --rpc-url "$RPC_URL"

Check routing events:

cast logs --rpc-url "$RPC_URL" --address "$QUANTILLON_VAULT" "StakingVaultConfigured(uint256,address,bool)"
cast logs --rpc-url "$RPC_URL" --address "$QUANTILLON_VAULT" "DefaultStakingVaultUpdated(uint256,uint256)"
cast logs --rpc-url "$RPC_URL" --address "$QUANTILLON_VAULT" "RedemptionPriorityUpdated(uint256[])"

If --yield-shift was used, verify source authorization/binding:

cast call "$YIELD_SHIFT" "authorizedYieldSources(address)(bool)" 0xAdapterA --rpc-url "$RPC_URL"
cast call "$YIELD_SHIFT" "sourceToVaultId(address)(uint256)" 0xAdapterA --rpc-url "$RPC_URL"
cast call "$YIELD_SHIFT" "enforceSourceVaultBinding()(bool)" --rpc-url "$RPC_URL"

Routing configuration coverage

Starting with QuantillonVault 1.5.1, the effective redemption set must include all tracked external principal. A nonempty priority list is the effective set; an empty list selects only the default vault. Both setRedemptionPriority and setDefaultStakingVaultId reject a resulting set whose included principal differs from totalUsdcInExternalVaults.

When changing the default while the old default remains funded, first configure an explicit priority list containing every funded vault. Then change the default. Retain the old vault in the priority list until its tracked principal is withdrawn or its loss is recognized. Zero reported NAV alone does not allow removal. A complete explicit list can also restore coverage to an existing configuration.

stQEURO reserve activation

stQEUROToken 1.3.0 uses matched virtual reserves while retaining 18-decimal shares and the existing ERC-4626 interface. New and empty series start at parity. A populated series calibrates its reserve ceiling to its current share price at the first accounting synchronization; that ceiling remains fixed until the series empties. The effective reserve is capped by backing after losses so withdrawals cannot quote more than the real assets. Vesting and the deposit round-trip loss bound remain in force.

For an existing proxy, rehearse the upgrade against a recent pinned block and verify its share precision, balances, supply, metadata, and withdrawal quotes. While the series is unpaused, execute upgradeToAndCall(newImplementation, abi.encodeCall(syncVesting, ())) through the authorized controller so reserve activation is atomic with the upgrade. For paused maintenance, use one authorized Safe batch to pause, execute the controller's scheduled upgrade, call syncVesting from the Safe holding GOVERNANCE_ROLE, and unpause. A paused token rejects a sync from a controller without that role. Verify all roles during rehearsal and recheck the live state before execution.

Calibration preserves the existing exchange rate; it does not reset a series with an already extreme asset-to-share ratio. If ordinary deposit previews are zero or fail the round-trip loss bound before activation, stop that series' rollout and resolve its migration without changing existing holders' claims. Update the factory's token implementation separately for future series; that setting does not upgrade existing token proxies.

Adapter withdrawal and migration invariants

An adapter must report the actual USDC withdrawn. A one-unit ERC-4626 rounding shortfall is permitted only when the aggregate flow can still satisfy the payout; principal trackers follow the actual return. Changing the ERC-4626 endpoint inside a current adapter requires zero old shares. Replacing an adapter must be rehearsed atomically while the vault is paused.

Replacing a funded MetaMorpho adapter

MetaMorphoAdapterMigration is a one-use, Safe-called helper bound at construction to one vault id and one old/new adapter pair using the same USDC and MetaMorpho vault. It reads the current principal at execution, withdraws it, collects the remaining yield, deposits the principal into the replacement, and leaves yield as uncredited USDC at the replacement. It changes neither QEURO supply nor the vault's tracked principal. Redeposition may lose at most one USDC base unit to ERC-4626 rounding, and replacement backing must still cover all principal.

In one Safe transaction: pause the vault, grant the helper temporary manager roles on both adapters and governance on the vault, grant the vault manager access to the replacement, call migrate(), revoke all temporary roles, retire the vault's manager role on the old adapter, and remove the Safe's direct manager role on the replacement. Verify the configured adapter and preserved accounting before resuming operations. Failure anywhere reverts the entire transaction.

The retired legacy adapter must have zero principal and zero valued underlying. Its withdrawal-only interface can leave fractional ERC-4626 shares worth zero USDC base units; retain its address in the deployment history and record that residue explicitly. The migration rejects losses, unavailable liquidity and principal mismatches, and cannot be reused or directed to another destination.

New-series authority check

After creating a staking series, preserve the governance and emergency roles assigned to the Safe, grant DEFAULT_ADMIN_ROLE to the configured controller, verify its controller configuration, and renounce the Safe's default-admin role. Complete creation, role handover and registry activation in one reviewed Safe batch while deposits are paused. The factory's initial tokenAdmin is a bootstrap identity; changing it to the controller alone would also redirect governance and emergency roles, so it is not a substitute for this explicit handover. Verify all role holders before unpausing and include the new series in subsequent upgrade inventories.

Dapp compatibility

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

Contract releases are accepted only after the frontend contract-drift check and dapp tests pass.

1. Build Solidity artifacts and run scripts/deployment/copy-abis.sh against a private dapp checkout.
2. Run npm run check:contract-drift, npm run test:run, and npm run build in quantillon-dapp.
3. Read minCollateralizationRatioForMinting from the deployed vault at runtime; source defaults and UI fallbacks are not authoritative.
4. Treat a reverted harvestAndDistributeVaultYield as retryable. The transaction is atomic and adapter yield remains available.
5. Verify generated ABI selectors for changed oracle, pricing, vault, and stQEURO contracts before deployment.

Normal conversions must use the signed wrapper on the authorized Vault or UserPool target. Complete token approval before requesting an executable quote. Validate chain, wallet, module, target, exact inner calldata, amounts and expiry; require user review again if output changes. Bare legacy mint/redeem calls are rejected in signed mode.

Test approval followed by issuance, 45-second expiry, replay rejection, wallet/chain changes, capacity exhaustion, stale reference, pause, and ambiguous transaction recovery. Simulate the exact wrapper call. Dashboard and keeper valuation must obtain a fresh signed reference in read-only simulation rather than equating an idle cache with unavailable delivery. A failed harvest remains atomic. The current emergency budget is zero; no automatic reference-only fallback should be offered.

Admin compatibility is part of release acceptance. Simulate each generated action from the Safe against current state. If the target's admin is the configured controller, simulate from the controller and generate matching schedule and execute transactions using its live minimum delay and a unique salt. Ordinary Safe actions remain direct. Do not turn a failed business-logic check into an unchecked proposal. Test both pre-handover and post-handover authority, rejected calls, role grants, and the retained immediate pause/resume controls. Keep generated transaction files local; they are never public application assets.

Contents

• IMigrationAdapter
• IMigrationVault
• MetaMorphoAdapterMigration
• IRebalancerSafe
• QuantillonRebalancerModule

IMigrationAdapter

Git Source

Functions

USDC

function USDC() external view returns (address);

metaMorphoVault

function metaMorphoVault() external view returns (address);

principalDeposited

function principalDeposited() external view returns (uint256);

totalUnderlying

function totalUnderlying() external view returns (uint256);

withdrawUnderlying

function withdrawUnderlying(uint256 amount) external returns (uint256);

harvestYieldToVault

function harvestYieldToVault() external returns (uint256);

depositUnderlying

function depositUnderlying(uint256 amount) external returns (uint256);

IMigrationVault

Git Source

Functions

paused

function paused() external view returns (bool);

usdc

function usdc() external view returns (address);

getVaultExposure

function getVaultExposure(uint256 id) external view returns (address, bool, uint256, uint256);

setStakingVault

function setStakingVault(uint256 id, address adapter, bool active) external;

MetaMorphoAdapterMigration

Git Source

Inherits: IVersioned, ReentrancyGuard

Title: MetaMorphoAdapterMigration

Moves one configured adapter's principal and uncredited yield atomically.

Grant temporary manager roles on both adapters and governance on the paused vault, then revoke them in the same Safe transaction. No user tokens are minted or burned.

Constants

safe

address public immutable safe

vault

IMigrationVault public immutable vault

oldAdapter

IMigrationAdapter public immutable oldAdapter

newAdapter

IMigrationAdapter public immutable newAdapter

usdc

IERC20 public immutable usdc

vaultId

uint256 public immutable vaultId

State Variables

completed

bool public completed

Functions

constructor

Binds this one-use operation to a Safe, vault and adapter pair.

constructor(address safe_, address vault_, uint256 id_, address old_, address next_) ;

version

Identifies the immutable migration implementation.

function version() external pure override returns (string memory);

migrate

Migrates current balances without embedding an amount that can become stale.

Leaves yield uncredited as idle USDC at the replacement adapter. A legacy adapter can retain fractional shares worth zero USDC base units; no valued assets may remain. Any failure rolls back the withdrawals, deposits, registry change and completion flag.

function migrate() external nonReentrant;

Events

Migrated

event Migrated(
    uint256 indexed vaultId,
    address indexed oldAdapter,
    address indexed newAdapter,
    uint256 principal,
    uint256 uncreditedYield
);

Errors

Unauthorized

error Unauthorized();

InvalidConfiguration

error InvalidConfiguration();

InvalidState

error InvalidState();

BalanceMismatch

error BalanceMismatch();

IRebalancerSafe

Git Source

Functions

execTransactionFromModuleReturnData

function execTransactionFromModuleReturnData(address to, uint256 value, bytes calldata data, uint8 operation)
    external
    returns (bool success, bytes memory returnData);

QuantillonRebalancerModule

Git Source

Inherits: ReentrancyGuard

Title: QuantillonRebalancerModule

A Safe-owned, non-upgradeable permission to add/remove margin on one position.

No arbitrary execution, transfers, delegatecalls, position entry/exit or bridging. The operator pays gas; USDC always moves between the Safe and HedgerPool's vault. Install only after independent review. Policy changes require a call from the Safe.

Note: security-contact: team@quantillon.money

Constants

safe

address public immutable safe

hedgerPool

IHedgerPool public immutable hedgerPool

usdc

IERC20 public immutable usdc

vault

IQuantillonVault public immutable vault

positionId

uint256 public immutable positionId

State Variables

operator

address public operator

paused

bool public paused = true

limits

Limits public limits

nonce

uint256 public nonce

lastExecution

uint256 public lastExecution

usageDay

uint256 public usageDay

currentDayUsage

uint256 public currentDayUsage

previousDayUsage

uint256 public previousDayUsage

Functions

constructor

constructor(address safe_, address pool_, uint256 positionId_, address operator_, Limits memory limits_) ;

version

Reports this standalone module's release version.

function version() external pure returns (string memory);

configure

Changes the operator and policy; existing usage and cooldown are preserved.

function configure(address operator_, Limits calldata limits_) external nonReentrant;

setPaused

Lets the Safe pause or resume automation without blocking its owner transactions.

function setPaused(bool paused_) external nonReentrant;

addMargin

Adds margin using an exact, atomic Safe approval and preserves its reserve.

Deposits remain possible with an invalid oracle to allow collateral recovery.

function addMargin(uint256 amount, uint256 expectedNonce, uint256 deadline) external nonReentrant;

removeMargin

Removes margin to the Safe, then checks fresh position and protocol solvency atomically.

function removeMargin(uint256 amount, uint256 expectedNonce, uint256 deadline) external nonReentrant;

windowUsage

Conservative rolling-day usage: sum of the current and previous UTC day.

This bounds every rolling 24h period, but can retain usage for almost 48h.

function windowUsage() public view returns (uint256);

_configure

function _configure(address operator_, Limits memory limits_) private;

_authorize

function _authorize(uint256 amount, uint256 expectedNonce, uint256 deadline) private;

_checkWithdrawalFloors

function _checkWithdrawalFloors() private;

_approve

function _approve(uint256 amount) private;

_execute

function _execute(address target, bytes memory data) private returns (bytes memory result);

Events

Configured

event Configured(address indexed operator, Limits limits);

PauseChanged

event PauseChanged(bool paused);

MarginRebalanced

event MarginRebalanced(uint256 indexed nonce, uint256 indexed positionId, bool increase, uint256 amount);

Errors

Unauthorized

error Unauthorized();

InvalidConfiguration

error InvalidConfiguration();

ModulePaused

error ModulePaused();

InvalidRequest

error InvalidRequest();

WrongPositionOwner

error WrongPositionOwner();

DependenciesChanged

error DependenciesChanged();

LimitExceeded

error LimitExceeded();

CooldownActive

error CooldownActive();

InvalidOracle

error InvalidOracle();

PositionFloorBreached

error PositionFloorBreached();

VaultFloorBreached

error VaultFloorBreached();

SafeReserveBreached

error SafeReserveBreached();

SafeExecutionFailed

error SafeExecutionFailed();

TokenOperationFailed

error TokenOperationFailed();

UnexpectedBalanceChange

error UnexpectedBalanceChange();

Structs

Limits

struct Limits {
    uint256 maxActionUsdc;
    uint256 maxWindowUsdc;
    uint256 cooldownSeconds;
    uint256 minSafeReserveUsdc;
    uint256 minMarginBps;
    uint256 marginBufferBps;
    uint256 vaultCrBufferBps;
}

Contents

• vaults
• yieldmanagement
• FeeCollector
• HedgerPool
• QEUROToken
• QTIToken
• QuantillonVault
• SecureUpgradeable
• TimelockUpgradeable
• UserPool
• stQEUROFactory
• stQEUROToken

Contents

• IMockAaveVault
• AaveStakingVaultAdapter
• MetaMorphoStakingVaultAdapter
• IMockMorphoVault
• MorphoStakingVaultAdapter

IMockAaveVault

Git Source

Functions

depositUnderlying

Deposits underlying assets into the mock Aave vault.

Forwards parameters to the underlying vault and relies on the adapter-level access control and nonReentrant protection in the main adapter.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on invalid amount or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit deposit events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 assets, address onBehalfOf) external returns (uint256 shares);

Parameters

Returns

withdrawUnderlying

Withdraws underlying assets from the mock Aave vault.

Forwards parameters to the underlying vault. Reverts and/or returns values are handled by the calling adapter.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on insufficient balance or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit withdrawal events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 assets, address to) external returns (uint256 withdrawn);

Parameters

Returns

totalUnderlyingOf

Returns underlying assets held for an account.

View helper used by the adapter to compute available yield.

Notes:

• security: Read-only helper.

• validation: No input validation required at interface level.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if implementation cannot service read.

• reentrancy: Not applicable for view function.

• access: Public view at implementation level.

• oracle: No oracle dependencies.

function totalUnderlyingOf(address account) external view returns (uint256);

Parameters

Returns

AaveStakingVaultAdapter

Git Source

Inherits: AccessControl, ReentrancyGuard, IExternalStakingVault

Title: AaveStakingVaultAdapter

Generic external vault adapter for Aave-like third-party vaults.

Mirrors MorphoStakingVaultAdapter structure for symmetric localhost testing. Wraps a MockAaveVault (simple share-accounting mock) and routes yield to YieldShift.

Constants

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

VAULT_MANAGER_ROLE

bytes32 public constant VAULT_MANAGER_ROLE = keccak256("VAULT_MANAGER_ROLE")

USDC

IERC20 public immutable USDC

State Variables

aaveVault

IMockAaveVault public aaveVault

principalDeposited

uint256 public principalDeposited

Functions

constructor

Initializes Aave adapter dependencies and roles.

Grants DEFAULT_ADMIN_ROLE, GOVERNANCE_ROLE, and VAULT_MANAGER_ROLE, then stores dependency pointers used by the adapter functions.

Notes:

• security: Validates non-zero dependency addresses.

• validation: Reverts on zero address.

• state-changes: Initializes role assignments and adapter dependency pointers.

• events: No events emitted by constructor.

• errors: Reverts with ZeroAddress on invalid inputs.

• reentrancy: Not applicable - constructor only.

• access: Public constructor.

• oracle: No oracle dependencies.

constructor(address admin, address usdc_, address aaveVault_) ;

Parameters

depositUnderlying

Deposits USDC into the configured Aave vault.

Tracks principal and forwards the deposit to aaveVault.depositUnderlying.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount or zero-share deposit outcome.

• state-changes: Increases principalDeposited and updates vault position.

• events: Emits downstream transfer/deposit events from dependencies.

• errors: Reverts on transfer/approval/deposit failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 sharesReceived);

Parameters

Returns

withdrawUnderlying

Withdraws USDC principal from the configured Aave vault.

Withdraws up to the tracked principal, then transfers the withdrawn USDC to msg.sender.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount or when no principal is tracked.

• state-changes: Decreases principalDeposited and updates vault position.

• events: Emits downstream transfer/withdrawal events from dependencies.

• errors: Reverts on withdrawal mismatch or transfer failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 usdcWithdrawn);

Parameters

Returns

harvestYieldToVault

Harvests accrued yield from the Aave vault and transfers it as USDC to the caller (the vault).

Withdraws only the amount above tracked principal, then transfers it to msg.sender (the vault) so the caller can apply its own distribution policy.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Returns zero when no yield is available; reverts only on downstream failures.

• state-changes: Leaves principalDeposited unchanged; transfers realized USDC to the caller.

• events: Emits downstream transfer events from dependencies.

• errors: Reverts on downstream withdrawal or transfer failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function harvestYieldToVault()
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 realizedYield);

Returns

totalUnderlying

Returns current underlying balance controlled by this adapter.

Reads the underlying amount from the configured aaveVault.

Notes:

• security: Read-only helper.

• validation: No input validation required.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if downstream vault read fails.

• reentrancy: Not applicable for view function.

• access: Public view.

• oracle: No oracle dependencies.

function totalUnderlying() external view override returns (uint256 underlyingBalance);

Returns

setAaveVault

Updates the configured Aave vault endpoint.

Updates the aaveVault pointer; the adapter uses the new vault for future deposits/withdrawals.

Notes:

• security: Restricted to GOVERNANCE_ROLE.

• validation: Reverts on zero address input.

• state-changes: Updates aaveVault pointer.

• events: Emits AaveVaultUpdated.

• errors: Reverts with ZeroAddress for invalid input.

• reentrancy: No external calls after state change.

• access: Restricted to governance role.

• oracle: No oracle dependencies.

function setAaveVault(address newAaveVault) external onlyRole(GOVERNANCE_ROLE);

Parameters

Events

AaveVaultUpdated

event AaveVaultUpdated(address indexed oldVault, address indexed newVault);

MetaMorphoStakingVaultAdapter

Git Source

Inherits: AccessControl, ReentrancyGuard, IExternalStakingVault, IVersioned

Title: MetaMorphoStakingVaultAdapter

Adapter for MetaMorpho ERC-4626 vaults such as 0xBEEFE94c8aD530842bfE7d8B397938fFc1cb83b2.

Constants

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

VAULT_MANAGER_ROLE

bytes32 public constant VAULT_MANAGER_ROLE = keccak256("VAULT_MANAGER_ROLE")

USDC

IERC20 public immutable USDC

State Variables

metaMorphoVault

IERC4626 public metaMorphoVault

principalDeposited

uint256 public principalDeposited

Functions

version

Semantic version of this non-upgradeable adapter.

Version changes accompany adapter behavior changes.

Notes:

• security: Read-only metadata.

• validation: None.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: None.

• access: Public.

• oracle: None.

function version() external pure override returns (string memory);

Returns

constructor

Initializes MetaMorpho adapter dependencies and roles.

Configures governance/manager roles, immutable USDC reference, and validates that the MetaMorpho ERC-4626 vault's asset matches USDC.

Notes:

• security: Validates non-zero dependencies and matching ERC-4626 asset.

• validation: Reverts on zero address or asset mismatch.

• state-changes: Initializes role assignments and adapter dependency pointers.

• events: No events emitted by constructor.

• errors: Reverts with ZeroAddress or InvalidAddress.

• reentrancy: Not applicable - constructor only.

• access: Public constructor.

• oracle: No oracle dependencies.

constructor(address admin, address usdc_, address metaMorphoVault_) ;

Parameters

depositUnderlying

Deposits USDC into the MetaMorpho ERC-4626 vault and tracks principal.

Pulls USDC from caller, deposits into the ERC-4626 vault using a scoped approval, and increases tracked principal by the deposited amount.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount, insufficient deposit capacity, or zero-share outcome.

• state-changes: Increases principalDeposited and updates the ERC-4626 vault position.

• events: Emits downstream transfer/deposit events from dependencies.

• errors: Reverts with InvalidAmount or InsufficientBalance on failed checks.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 sharesReceived);

Parameters

Returns

withdrawUnderlying

Withdraws tracked principal from MetaMorpho and returns USDC to the caller.

Caps the withdrawal to tracked principal, redeems from the ERC-4626 vault, verifies the received amount, decreases tracked principal, then transfers USDC to the caller.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Reverts on zero amount, no tracked principal, insufficient liquidity, or shortfall.

• state-changes: Decreases principalDeposited and updates the ERC-4626 vault position.

• events: Emits downstream transfer/withdrawal events from dependencies.

• errors: Reverts with InvalidAmount or InsufficientBalance on failed checks.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 usdcAmount)
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 usdcWithdrawn);

Parameters

Returns

harvestYieldToVault

Harvests accrued ERC-4626 share yield and transfers it as USDC to the caller (the vault).

Transfers the realized USDC to msg.sender (the vault) so the caller can apply its own distribution policy. Caps to the vault's liquid withdrawable amount and leaves tracked principal unchanged.

Notes:

• security: Restricted to VAULT_MANAGER_ROLE; protected by nonReentrant.

• validation: Returns zero when no yield is available; reverts only on downstream failures.

• state-changes: Leaves principalDeposited unchanged; transfers realized USDC to the caller.

• events: Emits downstream transfer events from dependencies.

• errors: Reverts with InvalidAmount on withdrawal mismatch or downstream failures.

• reentrancy: Protected by nonReentrant.

• access: Restricted to vault manager role.

• oracle: No oracle dependencies.

function harvestYieldToVault()
    external
    override
    onlyRole(VAULT_MANAGER_ROLE)
    nonReentrant
    returns (uint256 realizedYield);

Returns

writeDownPrincipal

Writes down tracked principal to the current ERC-4626 underlying value.

This records an externally observed loss so future withdrawals cannot rely on unavailable principal. It never transfers funds or changes share ownership.

Notes:

• security: Governance-only loss recognition.

• validation: Requires current underlying to be below tracked principal.

• state-changes: Decreases principalDeposited.

• events: PrincipalWrittenDown.

• errors: InvalidCondition when no loss is present.

• reentrancy: Protected by nonReentrant.

• access: GOVERNANCE_ROLE.

• oracle: No oracle dependency.

function writeDownPrincipal() external onlyRole(GOVERNANCE_ROLE) nonReentrant returns (uint256 writtenDown);

Returns

totalUnderlying

Returns the USDC value of MetaMorpho shares plus idle USDC.

Read helper used by QuantillonVault for exposure accounting; delegates to _totalUnderlying.

Notes:

• security: Read-only helper.

• validation: No input validation required.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if the downstream ERC-4626 read fails.

• reentrancy: Not applicable for view function.

• access: Public view.

• oracle: No oracle dependencies.

function totalUnderlying() external view override returns (uint256 underlyingBalance);

Returns

setMetaMorphoVault

Updates the configured MetaMorpho ERC-4626 vault endpoint.

Governance maintenance hook; validates the new vault's asset matches USDC before swapping.

Notes:

• security: Restricted to GOVERNANCE_ROLE.

• validation: Reverts on zero address or asset mismatch with USDC.

• state-changes: Updates metaMorphoVault pointer.

• events: Emits MetaMorphoVaultUpdated.

• errors: Reverts with ZeroAddress or InvalidAddress for invalid input.

• reentrancy: No external calls after state change.

• access: Restricted to governance role.

• oracle: No oracle dependencies.

function setMetaMorphoVault(address newMetaMorphoVault) external onlyRole(GOVERNANCE_ROLE);

Parameters

_totalUnderlying

Returns the USDC-equivalent value of this adapter's MetaMorpho shares.

Converts the adapter's ERC-4626 shares and adds idle USDC, including any rounding buffer.

Notes:

• security: Internal read-only helper.

• validation: No input validation required.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if the downstream ERC-4626 read fails.

• reentrancy: Not applicable for view function.

• access: Internal.

• oracle: No oracle dependencies.

function _totalUnderlying() internal view returns (uint256);

Returns

Events

PrincipalWrittenDown

event PrincipalWrittenDown(uint256 previousPrincipal, uint256 currentPrincipal);

MetaMorphoVaultUpdated

event MetaMorphoVaultUpdated(address indexed oldVault, address indexed newVault);

IMockMorphoVault

Git Source

Functions

depositUnderlying

Deposits underlying assets into the mock Morpho vault.

Test-only vault interface used by the adapter in localhost simulations.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on invalid amount or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit deposit events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function depositUnderlying(uint256 assets, address onBehalfOf) external returns (uint256 shares);

Parameters

Returns

withdrawUnderlying

Withdraws underlying assets from the mock Morpho vault.

Test-only vault interface used by the adapter in localhost simulations.

Notes:

• security: External dependency call; trust model is environment-specific.

• validation: Reverts on insufficient balance or vault-side checks.

• state-changes: Updates vault share/asset accounting.

• events: Vault implementation may emit withdrawal events.

• errors: Reverts on vault-side failures.

• reentrancy: Interface declaration only.

• access: Access control defined by vault implementation.

• oracle: No oracle dependencies.

function withdrawUnderlying(uint256 assets, address to) external returns (uint256 withdrawn);

Parameters

Returns

totalUnderlyingOf

Returns underlying assets held for an account.

Read helper used by the adapter for principal/yield accounting.

Notes:

• security: Read-only helper.

• validation: No input validation required at interface level.

• state-changes: No state changes.

• events: No events emitted.

• errors: May revert if implementation cannot service read.

• reentrancy: Not applicable for view function.

• access: Public view at implementation level.

• oracle: No oracle dependencies.

function totalUnderlyingOf(address account) external view returns (uint256);

Parameters

Returns

MorphoStakingVaultAdapter

Git Source

Inherits: AccessControl, ReentrancyGuard, IExternalStakingVault

Title: MorphoStakingVaultAdapter

Generic external vault adapter for Morpho-like third-party vaults.

Constants

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

VAULT_MANAGER_ROLE

bytes32 public constant VAULT_MANAGER_ROLE = keccak256("VAULT_MANAGER_ROLE")

USDC

IERC20 public immutable USDC

State Variables

morphoVault

IMockMorphoVault public morphoVault

principalDeposited

uint256 public principalDeposited

Functions

constructor

Initializes Morpho adapter dependencies and roles.

Configures governance/operator roles and immutable USDC reference.

Notes:

• security: Validates non-zero dependency addresses.

• validation: Reverts on zero address.

• state-changes: Initializes role assignments and adapter dependency pointers.

• events: No events emitted by constructor.

• errors: Reverts with ZeroAddress on invalid inputs.

• reentrancy: Not applicable - constructor only.

• access: Public constructor.

• oracle: No oracle dependencies.