@aegis-defi/sdk

Security middleware for autonomous DeFi agents. Protect AI-powered wallets from prompt injection, exploit patterns, and anomalous transactions.

Install

npm install @aegis-defi/sdk

Quick Start

import { AegisGuard } from '@aegis-defi/sdk'

const guard = new AegisGuard({
  chains: ['ethereum', 'base', 'solana'],
  maxTransactionAmount: 10_000,
  maxDailyLoss: 50_000,
  maxTransactionsPerMinute: 10,
  onThreatDetected: (result) => {
    console.log(`Threat detected: ${result.threats[0].name}`)
  },
  onCircuitBreak: (status) => {
    console.log(`Circuit breaker tripped! Total loss: ${status.totalLoss}`)
  },
})

// Wrap an ethers.js provider
const protectedProvider = guard.wrapProvider(provider)

// Or validate manually
const result = guard.validate({
  to: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD68',
  value: '1000',
  data: 'transfer(address,uint256)',
  chain: 'ethereum',
})

if (!result.safe) {
  console.log(`Blocked: ${result.recommendation}`, result.threats)
}

API Reference

AegisGuard

The main entry point. Creates and orchestrates all security components.

const guard = new AegisGuard(config: AegisConfig)

Methods:

| Method | Returns | Description | |--------|---------|-------------| | wrapProvider(provider) | Proxy | Wraps an EVM or Solana provider to intercept transactions | | validate(tx) | ValidationResult | Manually validate a transaction | | getAuditLog(filter?) | AuditEntry[] | Retrieve audit log entries | | getCircuitBreakerStatus() | CircuitBreakerStatus | Check circuit breaker state | | killSwitch(reason?) | void | Activate the kill switch | | resume() | void | Deactivate the kill switch |

Validator

Pattern matching and threat detection engine.

const validator = new Validator({
  maxTransactionAmount: 10_000,
  customPatterns: [],
})

Methods:

| Method | Returns | Description | |--------|---------|-------------| | validate(tx) | ValidationResult | Scan transaction for threats | | addPattern(pattern) | void | Add a custom threat pattern |

CircuitBreaker

Tracks cumulative losses and trips when limits are exceeded.

const cb = new CircuitBreaker({
  maxDailyLoss: 50_000,
  windowMs: 86_400_000,  // 24 hours (default)
})

Methods:

| Method | Returns | Description | |--------|---------|-------------| | recordLoss(amount) | void | Record a loss amount | | isTripped() | boolean | Check if circuit breaker is tripped | | reset() | void | Manually reset the circuit breaker | | getStatus() | CircuitBreakerStatus | Get full status |

KillSwitch

Emergency stop mechanism with optional remote control.

const ks = new KillSwitch({
  remoteEndpoint: 'https://api.example.com/killswitch',
})

Methods:

| Method | Returns | Description | |--------|---------|-------------| | activate(reason) | void | Activate the kill switch | | deactivate() | void | Deactivate the kill switch | | isActive() | boolean | Check if kill switch is active | | checkRemote() | Promise<boolean> | Check remote endpoint for kill signal | | getStatus() | KillSwitchStatus | Get full status |

AnomalyDetector

Statistical anomaly detection using z-score analysis.

const detector = new AnomalyDetector({
  windowSize: 100,       // sliding window size (default)
  zScoreThreshold: 2.5,  // z-score threshold (default)
})

Methods:

| Method | Returns | Description | |--------|---------|-------------| | addDataPoint(value) | void | Add a data point to the window | | isAnomaly(value) | boolean | Check if a value is anomalous | | getStats() | { mean, stdDev, count } | Get window statistics |

AuditLog

Transaction audit logging with optional remote sync.

const log = new AuditLog({
  maxEntries: 1000,
  remoteEndpoint: 'https://api.example.com/audit',
})

Methods:

| Method | Returns | Description | |--------|---------|-------------| | log(entry) | AuditEntry | Add an audit entry | | getEntries(filter?) | AuditEntry[] | Retrieve filtered entries | | flush() | Promise<void> | Send pending entries to remote | | clear() | void | Remove all entries |

Configuration

| Option | Type | Description | |--------|------|-------------| | chains | string[] | Supported chain identifiers | | maxTransactionAmount | number | Max allowed single transaction amount | | maxDailyLoss | number | Max cumulative loss before circuit breaker trips | | maxTransactionsPerMinute | number | Rate limit for transactions | | onThreatDetected | (result) => void | Callback when threat is detected | | onCircuitBreak | (status) => void | Callback when circuit breaker trips | | killSwitchEndpoint | string | Remote kill switch URL | | auditLogEndpoint | string | Remote audit log URL |

Threat Categories

| Category | IDs | Description | |----------|-----|-------------| | Prompt Injection | INJ-001 to INJ-007 | AI prompt manipulation attacks | | Flash Loan | DEFI-001 | Flash loan exploit signatures | | Reentrancy | DEFI-002 | Reentrancy attack patterns | | MEV Sandwich | DEFI-003 | Price oracle manipulation | | Approval Exploit | DEFI-004 | Batched call exploits | | Session Hijack | DEFI-005 | Self-destruct / contract destruction | | Anomalous Amount | AMT-001 to AMT-003 | Unusual transaction amounts | | Unknown Recipient | ADDR-001 to ADDR-002 | Suspicious addresses |

Chain Support

| Chain | Adapter | Provider Type | |-------|---------|---------------| | Ethereum | wrapEVMProvider | ethers.js / viem | | Base | wrapEVMProvider | ethers.js / viem | | Arbitrum | wrapEVMProvider | ethers.js / viem | | Solana | wrapSolanaConnection | @solana/web3.js |

License

MIT