Merge pull request #5 from saaj376/saajan

feat:semantic analysis and casual tracing done

Author: saaj376

backend/contracts/Phase2TestContracts.sol

@@ -34,6 +34,11 @@ contract TimeLockHoneypot {
         balanceOf[msg.sender] = totalSupply;
     }
 
+    // Allow easy testing via "Send ETH"
+    receive() external payable {
+        _checkTradingAllowed(msg.sender);
+    }
+
     modifier onlyOwner() {
         require(msg.sender == owner, "Not owner");
         _;
@@ -123,6 +128,11 @@ contract WhitelistHoneypot {
         isWhitelisted[msg.sender] = true;
     }
 
+    // Allow easy testing via "Send ETH"
+    receive() external payable {
+        _checkTransferAllowed(msg.sender);
+    }
+
     modifier onlyOwner() {
         require(msg.sender == owner, "Not owner");
         _;
@@ -219,6 +229,11 @@ contract DelayedTradingToken {
         balanceOf[msg.sender] = totalSupply;
     }
 
+    // Allow easy testing via "Send ETH"
+    receive() external payable {
+        _checkTradingOpen(msg.sender);
+    }
+
     modifier onlyOwner() {
         require(msg.sender == owner, "Not owner");
         _;

backend/scripts/verify_phase3.ts

@@ -0,0 +1,65 @@
+
+// Native fetch is available in Node > 18
+
+async function verifyPhase3() {
+    console.log("Verifying Phase 3: Dynamic Causal Analysis...");
+
+    // 1. Test Whitelist Honeypot (expecting High Severity + specific story)
+    const whitelistHoneypot = "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512";
+    console.log(`\n[1] Testing Whitelist Honeypot: ${whitelistHoneypot}`);
+
+    // Minimal transaction object
+    const tx = {
+        to: whitelistHoneypot,
+        from: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", // Random user
+        data: "0x",
+        value: "0x0"
+    };
+
+    try {
+        const response = await fetch('http://127.0.0.1:3000/rpc', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "sentinel_analyze",
+                params: [tx, 31337]
+            }),
+        });
+
+        const data = await response.json();
+
+        if (data.error) {
+            console.error("RPC Error:", data.error);
+            return;
+        }
+
+        const report = data.result.securityReport;
+
+        if (report.mechanismStory) {
+            console.log("✅ Mechanism Story Found!");
+            console.log("---------------------------------------------------");
+            console.log(`Title:    ${report.mechanismStory.title}`);
+            console.log(`Severity: ${report.mechanismStory.severity}`);
+            console.log(`Story:    ${report.mechanismStory.story}`);
+            console.log("---------------------------------------------------");
+
+            // Validation
+            if (report.mechanismStory.severity === 'High') console.log("✅ Severity Check Passed");
+            else console.log("❌ Severity Check Failed");
+
+            if (report.mechanismStory.title.includes("Owner Privileges") || report.mechanismStory.story.includes("Owner"))
+                console.log("✅ Content Check Passed (Mentions Owner)");
+            else console.log("❌ Content Check Failed (Missing Owner context)");
+
+        } else {
+            console.log("❌ No Mechanism Story returned.");
+        }
+
+    } catch (e) {
+        console.error("Verification failed:", e);
+    }
+}
+
+verifyPhase3();

backend/src/analyzers/ExplanationEngine.ts

@@ -0,0 +1,74 @@
+
+import { TraceResult } from './OpcodeTracer.js';
+
+export interface Explanation {
+    title: string;
+    story: string; // The "No-Jargon" story
+    severity: 'High' | 'Medium' | 'Low' | 'Safe';
+}
+
+export class ExplanationEngine {
+
+    static generateExplanation(trace: TraceResult, simulationStatus: string): Explanation {
+
+        // Default safe state
+        let explanation: Explanation = {
+            title: "Security Check Passed",
+            story: "No suspicious mechanisms detected during execution.",
+            severity: "Safe"
+        };
+
+        if (simulationStatus.startsWith("Reverted")) {
+            return this.explainRevert(trace);
+        }
+
+        // Detect Time Logic (even if success)
+        if (trace.usesTimestamp) {
+            explanation = {
+                title: "Time-Sensitive Logic Detected",
+                story: "The contract checks the current time. It might be locked until a specific date.",
+                severity: "Medium"
+            };
+        }
+
+        return explanation;
+    }
+
+    private static explainRevert(trace: TraceResult): Explanation {
+        // Did it revert after checking WHO sent it?
+        if (trace.usesMsgSender || trace.usesTxOrigin) {
+            // Heuristic: If we saw Sender -> Storage Read -> Revert, it's likely a Whitelist or Owner check
+            const lastEvents = trace.events.slice(-5);
+            const hasStorageCheck = lastEvents.some(e => e.includes("CHECK: Storage read"));
+
+            if (hasStorageCheck) {
+                return {
+                    title: "Access Denied (Whitelist/Owner)",
+                    story: "❌ The contract checked who you are and blocked the transaction. It likely requires you to be on a private 'Whitelist' or be the Owner.",
+                    severity: "High"
+                };
+            }
+
+            return {
+                title: "Sender Restriction",
+                story: "❌ The contract blocked your address. Specific reason unclear, but it discriminates based on who sends the transaction.",
+                severity: "Medium"
+            };
+        }
+
+        // Did it revert after checking TIME?
+        if (trace.usesTimestamp) {
+            return {
+                title: "Time-Lock Active",
+                story: "❌ The contract checked the time and decided it's too early (or too late) to trade.",
+                severity: "High"
+            };
+        }
+
+        return {
+            title: "Transaction Failed",
+            story: "❌ The transaction reverted. This might be a standard error, or a hidden blocking mechanism.",
+            severity: "Low"
+        };
+    }
+}

