Token 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

A token registry maintains the ownership information of tokens by mapping the token identifier and wallet address.

Context

A buyer (i.e., token owner) needs to pay a certain number of tokens to purchase a product or service. When a payment is made, the respective tokens’ ownership needs to be transferred from the buyer to the seller. Further, tracking historical ownership of tokens is required to ensure traceability. The payment application needs to manage a large number of transacting parties, tokens, and transactions.

Problem

How can a large number of tokens, their owners, and transactions be effectively tracked?

Forces

  • Dynamism – The ownership of tokens could change frequently.
  • Scalability – A large number of token and their owners need to be mapped.
  • Transparency – Transfer of token ownership needs to be tracked for compliance auditing

Solution

A table in the form of a token registry contract can be used to record the ownership information of tokens by mapping the token identifier (ID) to the owner’s wallet address. As seen in the figure below, the issuer first registers both the token ID and wallet address of the buyer as variables in the token registry smart contract. The registry may also keep track of the token balance. This registry provides the ground truth on token ownership, as it could be manipulated only through the smart contract by authorised parties. For example, while both the buyer and seller can verify their token status, only the buyer can initiate a request to transfer a token. When a product to be purchased, the buyer requests the registry to transfer the desired number of tokens. As it is in the seller’s best interest to ensure it receives only the accepted types of tokens, the seller could then confirm the token transfer to indicate its willingness to accept the tokens. Once confirmed, the registry smart contract updates the buyer’s and seller’s token balances. Delivery of product is handled off-chain.

Sequence diagram of token registry.

 

Writing permission to the registry can be added through a per-mission control module. For example, only the issuer should register tokens and perform the forced transfer for legal action or fund recovery. Further, it can be specified that ownership transfer should proceed only if the token is in the spendable state or once the seller approves. Such conditions can be checked through a method in the registry. If the conditions are not met, the registry can throw an error rather than receiving the token. This pattern can be generalised to keep track of eligible sellers and a matrix that maps products and sellers. For example, a registry contract can maintain the seller attributes such as names, wallet addresses, certifications, and accolades.

Benefits

  • Traceability – Traceability is enhanced, e.g., how many tokens are owned by whom at what time is reflected in the registry.
  • Upgradability – Because the token ownership and balance data are managed separately by the token registry, the rest of the smart contract code can be upgraded without changing the token registry contract.
  • Cost – By separating token ownership data from the application code, there is no additional cost for data migration when the application logic is upgraded.

Drawbacks

  • Cost – Recording ownership data in smart contract incur an additional cost if a public blockchain is adopted. Further, there could be additional costs for updating the registry while executing a transaction.

Related patterns

  • The token template pattern can use the token registry to maintain the ownership information of tokens generated using the token contract.
  • This pattern can also be used to build the credentials registry of sellers used in the seller credential pattern.
  • Once redeemed, a spent token can be destroyed or marked as unusable by the registry using the burned token pattern.
  • The contract registry is another pattern that maintains a registry mapping a smart contract name and the address of its latest version.
  • The identifier registry is pattern that maintains bindings between an identifier and the address of an identity attribute.

Known uses

  • Perth Mint Gold token uses a registry contract to map physical gold ownership (specified via GoldPass certificates) to the owner’s Ethereum address.
  • Lorikeet is a model-driven engineering tool that generates centralised and distributed asset registry smart contracts compliant with ERC-20 and ERC-721 standards. It could further specify relationships and many-to-many mappings between attributes (within the same or a different registry), enforce access control, and track the history of changes made to assets tracked by the registry.
  • Parity Token Registry enables all the registered tokens to be visible to Parity wallet users.
  • Codefi and Cardano provide an ownership registry for Universal and Ada tokens, respectively.
  • Making Money Smart, Stadjerspas Smart Vouchers, and Pension Infrastructure use registries to specify eligible sellers and fund providers.