Midas Protocol - EVM Smart Contracts

This repository contains EVM smart contracts for the Midas protocol.

Table of Contents

• Prerequisites
• Repository Structure
• Building and Testing
• Architecture Overview
• Core Contracts
• Crosschain Contracts
• Deployed Contract Addresses
• Deployment
• Upgradeability
• Documentation
• Development

Prerequisites

Required Software

• Node.js: >=22
• Yarn: Berry (check the installation guide)

Installation

# Install dependencies
yarn install

Environment Setup

In the root of the repo, create a .env file from .env.example

Repository Structure

midas-contracts/
├── contracts/          # Smart contract source code
│   ├── abstract/       # Abstract base contracts
│   ├── access/         # Access control contracts
│   ├── feeds/          # Price feed contracts
│   ├── interfaces/     # Contract interfaces
│   ├── libraries/      # Contract libraries
│   ├── misc/           # Miscellaneous contracts (LayerZero, Axelar, Custom price feed adapters)
│   ├── products/       # Individual mToken implementations
│   ├── testers/        # Non-production contracts that are used in tests
│   ├── mocks/          # Mocked contracts used in tests and some testnet deployments
│   ├── *.sol           # Core smart contracts
│   └── ...
├── config/             # Configuration files
│   ├── constants/      # Addresses and constants
│   ├── networks/       # Network configurations
│   └── types/          # TypeScript type definitions
├── scripts/            # Deployment and upgrade scripts
│   ├── deploy/         # Deployment scripts
│   └── upgrades/       # Upgrade scripts
├── test/               # Test files
│   ├── unit/           # Unit tests
│   └── integration/    # Integration tests
├── helpers/            # Helper utilities
├── tasks/              # Hardhat tasks
└── docgen/             # Auto-generated documentation

Building and Testing

Build Contracts

# Clean and compile contracts
yarn build

Run Tests

# Run all tests (unit + integration)
yarn test

# Run only unit tests
yarn test:unit

# Run only integration tests
yarn test:integration

Code Coverage

# Generate coverage report
yarn coverage

Coverage reports are generated in the coverage/ directory.

Security Analysis

# Run Slither static analysis
yarn slither

# Get summary report
yarn slither:summary

Note: Install Slither separately. See Slither installation guide.

Architecture Overview

Core Components

1. mTokens: ERC20 tokens (e.g., mTBILL, mBASIS, mBTC)
2. Vaults: Smart contracts managing minting (deposits) and redemption processes
3. Access Control: Role-based permission system for managing protocol operations
4. Price Feeds: Oracle integrations for conversion rates
5. Cross-Chain: LayerZero and Axelar integrations for multi-chain operations

System Flow

Deposit Flow (Minting)

1. User initiates the deposit
2. Vault calculates exchange rate and fees. For exchange rates vault calls data feeds for both payment token and mToken
3. Vault transfers payment tokens from user and redirect those funds to fees/proceeds wallets
4. For instant deposits (sync): mTokens are minted in the same transaction
5. For request deposits (async): Admin approves/rejects the request after off-chain processing

Redemption Flow (Burning)

1. User initiates the redemption
2. Vault calculates exchange rate and fees. For exchange rates vault calls data feeds for both payment token and mToken
3. Vault transfers fees from user to the fee recipient and burns the remaining of mTokens
4. For instant redemptions (sync): Payment tokens are transferred to user immediately
5. For request redemptions (async): Admin fulfills the request after off-chain processing

Core Contracts

MidasAccessControl (contracts/access/MidasAccessControl.sol)

Centralized access control contract managing all roles across the protocol

Key Features:

• Role-based access control
• Greenlist/blacklist management

Key Functions:

• grantRole() - grants role to a specific address. Can be invoked only by role admin
• revokeRole() - revokes role from a specific address. Can be invoked only by role admin

The default role admin for all roles is defaultAdmin. Only exceptions are:

• greenlisted - role admin is greenlistedOperator
• blacklisted - role admin is blacklistedOperator