backend/src/analyzers/OpcodeTracer.ts

@@ -0,0 +1,115 @@
+
+export interface ExecutionStep {
+    opcode: string;
+    pc: number;
+    stack: string[];
+    depth: number;
+    memory?: string;
+}
+
+export interface TraceResult {
+    steps: ExecutionStep[];
+    events: string[];
+    revertReason?: string;
+    touchedStorage: Set<string>;
+    usesMsgSender: boolean;
+    usesTxOrigin: boolean;
+    usesTimestamp: boolean;
+    suspiciousJumps: number;
+}
+
+export class OpcodeTracer {
+    private steps: ExecutionStep[] = [];
+    private events: string[] = [];
+    private touchedStorage = new Set<string>();
+    private usesMsgSender = false;
+    private usesTxOrigin = false;
+    private usesTimestamp = false;
+    private suspiciousJumps = 0;
+
+    // Track state for pattern matching (simple state machine)
+    private lastOpcode: string | null = null;
+    private pushedSender = false;
+
+    constructor() { }
+
+    handleStep(data: any) {
+        const opcode = data.opcode.name;
+        const pc = data.pc;
+        const depth = data.depth;
+
+        // Capture stack (top 5 items for efficiency)
+        const stack = data.stack ? data.stack.slice(-5).map((x: any) => x.toString(16)) : [];
+
+        this.steps.push({
+            opcode,
+            pc,
+            stack,
+            depth
+        });
+
+        // Taint Analysis / Pattern Matching
+
+        // 1. Sender Tracking
+        if (opcode === 'CALLER') { // msg.sender
+            this.usesMsgSender = true;
+            this.pushedSender = true;
+            this.events.push(`TAINT: msg.sender loaded at PC ${pc}`);
+        } else if (opcode === 'ORIGIN') { // tx.origin
+            this.usesTxOrigin = true;
+            this.events.push(`TAINT: tx.origin loaded at PC ${pc}`);
+        }
+
+        // 2. Storage usage logic
+        if (opcode === 'SLOAD') {
+            const slot = stack[stack.length - 1]; // Top of stack is slot key
+            this.touchedStorage.add(slot);
+            if (this.pushedSender) {
+                this.events.push(`CHECK: Storage read after Sender load - Potential Whitelist/Balance check`);
+            }
+        }
+
+        // 3. Time usage logic
+        if (opcode === 'TIMESTAMP') {
+            this.usesTimestamp = true;
+            this.events.push(`TAINT: block.timestamp loaded at PC ${pc}`);
+        }
+
+        // 4. Comparison Logic (EQ/LT/GT)
+        if (['EQ', 'LT', 'GT', 'SGT', 'SLT'].includes(opcode)) {
+            // If we just loaded sender or timestamp, this is a distinct check
+            if (this.lastOpcode === 'CALLER' || this.lastOpcode === 'ORIGIN') {
+                this.events.push(`CHECK: Comparing Sender address`);
+            }
+            if (this.lastOpcode === 'TIMESTAMP') {
+                this.events.push(`CHECK: Comparing Timestamp`);
+            }
+        }
+
+        // 5. Control Flow (JUMPI)
+        if (opcode === 'JUMPI') {
+            // If JUMPI happens after a critical check, it's a decision point
+            // This is minimal; real taint analysis requires stack tracing
+        }
+
+        // Reset transient flags
+        if (!['PUSH1', 'PUSH2', 'PUSH20', 'PUSH32', 'DUP1', 'DUP2'].includes(opcode)) {
+            // Keep pushedSender tag alive only through direct data manipulation
+            this.pushedSender = false;
+        }
+
+        this.lastOpcode = opcode;
+    }
+
+    getTrace(): TraceResult {
+        return {
+            steps: this.steps,
+            events: this.events,
+            touchedStorage: this.touchedStorage,
+            usesMsgSender: this.usesMsgSender,
+            usesTxOrigin: this.usesTxOrigin,
+            usesTimestamp: this.usesTimestamp,
+            suspiciousJumps: this.suspiciousJumps
+        };
+    }
+}

