Smart contracts on the blockchain play an important role in decentralised systems by automating and executing agreements without the need for intermediaries. As these contracts become integral to various domains, ensuring users’ understanding of their functioning is paramount. This article investigates the need for explanations in smart contracts, drawing inspiration from contract law principles and established practices in Explainable AI (XAI). It introduces key purposes—justification, clarification, compliance and consent to design explainability. Additionally, the study proposes a novel assessment framework informed by the Metacognitive Explanation-Based (MEB) theory to systematically evaluate surprise potential in smart contracts lacking explanations. We use surprise as a guiding factor to systematically identify areas requiring improvement in terms of justification, clarification, compliance and consent. To demonstrate the utility of the assessment approach, we evaluate two decentralised lending projects, uncovering potential surprises. One of the key observations is the lack of setting information, especially concerning compliance, consent and decision justification. This absence of information has heightened the potential for surprises. In the process of validating the explanation purposes, we implement techniques to improve the design of the assessed smart contracts. Further, the research explores the tradeoffs involved in integrating explanations, providing nuanced insights into economic implications such as increased deployment and execution costs. This work contributes to the broader comprehension of smart contract explainability requirements and lays out a theoretical foundation for a generic evaluation method. It aims to facilitate the development of more human-centric and comprehensible smart contracts.

Blockchain smart contracts (SCs) have emerged as a transformative technology, enabling the automation and execution of contractual agreements without the need for intermediaries. However, as SCs evolve to become more complex in their decentralised decision-making abilities, there are notable difficulties in comprehending the underlying reasoning process and ensuring users’ understanding. The existing literature primarily focuses on the technical aspects of SC, overlooking the exploration of the decision-making process within these systems and the involvement of humans. In this paper, we propose a framework that integrates human-centered design principles by applying Situation Awareness (SA) and goal directed task analysis (GDTA) concepts to determine information requirements necessary to design eXplainable smart contracts (XSC). The framework provides a structured approach for requirements engineers to identify information that can keep users well-informed throughout the decision-making process. The framework considers factors such as the business logic model, data model, and roles and responsibilities model to define specific information requirements that shape SC behaviour and necessitate explanations. To guide the determination of information requirements, the framework categorises SC decision mechanisms into autonomy, governance, processing, and behaviour. The ExplanaSC framework promotes the generation of XSC explanations through three levels aligned with SA: XSC explanation for perception, XSC explanation for comprehension, and XSC explanation for projection. Overall, this framework contributes to the development of XSC systems and lays the foundation for more transparent, and trustworthy decentralized applications. The XSC explanations aims to facilitate user awareness of complex decision-making processes. The evaluation of the framework uses a case to exemplify the working of our framework, its added value and limitations, and consults experts in the field for feedback and refinements.