All roles in the system are documented in ROLES.md. This file is auto-generated and contains:

• Common Roles: Roles shared across all contracts:

  • defaultAdmin: 0x0000000000000000000000000000000000000000000000000000000000000000
  • greenlisted: Allows access to vault operations (if greenlist is enforced)
  • blacklisted: Prevents token transfers and vaults access

• Token-Specific Roles: Roles for each mToken including:

  • minter - Can mint tokens
  • burner - Can burn tokens
  • pauser - Can pause/unpause token transfers
  • customFeedAdmin - Can manage custom price feeds and data feeds
  • depositVaultAdmin - Can manage deposit vault operations
  • redemptionVaultAdmin - Can manage redemption vault operations

mToken (contracts/mToken.sol)

Abstract base contract for all mToken implementations

Key Features:

• Minting and burning functionality (role-protected)
• Pausable transfers (inherited from ERC20PausableUpgradeable)
• Blacklist functionality - blacklisted users cannot send or receive any tokens

Key Functions:

• mint(address to, uint256 amount) - Mint tokens to any address (requires minter role)
• burn(address from, uint256 amount) - Burn tokens from any address (requires burner role)
• pause() / unpause() - Pause/unpause transfers (requires pauser role)

Vaults

There are 2 types of vaults - Deposit vaults and Redemption vaults. Also each type of vault have different variations (like USTB, Swapper, BUIDL etc.)

Common Key Features:

• Fee calculation and collection
• Multiple payment tokens support
• Greenlist/Blacklist
• Chainalysis sanction list integration
• Minimal mToken amount for instant/request operations
• Daily limits for instant operations
• Vault Allowance - limits the total amount of mTokens that a vault can mint or redeem. It is a risk-control mechanism managed by the vault admin and is independent from token supply caps.

Instant vs Request-Based Operations

Both vaults support two execution modes:

Instant (Synchronous):

• Fully on-chain
• Atomic mint/burn + transfer
• Subject to daily limits, liquidity, and minimum amounts

Request-Based (Asynchronous):

• Two-step process
• User submits request on-chain
• Admin approves or rejects after off-chain processing
• Used when instant liquidity is insufficient or instant operations are disabled. Also for fiat operations

DepositVault (contracts/DepositVault.sol)

Manages the minting process for mTokens. Users deposit payment tokens to receive mTokens.

Key Features:

• Instant deposits - minting happens atomically
• Request-based deposits - user pays in one transaction and tokens are minted in a second tx initiated by vault admin
• Supply cap management
• Minimal mTokens amount for first mint transaction

Key Functions:

• depositInstant() - Instant deposit with atomic minting
• depositRequest() - Create deposit request for admin approval
• approveRequest() - Admin approves deposit request
• rejectRequest() - Admin rejects deposit request

Vault Variations:

• USTB (contracts/DepositVaultWithUSTB.sol) - Automatically invests USDC into USTB tokens before transferring proceeds to the recipient.

RedemptionVault (contracts/RedemptionVault.sol)

Manages the redemption process for mTokens. Burns mTokens from a user and transfers payment tokens in exchange

Key Features:

• Instant redemptions - user receive payment tokens atomically
• Request-based redemptions - tokens are burned from user in one transaction and payment tokens are transferred in a second tx initiated by vault admin
• Fiat redemption support
• Separate liquidity source for request-based operations

Key Functions:

• redeemInstant() - Instant redemption with immediate token transfer
• redeemRequest() - Create redemption request
• redeemFiatRequest() - Create fiat redemption request
• approveRequest() - Admin fulfills redemption request
• rejectRequest() - Admin rejects redemption request

Vault Variations:

