Project Scaffold

Author: Akk525

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-build:
+    name: Lint & Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build shared package
+        run: pnpm --filter @agent-safe/shared build
+
+      - name: Build backend
+        run: pnpm --filter @agent-safe/backend build
+
+      - name: Build frontend
+        run: pnpm --filter @agent-safe/web build
+
+      - name: Lint
+        run: pnpm lint
+
+  contracts:
+    name: Foundry Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/contracts
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install contract dependencies
+        run: forge install
+
+      - name: Build contracts
+        run: forge build
+
+      - name: Run tests
+        run: forge test -vvv

.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+.next/
+out/
+.turbo/
+.env
+.env.local
+*.log
+coverage/
+.DS_Store
+
+# Foundry
+packages/contracts/cache/
+packages/contracts/out/
+packages/contracts/broadcast/

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2
+}

Makefile

@@ -0,0 +1,50 @@
+.PHONY: install dev build clean test lint format docker-up docker-down forge-build forge-test
+
+# ─── Setup ────────────────────────────────────────────────
+install:
+	pnpm install
+
+# ─── Development ──────────────────────────────────────────
+dev:
+	pnpm dev
+
+build:
+	pnpm build
+
+clean:
+	pnpm clean
+
+lint:
+	pnpm lint
+
+format:
+	pnpm format
+
+# ─── Contracts (Foundry) ─────────────────────────────────
+forge-build:
+	cd packages/contracts && forge build
+
+forge-test:
+	cd packages/contracts && forge test -vvv
+
+forge-deploy-local:
+	cd packages/contracts && forge script script/Deploy.s.sol --fork-url http://localhost:8545 --broadcast
+
+forge-deploy-base-sepolia:
+	cd packages/contracts && forge script script/Deploy.s.sol --rpc-url base_sepolia --broadcast --verify
+
+# ─── Docker ───────────────────────────────────────────────
+docker-up:
+	docker-compose up -d
+
+docker-down:
+	docker-compose down
+
+docker-logs:
+	docker-compose logs -f
+
+# ─── Database ─────────────────────────────────────────────
+db-reset:
+	docker-compose down -v && docker-compose up -d postgres
+	sleep 2
+	psql $(DATABASE_URL) -f db/schema.sql

README.md

