An Extended Pattern Collection
for Blockchain-based Applications

Summary: Introduce the state of external systems into the closed blockchain execution environment through a single centralized connector (called oracle). Fig. 2 is a graphical representation of the pattern.

Context: From the software architecture perspective, blockchain can be viewed as a component or connector within a large software system [26]. In the case where blockchain is used as a distributed database for more general purposes other than financial services, the applications built on blockchain might need to interact with other external systems. Thus, the validation of transactions on blockchain might depend on states of external systems.

Problem: Smart contracts running on blockchain are pure functions by design. The execution environment of smart contract is self-contained. It can only access information present in the data and transactions on the blockchain.The state of external systems are not directly accessible to smart contracts. How can function calls in smart contracts be enabled to access the state of the external world from within smart contracts?

Forces: The problem requires to balance the following forces:

• •

  Closed environment. Blockchain is a secure, self-contained environment, which is isolated from external systems. Smart contracts on blockchain cannot read the states of the external systems.

• •

  Connectivity. In addition to the data found on the blockchain, general-purpose applications might require information from external systems. For example, a parcel tracking application needs context information like geo-location information, a gambling application might need weather data from a Web API⁷⁷7https://openweathermap.org/api.

Solution: To connect the closed execution environment of blockchain with the external world, oracle is introduced to assist in evaluating conditions that cannot be expressed in a smart contract running within the blockchain environment. If the information flows from blockchain to external world, Reverse Oracle (Section 4.4) should be used. An centralized oracle is a trusted third party that provides the smart contracts with information about the external world. When validation of a transaction depends on external state, the oracle is requested to check the external state and inject the result to the blockchain in a transaction signed using its own key pair. The validators (miner) take the result provided by the oracle into account when validating the transaction. From the perspective of validator, by introducing the oracle, the validation of transactions is based on the authentication of the oracle (through digital signature) rather than the external state because what provided by oracle is trusted by the validator. From the perspective of the validator, the data injected from oracle is no different from data provided (through embedding into a transaction or as a variable value) by other users. What validators can do is to ensure the data integrity by checking the digital signature of the sender and executing the smart contract based on the input data, but they cannot check the originality or correctness of the input data from external world. More technical details of implementing the pattern could be found in  [16].

Consequences:

Related patterns:

• •

  Decentralized Oracle (Section 4.1) can be used to avoid the single point of failure introduced by a centralized oracle.

• •

  Reverse Oracle (Section 4.4) can be used when the information flows from blockchain to external components.

Known uses:

• •

  Oracle in Bitcoin is an instance of this pattern ⁸⁸8https://en.bitcoin.it/wiki/Contract#Example_4:_Using_external_state. Oracle is a server outside the Bitcoin blockchain network, which can evaluate user-defined expressions based on the external state.

• •

  Provable⁹⁹9https://provable.xyz/ is an oracle service provider, which utilises trusted hardware to directly fetch information from external trusted execution environment (TEE). Provable introduces three different proofs for fetching data from external data sources, namely, TLS-Notary, Ledger proof and Android proof.

• •

  Corda¹⁰¹⁰10https://www.corda.net/ has a centralized oracle mechanism embedded in its platform. The oracle mechanism uses Intel Software Guard Extensions (SGX) for hardware attestation to prevent unauthorised access outside of the SGX environment.

Summary: Introduce the state of external systems into the closed blockchain execution environment through a cluster of connectors (called oracles). Fig. 3 is a graphical representation of the pattern.

Context: In the case where blockchain is used as a distributed database for more general purposes other than financial services, the applications built on blockchain might need to interact with other external systems. A centralized oracle (Section 4.1) can be applied to inject the states of external systems into blockchain.

Problem: A centralized oracle introduces a single trusted third party into the system, which might becomes a single point of failure of the whole software system.

Forces: The problem requires to balance the following forces:

• •

  Reliability and Availability. A centralized oracle becomes a single point of failure from an architecture perspective. In the case that the status injected into the blockchain is a faulty status, the whole system might behave inaccurately. In the case that the oracle is unable to inject any state to the system, the whole system might be stuck and unavailable depending on how critical the state is.

• •

  Cost. The cost of data retrieval from external world is proportional to the number of oracles.

Solution: To improve trustworthiness of the oracle, a decentralized oracle mechanism is introduced, which is based on multiple oracles. These oracles can get data from one data source or multiple independent data sources. Voting (Section 4.3) can be applied to decentralized oracle to reach a consensus on the status to be injected into the blockchain.

Consequences:

Related patterns:

• •

  Centralized Oracle (Section 4.1) can be used if a single oracle is trusted by all the participants involved into a transaction.

• •

  Reverse Oracle (Section 4.4) can be used when the information flows from blockchain to external componnets.

• •

  Voting (Section 4.3) (Section 6.2) can be applied with decentralized oracles to achieve consensus among multiple oracles.

Known uses:

• •

  Orisi¹¹¹¹11http://orisi.org/ on Bitcoin maintains a set of independent oracles. Orisi allows the participants involved in a transaction to select a set of oracles and define the value of M (number of oracles) before initiating a conditional transaction.

• •

  Gnosis¹²¹²12https://gnosis.io/ is a decentralized prediction market that allows users to choose any oracle they trust, such as another user or a web service, e.g. , for weather forecasts. A human oracle is also called arbitrator, who is trusted by the interacting participants to resolve disputes or check external state.

• •

  Augur¹³¹³13https://www.augur.net/ is another prediction market that leverages the capability of human oracles to do prediction and resolve disputes.

Summary: To achieve an agreement on a state proposed on blockchain, anyone with blockchain account can propose tentative new state or vote for a proposed state by staking their tokens until a consensus is achieve. Fig. 4 is a graphical representation of the pattern.