backend/src/analyzers/SecurityAnalyzer.ts

@@ -18,6 +18,12 @@ export interface SecurityReport {
     analyzedAddress?: string; // The actual address analyzed (implementation if proxy)
     ownerAddress?: string; // [NEW] Needed for Counterfactual Simulation
     friendlyExplanation?: string;
+    mechanismStory?: {
+        title: string;
+        story: string;
+        severity: string;
+    };
+    tracingEvents?: string[];
 }
 
 export class SecurityAnalyzer {

backend/src/evm/EvmExecutor.ts

@@ -6,6 +6,8 @@ import { SecurityAnalyzer } from "../analyzers/SecurityAnalyzer.js";
 import { ProxyDetector } from "../analyzers/ProxyDetector.js";
 import { ScanHistory } from "../services/ScanHistory.js";
 import { AdvancedSimulator } from "../analyzers/AdvancedSimulator.js";
+import { OpcodeTracer } from "../analyzers/OpcodeTracer.js";
+import { ExplanationEngine } from "../analyzers/ExplanationEngine.js";
 
 export class EvmExecutor {
     constructor() { }
@@ -114,16 +116,26 @@ export class EvmExecutor {
         let sstoreCount = 0;
         let callCount = 0;
 
+        const tracer = new OpcodeTracer();
+
         evm.events.on('step', (data: any) => {
             if (instructionCount === 0) console.log("[Fork] First opcode executed:", data.opcode.name);
             instructionCount++;
             if (data.opcode.name === 'SSTORE') sstoreCount++;
             if (['CALL', 'DELEGATECALL', 'STATICCALL', 'CALLCODE'].includes(data.opcode.name)) callCount++;
+
+            // [PHASE 3] Dynamic Capability Tracing
+            tracer.handleStep(data);
         });
 
         console.log(`Executing Call: from=${sender.toString()} value=${txParams.value}`);
         const { status, result } = await this.executeCall(evm, txParams, sender);
 
+        // [PHASE 3] Generate Mechanism Story
+        const traceResult = tracer.getTrace();
+        const mechanismStory = ExplanationEngine.generateExplanation(traceResult, status);
+        console.log("[Phase3] Mechanism Story:", mechanismStory.story);
+
         console.log("EVM Execution Complete.");
         console.log(`Analysis: ${instructionCount} steps, ${sstoreCount} sstores`);
 
@@ -176,6 +188,10 @@ export class EvmExecutor {
             console.log("Running Security Checks on:", addressToAnalyze.toString());
             securityReport = await SecurityAnalyzer.analyze(evm, addressToAnalyze, { status }, activeProvider);
 
+            // [PHASE 3] Attach Detective Insights
+            securityReport.mechanismStory = mechanismStory;
+            securityReport.tracingEvents = traceResult.events;
+
             if (proxyInfo) {
                 securityReport.proxyInfo = proxyInfo;
                 if (proxyInfo.isProxy) {
@@ -237,6 +253,33 @@ export class EvmExecutor {
                 console.warn("[Phase2] Advanced simulation failed:", advErr.message);
             }
 
+            // [PHASE 3 Refinement] Reconcile Phase 2 and Phase 3
+            // If Phase 2 detected a scam (Revert/Honeypot) but Phase 3 trace (local) was Safe, it's likely due to missing storage.
+            // We trust Phase 2 (RPC-based) more for outcomes.
+            if (advancedAnalysis && advancedAnalysis.isScam && securityReport.mechanismStory.severity === 'Safe') {
+                console.log("[Phase3] Reconciling: Overwriting Safe story with Phase 2 detection.");
+
+                if (advancedAnalysis.counterfactual.hasOwnerPrivileges) {
+                    securityReport.mechanismStory = {
+                        title: "Privilege Abuse Detected",
+                        story: "🕵️ The Detective noticed a discrepancy: Expected safe execution, but real-world simulation confirms only the OWNER can trade. This is a clear Honeypot.",
+                        severity: "High"
+                    };
+                } else if (advancedAnalysis.timeTravel.isTimeSensitive) {
+                    securityReport.mechanismStory = {
+                        title: "Hidden Time-Lock",
+                        story: "🕵️ The Detective found that while code looks clean, it relies on time checks (likely uninitialized in scan) that strictly block trading.",
+                        severity: "High"
+                    };
+                } else {
+                    securityReport.mechanismStory = {
+                        title: "Hidden Revert Mechanism",
+                        story: "🕵️ The execution path is misleading. Deep simulation confirms this transaction WILL fail for you, likely due to hidden storage dependencies.",
+                        severity: "High"
+                    };
+                }
+            }
+
             console.log("Security Report:", securityReport);
 
             const chainIdNum = typeof chainId === 'string' && chainId.includes(':') ? parseInt(chainId.split(':')[1]) : Number(chainId);