SOLUS — The Autonomous Agent Operating System

SOLUS is an institutional-grade autonomous AI agent operating system built on the Arc Network. It enables operators to deploy, fund, coordinate, and supervise on-chain AI agents capable of holding self-custodial capital, executing autonomous market strategies, and collaborating within multi-agent swarms.

---

🏛️ System Architecture & Core Pillars

                     ┌──────────────────────────────────────────────┐
                     │          SOLUS OPERATOR DASHBOARD            │
                     │  (Mission Control · Ask Solus · Treasury)    │
                     └──────────────────────┬───────────────────────┘
                                            │
               ┌────────────────────────────┴────────────────────────────┐
               ▼                                                         ▼
┌─────────────────────────────┐                           ┌─────────────────────────────┐
│    AI SUPERVISORY ENGINE    │                           │  UNIFIED 2-of-2 MPC VAULT   │
│  • Anthropic Claude 3.5     │                           │  • Circle User-Controlled   │
│  • Swarm Task Delegator     │                           │  • Delegated Policy Engine  │
│  • Real-Time Market Scout   │                           │  • Direct 1-Hop Capital     │
└──────────────┬──────────────┘                           └──────────────┬──────────────┘
               │                                                         │
               └────────────────────────────┬────────────────────────────┘
                                            │
                                            ▼
                     ┌──────────────────────────────────────────────┐
                     │          ARC TESTNET INFRASTRUCTURE          │
                     │  • ERC-8004 On-Chain Identity Registry       │
                     │  • Arc AMM DEX & Token Settlement Engine     │
                     │  • On-Chain Proof-of-Execution Verifier      │
                     └──────────────────────────────────────────────┘

1. Dual-Wallet Identity & Custody

• Solus EVM Wallets: Direct browser extension connection (MetaMask, Rabby) via Sign-In with Ethereum (SIWE) and writeContractAsync for on-chain identity minting.
• Solus Circle Wallets: 2-of-2 Multi-Party Computation (MPC) self-custody with WebAuthn Passkeys and PIN challenges powered by @circle-fin/user-controlled-wallets.
• ERC-8004 Identity Registry: Persistent on-chain agent identities with immutable metadata, capabilities registration, and operational status logs.

2. Autonomous Treasury & Delegated Spending Policies

• Single-Master Treasury Hierarchy: Every operator possesses a unified master treasury account (user.circleWalletAddress / treasury.walletAddress).
• Signed Delegated Spending Policies: Background agent missions execute 100% autonomously within signed constraints (perTxLimitUsdc, dailyLimitUsdc, recipient allowlists).
• Human-in-the-Loop Safeguards: Transfers exceeding signed limits pause execution and require explicit operator sign-off via Ask Solus / Circle PIN Challenge.
• Dynamic Multi-Asset Engine: Live resolution of USDC, EURC, and ARC via on-chain asset registries (resolveAsset()).

3. AI Supervisory & Multi-Agent Swarms

• Context-Aware Supervisor: Powered by Claude 3.5 Sonnet with zero-hardcoding dynamic tool routing and intent validation.
• Multi-Agent Collaboration: Specialized agent roles (Market Scout, Liquidity Arbitrageur, Risk Auditor, Swarm Coordinator) dynamically orchestrated for complex workflows.
• Strict On-Chain Verification: Every fund allocation, settlement, and clawback requires verified on-chain transaction hashes before state reconciliation (ArcOnChainVerifier).

4. DEX & DeFi Interoperability

• Constant-Product AMM Pools: Native $x \cdot y = k$ liquidity pool architecture with 0.30% swap fees and slippage protection.
• Automated Token Trading: Real-time quotes, buy/sell executions, and dynamic pool routing across Arc Testnet.

---

💻 Institutional Tech Stack

