Underscore Developers
Looking for user documentation? Visit the User Documentation to learn about how the protocol works, mechanism design, and conceptual guides (non-technical).
Overview
Underscore Protocol is a comprehensive wallet infrastructure system that provides non-custodial smart contract wallets with integrated DeFi access, automated management capabilities, and sophisticated permission controls. The protocol creates programmable wallet instances that can interact with external DeFi protocols through standardized interfaces while maintaining granular security controls and delegation mechanisms.
Each User Wallet functions as an autonomous financial account capable of yield farming, token swapping, liquidity provision, collateralized borrowing, and rewards claiming across integrated protocols. The system supports delegation through Agents (automated managers with signature-based authentication), Payees (authorized payment recipients with configurable limits), and Cheques (time-locked payment promises), enabling complex financial workflows while preserving user control and security.
Key Features
Smart Contract Wallets
Non-custodial wallet contracts that track assets, calculate USD values, and manage yield profits with automatic price updates and comprehensive event logging.
Lego Partner Integrations
Standardized interfaces to external DeFi protocols enabling yield farming, swapping, lending, and liquidity operations through a unified routing system.
Delegation & Management System
Agents can execute wallet operations via EIP-712 signatures, Payees can receive payments within configured limits, and Cheques enable time-locked payment commitments.
Comprehensive Permission Model
WalletConfig contracts control action permissions per signer, enforce spending limits, manage time-locks, and validate transaction recipients.
Multi-Asset Yield Tracking
Automatic yield profit calculation for both rebasing and non-rebasing assets with price-per-share monitoring and fee distribution to protocol rewards.
Modular Security Architecture
Time-locked configuration changes, emergency pause controls, ejection modes for asset recovery, and multi-tier governance with protocol-wide coordination.
Cross-Protocol Operations
Multi-hop token swaps, concentrated liquidity management, collateral deposits/withdrawals, debt borrowing/repayment, and reward claiming across integrated protocols.
Protocol Components
The protocol consists of several interconnected systems:
Core Infrastructure: User wallets, configuration management, data storage, and billing systems
Lego Partners: Standardized integrations with external DeFi protocols for yield and trading
Registry System: Coordinated management of protocol components, templates, and permissions
Configuration Layer: Time-locked parameter management with governance oversight
Agent System: Automated management services with configurable strategies and risk controls
Wallet Backpack: Infrastructure services for transaction processing and system maintenance
Core Infrastructure
Essential protocol functionality for user wallets and system operations.
Intelligent wallet instance providing automated yield optimization and DeFi access with per-user configuration
Configuration management for individual wallets including risk parameters and strategy settings
Multi-oracle price aggregation system providing reliable asset valuations with staleness protection
Pull payment engine that enables authorized payees and cheque recipients to withdraw funds directly from a UserWallet, with logic to unwind yield positions if necessary
User wallet factory with trial fund management and creation limit enforcement
Rewards distribution system managing loot claiming, deposit points, and user incentives
Data & Configuration
Protocol state management and configuration systems.
Central data storage managing user positions, vault tokens, and protocol metrics with indexed access
Configuration hub storing operational parameters, security settings, and protocol defaults
Configuration management for user wallets, assets, agents, and security with time-locked changes
Operational management for fund recovery, loot adjustment, and maintenance functions
Vaults
Protocol-managed vault system for yield optimization and leveraged strategies.
ERC-4626 compliant yield aggregation vault for passive yield optimization across multiple protocols
Internal wallet module for EarnVault handling yield position management and lego interactions
ERC-4626 compliant leveraged yield vault enabling amplified returns through collateralized borrowing
Internal wallet module for LevgVault handling debt positions, collateral, and leverage operations
Utility contract providing leverage calculations, health factor monitoring, and position safety checks
Reusable ERC-20 token module for vault share tokens with mint/burn functionality
Central registry for all Underscore vaults tracking vault types, underlying assets, and approval status
Lego Partners
Modular integrations with external DeFi protocols for yield generation and trading.
Lego Interfaces
All legos implement standardized interfaces for consistent behavior across protocols:
Standard interface for yield protocol integrations (deposits, withdrawals, rewards)
Standard interface for DEX integrations (swaps, liquidity, quotes)
Special Legos
Universal routing engine providing unified access to all Lego Partners with optimal path discovery
Integration with Ripe Protocol for yield farming, collateralized borrowing, PSM swaps, and RIPE rewards
Integration with Underscore's own EarnVault system for depositing into managed yield strategies
Integrated Protocols
Yield Protocols: Aave V3, Compound V3, Euler, Fluid, Moonwell, Morpho, ExtraFi, Sky PSM, Wasabi, 40 Acres, Avantis
DEX Protocols: Uniswap V2, Uniswap V3, Aerodrome Classic, Aerodrome Slipstream, Curve
See Yield Lego Interface and DEX Lego Interface for the common functions all legos implement.
Lego Data Management
Data management for yield protocol integrations with bidirectional vault token mappings
Minimal data module for DEX integrations that serves as a foundational module for DEX Legos that provide routing support
Registries
Central coordination points for protocol components and authoritative records.
Master protocol registry and governance hub coordinating all system components
Registry of approved Lego Partner contracts with validation and integration management
Time-locked configuration registry managing protocol parameters and access control
Infrastructure component registry for wallet support services and system utilities
Agent System
Automated management services with configurable strategies.
Automated portfolio management agent providing strategy execution and risk management for user wallets
Wallet Backpack Infrastructure
Modular components that provide specialized functionality for UserWallet operations.
Whitelist management module that handles the time-locked addition, confirmation, and removal of whitelisted addresses for a UserWallet
Manager administration module that allows the wallet owner to add, update, and remove managers and configure their specific permissions and spending limits
Cheque creation and management module that allows the wallet owner or authorized managers to create, cancel, and configure time-locked payment promises (cheques)
Payee administration module that allows the wallet owner to add, update, and remove authorized payment recipients (payees) and configure their specific spending limits
Stateless validation engine that enforces all permission and limit rules for managers, payees, and cheques with no stored state
User wallet migration module that facilitates the secure transfer of all funds and configurations from one UserWallet to another
Common Modules
Shared functionality used across multiple contracts.
Centralized address resolution providing validated protocol component addresses
Flexible registry for managing dynamic address mappings with time-lock controls
Base functionality for protocol departments including pause controls and access management
Enhanced ERC20 implementation with advanced features and protocol integration
Two-tier governance system enabling both protocol-wide and contract-specific administration
Ownership management module with transfer controls and access validation
Time-delay mechanism for critical configuration changes with expiration windows
Getting Started
New Users: Start with UserWallet.vy to understand wallet functionality
Developers: Review UndyHq.vy for protocol architecture overview
Integrators: Explore LegoTools.vy for protocol integration patterns
Operators: Check SwitchboardAlpha.vy for configuration management
Architecture Principles
Modular Design: Reusable modules reduce complexity and enable rapid feature development
Department Pattern: Logical separation of concerns with specialized contract roles
Registry Coordination: Central registries maintain authoritative records and component relationships
Time-Locked Governance: Critical changes require delays and multi-signature approval
Multi-Oracle Resilience: Diverse price sources prevent single points of failure
User-Centric Security: Non-custodial design with user-controlled risk parameters and emergency controls
Protocol Flow
The protocol creates a unified interface for DeFi interactions while maintaining the flexibility and composability that makes decentralized finance powerful. Users benefit from automated optimization without sacrificing control, while developers can easily integrate new protocols and strategies through the standardized Lego Partner interface.
Last updated