VAULT — Threat Research Playground 🌑

Ship it. Break it. Learn.

VAULT is a smart contract security research platform where you deploy vulnerable contract scenarios, execute real exploits, have AI analyze the attack in real-time, and submit findings to a shared research queue.

---

Quick Start

# Install
npm install @darksol/vault

# Start local Anvil chain
npx vault anvil:start

# List scenarios
npx vault scenarios

# Deploy a scenario
npx vault run reentrancy-vault

# Analyze exploit with AI
npx vault analyze 0xtxhash --scenario reentrancy-vault

# Submit findings
npx vault submit findings.json

---

What is VAULT?

The original tweet: "Self-executing smart contracts that use AI-scaled threat analysis and consensus human judgement sourced across decentralized oracles."

VAULT builds the research layer for that vision. Instead of trying to solve the oracle latency problem, it focuses on what works right now:

• Researchers deploy realistic attack scenarios and test them against AI threat detectors
• Attack patterns are classified by AI and submitted to a shared findings library
• The pattern library improves over time — creating a behavioral dataset for automated threat detection

This is a research tool. Everything runs on testnet or local Anvil — no real money, no liability.

---

Scenarios

🔴 ReentrancyVault (Severity: 8/10)

Classic cross-function reentrancy. The withdraw() function calls user.call{value}() before zeroing the balance. Exploit via a malicious contract's receive() fallback.

🔴 OracleManipulation (Severity: 8/10)

A lending pool that reads Uniswap spot price without TWAP sanity checks. Flash-loan a large swap to manipulate collateral valuation within a single block.

🟡 AccessControlBypass (Severity: 7/10)

An admin contract where transferOwnership() has no auth check. Anyone can claim ownership. Also: emergencyDrain() is publicly callable.

---

Architecture

vault/
├── contracts/              # Solidity contracts
│   ├── SubmissionRegistry.sol   # Onchain submission anchor
│   └── templates/          # Vulnerable victim contracts
│       ├── ReentrancyVault.sol
│       ├── OracleManipulation.sol
│       └── AccessControlBypass.sol
├── sdk/                   # TypeScript SDK
│   └── src/
│       ├── ai.ts          # AI analysis via Bankr LLM Gateway
│       ├── scenario.ts     # Scenario deployment
│       ├── submit.ts       # Findings submission
│       └── types.ts        # Shared types
├── api/                   # Express submission receiver
└── cli/                   # CLI runner

---

SDK Usage

import { listScenarios, deployScenario, analyzeTransaction, submit } from '@darksol/vault';

// 1. List scenarios
const scenarios = listScenarios();

// 2. Deploy to Anvil
const deployed = await deployScenario('reentrancy-vault', {
  rpcUrl: 'http://127.0.0.1:8545',
});

// 3. Execute exploit, then analyze with AI
const analysis = await analyzeTransaction({
  txHash: '0x...',
  scenarioId: 'reentrancy-vault',
  rpcUrl: 'http://127.0.0.1:8545',
});
// → { classification: "Reentrancy — severity 8/10", ... }

// 4. Submit findings
const result = await submit({
  scenario: 'reentrancy-vault',
  chainId: 31337,
  attackerAddress: '0x...',
  victimAddress: deployed.victimAddress,
  txHash: '0x...',
  blockNumber: 123,
  aiAnalysis: analysis,
});

---

Environment Variables

# AI Analysis (Bankr LLM Gateway)
BANKR_LLM_KEY=bk_your_key_here

# RPC endpoints
ANVIL_RPC=http://127.0.0.1:8545
BASE_SEPOLIA_RPC=https://sepolia.base.org

# Private key (for onchain registration on Base Sepolia)
PRIVATE_KEY=0x...

# Submission API
VAULT_API_URL=https://api.vault.darksol.net

---

Submission Format

Submissions are JSON:

{
  "version": "1.0",
  "scenario": "reentrancy-vault",
  "chainId": 31337,
  "attackerAddress": "0x...",
  "victimAddress": "0x...",
  "txHash": "0x...",
  "blockNumber": 12345678,
  "aiAnalysis": {
    "classification": "Reentrancy — severity 8/10",
    "attackPattern": "Cross-function reentrancy via receive()",
    "rootCause": "Vault.withdraw() calls external contract before updating balance",
    "remediation": "Apply CEI pattern — update balance before external call"
  },
  "submittedBy": "0x...",
  "timestamp": "2026-04-21T10:00:00Z"
}

---

Deployment

Contracts (Foundry)

cd contracts
forge install
forge build
forge script script/Deploy.s.sol --rpc-url base_sepolia --broadcast

API Server

cd api
npm install
node server.js  # or: npx wrangler pages dev api

---

Roadmap

• Pro tier: unlimited scenarios, Base Sepolia deployment, AI analysis, onchain registration
• Submission review dashboard
• IPFS storage for findings
• More scenario templates (flash loan, governance attack, MEV sandwich)
• Team collaboration and shared research threads

---

Built with teeth. 🌑