AgentNexus

An end-to-end, privacy-aware DeFi execution stack that combines:

• Agents (uAgents) for scanning yields, assessing risk, and executing on-chain strategies
• Smart contracts (Foundry) including an AgentVault and protocol adapters
• Zero-knowledge circuits (Circom + snarkjs) for strategy proofing and an on-chain Groth16 verifier
• A Next.js frontend for visualizing states and interacting with agents/contracts

Monorepo Layout

• packages/agents/: Python agents and orchestration
  • yield_scanner.py: discovers opportunities and emits YieldOpportunities
  • risk_assessor.py: ranks opportunities (optionally via ASI:One) and emits RiskAssessments
  • crosschain_executor.py: validates/executes strategies using adapters on Base Sepolia
  • asi_chat_agent.py: simple chat agent with portfolio context
  • models.py, config.py: shared message schemas and chain/contract config
  • requirements.txt: pinned deps (Python 3.12)
• packages/contracts/: Foundry workspace
  • src/AgentVault.sol: ERC20 receipt vault (agUSDC) with ZK strategy proof gating
  • src/adapters/*Adapter.sol: Aave/Compound/Morpho adapter interfaces for supply flows
  • src/interfaces/IProtocolAdapter.sol
  • src/StrategyVerifier.sol: Groth16 verifier (snarkjs-generated)
  • script/ and broadcast/: deployment scripts and artifacts
• packages/circuits/: ZK artifacts and verifier sources
  • PrivateYieldStrategy.circom, *_js/*.wasm, *_final.zkey, verification_key.json
  • test_proof.js: local proof generation/verification script
  • StrategyVerifier.sol: snarkjs-generated verifier (reference)
• packages/frontend/: Next.js app
  • Serves UI, integrates with snarkjs and on-chain data

Quick Start

Prereqs: Python 3.12, Node.js 18+, pnpm, Foundry (forge/anvil), jq, git.

1. Install root JS deps

pnpm install

2. Python virtualenv for agents

cd packages/agents
python -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
# Note: metta-dsl is optional and may not be published for your platform; agents run without it

3. Environment

Create a .env in packages/agents/ with:

# Agents / API
ASI_ONE_API_KEY=your_asi_api_key
ASI_ONE_URL=https://api.asi1.ai/v1/chat/completions

# Base Sepolia
RPC_URL=https://sepolia.base.org
CHAIN_ID=84532
USDC_ADDRESS=0x036CbD53842c5426634e7929541eC2318f3dCF7e

# Execution key (DO NOT commit real keys)
PRIVATE_KEY=0xabc...dead

# Adapter addresses (must exist on target chain)
AAVE_ADAPTER_BASE_SEPOLIA=0xe64834f0A0764Fe7BD3b96465BF1D95Ec2bB1927
COMPOUND_ADAPTER_BASE_SEPOLIA=0xc61f427e9004aFC8B2905b8761A12D3353e0C5f8
MORPHO_ADAPTER_BASE_SEPOLIA=0xF2c1085F908723Ea3e5B07D7A80c08723Aea6AFc

# Optional UI context
PORTFOLIO_API=http://127.0.0.1:3000/api/portfolio

4. Contracts (Foundry)

cd packages/contracts
forge install
forge build
# Optionally run tests
forge test -vvv

5. Circuits: local proof check

cd packages/circuits
pnpm exec node test_proof.js

6. Frontend

cd packages/frontend
pnpm dev
# App on http://localhost:3000

Running Agents

Use the same Python venv for all agents:

source packages/agents/venv/bin/activate

• Risk Assessor (port 8001)

python packages/agents/risk_assessor.py

• CrossChain Executor (port 8004, retry server 8010)

python packages/agents/crosschain_executor.py

• Yield Scanner (port 8000)

python packages/agents/yield_scanner.py

• ASI Chat Agent (port 8005)

python packages/agents/asi_chat_agent.py

Agent inspection links are printed on startup (Agentverse).

Message Flow

1. yield_scanner emits YieldOpportunities to risk_assessor every 60s.
2. risk_assessor computes risk scores (ASI:One or heuristic) and sends RiskAssessments to crosschain_executor.
3. crosschain_executor builds a strategy and executes via protocol adapters on Base Sepolia.

Models are defined in packages/agents/models.py and used across agents.

Contracts Overview

• AgentVault.sol:
  • USDC vault with receipt token agUSDC (6 decimals)
  • Requires a recent Groth16 strategy proof via submitStrategyProof
  • Standard deposit/redeem/withdraw with ERC4626-like math
• StrategyVerifier.sol:
  • Groth16 verifier generated by snarkjs, used by the vault
• adapters:
  • Minimal adapters for Aave/Compound/Morpho supply flows (demo selectors)

Circuits Overview

• Circom circuit computes a portfolio hash and public signals
• Artifacts included: .wasm, .zkey, verification_key.json
• test_proof.js demonstrates fullProve and local verification

Frontend Overview

• Next.js 15 app (Turbopack) with wagmi/viem integration
• Includes snarkjs and data visualization libs

Common Issues

• Port in use (8000/8001/8004/8005/8010): stop stale processes and relaunch
• RPC not reachable: ensure RPC_URL is correct and network is accessible
• Missing metta-dsl: optional; agents run without it

License

This repository bundles multiple components. Each package retains its own license headers. See individual files.