@prime-vaults/contract

v0.4.2

Published

a month ago

<p align="center"> <img src="https://img.shields.io/badge/Solidity-0.8.30-363636?logo=solidity&logoColor=white" alt="Solidity"> <img src="https://img.shields.io/badge/Hardhat-2.x-yellow?logo=ethereum&logoColor=white" alt="Hardhat"> <img src="https:/

0High
0Medium
0Low

michaelthebra

blockchain ethers ethereum hardhat smart-contracts solidity template typescript viem

📖 Overview

Prime Vaults is a sophisticated DeFi infrastructure built on the BoringVault architecture that enables users to:

🔒 Deposit assets and receive ERC20 vault shares
💰 Earn passive income through automated DeFi strategies
🌐 Cross-chain execution via bridge integrations (Stargate, LiFi)
🎁 Multi-token rewards with automatic distribution

🏗 Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                          PRIME VAULTS ECOSYSTEM                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   👤 USER (Any Chain)                                                       │
│      │                                                                      │
│      ▼                                                                      │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │                     🌉 PRIMEEXECUTOR (Bridge Layer)                  │  │
│   │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐       │  │
│   │  │    Stargate     │  │      LiFi       │  │   LayerZero     │       │  │
│   │  │    Bridge       │  │     Bridge      │  │   Messaging     │       │  │
│   │  └─────────────────┘  └─────────────────┘  └─────────────────┘       │  │
│   └──────────────────────────────────────────────────────────────────────┘  │
│             │                                                               │
│             ▼         Cross-chain transfer to Native Chain                  │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │                    📱 SMART ACCOUNT (User Wallet)                    │  │
│   └──────────────────────────────────────────────────────────────────────┘  │
│             │                                                               │
│             ▼                                                               │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │                      🏦 PRIMEVAULT (Core Vault)                      │  │
│   │  ┌─────────────┐   ┌──────────────┐   ┌──────────────┐               │  │
│   │  │BoringVault  │◄──┤ Accountant   │◄──┤   Teller     │◄── Deposit    │  │
│   │  │(ERC20 Vault)│   │(Rates & Fees)│   │ (Gateway)    │               │  │
│   │  └──────┬──────┘   └──────────────┘   └──────────────┘               │  │
│   │         │                                                            │  │
│   │  ┌──────▼──────┐   ┌──────────────┐   ┌──────────────┐               │  │
│   │  │  Manager    │   │DelayedWithdraw│   │ Distributor  │── Rewards    │  │
│   │  │ (Merkle)    │   │ (Time-lock)  │   │  (Multi-tok) │               │  │
│   │  └──────┬──────┘   └──────────────┘   └──────────────┘               │  │
│   └─────────┼────────────────────────────────────────────────────────────┘  │
│             │                                                               │
│             ▼                                                               │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │                      ⚡ PRIMESTRATEGY (Yield)                         │  │
│   │         Deploy vault assets to DeFi protocols for yield              │  │
│   └──────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│   ┌──────────────────────────────────────────────────────────────────────┐  │
│   │                🔐 ACCESS CONTROL (PrimeRBAC)                         │  │
│   │     OWNER_ROLE  │  PROTOCOL_ADMIN_ROLE  │  OPERATOR_ROLE             │  │
│   └──────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

🏦 PrimeVault (Core)

The core vault system manages asset custody, share issuance, and yield generation.

Components

| Component | Description | Key Features | | ------------------- | ------------------------------------- | ---------------------------------------------------- | | BoringVault | Minimal ERC20 vault (~100 lines) | Asset custody, share minting/burning, DeFi execution | | Accountant | Exchange rate & fee manager | Time-based fee accrual, rate calculations | | Teller | User gateway for deposits/withdrawals | Slippage protection, deposit caps | | DelayedWithdraw | Time-locked withdrawal security | 3-day delay, expedited option with fee | | Distributor | Multi-token reward distribution | Automatic accrual, compounding support | | Manager | Merkle-verified strategy executor | Whitelist all DeFi operations |

Key Formulas

📊 Exchange Rate:
   shareValue = (totalAssets - feesOwed) / totalShares

💰 Platform Fee (Annual):
   fees = (shares × rate × platformFee × timeDelta) / (10000 × 365 days)

🎁 Rewards per Token:
   rewardPerToken = stored + ((now - lastUpdate) × rate × 1e27) / totalSupply

User Flows

1. User approves Teller to spend tokens
2. User calls deposit(amount, minimumShares)
3. Accountant updates exchange rate
4. Teller calculates shares = amount / rate
5. Vault mints shares (locked for 1 day)
6. User starts earning rewards automatically

1. User calls requestWithdraw(shares)
2. Shares transferred to DelayedWithdraw contract
3. Request locked for 3 days (or pay 2% for 1-day)
4. After maturity, user calls completeWithdraw()
5. Vault burns shares and transfers assets

⚡ PrimeStrategy

Strategy execution module for deploying vault assets across DeFi protocols (Aave, Compound, Uniswap, Curve, etc.). Supports both single-asset and pair-asset allocations with Merkle-verified operations.

🌉 PrimeExecutor

Cross-chain bridge executor for moving assets between supported chains. Integrates with Stargate (LayerZero) and LiFi aggregator for optimal routing and execution.

📍 Deployments

Mainnet Contracts

pUSD Vault