Context: The public access of blockchain provides equal rights that allow [27] every participant the same ability to access and manipulate the blockchain. This property of blockchain enables a way for blockchain users to make decisions together and achieve consensus on the result. During the consensus process, everyone has equal right to participate in decision making. In the context of decentralized oracle, especially the one using human oracles, blockchain users use different sources to report the result. They may have different preferences.

Problem: During a process to achieve an agreement on certain state on blockchain, what if the state proposed by an blockchain account (oracle or human) is disputed?

Forces: The problem requires to balance the following forces:

• •

  Fairness. Every participant in blockchain network has a equal right to access and manipulate the blockchain. Each participant’s vote should have the same weight as the others.

• •

  Consensus. Multiple participants in different opinions need to reach an agreement to make decision. Participants also need to agree on which of the many paths leading to an outcome based on their preferences (e.g., simple or qualified majority) is taken.

• •

  Transparency/Auditability. The voting process should be deterministic and auditable so that the outcome can be reproduced from the same input (which should not disappear after the vote).

Solution:

Consequences:

Related patterns:

• •

  Decentralized Oracles (Section 4.2) works with voting pattern to achieve consensus on the answer reported to blockchain.

• •

  Security Deposit (Section 7.5) provides a mechanism for participants to weight their vote using their stake.

• •

  Multiple Authorization (Section 6.2) is one on-chain mechanism to enable voting.

• •

  Dynamic Authorization (Section 6.2) is one off-chain mechanism to enable voting.

Known uses:

• •

  Voting mechanism is used in DAOs (Decentralised Autonomous Organisations)¹⁵¹⁵15https://www.ethereum.org/dao.

• •

  In Gnosis¹² prediction market, a voting mechanism is used if someone challenges the reported outcome. This voting mechanism allows users to vote on what the correct outcome was by betting Ether on that outcome.

• •

  In Augur¹³ prediction market, a similar voting mechanism is used to resolve disputes on the outcome reported by oracles.

Summary: The reverse oracle of an existing system relies on smart contracts running on blockchain to validate requested data and check required status. Fig. 5 is a graphical representation of the pattern.

Context: In a software system, where blockchain is one of the components, the off-chain components might need to use the data stored on the blockchain and the smart contracts running on the blockchain to check certain conditions.

Problem: Some domains use very large and mature (or even legacy) systems, which comply with existing standards. For such domain, how to integrate the existing complex systems with blockchain in an non-intrusive approach without changing the core of the existing systems?

Forces: The problem requires to balance the following forces:

• •

  Connectivity. Integrating blockchain into an existing system to leverage the unique properties of blockchain, as discussed in Section 2.1.1.

• •

  Simplicity. Introduce minimal changes to the existing system.

Solution: The unique ID of the transactions or blocks on blockchain is a piece of data that can be easily integrated into the existing systems so that they can refer to specific transactions as having taken place or address data permanently stored in specific blocks. Reverse Oracle is a component sitting between the blockchain and the other components in the system. Reverse Oracle is mainly reading data from the blockchain, and inserting the reference (ID of transaction) of this data into other components in the system. Oracle, however, is mainly writing data into the blockchain from other components. Validation of such data is implemented by smart contracts running on blockchain. Any off-chain component is required to query the blockchain through using the ID of the referenced data. More technical details of implementing the pattern could be found in  [16].

Consequences:

Related patterns:

• •

  Centralized Oracle (Section 4.1) and Decentralized Oracles (Section 4.2) can be used when the information flows from external to blockchain.

Known uses:

• •

  Identitii¹⁶¹⁶16https://identitii.com/ provides a solution to enrich the payments in banking systems with documents and tamper-proof attributes stored on a private blockchain. Identitii invents the concept of identity token stored on a blockchain. Every payment is associated with an identity token, which is used to exchange enriched information about a payment. The identity token is exchanged between the banks through being embedded into existing SWIFT protocol messages and can be verified against the copy in the blockchain.

• •

  Chaintrace¹⁷¹⁷17https://chainflux.com/wine-traceability-using-blockchain/ records all the information about a wine, such as source, location, volume of the ingredients on blockchain. Chaintrace can be connected to external supply chain system and injects relevant information about a bottle of wine for cross verification.

Summary: Using tokens on blockchain to represent fungible goods for easier distribution.

Context: The concept of tokenisation has emerged centuries ago with the first currency systems. Tokenisation is a means to reduce risk in handling high value financial instruments by replacing them with equivalents, for example, the tokens used in casino. Tokens can represent a wide range of goods which are transferable and fungible, like shares, or tickets. Blockchain is a suitable technique for asset management because of its immutability and transparency.

Problem:

Forces: The problem requires to balance the following forces:

• •

  Risk. Handling fungible financial assets with high value is risky, e.g., lost assets cannot be replaced.

• •

  Repetition. An asset should be represented by only one token as the authoritative source.

Solution: Tokenisation is a process starting from an asset (e.g., money) is locked under a custody (e.g., a bank), and gets represented in the cryptographic world through a token. The ownership of the digital token matches the ownership of the corresponding asset. The reverse process can take place by which the user redeems the token to recover the value which is sitting within the bank.

Consequences:

Related patterns:

• •

  Off-Chain Data Storage (Section 5.2) can be used to add a hash of a digital asset as an ID on blockchain.

Known uses:

• •

  Digix²⁰²⁰20https://digix.global/ uses tokens to track the ownership of gold as a physical property.

• •

  Elevated Returns²¹²¹21https://www.elevatedreturns.com/ is an asset management firm that uses tokenisation to manage ownership on real estates.