• Swapper (contracts/RedemptionVaultWithSwapper.sol) - Uses an external liquidity source to exchange one mToken for another and redeems the obtained mTokens through a different Midas redemption vault. This flow is activated only when there is insufficient liquidity in the current Redemption Vault.
• BUIDL (contracts/RedemptionVaultWithBUIDL.sol) (deprecated) - Stores pending liquidity as BUIDL tokens. When the vault has insufficient USDC liquidity to fulfill an instant redemption, BUIDL tokens are redeemed for USDC and used to complete the redemption.
• USTB (contracts/RedemptionVaultWithUSTB.sol) - Stores pending liquidity as USTB tokens. When the vault has insufficient USDC liquidity to fulfill an instant redemption, USTB tokens are redeemed for USDC and used to complete the redemption.

DataFeed (contracts/feeds/DataFeed.sol)

Wraps Chainlink AggregatorV3 price feeds, validates the price (max/min/staleness) and converts answers to 18 decimals format

Key Functions:

• getDataInBase18()- View function, returns the validated and converted price with 18 decimals. Checks price for min/max allowed values, checks that its not stale

DataFeed Variations:

• CompositeDataFeed (contracts/feeds/CompositeDataFeed.sol) - computing the ratio of two underlying data feeds (numerator ÷ denominator)

CustomAggregatorV3CompatibleFeed (contracts/feeds/CustomAggregatorV3CompatibleFeed.sol)

Custom price aggregator compatible with Chainlink's AggregatorV3 interface. Used to publish mToken prices on-chain

Key Functions:

• setRoundData()- function to push the price on-chain
• setRoundDataSafe()- same as setRoundData() but also performs a deviation check by comparing current and new prices
• latestRoundData() - View function, returns latest submitted price with submission details (check AggregatorV3Interface.sol)

CustomAggregatorV3CompatibleFeed Variations:

• CustomAggregatorV3CompatibleFeedGrowth (contracts/feeds/CustomAggregatorV3CompatibleFeedGrowth.sol) - includes a growth parameter that automatically increases the feed price over time

Crosschain Contracts (Axelar, LayerZero)

LayerZero Integration (contracts/misc/layerzero/)

Contracts for LayerZero cross-chain messaging:

• MidasLzMintBurnOFTAdapter.sol - OFT adapter that uses native mint/burn on mTokens
• MidasLzVaultComposerSync.sol - Vault composer for instant-only operations

Axelar Integration (contracts/misc/axelar/)

Contracts for Axelar cross-chain functionality:

• MidasAxelarVaultExecutable.sol - Executable contract for cross-chain operations

Deployed Contract Addresses

All deployed contract addresses are stored in config/constants/addresses.ts.

The addresses are organized by network and token. For example:

main: {
  accessControl: '0x0312A9D1Ff2372DDEdCBB21e4B6389aFc919aC4B',
  timelock: '0xE3EEe3e0D2398799C884a47FC40C029C8e241852',
  mTBILL: {
    token: '0xDD629E5241CbC5919847783e6C96B2De4754e438',
    depositVault: '0x99361435420711723aF805F08187c9E6bF796683',
    redemptionVault: '0xF6e51d24F4793Ac5e71e0502213a9BBE3A6d4517',
    // ...
  },
  // ...
}

Deployment

Please fefer to this deployment README

Upgradability

Most contracts in this repository are designed to be upgradeable. We are using OpenZeppelin's TransparentUpgradeableProxy for proxy deployments

Safety measures:

• We use @openzeppelin/hardhat-upgrades package which automatically checks for storage layout compatibility
• Upgrades are typically executed through a timelock to allow for review before execution

Non-upgradeable contracts:

Some miscellaneous contracts (like adapters and test contracts) are not upgradeable as they don't hold state or manage user funds.

Documentation

All contracts are documented using NatSpec format. Generated documentation is available in docgen/index.md.

To regenerate documentation:

yarn docgen

Development

Code Style

# Check code style
yarn codestyle

# Fix code style issues
yarn codestyle:fix

Linting

# Lint TypeScript files
yarn lint:ts

# Lint Solidity files
yarn lint:sol

# Fix linting issues
yarn lint:ts:fix
yarn lint:sol:fix

Formatting

# Check formatting
yarn format:ts
yarn format:sol

# Fix formatting
yarn format:ts:fix
yarn format:sol:fix