# Smart Contract Architecture

### Smart Contract Topography

<figure><img src="https://1075741769-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6yeOl0TElnVRI1K1E8Bo%2Fuploads%2Fw3oLoHJQ2MceXzuQYDJU%2FDeFi%20Jamming%20-%20Frame%2018.jpg?alt=media&#x26;token=e7ee75f5-54c2-47ae-a943-47c532552632" alt=""><figcaption></figcaption></figure>

### 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.
