Docs
Protocol
Contract Design

Contract Design

The SoulPeg protocol consists of a modular smart contract system designed to generate yields while maintaining security and operational flexibility. The architecture separates concerns between token management, yield routing, and strategy implementation.

Architecture Overview

Core Contracts

1. StakeableAssetImpl (sUSDC Token)

Inherits from OpenZeppelin upgradeable components:

  • ERC20Upgradeable: standard token interface with upgradeability
  • ERC20PermitUpgradeable: enables gasless approvals (EIP-2612)
  • Ownable2StepUpgradeable: two-step ownership transfer for security
  • PausableUpgradeable: allows emergency pause of critical functions
  • ReentrancyGuardUpgradeable: prevents nested reentrant calls

2. StrategyRouter

Manages yield generation strategies:

  • Routes USDC deposits to Venus Protocol
  • Handles strategy weights and allocations
  • Controls withdrawals from yield sources
  • Owner-managed strategy configuration

3. VenusUSDCVault

ERC-4626 compliant vault for Venus integration:

  • Deposits USDC into Venus Protocol
  • Manages vUSDC tokens
  • Tracks yield accrual
  • Provides standardized interface for router

Key Features

Token Management (StakeableAssetImpl)

  • Soul-bound logic: Enforced via a custom _update() hook that locks transfers by default.
  • Time-based locks: Implemented using unlockAt mapping per wallet.
  • Manual unlocking: Users must call unlock() to enable transferability.
  • Whitelist control: DEX and pool addresses can be whitelisted via setDex().
  • Reward minting: Admin can issue locked or dummy-locked sUSDC using rewardMint().
  • Emergency functions: Includes pause(), adminUnlock(), sweepUSDC().

Yield Generation (StrategyRouter + VenusUSDCVault)

  • Automated routing: USDC deposits automatically routed to Venus Protocol
  • Yield optimization: Deposits earn lending interest on Venus
  • Strategy management: Owner can adjust weights and add new strategies
  • Transparent yields: Venus APY publicly verifiable on-chain
  • Protocol fee: 7% of Venus yields retained as protocol revenue

Events

All critical actions emit events for external tracking and transparency:

  • Deposited, Unlocked, RewardsDistributed, EarlyRedeemed
  • DexWhitelisted, TreasurySweep, SpecialAddressSet
  • StakedTokensBurned, EmergencyWithdraw

These events facilitate frontend updates, subgraph indexing, and audit logging.

Versioning and Deployment

  • Solidity version: ^0.8.28
  • Deployed on: Binance Smart Chain (BSC)
  • USDC target: BSC USDC uses 18 decimals
  • Upgradeability: StakeableAssetImpl uses transparent proxy pattern for upgradeability
  • Venus Integration: Connects to Venus Protocol's vUSDC market on BSC
  • Multisig recommended: Contract ownership should be transferred to a Gnosis Safe multisig for operational security

Gas and Efficiency

The contract is optimized for gas usage:

  • Batch operations available for minting and deposit (batchDepositAndMint)
  • Single ERC20 balance storage per user
  • Lock information stored in lightweight uint40 timestamps

Yield Flow Architecture

User Deposits USDC
       ↓
StakeableAssetImpl (mints sUSDC)
       ↓
StrategyRouter (routes to strategies)
       ↓
VenusUSDCVault (deposits to Venus)
       ↓
Venus Protocol (generates yield)
       ↓
Protocol retains 7% fee
       ↓
93% of yield distributed to users

Summary

The SoulPeg protocol combines soul-bound token mechanics with automated yield generation through Venus Protocol. This modular design provides users with transparent, sustainable yields while maintaining the security and non-transferability features essential to the protocol's mission. The 7% protocol fee ensures long-term sustainability while users benefit from 93% of generated yields.