Smart Contract Architecture

Smart Contract Topography

Core Contracts

NodeRegistry

The central registry and governance contract for the protocol. It:

• Maintains whitelist of protocol participants (factories, routers, quoters, rebalancers)

• Store a list of valid Nodes

• Stores protocol-wide parameters and fee settings

• Controls deployment permissions through role-based access

• Acts as the source of truth for valid protocol components

NodeFactory

A factory pattern contract that standardizes and controls Node deployment. It:

• Creates new Node instances with standardized initialization

• Deploys associated Escrow contracts

• Registers new Nodes with the NodeRegistry

• Ensures proper initialization of Node parameters and permissions

Escrow

A simple but critical security contract that:

• Holds assets during the withdrawal process

• Provides secure asset custody during async operations

• Grants specific permissions to its associated Node

• Prevents direct manipulation of held assets

Extensible Contract Classes

Nodes

Nodes are the core investment vehicle contracts that can be implemented for different investment strategies and mechanics.

Current Implementation - Node.sol:

• Implements an MMF (Money Market Fund) style investment vehicle using swing pricing

• Manages reserve ratios and component allocations

• Handles deposits and redemptions with dynamic pricing

• Coordinates with Routers for component interactions

• Processes management and execution fees

• Controls rebalancing windows and cooldowns

Future Node implementations could support:

• Different pricing mechanisms

• Various investment strategies

• Alternative asset management approaches

• Specialized financial instruments

Routers

Routers are specialized contracts that handle interactions with specific asset types or protocols. They abstract away the complexity of different asset interfaces.

Current Implementations:

1. ERC4626Router

   • Handles standard yield-bearing vault interactions

   • Manages deposits and withdrawals

   • Tracks component assets

2. ERC7540Router

   • Manages async vault interactions

   • Handles request/claim patterns

   • Coordinates multi-step operations

Future Router implementations could support:

• DEX integrations

• Lending protocol interactions

• Complex derivative positions

• Cross-chain assets

• Other specialized protocols

Quoters

Quoters are contracts that calculate pricing and execution parameters. They can be implemented for different pricing strategies.

Current Implementation - QuoterV1:

• Implements swing pricing calculations

• Computes deposit bonuses and withdrawal penalties

• Manages reserve ratio impacts

• Uses exponential scaling for price adjustments

Future Quoter implementations could support:

• Alternative pricing models

• Reading oracle data onchain

• Interacting with offchain data sources such as ZKVMs

Libraries

BaseRouter

A foundational library that:

• Provides common Router functionality

• Implements standard security checks

• Manages component whitelisting

• Handles fee calculations

BaseQuoter

A foundational library that:

• Provides common Quoter functionality

• Implements access controls

• Manages Node validation

• Standardizes interface requirements

Other Libraries

• ErrorsLib: Standardized error handling

• EventsLib: Standardized event emissions

• MathLib: Safe mathematical operations

Protocol Extensibility

The protocol is designed for extensibility through:

1. Modular Architecture: Clear separation of concerns between contracts

2. Abstract Base Contracts: Common functionality in base contracts

3. Standardized Interfaces: Clear interface definitions for new implementations

4. Registry Pattern: Centralized control and validation

This architecture allows for:

• New asset type support through additional Routers

• Different investment strategies through new Node implementations

• Alternative pricing mechanisms through new Quoters

• Protocol evolution without core contract modifications

The current implementation focuses on MMF-style functionality with swing pricing, but the architecture supports expansion into various other financial instruments and strategies while maintaining security and standardization.