Merge pull request #2 from anu-m03/api

Api

Author: Akk525

apps/backend/.data/logs.jsonl

@@ -0,0 +1,12 @@
+{"id":"6e346965-e789-4669-a770-e905559a397a","timestamp":1771343000368,"type":"SWARM_START","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","payload":{"tx":{"chainId":8453,"from":"0xaaa","to":"0x0000000000000000000000000000000000000000","data":"0x","value":"2000000000000000000"},"runId":"5549e732-09cf-4868-a9ff-7da53747a22a"},"level":"INFO"}
+{"id":"e769b63d-9433-4e26-b968-f5204eaeabfb","timestamp":1771343000369,"type":"AGENT_REPORTS","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","payload":{"reports":[{"agentId":"sentinel-7dbc246e","agentType":"SENTINEL","timestamp":1771343000368,"riskScore":70,"confidenceBps":8500,"severity":"HIGH","reasons":["Transaction targets zero address","Plain ETH transfer with high value and no calldata"],"evidence":{"zeroAddress":true,"highValueNoData":true},"recommendation":"REVIEW"},{"agentId":"scam-ba29b285","agentType":"SCAM","timestamp":1771343000368,"riskScore":5,"confidenceBps":5500,"severity":"LOW","reasons":["No scam indicators detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"mev-c0988863","agentType":"MEV","timestamp":1771343000368,"riskScore":5,"confidenceBps":5000,"severity":"LOW","reasons":["No MEV risk detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"liq-47a7f78d","agentType":"LIQUIDATION","timestamp":1771343000369,"riskScore":5,"confidenceBps":4000,"severity":"LOW","reasons":["No lending risk detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"coord-e871db43","agentType":"COORDINATOR","timestamp":1771343000369,"riskScore":29,"confidenceBps":5750,"severity":"HIGH","reasons":["SENTINEL: score 70 (HIGH)"],"evidence":{"peerCount":4,"severityCounts":{"LOW":3,"MEDIUM":0,"HIGH":1,"CRITICAL":0},"avgScore":29},"recommendation":"ALLOW"}]},"level":"INFO"}
+{"id":"19bafafb-c49b-49e4-bbcc-a4289da00b41","timestamp":1771343000369,"type":"CONSENSUS","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","payload":{"decision":{"runId":"5549e732-09cf-4868-a9ff-7da53747a22a","timestamp":1771343000369,"finalSeverity":"HIGH","finalRiskScore":21,"decision":"ALLOW","threshold":{"approvalsRequired":2,"criticalBlockEnabled":true},"approvingAgents":[{"agentId":"scam-ba29b285","riskScore":5,"confidenceBps":5500,"reasonHash":"e1ae697e917bdc20"},{"agentId":"mev-c0988863","riskScore":5,"confidenceBps":5000,"reasonHash":"ef447bf5eec9a74f"},{"agentId":"liq-47a7f78d","riskScore":5,"confidenceBps":4000,"reasonHash":"4630f0c56999a0c4"}],"dissentingAgents":[{"agentId":"sentinel-7dbc246e","reason":"Transaction targets zero address; Plain ETH transfer with high value and no calldata"}],"notes":["Approvals: 3/4 (required 2)"]}},"level":"INFO"}
+{"id":"94abc094-c5c8-41f3-a4f3-75fc3d942752","timestamp":1771343000369,"type":"INTENT","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","payload":{"intent":{"intentId":"4227387c-611a-4da2-807b-7d83acac74e9","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","action":"EXECUTE_TX","chainId":8453,"to":"0x0000000000000000000000000000000000000000","value":"2000000000000000000","data":"0x","meta":{"finalSeverity":"HIGH","finalRiskScore":21,"timestamp":1771343000369}}},"level":"INFO"}
+{"id":"f414433e-9456-4e7c-9290-d0d03914ba55","timestamp":1771343000369,"type":"SWARM_END","runId":"5549e732-09cf-4868-a9ff-7da53747a22a","payload":{"runId":"5549e732-09cf-4868-a9ff-7da53747a22a","decision":"ALLOW"},"level":"INFO"}
+{"id":"4dc90534-1713-4cc3-bb46-973ccf360dfa","timestamp":1771343000582,"type":"GOVERNANCE_VOTE","payload":{"proposalId":"proposal-002","recommendation":"AGAINST","confidenceBps":7500,"summary":"Summary: Upgrade proxy to v2.1 — emergency patch Emergency upgrade to fix a critical vulnerability in the proxy contract. The admin key will be rotated and the quorum threshold adjusted from 3/5 to 4/7. Immedi..."},"level":"INFO"}
+{"id":"c3586e9a-cc5b-46cd-9cf8-f1bfee71e3c9","timestamp":1771343126538,"type":"SWARM_START","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","payload":{"tx":{"chainId":8453,"from":"0xaaa","to":"0x0000000000000000000000000000000000000000","data":"0x","value":"2000000000000000000"},"runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123"},"level":"INFO"}
+{"id":"1d4f1f4a-7964-43c3-99aa-387a8d1a915c","timestamp":1771343126539,"type":"AGENT_REPORTS","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","payload":{"reports":[{"agentId":"sentinel-1dc31a5f","agentType":"SENTINEL","timestamp":1771343126539,"riskScore":70,"confidenceBps":8500,"severity":"HIGH","reasons":["Transaction targets zero address","Plain ETH transfer with high value and no calldata"],"evidence":{"zeroAddress":true,"highValueNoData":true},"recommendation":"REVIEW"},{"agentId":"scam-5148bfbe","agentType":"SCAM","timestamp":1771343126539,"riskScore":5,"confidenceBps":5500,"severity":"LOW","reasons":["No scam indicators detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"mev-fa3d94d6","agentType":"MEV","timestamp":1771343126539,"riskScore":5,"confidenceBps":5000,"severity":"LOW","reasons":["No MEV risk detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"liq-eb561ba8","agentType":"LIQUIDATION","timestamp":1771343126539,"riskScore":5,"confidenceBps":4000,"severity":"LOW","reasons":["No lending risk detected"],"evidence":{},"recommendation":"ALLOW"},{"agentId":"coord-ae69d24c","agentType":"COORDINATOR","timestamp":1771343126539,"riskScore":29,"confidenceBps":5750,"severity":"HIGH","reasons":["SENTINEL: score 70 (HIGH)"],"evidence":{"peerCount":4,"severityCounts":{"LOW":3,"MEDIUM":0,"HIGH":1,"CRITICAL":0},"avgScore":29},"recommendation":"ALLOW"}]},"level":"INFO"}
+{"id":"6e429b37-ce27-4f25-9ba6-faac0ea206e3","timestamp":1771343126540,"type":"CONSENSUS","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","payload":{"decision":{"runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","timestamp":1771343126540,"finalSeverity":"HIGH","finalRiskScore":21,"decision":"ALLOW","threshold":{"approvalsRequired":2,"criticalBlockEnabled":true},"approvingAgents":[{"agentId":"scam-5148bfbe","riskScore":5,"confidenceBps":5500,"reasonHash":"e1ae697e917bdc20"},{"agentId":"mev-fa3d94d6","riskScore":5,"confidenceBps":5000,"reasonHash":"ef447bf5eec9a74f"},{"agentId":"liq-eb561ba8","riskScore":5,"confidenceBps":4000,"reasonHash":"4630f0c56999a0c4"}],"dissentingAgents":[{"agentId":"sentinel-1dc31a5f","reason":"Transaction targets zero address; Plain ETH transfer with high value and no calldata"}],"notes":["Approvals: 3/4 (required 2)"]}},"level":"INFO"}
+{"id":"7567ac1e-432f-4dab-9489-d077d7e60769","timestamp":1771343126540,"type":"INTENT","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","payload":{"intent":{"intentId":"18403edf-fd49-4295-990b-9627c87dfb23","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","action":"EXECUTE_TX","chainId":8453,"to":"0x0000000000000000000000000000000000000000","value":"2000000000000000000","data":"0x","meta":{"finalSeverity":"HIGH","finalRiskScore":21,"timestamp":1771343126540}}},"level":"INFO"}
+{"id":"3beb2f0b-146a-4fc3-a5d0-3425be3d122c","timestamp":1771343126540,"type":"SWARM_END","runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","payload":{"runId":"8c6e82b4-0aaa-4f84-bb39-3932add59123","decision":"ALLOW"},"level":"INFO"}
+{"id":"f0b77d60-6a64-499b-ba5c-d0b61576f459","timestamp":1771343133545,"type":"GOVERNANCE_VOTE","payload":{"proposalId":"proposal-002","recommendation":"AGAINST","confidenceBps":7500,"summary":"Summary: Upgrade proxy to v2.1 — emergency patch Emergency upgrade to fix a critical vulnerability in the proxy contract. The admin key will be rotated and the quorum threshold adjusted from 3/5 to 4/7. Immedi..."},"level":"INFO"}

apps/backend/.env.example

@@ -0,0 +1,18 @@
+# AgentSafe Backend env configuration
+# Copy this file to .env and fill in values
+
+# ─── Server ──────────────────────────────────────────────
+PORT=4000
+
+# ─── QuickNode RPC (Base chain) ──────────────────────────
+# Leave empty to run in "disabled" mode (no live chain data)
+QUICKNODE_RPC_URL=
+
+# ─── Kite AI ─────────────────────────────────────────────
+# Leave empty to run with deterministic stubs
+KITE_BASE_URL=
+KITE_API_KEY=
+
+# ─── Log Store ───────────────────────────────────────────
+# Directory for JSONL log files (defaults to .data/ in cwd)
+LOG_STORE_PATH=

apps/backend/README.md

@@ -1,30 +1,110 @@
 # @agent-safe/backend
 
-Node.js + Express backend API for the AgentSafe swarm agent orchestrator.
+Express + TypeScript backend for **AgentSafe** — SwarmGuard orchestrator,
+governance recommender, and audit log API.
+
+## Quick start
+
+```bash
+cp .env.example .env   # fill in optional keys
+pnpm install
+pnpm dev               # tsx watch — http://localhost:4000
+```
 
 ## 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 |
+| Method | Path                          | Description |
+|--------|-------------------------------|-------------|
+| GET    | `/health`                     | Rich health check (QuickNode + Kite AI status) |
+| GET    | `/status`                     | Quick liveness probe |
+| POST   | `/api/swarm/evaluate-tx`      | Evaluate a transaction through SwarmGuard |
+| GET    | `/api/swarm/logs`             | Fetch audit log (`?runId=...&limit=100`) |
+| GET    | `/api/governance/proposals`   | List mock governance proposals |
+| GET    | `/api/governance/proposals/:id` | Get single proposal |
+| POST   | `/api/governance/recommend`   | Get vote recommendation for a proposal |
+
+## Architecture
+
+```
+src/
+├── index.ts                      Express entry point
+├── middleware/logger.ts           Request logger with requestId
+├── routes/
+│   ├── health.ts                  /health + integration status
+│   ├── swarm.ts                   /api/swarm/*
+│   └── governance.ts              /api/governance/*
+├── agents/                        V2 heuristic agents
+│   ├── sentinel.ts                Approval / zero-addr / calldata checks
+│   ├── scamDetector.ts            Contract reputation checks
+│   ├── mevWatcher.ts              DEX swap sandwich risk
+│   ├── liquidationPredictor.ts    Health factor monitoring
+│   ├── coordinator.ts             Weighted aggregation
+│   └── defender.ts                Defensive action stub
+├── orchestrator/
+│   ├── swarmRunner.ts             Full pipeline: agents → consensus → intent
+│   ├── consensus.ts               MVP consensus rules (critical-block, approval count)
+│   ├── intent.ts                  Maps consensus decision → ActionIntent
+│   └── governanceRunner.ts        Proposal evaluation via Kite AI + policies
+├── governance/
+│   ├── proposals.ts               Reads mockProposals.json
+│   └── mockProposals.json         3 sample proposals
+├── storage/
+│   └── logStore.ts                JSONL-backed audit log
+└── services/
+    ├── rpc/quicknode.ts           QuickNode RPC wrapper (graceful degradation)
+    └── agents/kite.ts             Kite AI summarise / classify (stub fallback)
+```
+
+## Agents (V2)
 
-## Agents
+All agents export `evaluateTx(ctx, tx): Promise<AgentRiskReportV2>` and run
+**deterministic heuristics** — no LLM calls in the hot path.
 
-| 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 |
+| Agent        | Key heuristics |
+|--------------|----------------|
+| Sentinel     | Zero-address, empty calldata + high value, approve()/setApprovalForAll(), MAX_UINT |
+| Scam         | contractVerified, contractAge, phishing labels, honeypot flag |
+| MEV          | SWAP kind, DEX selector detection, high value, slippage > 300 bps |
+| Liquidation  | healthFactor thresholds (< 1.05 critical, < 1.2 high), collateral ratio |
+| Coordinator  | Weighted average of peer reports, severity counts |
 
-## Run
+## Consensus rules
+
+1. **Critical block** — any CRITICAL severity with ≥ 7 000 bps confidence ⇒ BLOCK
+2. **Approval count** — ALLOW or (LOW/MEDIUM + ≥ 6 000 bps) counts as approval; need ≥ 2 ⇒ ALLOW
+3. Otherwise ⇒ REVIEW_REQUIRED
+
+## Environment variables
+
+| Variable           | Required | Default | Notes |
+|--------------------|----------|---------|-------|
+| `PORT`             | No       | 4000    | HTTP listen port |
+| `QUICKNODE_RPC_URL`| No       |         | Base-chain RPC; omit for disabled mode |
+| `KITE_BASE_URL`    | No       |         | Kite AI endpoint; omit for stub mode |
+| `KITE_API_KEY`     | No       |         | Bearer token for Kite AI |
+| `LOG_STORE_PATH`   | No       | `.data` | Directory for JSONL logs |
+
+## Example curl commands
 
 ```bash
-pnpm dev   # starts on http://localhost:4000
+# Health
+curl http://localhost:4000/health | jq
+
+# Evaluate transaction
+curl -X POST http://localhost:4000/api/swarm/evaluate-tx \
+  -H 'Content-Type: application/json' \
+  -d '{"chainId":8453,"from":"0xYou","to":"0xTarget","data":"0x095ea7b3000000000000000000000000spenderffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff","value":"0"}' \
+  | jq
+
+# Fetch logs
+curl 'http://localhost:4000/api/swarm/logs?limit=10' | jq
+
+# List proposals
+curl http://localhost:4000/api/governance/proposals | jq
+
+# Get vote recommendation
+curl -X POST http://localhost:4000/api/governance/recommend \
+  -H 'Content-Type: application/json' \
+  -d '{"proposalId":"proposal-002"}' \
+  | jq
 ```

apps/backend/src/agents/coordinator.ts

@@ -1,41 +1,71 @@
-import type { AgentRiskReport, SwarmConsensusDecision } from '@agent-safe/shared';
-import { CONSENSUS_THRESHOLD } from '@agent-safe/shared';
+import type { AgentRiskReportV2, Severity, Recommendation } from '@agent-safe/shared';
+import crypto from 'node:crypto';
 
 /**
- * Coordinator Agent – aggregates individual agent reports and produces consensus.
- * TODO: Implement weighted voting, configurable thresholds.
+ * Coordinator Agent – aggregates individual agent reports and produces a summary report.
+ * Does not perform independent analysis; reflects swarm consensus.
  */
-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;
+export async function evaluateTx(
+  _ctx: unknown,
+  _tx: unknown,
+  peerReports: AgentRiskReportV2[],
+): Promise<AgentRiskReportV2> {
+  if (peerReports.length === 0) {
+    return {
+      agentId: `coord-${crypto.randomUUID().slice(0, 8)}`,
+      agentType: 'COORDINATOR',
+      timestamp: Date.now(),
+      riskScore: 0,
+      confidenceBps: 0,
+      severity: 'LOW',
+      reasons: ['No peer reports to aggregate'],
+      evidence: {},
+      recommendation: 'ALLOW',
+    };
+  }
+
+  // Weighted average risk score (weight = confidence)
+  let totalWeight = 0;
+  let weightedScore = 0;
+  const severityCounts: Record<Severity, number> = { LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0 };
+  const reasons: string[] = [];
+
+  for (const r of peerReports) {
+    const w = r.confidenceBps / 10_000;
+    weightedScore += r.riskScore * w;
+    totalWeight += w;
+    severityCounts[r.severity]++;
+    if (r.riskScore > 30) {
+      reasons.push(`${r.agentType}: score ${r.riskScore} (${r.severity})`);
+    }
+  }
+
+  const avgScore = totalWeight > 0 ? Math.round(weightedScore / totalWeight) : 0;
+
+  let severity: Severity = 'LOW';
+  if (severityCounts.CRITICAL > 0) severity = 'CRITICAL';
+  else if (severityCounts.HIGH > 0) severity = 'HIGH';
+  else if (severityCounts.MEDIUM > 0) severity = 'MEDIUM';
+
+  let recommendation: Recommendation = 'ALLOW';
+  if (avgScore >= 70) recommendation = 'BLOCK';
+  else if (avgScore >= 40) recommendation = 'REVIEW';
+
+  if (reasons.length === 0) reasons.push('All peer agents report low risk');
 
   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(),
+    agentId: `coord-${crypto.randomUUID().slice(0, 8)}`,
+    agentType: 'COORDINATOR',
+    timestamp: Date.now(),
+    riskScore: avgScore,
+    confidenceBps: Math.round(totalWeight / peerReports.length * 10_000),
+    severity,
+    reasons,
+    evidence: {
+      peerCount: peerReports.length,
+      severityCounts,
+      avgScore,
+    },
+    recommendation,
   };
 }

apps/backend/src/agents/defender.ts

@@ -1,26 +1,28 @@
-import type { SwarmConsensusDecision } from '@agent-safe/shared';
+import type { SwarmConsensusDecisionV2, ActionIntent, ConsensusDecision } from '@agent-safe/shared';
 
 /**
- * Defender Agent – executes defensive actions when allowed.
- * TODO: Implement approval revocation, swap prevention, repayment triggers.
+ * Defender Agent – executes defensive actions when the swarm consensus
+ * is BLOCK or REVIEW.  Currently simulates execution; real integration
+ * would submit a UserOp to revoke approvals or cancel pending txns.
  */
 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)
+  decision: SwarmConsensusDecisionV2,
+  intent?: ActionIntent | null,
+): Promise<{ executed: boolean; action: string; txHash?: string }> {
+  const shouldAct: ConsensusDecision[] = ['BLOCK', 'REVIEW_REQUIRED'];
 
-  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',
-    };
+  if (!shouldAct.includes(decision.decision)) {
+    return { executed: false, action: 'NO_ACTION_NEEDED' };
   }
 
+  console.log(
+    `[DefenderAgent] Would execute defensive action: ${intent?.action ?? 'N/A'}`,
+  );
+
+  // In production this would build + submit a UserOp via EntryPoint.
   return {
-    executed: false,
-    action: 'NO_ACTION_NEEDED',
+    executed: false, // stub – no real on-chain tx
+    action: intent?.action ?? 'BLOCK_TX',
+    txHash: undefined,
   };
 }