Contract Registry

Disclaimer: This is a summary of patterns we have observed during our research and should not be considered any form of technical or investment advice. Also, the given “known examples” do not imply they are the best implementations of the said pattern or any superior to any other implementation of the pattern not listed.

Summary

Maintain a registry mapping a smart contract name and the address of its latest version as a (name, address) pair. Before invoking a smart contract, look up the registry to find its address.

Context

Like 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 and fulfil new requirements.

Problem

A smart contract deployed on a blockchain cannot be upgraded because the smart contract (binary) code is stored as immutable ledger data. Therefore, when a new version of the smart contract is deployed, it will be assigned a different address. Not all transaction issuers may be aware of the existence of the new smart contract version or its address. How to reach the latest version of smart contracts?

Forces

  • Immutability – Every bit of data, including deployed smart contracts, stored on the blockchain is immutable.
  • Upgradability – There is a fundamental need to upgrade all but short-lived applications and their smart contracts over time.
  • Human-readable names – The identifier of a smart contract on blockchain platforms, like Ethereum, is a hexadecimal address hence not human-readable.
  • Transparency – Updates to a smart contract should be visible to all its stakeholders.

Solution

We could adopt the idea of DNS (Domain Name Service) to resolve this issue. Like DNS resolves a human-readable name to an IP address(es), a symbolic name can be given to a smart contract and then map it to the address of the latest version using a look-up table.

Contract registry pattern

First, deploy a smart contract to maintain the mapping between user-defined symbolic names and the blockchain addresses of registered smart contracts. A service that keeps track of a set of (name, address) pairs is typically referred to as a registry. Second, advertise the address of the registry smart contract off-chain. Then the creator/manager of a smart contract can register the name and the address of the contract to the registry once it is deployed onto the blockchain. Forth, the invoker of a registered contract retrieves the latest address of the smart contract from the registry contract. Finally, once a new version of the smart contract is deployed, the creator/manager can update the registry to replace the previous address with the new address.

The contract address should be stored as a variable in the registry contract such that it can be updated. Also, to prevent a random party from updating a registry entry, the creator/manager of the contract should be tracked and write permission should be validated at the time of the update. Smart contract version control can be supported by extending the (name, address) pair to be a (name, version, address) tuple. However, if the old version of a smart contract should no longer be used, it should not be retained in the registry. If the smart contract function definitions also change with the upgrade, techniques such as API or service interface management need to be implemented, e.g., through versioning and depreciation flags.

Benefits

  • Human-readable names – The registry contract maintains a mapping between human-readable names and the hexadecimal addresses of the smart contracts. A human-readable form of smart contract names is desired, e.g., to be exposed to the user interface or for developer testing.
  • Constant contract name – The smart contract associated with a registered name can be updated without changing its symbolic name. This way dependencies relying on the name of the smart contract do not get broken.
  • Transparency – The smart contract associated with a registered name could be replaced by a new version while ensuring it is visible to all stakeholders. Also, all the previous addresses of the contract are still stored on the blockchain.
  • Version control – Version control can be integrated into the registry contract to allow a lookup based on the name and version of a smart contract.

Drawbacks

  • Upgradability – Upgradability is still limited if the functions defined in the smart contract are directly called by other contracts. Although the implementation of the function can be upgraded, the interface (i.e., function signature) cannot be modified without breaking the dependencies.
  • Cost – There is an additional cost to deploy and update the registry. Furthermore, all the inter-contract function calls require a registry look-up to find the latest version of the smart contract to be invoked. However, in most blockchains read requests are free.

Related Patterns

  • The embedded permission pattern could be used to define write permission of a registry entry.
  • A factory contract can use the registry to include addresses of the contracts spawned from the same smart contract template.
  • The proxy contract is an alternative pattern that hides the latest contract instance from its users.
  • Data contract and this pattern can work together to further improve the upgradability of smart contracts.
  • The token registry is another pattern that maintains the ownership information of tokens by mapping the token identifier and wallet address.
  • The identifier registry is a pattern that maintains bindings between an identifier and the address of an identity attribute.

Known uses

  • ENS is a name service on the Ethereum blockchain that 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 a blockchain platform, which is accessible to everyone.
  • Regis is an in-browser application that makes it easy to build, deploy, and manage registries as smart contracts on the Ethereum blockchain. It allows user-defined key-value pairs. It can be used to create a contract registry.
  • Lorikeet is a model-driven engineering tool for blockchain-based business and asset management that supports the generation of general registry contracts. It can also track the updates to registry entries.