@@ -1 +1,60 @@
-# Agent-Safe
+# AgentSafe
+
+> An ERC-4337 smart wallet on Base powered by **SwarmGuard** (multi-agent AI defense) and **GovernanceSafe** (proposal analysis + safe auto-voting with veto).
+
+## Monorepo Structure
+
+```
+apps/
+  web/          → Next.js frontend dashboard
+  backend/      → Node.js + Express agent orchestrator API
+packages/
+  contracts/    → Foundry Solidity smart contracts
+  shared/       → Shared TypeScript types, Zod schemas, constants
+```
+
+## Prerequisites
+
+- Node.js ≥ 20
+- pnpm ≥ 9
+- Foundry (for contracts)
+
+## Quick Start
+
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Copy environment variables
+cp .env.example .env
+# Fill in your keys
+
+# 3. Run everything in dev mode
+pnpm dev
+
+# Frontend → http://localhost:3000
+# Backend  → http://localhost:4000
+```
+
+## Useful Commands
+
+```bash
+pnpm build          # Build all packages
+pnpm lint           # Lint all packages
+pnpm format         # Format all files with Prettier
+
+# Contracts (from packages/contracts)
+forge build
+forge test
+```
+
+## Architecture
+
+- **AgentSafe Wallet** – ERC-4337 account abstraction wallet on Base
+- **SwarmGuard** – Multi-agent defense system (Sentinel, MEV Watcher, Liquidation Predictor, Scam Detector, Coordinator, Defender)
+- **GovernanceSafe** – Proposal parser, risk analysis, vote recommendation, execution with human veto
+- **Policy Engine** – On-chain deterministic guardrails that AI cannot override
+
+## License
+
+MIT

apps/backend/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:20-alpine AS base
+RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
+WORKDIR /app
+
+# Copy workspace config
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml* turbo.json tsconfig.base.json ./
+
+# Copy package sources
+COPY packages/shared ./packages/shared
+COPY apps/backend ./apps/backend
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile || pnpm install
+
+# Build shared package first
+RUN pnpm --filter @agent-safe/shared build
+
+# Build backend
+RUN pnpm --filter @agent-safe/backend build
+
+EXPOSE 4000
+CMD ["node", "apps/backend/dist/index.js"]

apps/backend/README.md

@@ -0,0 +1,30 @@
+# @agent-safe/backend
+
+Node.js + Express backend API for the AgentSafe swarm agent orchestrator.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| POST | `/api/swarm/evaluate-tx` | Evaluate a transaction through SwarmGuard |
+| GET | `/api/swarm/logs` | Fetch audit log of swarm decisions |
+| GET | `/api/governance/proposals` | Fetch governance proposals (Snapshot stub) |
+| POST | `/api/governance/recommend` | Analyse a proposal and return recommendation |
+
+## Agents
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| Sentinel | `agents/sentinel.ts` | Approval & activity monitoring |
+| MEV Watcher | `agents/mevWatcher.ts` | Sandwich attack detection |
+| Liquidation Predictor | `agents/liquidationPredictor.ts` | Health factor tracking |
+| Scam Detector | `agents/scamDetector.ts` | Contract reputation checks |
+| Coordinator | `agents/coordinator.ts` | Consensus aggregation |
+| Defender | `agents/defender.ts` | Defensive action execution |
+
+## Run
+
+```bash
+pnpm dev   # starts on http://localhost:4000
+```

apps/backend/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@agent-safe/backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "lint": "echo 'lint: ok'"
+  },
+  "dependencies": {
+    "@agent-safe/shared": "workspace:*",
+    "express": "^4.21.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/cors": "^2.8.17",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

apps/backend/src/agents/coordinator.ts

@@ -0,0 +1,41 @@
+import type { AgentRiskReport, SwarmConsensusDecision } from '@agent-safe/shared';
+import { CONSENSUS_THRESHOLD } from '@agent-safe/shared';
+
+/**
+ * Coordinator Agent – aggregates individual agent reports and produces consensus.
+ * TODO: Implement weighted voting, configurable thresholds.
+ */
+export async function runCoordinatorAgent(
+  reports: AgentRiskReport[],
+): Promise<SwarmConsensusDecision> {
+  // TODO: Implement weighted voting based on agent confidence
+  // TODO: Configurable consensus threshold
+  // TODO: Handle conflicting agent outputs
+
+  const highRiskCount = reports.filter(
+    (r) => r.risk_level === 'HIGH' || r.risk_level === 'CRITICAL',
+  ).length;
+
+  const riskScore = Math.round(
+    (reports.reduce((sum, r) => {
+      const levelScore = { LOW: 10, MEDIUM: 40, HIGH: 75, CRITICAL: 95 }[r.risk_level];
+      return sum + levelScore * r.confidence;
+    }, 0) /
+      reports.length) *
+      1,
+  );
+
+  const consensusMet = highRiskCount >= CONSENSUS_THRESHOLD;
+
+  return {
+    final_decision: consensusMet ? 'BLOCK' : 'ALLOW',
+    risk_score: riskScore,
+    consensus: `${highRiskCount}/${reports.length} agents`,
+    summary: consensusMet
+      ? 'Multiple agents flagged high risk – transaction blocked.'
+      : 'Risk level acceptable – transaction allowed.',
+    actions: consensusMet ? ['BLOCK_TX'] : ['ALLOW'],
+    agent_reports: reports,
+    timestamp: new Date().toISOString(),
+  };
+}

apps/backend/src/agents/defender.ts

@@ -0,0 +1,26 @@
+import type { SwarmConsensusDecision } from '@agent-safe/shared';
+
+/**
+ * Defender Agent – executes defensive actions when allowed.
+ * TODO: Implement approval revocation, swap prevention, repayment triggers.
+ */
+export async function runDefenderAgent(
+  decision: SwarmConsensusDecision,
+): Promise<{ executed: boolean; action: string }> {
+  // TODO: Revoke approvals via UserOp
+  // TODO: Prevent swap execution
+  // TODO: Trigger repayment on lending positions (stretch)
+
+  if (decision.final_decision === 'EXECUTE_DEFENSE') {
+    console.log('[DefenderAgent] Would execute defensive action:', decision.actions);
+    return {
+      executed: false, // Stub – no real execution
+      action: 'STUB_DEFENSE_ACTION',
+    };
+  }
+
+  return {
+    executed: false,
+    action: 'NO_ACTION_NEEDED',
+  };
+}