Domain	Technologies
Frontend & UI	Next.js 15 (App Router), React 19, TypeScript 5, Tailwind CSS, Framer Motion, Lucide Icons
Design System	SOLUS Dark Glass Institutional Design System (#000000, #FFFFFF, Restrained Violet Accent)
Web3 & Blockchain	Viem, Wagmi, RainbowKit, OpenZeppelin Contracts v5, Arc Testnet (Chain ID 5042002)
Payments & Treasury	Circle Developer Stack (@circle-fin/user-controlled-wallets, W3S SDK, CCTP)
AI & Orchestration	Anthropic Claude 3.5 Sonnet, Custom Tool Registry, ReAct Decision Planners
Database & Cache	Prisma ORM, Neon Serverless PostgreSQL
Authentication	SIWE (Sign-In with Ethereum), NextAuth, Circle Passkey WebAuthn

---

📁 Repository Structure

├── prisma/
│   └── schema.prisma             # PostgreSQL schema (Users, Agents, Treasury, Swarms)
├── public/
│   └── branding/                 # Official SVGs, partner assets, and vector icons
├── src/
│   ├── app/                      # Next.js 15 App Router surfaces
│   │   ├── (auth)/               # SIWE & Passkey authentication flows
│   │   ├── activity/             # Chronological audit logs & JSON inspector
│   │   ├── agents/               # Fleet management, creation wizard & telemetry
│   │   ├── ask-solus/            # Natural language conversational command center
│   │   ├── treasury/             # Capital matrix, balance reconciliation & funding
│   │   ├── wallets/              # Self-custodial connection & MPC wallet status
│   │   └── api/                  # Edge API routes (AI, Circle, Treasury, Webhooks)
│   ├── components/               # Institutional UI primitives & modular panels
│   │   ├── dashboard/            # Mission Control, fleet stats & operational radar
│   │   ├── layout/               # Sidebar (3-stage master hierarchy), Topbar & Nav
│   │   └── shared/               # SolusLogo, badges, glass cards & data tables
│   ├── hooks/                    # Custom React hooks (Wallet, Activity, Treasury)
│   ├── lib/                      # Core business logic, design system & navigation
│   │   └── ai/                   # Supervisory planners, swarm delegators & tool registry
│   └── services/                 # Infrastructure integration services
│       ├── arc/                  # On-chain verifier, DEX router, token registry & RPC
│       ├── circle/               # Circle W3S SDK, user-controlled wallets & passkeys
│       └── market/               # Real-time price oracles & market intelligence
└── docs/                         # Architecture blueprints, database & design playbooks

---

🚀 Getting Started

Prerequisites

• Node.js: v22.13.0 or higher
• Package Manager: npm v10.9.0+
• Database: PostgreSQL (or Neon Serverless Postgres)
• Arc Testnet RPC: https://rpc.testnet.arc.network

1. Clone & Install Dependencies

git clone https://github.com/Astreus-5/SOLUS.git
cd SOLUS
npm install

2. Configure Environment Variables

Create a local .env file from .env.example:

cp .env.example .env

Ensure the following core variables are configured:

# Database
DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"

# Authentication & NextAuth
NEXTAUTH_SECRET="your-secure-nextauth-secret"
NEXTAUTH_URL="http://localhost:3000"

# Arc Network Configuration
NEXT_PUBLIC_ARC_RPC_URL="https://rpc.testnet.arc.network"
NEXT_PUBLIC_ARC_CHAIN_ID="5042002"
NEXT_PUBLIC_ARC_EXPLORER_URL="https://testnet.arcscan.app"

# Circle Developer Stack
CIRCLE_API_KEY="your-circle-api-key"
CIRCLE_ENTITY_SECRET="your-circle-entity-secret"
NEXT_PUBLIC_CIRCLE_APP_ID="your-circle-app-id"

# AI Orchestration
ANTHROPIC_API_KEY="your-anthropic-api-key"

3. Database Migration & Client Generation

npx prisma generate
npx prisma migrate deploy

4. Run Development Server

npm run dev

Open http://localhost:3000 to access the SOLUS Operator Dashboard.

---

🛡️ Security, Governance & Verification

1. Deterministic Verification: No off-chain state changes or database mutations are approved without cryptographic on-chain event confirmation via ArcOnChainVerifier.
2. Strict Financial Isolation: Real accounts are isolated from test fixtures; direct balance overrides are prohibited outside audited settlement pipelines.
3. Open Standards: Fully compliant with ERC-8004 (Agent Identity), ERC-20 (Asset standard), and EIP-2612 (Gasless Permits).

---

📜 License

This project is licensed under the MIT License.