A Unified Framework for Function-Level Vulnerability Detection and Explanation in Smart Contracts

Abstract

Smart contracts enable decentralized applications, yet their immutability makes security vulnerabilities catastrophic, often leading to irrecoverable financial losses and systemic risks. Existing machine learning approaches typically operate at the coarse contract level, failing to localize issues to specific functions or provide interpretable remediation guidance for developers. To address these persistent limitations, we introduce a unified framework combining a novel Hierarchical Cross-Attention Subgraph Neural Network (HCA-SGNN) for detection with Large Language Models (LLMs) for explanation. For detection, HCA-SGNN processes functions as subgraphs, explicitly modeling control- and data-flow dependencies while capturing cross-function interactions to pinpoint localized risks. To enable robust training, we develop an AST-driven injection system that generates stealthy, context-aware vulnerabilities through template-based synthesis. Uniquely, this system ensures collision-free variable naming and version-specific compatibility, producing a comprehensive, function-level annotated dataset covering diverse classes such as reentrancy, integer overflows, and access control flaws. Complementing detection, we generate structured, human-readable justifications using synthetic data and chain-of-thought prompting. These explanations detail the vulnerability type, affected area, root cause, and actionable mitigation strategies, effectively bridging the gap between automated detection and practical insight. Together, these components form a comprehensive framework that significantly enhances both the technical accuracy and operational usability of smart contract analysis.