Identifier 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.


The identifier registry maintains bindings between an identifier and the address of an identity attribute (e.g., name and profile picture of a party).


An identity is defined as sets of attributes related to a party. An application needs to access an identity attribute, e.g., a hospital needs to access a patient’s name and age. An identifier should be globally unique. Hence, it is typically represented as a unique series of digits or characters, e.g., social security number and business number. An identifier is then used as a key to refer to other attributes of the identity. A Decentralised Identifier (DID) is a new type of identifier that is designed for cryptographically verifiable self-sovereign identity.


The mappings between an identifier and the identity data or its location is typically maintained by a centralised authority. This may become a single point of failure. How to maintain an identity and its attributes in a decentralised system?


  • Upgradability – Identity data needs to be updated over time, e.g., change of one’s profile photo or renewal of a business license.
  • Scalability – An identity may have a large number of static and dynamic attributes. Also, a large number of identities need to be handled.
  • Cost – Storing data on a blockchain may involve transaction fees.


Similar to the contract registry pattern we can use a smart contract to store and manage the list of (identifier, identity_attribute1, identity_attribute2, …, identity_attributen) tuples. Such a registry is referred to as an identity registry.

Identifier registry pattern

Identifier registry pattern

First, deploy a smart contract to keep track of the above tuples that binds an identifier and the identity attribute data. Second, for each identifier, record its identity attributes on the smart contract using a set of transactions. Then query the identifier registry smart contract to retrieve the attribute(s) of an identity. As the queries are typically based on an identifier, it could be used as the key to index the identity registry. The registry should also allow updates to the tuples to reflect changes to the identity attributes. Only the identifier owner should be allowed to update the identity attributes. Hence, each tuple should also track ownership information.

Relatively small attribute data like name, date of birth, and the public key can be stored on-chain. Whereas large data like the photo, scan of a government-issued identity document, or even a digital certificate could be stored off-chain and their URIs could be included on-chain. To enhance the decentralisation of off-chain data they could be stored on a decentralised file system like IPFS.


  • Upgradability – Through the cryptographic access controls built into the blockchain, it is guaranteed that only the owner of the identity (i.e., the key owner) has the right to modify the data reference in the identifier registry.
  • Scalability – The data structure of the identifier registry is simple and lightweight, which only stores identifiers and locations of identity attributes.


  • Integrity – The off-chain identity data store might not be as secure as the blockchain. The raw data may be changed without authorisation. If IPFS is used for identity data storage, the change could be detected. However, without additional measures, it will neither be possible to recover the original data nor to prevent the change from happening in the first place.
  • Data loss – Since the raw data is stored off-chain, it may be deleted or lost.
  • Cost – If a public blockchain is used, there is a cost to store and update an identifier and its identity attributes.

Related patterns

  • Using the multiple registration pattern an entity can register multiple identifiers.
  • In the dual resolution pattern, entities resolve each other’s identifiers in the identifier registry.
  • Predefined delegates in the delegate list pattern can change the binding key of a compromised identifier in the identity registry.
  • In master and sub-key generation pattern entities register identifiers in the identifier registry through their sub-keys.
  • The token registry is another pattern that maintains the ownership information of tokens by mapping the token identifier and wallet address.
  • The contract registry is another pattern that maintains a registry mapping a smart contract name and the address of its latest version.

Known uses

  • In uPort, the registry contract maintains mappings between an identifier and an IPFS hash linking to a data structure storing a party’s attributes.
  • Sovrin offers a registry for decentralised identifiers and the associated public keys and communications endpoints. The operations (i.e., registration, update, resolution, and revocation) are all determined by the Sovrin protocol.
  • Jolocom distributed identity system integrates Ethereum blockchain and IPFS. A deployed smart contract maintains the mapping from a DID to the corresponding DID document stored in IPFS.