| Contract | Address | | --------------- | -------------------------------------------- | | BoringVault | 0x8596cD23aa747Fd867235D422F3C4896A5A6Bb24 | | Accountant | 0xa2d2085504c3e7C83e8E37b33Df50709c00f2bBB | | Teller | 0xC59b0CE194Bf8b202f21C03F6F9F394eEf10d1CF | | Distributor | 0x5429F08D515f65681418145A367046712D4adDa2 | | DelayedWithdraw | 0xFE609D66BC15b409b8F657cA0F78c95031C7D26c | | Manager | 0x1E526f3255458Dd0a38D1F018eda7518A4A6a8E2 |

pBTC Vault

| Contract | Address | | --------------- | -------------------------------------------- | | BoringVault | 0x5a4C11645E58E732092494db0dBb57B0646CDa1d | | Accountant | 0xd7300E0C572AEd4251dED65C70c74d2c7732197A | | Teller | 0x87E842c626a4c14C60B2acE6293400a4000Df4be | | Distributor | 0xbf84E1cBc598952536F62Da3F6F39dF786C95bef | | DelayedWithdraw | 0x540E06c68366aA3f79D700b7d82c69cEabDB9990 | | Manager | 0xb47197d81604f3058BdDd993372a14a36183a11f |

Shared Infrastructure

| Contract | Address | | ------------------- | -------------------------------------------- | | PrimeRBAC | 0xe4d53b98e09FdAb10aFaB99393AD0ffbe37dD446 | | PrimeTimelock | 0x8C256f131D86b7301106F943221f749157B1FeF3 | | PrimeExecutor | 0xf9e8D18003590E06334E8C70cE6dD0B480462ec5 | | DecoderAndSanitizer | 0x7178182Fd96148B4E72b2b1e93292b0A493A7fB4 | | PrimeStrategist | 0xcfDB218585d77BeD370781D9C5eF40CeFa634427 |

| Contract | Address | | ------------- | -------------------------------------------- | | PrimeExecutor | 0xb2f865041e3F7De4576FB5B30ac8e9fbDA82e29d |

🔐 Security

Security Features

| Feature | Description | | -------------------------- | -------------------------------------------------- | | 🔒 Share Locks | 1-day lock on deposits prevents flash loan attacks | | ⏱️ Withdrawal Delays | 3-day delay allows emergency response | | 🌳 Merkle Verification | All DeFi operations must be pre-approved | | ⏸️ Pause Mechanism | Emergency pause for all critical contracts | | 🛡️ Reentrancy Guards | Protection against callback exploits | | 📊 Supply Invariants | Prevents share dilution attacks |

Audits

| Auditor | Date | Report | | ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | Salus Security | December 2025 | View Report | | Shieldify | December 2025 | View Report |

🚀 Getting Started

Prerequisites

Node.js >= 18.16.0
pnpm

Installation

# Clone repository
git clone https://github.com/prime-vaults/prime-vaults-contract.git
cd prime-vaults-contract

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env

Commands

# Compile contracts
pnpm compile

# Run tests
pnpm test

# Deploy
pnpm hardhat ignition deploy --network <network>

# Check contract sizes
pnpm contract-size

# Lint
pnpm lint:sol
pnpm lint:ts

Networks

# Testnets
pnpm hardhat ignition deploy --network bepolia
pnpm hardhat ignition deploy --network sepolia
pnpm hardhat ignition deploy --network bscTestnet
pnpm hardhat ignition deploy --network arbitrumSepolia

# Mainnets
pnpm hardhat ignition deploy --network berachain
pnpm hardhat ignition deploy --network mainnet
pnpm hardhat ignition deploy --network bsc
pnpm hardhat ignition deploy --network arbitrum
pnpm hardhat ignition deploy --network coreDao

📁 Project Structure

contracts/
├── 🏦 core/                    # Core vault components
│   ├── BoringVault.sol         # ERC20 vault & asset custody
│   ├── AccountantProviders.sol # Exchange rates & fees
│   ├── Teller.sol              # Deposit/withdraw gateway
│   ├── DelayedWithdraw.sol     # Time-locked withdrawals
│   ├── Distributor.sol         # Multi-token rewards
│   └── ManagerWithMerkle...    # Strategy execution
│
├── ⚡ strategy/                 # Strategy management
│   ├── PrimeStrategy.sol       # Strategy orchestration
│   └── ...
│
├── 🌉 executor/                 # Cross-chain bridges
│   ├── BaseBridgeExecutor.sol  # Shared bridge logic
│   ├── StargateBridgeExec...   # Stargate integration
│   └── LiFiBridgeExecutor.sol  # LiFi integration
│
├── 🔐 auth/                     # Access control
│   ├── PrimeRBAC.sol           # Role-based permissions
│   ├── PrimeAuth.sol           # Contract authentication
│   └── RolesAuthority.sol      # Solmate roles
│
├── 🔍 decodersAndSanitizers/    # Transaction validation
│   └── ...
│
└── 📚 interfaces/               # Contract interfaces
    └── ...

📚 Documentation

| Document | Description | | -------------------------------------- | ------------------------- | | Architecture | Detailed system design | | Security | Security best practices | | Timelock | Governance timelock setup | | Cross-chain | Bridge integration guide | | Audit Report | Security audit findings |

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

MIT License - see LICENSE for details.