This repository contains software design patterns to address common challenges in the development of smart contracts, which we have identified in close collaboration with EnBW Energie Baden-Württemberg AG. Each directory of a software design pattern includes a README.md file with a pattern description and code examples. Feel free to use the code examples for your individual purposes. This repository is part of our publication "Challenges and Common Solutions in Smart Contract Development" published in the journal IEEE Transactions on Software Engineering.
We encourage you to support us in maintaining this repository and welcome your questions and comments on the software design patterns. To comment on the software design patterns, please open an issue for specific feedback on a software design pattern or post your general comments in the discussion section.
The theoretical pattern descriptions can be found in the pattern directory. Or just follow the links from the tables below. For practical examples and demonstrations take a look at our project-examples.
| Architectural Patterns | Usage | EOSIO | Ethereum | Hyperledger Fabric |
|---|---|---|---|---|
| Façade Pattern | Enable secure orchestration of smart contract systems | ☑ | ☑ | |
| Name-Service Pattern | Create a registry for smart contracts to assign intuitive names to smart contracts | ☑ | ||
| Observer Pattern | Automate communication of address changes due to updates in smart contracts | ☑ | ||
| Oracle Pattern | Enable access to external data for smart contracts | ☑ | ☑ | ☑ |
| Proxy Pattern | Enable code updatability of smart contract | ☑ |
| Design Patterns | Usage | EOSIO | Ethereum | Hyperledger Fabric |
|---|---|---|---|---|
| Commitment Pattern | Allow for binding commitments of values, which may remain secret until all values are to be revealed | ☑ | ☑ | ☑ |
| Event-Ordering Pattern | Ensure a transaction is only executed in a certain smart contract state | ☑ | ☑ | ☑ |
| Factory Pattern | Enable automatic redeployment of similar smart contracts | ☑ | ||
| Identity-Service Pattern | Enable decentralized identity management | ☑ | ☑ | |
| Indexed-Loop Pattern | Ensure an unbounded data structure can be interrupted and continued with the following call | ☑ | ☑ | |
| Mutex Pattern | Prevent reentrancy attacks | ☑ | ||
| Pull Pattern | Prevent abortion of execution caused by unbounded data structure and ensure fair distribution of costs | ☑ | ||
| Replay-Protection Pattern | Prevent variable overflow caused by unappropriate data type use | ☑ |
| Idioms | Usage | EOSIO | Ethereum | Hyperledger Fabric |
|---|---|---|---|---|
| Checks-Effects-Interactions Pattern | Prevent a reentrancy attack within the same function of the smart contract | ☑ | ||
| Deactivation Pattern | Disable a smart contract instead of destructing it so that all function calls result in a revert and no assets sent to the contract are lost | ☑ | ||
| Error-Handling Pattern | Handle errors in smart contracts appropriately | ☑ | ||
| External-Call Pattern | Handle failed external calls and prevent unintended side effects | ☑ | ||
| Guarding Pattern | Restrict authorization to execute smart contract functions to particular accounts in defined contexts | ☑ | ☑ | ☑ |
| Overflow/Underflow Pattern | Prevent variable overflow and underflow caused by inappropriate data type use | ☑ | ||
| Token Pattern | Mitigate the risks related to the update of smart contracts keeping tokens | ☑ |
To make smart contract developers aware of the peculiarities of smart contracts and how to deal with these peculiarities, we present several software design patterns. The software design patterns comprise three levels of abstractions:
-
Architectural patterns describe “[…] a fundamental structural organization or scheme for software systems and provide a set of predefined subsystems, specify their responsibilities, and include rules and guidelines for organizing the relationships between them” [1, p. 12].
-
Design patterns provide “[…] a scheme for refining the subsystems or components of a software system, or the relationships between them” [1, p. 13] to solve a general design problem within a specific context.
-
Idioms are patterns on the lowest level of abstraction and “describe[s] how to implement particular aspects of components or the relationships between them using the features of the given language” [1, p. 14].
Each pattern is comprised of components to describe the pattern consistently and comprehensively. In this repository, we follow the canonical form comprising the following elements:
-
Name: the pattern in one word "[…] to use a single word or short phrase to refer to the pattern, and the knowledge and structure it describes" [2, p. 5].
-
Context: "the preconditions under which the problem and its solution seem to recur, and for which the solution is desirable. This tells us the pattern's applicability" [2, p. 5].
-
Problem: "[…] the goals and objectives [the developer] wants to reach within the given context and forces. Often the forces oppose these objectives as well as each other" [2, p. 5].
-
Forces: "[…] the relevant forces and constraints and how they interact/conflict with one another and with goals we wish to achieve […]. Forces reveal the intricacies of a problem and define the kinds of trade-offs that must be considered in the presence of the tension or dissonance they create" [2, p. 5].
-
Solution: the "static relationships and dynamic rules describing how to realize the desired outcome. This is often equivalent to giving instructions which describe how to construct the necessary work products" [2, p. 5].
-
Examples: "one or more sample applications of the pattern which illustrate: a specific initial context; how the pattern is applied to, and transforms that context; and the resulting context left in its wake" [2, p. 6].
-
Resulting Context: "the state or configuration of the system after the pattern has been applied, including the consequences (both good and bad) of applying the pattern, and other problems and patterns that may arise from the new context. It describes the postconditions and side-effects of the pattern" [2, p. 6].
-
Rationale: "a justifying explanation of steps or rules in the pattern, and also of the pattern as a whole in terms of how and why it resolves its forces in a particular way to be in alignment with desired goals, principles, and philosophies" [2, p. 6].
-
Related Patterns: "the static and dynamic relationships between this pattern and others within the same pattern language or system" [2, p. 6].
-
Known Uses: "[…] known occurrences of the pattern and its application within existing systems" [2, p. 6].
[1] F. Buschmann, Ed., Pattern-oriented software architecture: a system of patterns. Chichester; New York: Wiley, 1996.
[2] B. Appleton, “Patterns and Software: Essential Concepts and Terminology.” 2000, Accessed: Aug. 02, 2019. [Online]. Available: http://www.enteract.com/~bradapp/docs/patterns-intro.html.