• •

  CargoX²²²²22https://cargox.io/ creates a smart token to replace their bill of lading. The ownership of goods are claimed by using the smart token.

Summary: Use hashing to ensure the integrity of arbitrarily large datasets which may not fit directly on the blockchain. Fig. 6 is a graphical representation of the pattern solution.

Context: Some applications consider using the blockchain to guarantee the integrity of large amounts of data.

Problem: The blockchain, due to its full replication across all participants of the blockchain network, has limited storage capacity. Storing large amounts of data within a transaction may be impossible due to the limited size of the blocks of the blockchain (for example, the gas limit on Ethereum). Data cannot take advantage of the immutability or integrity guarantees without being stored on the blockchain. How to store data of arbitrary size and take advantage of the immutability and integrity guarantees provided by the blockchain?

Forces: The problem requires to balance the following forces:

• •

  Integrity. Applications leverage blockchain to achieve data integrity.

• •

  Scalability. Blockchain provides limited scalability because every bit of data is replicated across all nodes, where it is kept permanently.

• •

  Cost. If a public blockchain is used, storing data on blockchain costs real money, although the cost is a one-time cost to write the data. This is in contrast to traditional distributed data storage, like cloud, which charge based on the amount of allocated storage space over time. A piece of data can be stored on blockchain through being embedded into a transaction, or as a variable of smart contract or as a log event. Embedding data into a transaction is the cheapest way, while storing data in a contract is more efficient to enable manipulation, but can be less flexible due to the potential constraints of the smart contract languages on the value types and length [27]. Different blockchain has different cost model for storing data.

• •

  Size. There are limits of transaction size or block size. For example, on Bitcoin blockchain, The default Bitcoin client only relayed $\mathit{OP\_RETURN}$ transactions up to 80 bytes, which was reduced to 40 bytes in 2014²³²³23https://github.com/bitcoin/bitcoin/pull/3737. Ethereum has a block gas limit that restricts the amount of gas which all transactions in a block are allowed to use.

Solution: The blockchain can be used as a general-purpose replicated database, as transactions logged in the blockchain can include arbitrary data on some blockchain platforms. For data of big size (essentially data that is bigger than its hash value), rather than storing the raw data directly on blockchain, a representation of the data with smaller size can be stored on blockchain with other small sized metadata about the data (e.g., a URI pointing to it). The solution is to store a hash value (also called digest) of the raw data on chain. The value is generated by a hash function, e.g. one from the SHA2 [7] family, which maps data of arbitrary size to data of fixed size. Hash function is a one-way function which is easy to compute, but hard to invert given the output of a random input. If even one bit of the data changes, its corresponding hash value would change as well. The hash value is used for ensuring the integrity of the raw data stored off-chain, and the transaction on blockchain that includes the hash value guarantees the integrity of the hash value as well as the original raw data from which the hash was derived.

Consequences:

Related patterns:

• •

  Tokenisation (Section 5.1) can be used to add a authoritative representative of an asset on blockchain.

• •

  Legal and Smart Contract Pair (Section 5.4) is enabled by Off-Chain Data Storage.

Known uses:

• •

  Proof-of-Existence (POEX.IO²⁴²⁴24https://poex.io/) allows entering an SHA-256 cryptographic hash of a document into the Bitcoin blockchain as a “proof-of-existence” of the document at a certain time. The hash value guarantees the data integrity of the document.

• •

  Chainy²⁵²⁵25https://chainy.info/ is a smart contract running on Ethereum blockchain. Chainy stores a short link to an off-chain file and its corresponding hash value in one place.

Summary: Micro-payments transactions are too expensive to be performed on-chain because the required transaction fee might be higher than the monetary value associated with the transaction assuming a public blockchain is used. Thus, micro-payments should be exchanged off-chain while periodically recording settlements for larger amounts on chain. Such a payment channel can be generalized for arbitrary state updates for more general purposes other than monetary value. Fig. 7 is a graphical representation of the pattern.

Context: Micro-payments are payments that can be as small as a few cents, e.g., payment of a very small amount of money to a WiFi hot-spot for every 10 kilobytes of data usage. Blockchain has potential to be used for such financial transactions with tiny monetary value. The question is if it is necessary and cost effective to store all the micro-payment transactions on blockchain.

Problem: The decentralized design of blockchain has limited performance. Transactions can take several minutes or even one hour (for Bitcoin blockchain) to be committed on the blockchain [21]. Due to the long commit time and high transaction fees on a public blockchain (where fees are largely independent of the transacted amount), it is often infeasible to store every micro-payment transaction on the blockchain network. During a peak in demand, the average fee per transaction raised to the equivalent of US$55²⁶²⁶26 https://bitinfocharts.com/comparison/bitcoin-transactionfees.html for 22 Dec 2017; accessed on 11/03/2021. on Bitcoin. On-chain transactions are suitable for transactions with medium to large monetary value, relative to the transaction fee.

Forces: The problem requires to balance the following forces:

• •

  Trustworthiness. Payment transactions on the blockchain are trusted.

• •

  Latency. Blockchain transactions may take a long time to be committed while users expect micro-payments to happen instantaneously.

• •

  Scalability. Blockchain has limited scalability because every bit of data is replicated across all nodes, and kept permanently.

• •

  Cost. Storing data on a public blockchain costs real money. The transaction fee of individual micro-payment transaction might be higher than the monetary value associated with the micro-payment transaction.

Solution: Storing every micro-payment transaction on blockchain is infeasible in certain contexts due to the small monetary value associated with it. Thus, a solution is to establish a payment channel between two participants, with a deposit from one or both sides of the participants locked up as security in a smart contract for the lifetime of the payment channel. The payment channel keeps the intermediate states of the micro-payment off-chain, and only stores the finalized payment on chain. The frequency of transaction settlement depends on the use case, and agreement between the two sides. For example, in scenarios around utilities, internet service providers or electricity companies can establish payment channel with their consumers for an agreed billing period, for example, a month. As the consumer uses data or energy daily, the intermediate state is stored in the channel until the end of the month, when the channel is closed to finalize the payment of that month. A network of micro-payment channels can be built where the transactions transferring small values occur off-chain. The individual transactions take place entirely off the blockchain and exclusively between the participants, across multiple hops where needed. Only the final transaction that settles the payment for a given channel or set of channels is submitted to the blockchain. The technologies used to implement state channel are normally specific to blockchain platform. For example, Lightning network²⁷²⁷27https://lightning.network/ on the Bitcoin blockchain is a proposed implementation of Hashed Timelock Contracts (HTLCs)²⁸²⁸28https://en.bitcoin.it/wiki/Hashed_Timelock_Contracts with bi-directional payment channels which allows secure payments across multiple peer-to-peer channels. A HTLC is a type of payments that use the features of Script, like hashlocks and timelocks, to require that the receiver of a payment acknowledges receiving the payment prior to a deadline by generating cryptographic proof.

Consequences:

Related patterns:

• •

  Off-Chain Data Storage (Section 5.2) is another mechanism that reduces data on blockchain.

Known uses:

• •

  The Lightning network uses an off-chain protocol to enable micro-payments of Bitcoin and several other crypto-currencies.

• •

  The Raiden network²⁹²⁹29https://raiden.network/ on the Ethereum blockchain is a similar solution as lightning network. The basic idea is to avoid the consensus bottleneck by leveraging a network of off-chain payment channels that allow to securely transfer monetary value. Smart contracts are used to deposit value into the payment channels.

• •

  State channel on Ethereum³⁰³⁰30http://www.jeffcoleman.ca/state-channels/ and Gnosis Go³¹³¹31https://forum.gnosis.pm/t/how-offchain-trading-will-work/63 offer a more generalized form of state channels that support exchanging state for general-purpose applications.

Summary: A bidirectional binding is established between a legal agreement and the corresponding smart contract. Fig. 8 is a graphical representation of the pattern.

Context: The legal industry is becoming digitized, for example, using digital signatures has become a valid way to sign legal agreements. The Ricardian contract [10] was developed in the mid 1990s to interpret legal contracts digitally without losing the value of the legal prose. Digital legal agreements need to be executed and enforced.

Problem: An independent trustworthy execution platform trusted by all the involved participants is needed to execute the digital legal agreement. How to bind a legal agreement to the corresponding smart contract on a trusted execution environment to ensure a 1-to-1 mapping?

Forces: The problem requires to balance the following forces:

• •

  Authoritative source. A 1-to-1 mapping is required between a legal contract and its corresponding smart contract to make the smart contract as the authoritative source of the legal contract.

• •

  Secure storage. A secure and trustworthy data storage is required to keep the legal agreement.

• •

  Secure execution. A trustworthy computational platform is required to execute digital agreements to enforce certain conditions as defined in a legal contract.

Solution:

Consequences:

Related patterns:

• •

  Legal and Smart Contract Pair is enabled by Off-Chain Data Storage (Section 5.2) .

Known uses:

• •

  OpenLaw³²³²32http://openlaw.io/ is a platform that allows lawyers to make legally binding and self-executable agreements on the Ethereum blockchain. The legal agreement templates are stored on a decentralized data storage, IPFS³³³³33https://ipfs.io/. Users can create customized contracts for specific uses.

• •

  Smart Contract Template proposed by Barclays³⁴³⁴34https://www.barclays.co.uk/ uses legal document templates to facilitate smart contracts running on Corda10 blockchain platform [5, 6].

• •

  Specific proposals for the representation of machine-interpretable legal terms have been explored in KWM’s project on digital and analog (DnA) contracts³⁵³⁵35https://github.com/KingandWoodMallesonsAU/Project-DnA and in the Accord Project³⁶³⁶36https://www.accordproject.org/.

Summary: Ensure confidentiality of the data stored on blockchain by encrypting it. Fig. 9 is a graphical representation of the pattern.

Context: For some applications on blockchain, there might be commercially critical data that should be only accessible to the involved participants. An example would be a special discount price offered by a service provider to a subset of its users. Such information should not be accessible to the other users who do not get the discount.

Problem: The lack of data privacy is one of the main limitations of blockchain. All the information on blockchain is publicly available to the participants of the blockchain network. There is no privileged user within the blockchain network, no matter the blockchain is public, consortium or private. On a public blockchain, new participants can join the blockchain network freely and access all the information recorded on blockchain. Any confidential data on public blockchain is exposed to the public.

Forces: The problem requires to balance the following forces:

• •

  Transparency. Every participant within a blockchain network is able to access all the historical transactions on blockchain, which is required to enable them to validate previous transactions. The transactions on a public blockchain are also accessible to everyone with access to the internet, simply using tools like a blockchain explorer such as Etherscan³⁷³⁷37http://etherscan.io.

• •

  Lack of confidentiality. Since all the information on blockchain is publicly available to everyone in the network, commercially sensitive data meant to be kept confidential should not be stored on blockchain, at least not in plain form.

Solution: To preserve the privacy of the involved participants, symmetric or asymmetric encryption can be used to encrypt data before inserting the data into blockchain. One possible design for sharing encrypted data among multiple participants is as follows. First, one of the involved participants creates a secret key for encrypting data and distributes it during an initial key exchange. When one of the participants needs to add a new data item to the blockchain, they first symmetrically encrypt it using the secret key. Only the participants allowed to access the transaction have the secret key and can decrypt the information.

Consequences:

Related patterns:

• •

  Off-Chain Data Storage (Section 5.2) also provides data confidentiality because the raw data is not stored on blockchain.

Known uses:

• •

  Encrypted queries from Provable9. Provable is a smart contract running on Ethereum public blockchain, which provides a service to access state from external world. Provable allows smart contract developers to encrypt the parameters of their queries locally by using a public key before passing them to a smart contract. The only one who can decrypt the call parameters is Provable with the paired private key.

• •

  Crypto digital signature is suggested by MLGBlockchain³⁸³⁸38https://mlgblockchain.com/crypto-signature.html to encrypt data and share the data between the parties who interact and transmit data through blockchain.

• •

  Hawk [11] is a smart contract system that stores transactions as encrypted data on blockchain to retain the privacy of the transactions. The compiler of Hawk can automatically generate a cryptographic protocol for a smart contract. The involved participants interact with the blockchain following the cryptographic protocol.

Summary: A set of blockchain addresses which can authorise a transaction is pre-defined. Only a subset of the addresses is required to authorize transactions. Fig. 10 is a graphical representation of the pattern.

Context: In blockchain-based applications, activities might need to be authorized by multiple blockchain addresses. For example, a monetary transaction may require authorization from multiple blockchain addresses.

Problem: The actual addresses that authorize an activity might not be able to be decided due to the availability of the authorities. How to allow multiple authorities to dynamically authorize a transaction based on their avilability?

Forces: The problem requires to balance the following forces:

• •

  Flexibility. The actual authorities who authorize the transaction can be from a set of pre-defined authorities.

• •

  Tolerance of compromised or lost private key Authentication on blockchain uses digital signature. However, blockchain does not offer any mechanism to recover a lost or a compromised private key. Losing a key results in permanent loss of control over an account, and potentially smart contracts that refer to it.

Solution: It would enable more dynamism if the set of blockchain addresses for authorization are not decided before the corresponding transaction being submited into the blockchain network, or the corresponding smart contract being deployed on blockchain. On the Bitcoin blockchain, a multi-signature mechanism can be used to require more than one private key to authorize a Bitcoin transaction. In Ethereum, smart contract can mimic multi-signature mechanism.

Consequences:

Related patterns:

• •

  Dynamic Authorization (Section 6.3). An off-chain secret enabled dynamic authorization pattern is used when the possible authorities are unknown beforehand.

• •

  Voting (Section 4.3) can be enabled by Multiple Authorization.

Known uses:

• •

  Multi-Signature mechanism provided by Bitcoin³⁹³⁹39https://en.bitcoin.it/wiki/Multisignature.

• •

  Multi-signature wallet, written in Solidity, running on Ethereum blochchain and is available in the Ethereum DApp browser Mist⁴⁰⁴⁰40https://github.com/ethereum/mist.

Summary: Using a hash created off-chain to dynamically bind authority for a transaction. Fig. 11 is a graphical representation of the pattern. This solution is sometimes referred to as Hashlock.

Context: In blockchain-based applications, some activities need to be authorized by one or more participants that are unknown when a first transaction is submitted to blockchain.

Problem: Sometimes, the authority who can authorize a given activity is unknown when the corresponding smart contract is deployed, or the corresponding transaction is submitted to the blockchain. Blockchain uses digital signature for authentication and transaction authorization. Blockchain does not support dynamic binding with an address of a participant which is not defined in the respective transaction or smart contract. All accounts that can authorize a second transaction have to be defined in the first transaction before that transaction is added to the blockchain. How to allow one or more unknown authorities to dynamically authorize a transaction?

Forces: The problem requires to balance the following forces:

• •

  Dynamism. Dynamic binding one or more unknown authorities with a second transaction representing an activity after the first transaction submitted to blockchain.

• •

  Pre-defined authorities. Using only on-chain mechanisms, all the possible authorities are required to be defined beforehand.

Solution: An off-chain secret can be used to enable a dynamic authorization when the participant authorizing a transaction is unknown beforehand. In the context of payment, for example, a smart contract can be used as an escrow. When the sender deposits the money to an escrow smart contract, a hash of a secret (for example, a random string, called pre-image) is submitted with the money as well. Whoever receives the secret off-chain can claim the money from the escrow smart contract by revealing the secret. With this solution, the receiver of the money does not need to be defined beforehand in the escrow contract. This can be generalized to any transaction that needs authorization from a dynamically bound participant. Note that since the secret is revealed, it cannot be reused. One variant is to lock multiple transactions with the same secret – by unlocking one, all of them are unlocked.

Consequences:

Related patterns:

• •

  Multiple Authorization (Section 6.2). The multiple authorization pattern is used when all the possible authorities are known beforehand. Multiple authorization pattern is an on-chain mechanism.

• •

  Voting (Section 4.3) can be enabled by Dynamic Authorization.

• •

  Dynamic Authorization enables routability for State channel (Section 5.3) in the financial transaction scenarios.

Known uses:

• •

  Raiden network29 is a network of off-chain payment channels on top of Ethereum blockchain network, which enables secure value transfer. The multi-hop transfer mechanism in Raiden Network uses hashlocked transactions to securely router payment through a middleman.

• •

  In the Bitcoin ecosystem, atomic cross-chain trading⁴¹⁴¹41https://en.bitcoin.it/wiki/Atomic_cross-chain_trading allows one crytocurrency (for example, Bitcoin) to be traded for another cryptocurrency (for example, tokens on a Bitcoin sidechain) using a off-chain hash secret.

Summary: Smart contracts use an embedded permission control to restrict access to the invocation of the functions defined in the smart contracts. Fig. 12 is a graphical representation of the pattern.

Context: All the smart contracts running on blockchain can be accessed and called by all the blockchain participants and other smart contracts by default, because there are no privileged users in blockchain network. In the case of public blockchain, every one with internet access can join the network to access all the information and code stored and running on blockchain.

Problem: A smart contract by default has no owner, meaning that once deployed the author of the smart contract has no special privilege on the smart contract. A permission-less function can be triggered by unauthorized users accidentally. Such a permission-less function becomes vulnerability of blockchain-based application. For example, a permission-less function which is discovered in a smart contract library used by the Parity multi-signature wallet, caused the freezing of about 500K Ethers⁴²⁴²42https://paritytech.io/a-postmortem-on-the-parity-multi-sig-library-self-destruct/. 7% smart contract on public Ethereum can be terminated without authority [21].

Forces: The problem requires to balance the following forces:

• •

  Security. The functions defined in the smart contracts should be called only by the authorized participants. Due to the transparency of public blockchains, all the smart contracts are also publicly available to everyone connecting to the Internet. In contrast, in a conventional software system, the internal logic is normally not visible to the end uses. Interaction with the software system is either through a user interface or API, where it is possible to enforce access control policies.

Solution: Adding permission control to every smart contract function to check permissions for every caller that triggers the functions defined in the smart contract based on the blockchain addresses of the caller. This can be done by checking the authorization of the caller before executing the logic of the function: unauthorized calls are rejected and the execution of the function terminated before reaching the core logic of the function.

Consequences:

Related patterns:

• •

  Multiple authorization (Section 6.2) is one way of implementing embedded permission pattern.

• •

  Dynamic authorization (Section 6.3) is another way of implementing embedded permission pattern.

Known uses:

• •

  The Mortal contract discussed in the Solidity tutorial⁴³⁴³43http://solidity.readthedocs.io/en/develop/contracts.html restricts the permission of invoking the selfdestruct function to the “owner” of the contract – where “owner” is a variable defined in the contract code itself.

• •

  The Restrict access pattern suggested in the Solidity tutorial⁴⁴⁴⁴44http://solidity.readthedocs.io/en/develop/common-patterns.html uses modifier to restrict who can make modifications to the state of the contract or call the functions of the contract. Modifier is a mechanism that adds a piece of code before the function to check certain conditions.

Summary: Before invoking it, the address of the latest version of a smart contract is located by looking up its name on a contract registry. Fig. 13 is a graphical representation of the pattern.

Context: As any software application, blockchain-based applications need to be upgraded to new versions. To do so, the on-chain functions defined in smart contracts need to be updated to fix bugs as well as to fulfill new requirements.

Problem: Smart contracts deployed on blockchain cannot be upgraded because the code of the smart contracts as a type of data, stored on blockchain is immutable. How to perform upgrades of smart contracts?

Forces: The problem requires to balance the following forces:

• •

  Immutability. Every bit of data, including deployed smart contracts, stored on blockchain is immutable.

• •

  Upgradability. There is a fundamental need to upgrade all but short-lived applications and their smart contracts over time.

• •

  Human-readable contract identifier. The identifier of a smart contract on blockchain platforms, like Ethereum, is hexadecimal address, which is not human-readable.

Solution: An on-chain registry contract is used to maintain a mapping between user-defined symbolic names and the blockchain addresses of the registered contracts. The address of the registry contract needs to be advertised off-chain. The creator of a contract can register the name and the address of the new contract to the registry contract after the new contract being deployed. The invoker of a registered contract retrieves the latest version of the new smart contract from the registry contract. The corresponding functions provided by the registered contract can be upgraded by replacing the address of the old version contract in the registry contract with the address of a new version without breaking the dependency between the upgraded smart contract and other smart contracts that depend on its functions. The address of a contract is stored as a variable in the registry contract. The value of contract variables can be updated. The registry contract can have a permission control module to maintain the writing permission. Note that all the previous values of the variable are still stored on the blockchain.

Consequences:

Related patterns:

• •

  Embedded permission (Section 6.4) can be used to define writing permission.

• •

  Data contract (Section 7.2) and this pattern can work together to further improve upgradability of smart contracts.

Known uses:

• •

  ENS⁴⁵⁴⁵45https://ens.domains is a name service on Ethereum blockchain, which is implemented as smart contracts. ENS maintains a mapping between both smart contracts on-chain and resources off-chain and simple, human-readable names. ENS can be viewed as a contract registry built on Ethereum blockchain, which is accessible to everyone. A blockchain-based application can also maintain a separate registry contract for the application.

• •

  KairosFuture⁴⁶⁴⁶46https://www.kairosfuture.com/publications/reports/the-land-registry-in-the-block-chain-testbed/ experimented using blockchain smart contract as a replacement for land registry. All the signed contracts are recorded by a registry contract on the blockchain.

• •

  Kaleido⁴⁷⁴⁷47https://www.kaleido.io/blockchain-blog/smart-contract-management-solution-how-it-works-why-you-need-it proposed a enterprise-level smart contract management solution. The core function of their management solution is the contract registry that is accessable to every participants in Kaleido network.

Summary: Store data in a separate smart contract. Fig. 14 is a graphical representation of the pattern.

Context: The need to upgrade a blockchain-based application over time is ultimately necessary, so as the smart contracts used by the application. In general, logic and data change at different times and with different frequencies. There are different ways to store a data on blockchain, as discussed in Off-chain Data Storage pattern (Section 5.2).

Problem: Storing data on blockchain is expensive and there is a limitation on the amount of data and amount of computation a transaction can contain. In the context of upgrading smart contracts, the upgrading transactions might contain a large data storage for copying the data from the old version of the smart contract to the new version of the smart contract. Porting data to a new version might even require multiple transactions, e.g. when the block gas limit on Ethereum prevents an overly complex data migration transaction.

Forces: The problem requires to balance the following forces:

• •

  Coupling. Smart contracts can live forever on blockchain if not being explicitly terminated. If a smart contract is deactivated in this way, the data stored in the smart contract cannot be accessed through the smart contract functions any more – although it can still be accessed with some effort, e.g. for provenance or audit purposes.

• •

  Upgradability. The need to upgrade the application and the smart contracts supporting the application over time is ultimately necessary for many applications.

• •

  Cost. If a public blockchain is used, storing data on blockchain costs money. Thus copying data from an old version of a smart contract to a new version should be avoid or minimized.

Solution: To avoid moving data during upgrades of smart contracts, the data store is isolated from the rest of the code. In the context of blockchain, data could be separately stored in different smart contracts to enable isolation. Depending on the circumstances of the application, how large of a data store it needs and whether the data structure is expected to change often, the data store could use a strict definition or a loosely typed flat store. The more generic and flexible data structure can be used by all the other logic smart contracts and is unlikely to require changes. One example of a generic data structure is a mapping to store SHA-256 key and value pairs.

Consequences:

Related patterns:

• •

  Contract registry (Section 7.1) and Data Contract can work together to further improve upgradability of smart contracts.

Known uses:

• •

  Chronobank⁴⁸⁴⁸48https://chronobank.io/ is a blockchain project that tokenizes labour and provides a market for professionals to trade their labour time with businesses. It uses a smart contract with a generic data structure as the data store used by all the other logic smart contracts.

• •

  Colony⁴⁹⁴⁹49https://colony.io/, a platform for open organizations running on Ethereum. Similar to Chronobank, Colony has a data contract with a generic data structure.

Summary: An on-chain template contract is used as a factory that generates contract instances from the template. Fig. 15 is a graphical representation of the pattern.

Context: Applications based on blockchain might need to use multiple instances of a standard contract with customization. Each contract instance is created by instantiating a contract template. For example, in a business process management system, each of the business process instances might be represented by a smart contract being generated from a contract template representing the business process model [22]. The template can be stored off-chain in a code repository, or on-chain, within its own smart contract.

Problem: Keeping the contract template off-chain cannot guarantee consistency between different smart contract instances created from the same template because the source code of the template can be independently modified.

Forces: The problem requires to balance the following forces:

Solution: Smart contracts are created from a contract factory deployed on blockchain. The factory contract is deployed once from the off-chain source code. The factory may contain the definition of multiple smart contracts. Smart contract instances are generated by passing parameters to the contract factory to instantiate customized smart contract instances. Factory contract is analogous to a Class in an object-oriented programming language. Every transaction that generates a smart contract instance essentially instantiates an object of the factory contract class. This contract instance (the object) will maintain its own properties independently of the other instances but with a structure consistent with its original template.

Consequences:

Related patterns:

• •

  Contract registry (Section 7.1) can be used to store the addresses of all the smart contract instances generated from a factory contract. The factory and instance registry can be implemented in the same contract, although that limits upgradability.

Known uses:

• •

  A tutorial from Ethereum developers⁵⁰⁵⁰50https://ethereumdev.io/manage-several-contracts-with-factories/ about how to create a contract factory from which smart contract instances can be created.

• •

  Factory pattern has been applied in a real-world blockchain-based health care application [28].

• •

  The business process management system in an academic work [22] uses a contract factory to generate process instances.

Summary: Reward is provided to the caller of the contract function for invoking the execution. Fig. 16 is a graphical representation of the pattern.

Context: Smart contracts are event-driven programs, which cannot execute autonomously. All the functions defined in a smart contract need to be triggered either by a transaction from external account or another smart contract to execute. Other than the functions that provide regular services to users, some functions need to run asynchronously from regular user interaction, for example, to clean up the expired records, or make dividend payouts etc. Such accessorial functions usually involve a time, after which the function should start.

Problem: Users of a smart contract have no direct benefit from calling the accessorial functions. If a public blockchain is used, executing these functions causes extra monetary cost. Some accessorial functions are expensive to execute. How to make sure the the accessorial functions are invoked?

Forces: The problem requires to balance the following forces:

• •

  Completeness. The regular services provided by a smart contract are supported by some accessorial functions.

• •

  Cost. Execution of accessorial functions causes extra costs from the users.

Solution: Reward the caller of a function defined in a smart contract for invoking the execution, for example, sending back a percentage of payout to the caller to reimburse the (gas) execution cost.

Consequences:

Related patterns:

• •

  Both Security Deposit (Section 7.5) and Incentive Execution provide incentive mechanisms.

Known uses:

• •

  Ethereum alarm clock⁵¹⁵¹51http://www.ethereum-alarm-clock.com/ is a service provided by a smart contract running on Ethereum. It facilitates scheduling function calls for a specified block in the future and provides incentive for users to execute the scheduled function.

Summary: A user put aside a certain amount of money, which will be paid back to the user for her honesty or given to the other parties to compensate them for the dishonesty of the user. Fig. 17 is a graphical representation of the pattern.

Context: In a decentralized environment like blockchain, trust in the blockchain-based application is achieved from the interactions between participants within the network. A blockchain-based application rely on all the users rather than relying on trusted third-party organisations to facilitate transactions.

Problem: The equal rights property of blockchain allows every participant the same ability to access and manipulate the blockchain and the decentralized applications running on blockchain. How can a certain participant proves to others that he/she behaves honestly?

Forces: The problem requires to balance the following forces:

• •

  Security. The security of a decentralized application relies on the behaviour of all the participants of the application.

• •

  Incentive. In a decentralized application, participants can be incentivised to behave honestly.

Solution: Initially, participant is required to put aside amount of tokens, which will be paid back to the participant if she behave honestly, otherwise the deposit is given to the other parties to compensate them for their loss. Such security deposit is recorded on blockchain, which is publicly available to other parties. Security deposit is a way to reduce the risk of participants in the network misbehave by temporarily sacrificing some of her stake.

Consequences:

Related patterns:

• •

  Both Incentive Execution (Section 7.4) and Security Deposit provide incentive mechanisms.

Known uses:

• •

  The notion of “deposits” has already been used in Bitcoin’s contract⁵²⁵²52https://en.bitcoin.it/wiki/Contract#Example_1:_Providing_a_deposit, where deposit is bought by a party with no reputation as a proof of her trust.

• •

  Ethereum alarm clock51 enables scheduling of transactions for delayed execution in the future. Before the execution window, there is a claim window when the request may be claimed by a participant for execution. To claim a request, the participant is required to put down a deposit. If the claimer fulfils their commitment to execute the request, the deposit is returned to them, otherwise, the deposit is given to someone else that executes the request as an additional reward.

Summary: Decentralized applications (DApps) are applications running on P2P network rather than a single computer. DApps are blockchain-based web applications that allow users to interact with smart contracts deployed on blockchain. Fig. 18 is a graphical representation of the pattern.

Context: Users interact with smart contracts through sending transactions to invoke the functions defined in smart contracts. In order for the users to understand how to interact with a smart contract, the source code of the smart contract is open source and visible to users. Second, the application binary interface (ABI) of the smart contract is also publicly accessible so that users can send transactions to it.

Problem: Users need a strong technical understanding of blockchain and smart contract to be able to generate transactions calling smart contracts. Such process is error-prone and with a bad user experience [23]. How to call a smart contract in a trustless environment?

Forces: The problem requires to balance the following forces:

• •

  Learning Curve. Users need to understand the functionality of a smart contract before being able to interact with it. To understand the input required and the output produced by a smart contract, users need to read the documentation or the source code of the smart contract.

• •

  Convenience. Manually generating transactions to interact with an smart contract is an error-prone process despite the understanding of the smart contract. Depending on whether many transactions need to be sent, it may be worth to invest into automating the transaction submission process.

• •

  Trust. The user needs to trust the provider of such automated transaction submission process.

Solution: DApp provides a front-end user interface for users to easily interact with smart contracts. The frond end uses the same technology as conventional web applications to render web pages. The difference is that DApps can be hosted on a decentralized storage, like IPFS, and are rendered by DApp browsers, like Ethereum Mist40 or a plug-in to a web application browser, like MetaMask⁵³⁵³53https://metamask.io/. Both the smart contract on blockchain and the DApp is deployed on a local node. The transactions calling smart contracts are generated by DApps, and are presented to the users for further verification before being sent to the blockchain.

Consequences:

Related patterns:

• •

  Semi-DApp (Section 8.2) can be browsed using a conventional web browser without any DApp plugin.

Known uses:

• •

  State of the DApps⁵⁴⁵⁴54https://www.stateofthedapps.com/ provides a directory of the DApps on Ethereum blockchain. There are 1800+ DApps with different levels of maturity registered to the directory. DappRadar⁵⁵⁵⁵55https://dappradar.com/ also provides a directory of DApps, not only on Ethereum blockchain but also included DApps deployed on EOS⁵⁶⁵⁶56https://eos.io/ and TRON⁵⁷⁵⁷57https://tron.network/index?lng=en.

• •

  Remix⁵⁸⁵⁸58https://remix.ethereum.org is an open source smart contract compiler that allow user to write and interact with Solidity contracts from the browser.

Summary: Semi-DApp provider offers a web application, which can be browsed using a conventional web browser without any DApp plugin (like MetaMask). Fig. 19 is a graphical representation of the pattern.

Context: Users interact with smart contracts through sending transactions to invoke the functions defined in smart contracts. In order for the users to interact with a smart contract, the source code of the smart contract is open source and visible to users. Second, the application binary interface (ABI) of the smart contract is also publicly accessible.

Problem: Users need a strong technical understanding of blockchain and smart contract to be able to generate transactions and interact with smart contracts. Such process is error-prone, with a bad user experience [23]. Even with a front-end that assists the user to interact with smart contracts, some basic technical knowledge regarding transactions and gas is still required by users to use DApps and verify the transactions generated by the DApps (Section 8.1). It is not feasible for non-technical user to learn and understand the source code of smart contract to use it.

Forces: The problem requires to balance the following forces:

• •

  Learning Curve. Users need some basic technical knowledge of smart contracts in order to use DApps.

• •

  User Experience. Due to the decentralization nature of DApps, the front-end of most DApps is quite simple, and exposes too many technical details of the underlying smart contract, which not all users are capable to grasp.

Solution: Semi-DApp provider offers a standard web application for users to easily interact with smart contracts. The web application keeps the technical details of the corresponding smart contracts opaque to the users. The website communicates with the backend through RESTful API callsThus, the backend is responsible for interacting with the smart contracts on behalf of the user who is not able to inspect nor validate the transactions being sent to the blockchain. The transaction ID is normally returned to the user for the user to check the transaction on blockchain using blockchain explorer, like EtherScan37.

Consequences:

Related patterns:

• •

  DApp (Section 8.1) allows users to interact with smart contracts.

Known uses:

• •

  Cryptocurrency exchanges are common examples of this patterns as they always interact with the blockchain on behalf of the users. Kraken⁶⁰⁶⁰60https://www.kraken.com/ is a San Francisco-based Bitcoin exchange.

• •

  Binance⁶¹⁶¹61https://www.binance.com/ is a cryptocurrency exchange founded in China.