Generic Protocol

A fully collateralized, omnichain stablecoin protocol built on Ethereum with multi-asset vault infrastructure implementing the ERC7575 standard.

Overview

Generic Protocol introduces GUSD (Generic USD), a stablecoin backed by multiple isolated vaults holding USDC and USDT. The protocol enforces hard caps, deterministic mint/redeem bands, and circuit breakers while harvesting yield from whitelisted Layer 1 strategies. All yield is rebated by minting additional GUSD and bridging it proportionally across chains, maintaining canonical supply discipline.

Key Features

• ERC7575 Multi-Asset Vaults: Implements the latest ERC7575 standard for advanced vault operations
• Omnichain Architecture: Canonical supply on Ethereum L1 with cross-chain bridging via periphery contracts and the generic-bridging repository
• Whitelabeled Unit System: GenericUSD wraps GenericUnit tokens providing flexible token branding
• Isolated Collateral Vaults: Separate ERC4626 vaults for USDC and USDT with hard caps
• Yield Generation: Integration with whitelisted L1 strategies (Morpho, Aave, Sky Protocol)
• Automatic Decimal Normalization: All assets normalized to 18 decimals for consistent calculations
• Circuit Breakers: Built-in safety mechanisms and emergency pause functionality
• Modular Controller: Highly modular controller architecture with specialized manager contracts
• Periphery Integrations: Built-in support for cross-chain deposits and DEX swapper integrations

Architecture

Core Components

┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   GenericVault  │    │   Controller    │    │   GenericUnit    │    │   GenericUSD     │
│   (USDC/USDT)   │    │                 │    │    (Unit Token)  │    │     (GUSD)       │
│                 │◄──►│ • Price Feeds   │◄──►│                  │◄──►│                  │
│ • ERC4626       │    │ • Vault Mgmt    │    │ • ERC20Mintable  │    │ • Whitelabeled   │
│ • Strategy      │    │ • Rebalancing   │    │ • Share Logic    │    │   Wrapper        │
│ • Caps & Limits │    │ • Yield Dist.   │    │ • Mint/Burn      │    │ • Wrap/Unwrap    │
│                 │    │ • Emergency     │    │ • Vault Queries  │    │                  │
└─────────────────┘    └─────────────────┘    └──────────────────┘    └──────────────────┘

Module Structure

• src/vault/: Vault primitives (ControlledERC7575Vault, SingleStrategyVault, GenericVault)
• src/unit/: Unit token logic with ERC-4626 supply accounting (GenericUnit.sol, GenericUnitL2.sol) and whitelabeled implementations
• src/controller/: Central controller with modular managers for different protocol aspects
• src/interfaces/: Protocol-wide interfaces (IController, IERC7575Vault, IERC7575Share, IBridgeCoordinatorL1Outbound)
• src/utils/: Helper utilities for cross-asset math and decimal handling (tryGetAssetDecimals.sol)
• src/periphery/: Cross-chain bridge interfaces, depositors, and swapper integrations

Getting Started

Prerequisites

• Foundry

Installation

1. Clone the repository:

git clone https://github.com/MetaFi-Labs/generic-protocol.git
cd generic-protocol

2. Initialize submodules:

git submodule update --init --recursive

3. Install dependencies:

forge install

4. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

Build

The project uses Solidity 0.8.29 with Prague EVM and optimized for 10,000 runs:

forge build

Testing

Run the full test suite:

forge test

Run with gas reporting:

forge test --gas-report

Run with fork testing (requires ETH_RPC_URL):

forge test --fork-url $ETH_RPC_URL

Deploy the contracts:

source .env
forge script script/Deploy.s.sol:Deploy --via-ir --fork-url "$ETH_RPC_URL" --broadcast --verify

Generate coverage report:

forge coverage

Protocol Design

Invariants

The protocol maintains these core invariants:

• Redemption Integrity: Every GUSD is fully backed; redemptions always pay current redemption value (≤ $1)
• No Over-Par Issuance: Deposits valued at min(oracle_price, $1.00) ensuring no inflation
• Bounded Exposure: Vault hard caps limit blast radius of single collateral failure
• Canonical Supply: All minting/burning occurs on Ethereum L1; L2s hold mirrored balances only

Vault System

Each collateral type (USDC, USDT) has:

• Isolated Vault: Separate ERC4626 vault with independent risk profile
• Hard Caps: Maximum exposure limits as percentage of total collateral
• Strategy Integration: Whitelisted yield strategies on Ethereum mainnet
• Decimal Normalization: All amounts converted to 18-decimal precision

Controller Architecture

The Controller contract uses a modular design with specialized managers and logic contracts:

Core Logic Contracts:

• AccountingLogic: Core accounting and mathematical operations for vault interactions
• VaultLimitsLogic: Vault capacity management and hard cap enforcement
• BaseController: Foundation contract providing shared state and access control

Specialized Managers:

• VaultManager: Vault registration and lifecycle management
• PriceFeedManager: Oracle integration and price validation
• RebalancingManager: Cross-vault asset rebalancing with slippage protection
• YieldManager: Yield harvesting and distribution coordination
• EmergencyManager: Circuit breakers and pause functionality
• ConfigManager: Protocol parameters and fee management
• PeripheryManager: Integration with swappers and yield distributors
• RewardsManager: Rewards distribution and management

Cross-Chain Bridging

The protocol's omnichain functionality is handled by a separate bridging infrastructure:

• Generic Bridging Repository: MetaFi-Labs/generic-bridging manages cross-chain token transfers
• Canonical Supply Model: All GUSD minting and burning occurs on Ethereum L1, with L2s holding mirrored balances
• Multi-Protocol Support: The bridging system supports multiple bridge protocols and can be configured for different destination chains
• Yield Distribution: Cross-chain yield distribution is coordinated through the bridging system to maintain pro-rata allocation

Testing Strategy

Test Categories

• Unit Tests: Individual contract functionality (tests/unit/)
• Integration Tests: Cross-contract interactions (tests/integration/)
• Invariant Tests: Property-based testing (tests/invariant/)
• Fork Tests: Mainnet state testing (tests/fork/)

Key Test Areas

• Decimal edge cases and precision handling
• Circuit breaker activation scenarios
• Mint/redeem price band validation
• Multi-asset vault interactions
• Emergency pause semantics

Documentation

• Whitepaper: specs/whitepaper-v1.0.md
• Contract Specifications: specs/contracts/

License

This project is licensed under the Business Source License 1.1 (BUSL-1.1).

Links

• Repository: github.com/MetaFi-Labs/generic-protocol
• Bridging Infrastructure: github.com/MetaFi-Labs/generic-bridging
• Documentation: docs.generic.money (coming soon)
• Website: generic.money (coming soon)

---

Built with ❤️ by the MetaFi Labs team