Agent L3 Component Breakdown

Component Hierarchy & Responsibilities

---

1. Smart Contract Components

1.1 AgentRegistry.sol

Purpose: Central registry for all agents on the platform

Key Functions:

// Registration
registerAgent() - Create new agent entry
updateAgentMetadata() - Update agent info
setAgentWallet() - Set/change agent wallet

// Query
getAgent() - Get agent by ID
getAllAgents() - List all agents
getAgentsByIntegration() - Filter by integration
getAgentCount() - Total registered agents

// Management
addIntegration() - Add integration to agent
removeIntegration() - Remove integration
setActiveStatus() - Enable/disable agent

Storage:

• agents[] - Array of Agent structs
• agentByWallet - Mapping wallet to agent ID
• agentsByIntegration - Index by integration
• integrationRegistry - Available integrations

Events:

• AgentRegistered(address indexed creator, uint256 indexed agentId)
• AgentUpdated(uint256 indexed agentId)
• IntegrationAdded(uint256 indexed agentId, string integration)

---

1.2 AgentDeposit.sol (Extended)

Purpose: Manage liquidity provision and ownership

Current Functions (from existing):

• Deposit funds
• Basic fee distribution

New Functions to Add:

// Liquidity
provideLiquidity(agentId, amount) - Provide liquidity, mint tokens
withdrawLiquidity(agentId, tokens) - Withdraw, burn tokens
getOwnershipPercent(agentId, owner) - Calculate ownership %

// Ownership Tokens (ERC-20 per agent)
mintOwnershipTokens(agentId, to, amount)
burnOwnershipTokens(agentId, from, amount)
transferOwnershipTokens(agentId, from, to, amount)

// Fee/Yield Accounting
recordFee(agentId, amount) - Record fee received
recordYield(agentId, amount) - Record yield generated
calculateOwnerRewards(agentId, owner) - Calculate pending rewards

// Distribution
distributeToOwners(agentId) - Distribute fees/yield to owners
claimOwnerRewards(agentId) - Claim rewards

Storage:

• ownershipTokens[agentId] - ERC-20 token address per agent
• ownership[agentId][owner] - Ownership struct per user
• pendingRewards[agentId][owner] - Unclaimed rewards
• totalLiquidity[agentId] - Total ETH locked

---

1.3 FeeDistributor.sol

Purpose: Handle fee distribution logic

Key Functions:

// Distribution
distributeFees(agentId, totalFees) - Split and distribute fees
distributeYield(agentId, totalYield) - Split and distribute yield

// Configuration
setDistributionRatio(ownerShare, stakerShare) - Set split ratio
setDistributionFrequency(frequency) - Batch vs real-time

// Query
getPendingDistribution(agentId) - Check pending amounts
getDistributionHistory(agentId) - Historical distributions

Distribution Logic:

• Receive fees/yield from agents
• Split based on configured ratio (e.g., 60/40)
• Send to AgentDeposit for owner distribution
• Send to CR8Staking for staker rewards

Storage:

• distributionRatio - Owner/staker split (e.g., 60/40)
• distributionHistory[agentId][] - Historical records
• pendingDistributions[agentId] - Pending amounts

---

1.4 IntegrationRegistry.sol

Purpose: Manage available integrations

Key Functions:

// Integration Management
registerIntegration(id, name, category, implementation)
updateIntegration(id, ...)
approveIntegration(id) - Admin approval
disableIntegration(id)

// Agent Integration
attachIntegration(agentId, integrationId, config)
detachIntegration(agentId, integrationId)
getAgentIntegrations(agentId) - List agent's integrations

// Execution (Future)
executeIntegration(agentId, integrationId, action, params)

Storage:

• integrations[id] - Integration metadata
• agentIntegrations[agentId][] - Agent's integration list
• integrationConfigs[agentId][integrationId] - Per-agent configs

---

2. Frontend Components

2.1 Page Components

Agent Registry Page (/)

Components Used:

• AgentStats - Network statistics
• AgentRegistry - Agent listing
• CR8TokenBalance - Header balance

Features:

• Search and filter agents
• Sort by various metrics
• Display agent cards
• Navigate to agent details

Agent Detail Page (/agents/[id])

Components Used:

• AgentDetail - Main agent info
• OwnershipChart - Ownership visualization
• LiquidityModal - Provide liquidity
• CR8TokenBalance - Header balance

Features:

• View agent information
• See ownership distribution
• Provide/withdraw liquidity
• Claim rewards
• View performance metrics

Agent Registration Page (/agents/register)

Components Used:

• AgentRegistration - Multi-step form

Features:

• Step 1: Basic information
• Step 2: Select integrations
• Step 3: Review and confirm
• Submit registration transaction

Portfolio Page (/portfolio)

Components Used:

• Portfolio - User holdings overview

Features:

• CR8 token balance
• Staked CR8 amount
• Pending rewards
• Agent holdings list
• Quick actions

Staking Page (/staking)

Components Used:

• CR8Staking - Staking interface

Features:

• View staking stats
• Stake/unstake CR8
• Claim rewards
• View pending rewards

---

2.2 Core UI Components

AgentStats

Purpose: Display network-wide statistics

Data:

• Total agents count
• Total CR8 supply
• Total staked CR8
• Total rewards distributed

Updates: Real-time via contract reads

AgentRegistry

Purpose: List and search agents

Features:

• Search functionality
• Filter by integration
• Sort options
• Pagination (future)

State Management:

• Search query
• Sort parameter
• Filter criteria

AgentDetail

Purpose: Display agent information

Sections:

• Agent header (name, description, status)
• Statistics (liquidity, fees, yield)
• User holdings (if connected)
• Ownership chart
• Action buttons

AgentRegistration

Purpose: Multi-step registration form

Steps:

1. Basic Info (name, description, fee rate)
2. Integrations (select from marketplace)
3. Review & Confirm

State:

• Form data
• Current step
• Validation errors
• Transaction status

CR8Staking

Purpose: Staking interface

Features:

• View current stake
• View pending rewards
• Stake tokens
• Unstake tokens
• Claim rewards

Tabs:

• Stake
• Unstake

Portfolio

Purpose: User's complete holdings

Sections:

• CR8 token overview
• Staking summary
• Agent holdings
• Quick links

LiquidityModal

Purpose: Provide liquidity to agents

Features:

• Amount input
• Ownership preview
• Transaction handling
• Success/error states

OwnershipChart

Purpose: Visualize ownership distribution

Display:

• Top owners list
• Percentage bars
• Total liquidity
• Owner count

---

3. Integration Components

3.1 Integration System Architecture

Integration Layer:
├── IntegrationRegistry (Smart Contract)
├── Integration Manager (Frontend)
│   ├── Integration Marketplace
│   ├── Integration Selector
│   └── Integration Configurator
└── Integration Executors
    ├── DeFi Executor
    ├── AI Executor
    ├── NFT Executor
    └── Oracle Executor

3.2 Integration Components

IntegrationMarketplace

Purpose: Browse available integrations

Features:

• List all integrations
• Filter by category
• Integration details
• Enable/disable for agent

IntegrationSelector

Purpose: Select integrations during registration

Features:

• Checkbox selection
• Category grouping
• Description preview
• Icon display

IntegrationConfigurator

Purpose: Configure integration settings

Features:

• API key input (encrypted)
• Parameter configuration
• Test connection
• Save settings

---

4. State Management

4.1 React Query (TanStack Query)

Queries:

• Agent data
• User balance
• Staking info
• Ownership data
• Pending rewards

Mutations:

• Register agent
• Provide liquidity
• Stake/unstake
• Claim rewards

4.2 Wagmi Hooks

Contract Reads:

• useReadContract - Read agent data, balances, etc.
• useAccount - User wallet info

Contract Writes:

• useWriteContract - Transaction writes
• useWaitForTransactionReceipt - Transaction status

---

5. Data Flow

5.1 Agent Registration Flow

User Input → AgentRegistration Component
    ↓
Form Validation
    ↓
writeContract(AgentRegistry.registerAgent)
    ↓
Transaction Pending
    ↓
Transaction Confirmed
    ↓
Refetch Agent List
    ↓
Show Success → Navigate to Agent Detail

5.2 Liquidity Provision Flow

User Clicks "Provide Liquidity"
    ↓
LiquidityModal Opens
    ↓
User Enters Amount
    ↓
Preview Ownership %
    ↓
Approve Contract (if needed)
    ↓
writeContract(AgentDeposit.provideLiquidity)
    ↓
Transaction Confirmed
    ↓
Update Ownership Chart
    ↓
Update User Portfolio

5.3 Fee Distribution Flow

Agent Receives Fee (External)
    ↓
Fee Transfered to AgentDeposit Contract
    ↓
FeeDistributor.distributeFees Called
    ↓
Split Calculation (60/40)
    ↓
Distribute to Owners (AgentDeposit)
    ↓
Distribute to Stakers (CR8Staking)
    ↓
Update Pending Rewards
    ↓
Users See Updated Rewards in UI

---

6. Component Dependencies

6.1 Component Tree

App
├── Layout
│   ├── Header
│   │   ├── CR8TokenBalance
│   │   └── ConnectButton
│   └── Navigation
├── Page Components
│   ├── AgentRegistry (uses AgentStats, AgentRegistry)
│   ├── AgentDetail (uses AgentDetail, OwnershipChart, LiquidityModal)
│   ├── AgentRegistration (uses AgentRegistration)
│   ├── Portfolio (uses Portfolio)
│   └── Staking (uses CR8Staking)
└── Providers
    ├── WagmiProvider
    ├── QueryClientProvider
    └── RainbowKitProvider

6.2 Shared Components

Lib/Utilities:

• contracts.ts - Contract address helpers
• abis.ts - Contract ABIs
• utils/ - Helper functions

---

7. Future Components

7.1 Analytics Dashboard

• Performance charts
• Historical data
• Comparisons

7.2 Agent Management

• Settings page
• Integration management
• Wallet management

7.3 Notification System

• Reward notifications
• Agent updates
• System alerts

7.4 Governance (Future)

• Proposal system
• Voting interface
• Treasury management

---

This component breakdown provides a clear view of all pieces that make up Agent L3. Each component has a specific responsibility and integrates with others to create the complete system.