The Sovrin Identity Metasystem is based on a sophisticated stack of protocols, implemented in open-source code, backed and supported by hundreds of organizations, large and small, around the world. The metasystem can be used to build identity systems for any context and provides people with autonomy and freedom to make choices about how information that identifies them is shared and used. This post describes how the metasystem is implemented by the Sovrin SSI Stack.

This post is based on Section 2 of the Sovrin Technical Architecture paper that Drummond Reed and I authored (to be published). Many others contributed to the thinking and provided useful critique and editing.

The Sovrin Network is a metasystem for building identity systems. The metasystem provides the means for anyone to issue, hold, present, accept, and verify credentials. The metasystem provides a universal means of discovering issuer identifiers and credential definitions in the ledger layer, and a universal protocol, called DIDComm, for connecting and sharing credentials in the agent layer. This universal protocol, combined with interoperable agents, creates an interoperable ecosystem. Participants share this interoperable ecosystem while exchanging credentials to solve their own individual problems.

The issuance, presentation, and verification of credentials in the Sovrin Network takes place within a stack of protocols and technologies. The Sovrin Stack comprises four layers:

  1. The Ledger Layer
  2. The Agent Layer
  3. The Credential Exchange Layer
  4. The Governance Layer

These layers are shown in Figure 1. The rest of this paper will discuss each layer in detail.

The Sovrin SSI Stack
The Sovrin SSI Stack (click to enlarge)

Layer One: The Sovrin Public Ledger

The bottom layer of the stack is the Sovrin Public Ledger. This decentralized ledger is specifically designed to support identity transactions and has several important properties:

  • Publicly accessible—this ledger is publicly readable and writable so that anyone can use it without an intermediary. This makes the network resistant to censorship. By having a decentralized network of nodes run by Sovrin Stewards around the world, anyone will be able to access the network at any time, even if one or many nodes get shut down or become inoperable.
  • Open source—the ledger nodes each run Hyperledger Indy, an open-source distributed ledger purpose-built for decentralized identity.
  • It enables the generation of state proofs—the ledger is capable of generating state proofs1 that can be used by Sovrin-compatible clients to know the state of the ledger without having to download and access the entire ledger. Each state proof contains a time stamp so the client can decide if the state proof is current enough for their use case or needs to be refreshed. This makes it ideal for use in credential verification where the clients may not have internet access for a period of time, a key requirement for universal adoption of digital credentials.

    In addition, state proofs can be cross anchored on other ledgers to increase reliability, trustworthiness, and resistance to censorship. This allows any holder to present a verified credential stored in their digital wallet—such as a driver’s license—anywhere and at any time in order to prove an attribute about themselves—such as their age—as needed, for example, to purchase a product requiring a legal minimum age.

  • Inexpensive to operate—transaction validation on the ledger is performed by known entities under proof-of-authority, making ledger access inexpensive enough to support the Network’s mission of establishing Identity for All (I4A). This means everyone—regardless of circumstances—has access to the Sovrin Network. The Sovrin Foundation’s I4A Council partners with NGOs, civil society organizations, and other groups promoting more inclusive identification systems to help bring identity network technology to populations who may not otherwise be served.
  • Provides support for the Sovrin Protocol Token—the ledger supports transactions of the Sovrin Token and ties it to identity transactions.

Unlike many other blockchain-based identity systems, using the Sovrin Network does not require storing personal identifying information, encrypted or otherwise, on the ledger. Rather, the Sovrin Network uses the ledger to store credential definitions, decentralized identifiers (DIDs) for issuers, schema definitions, and revocation registries. Without a decentralized ledger to store these, the Sovrin Network would have a single point of failure for these critical objects.

Objects like DIDs are created by Transaction Authors and added to the ledger by Stewards acting as Transaction Validators. Because the Sovrin Network is public, anyone can be a Transaction Author. But only organizations that function as Sovrin Stewards can validate the transactions that enable proof-of-authority consensus. Validation is done using a modified Redundant Byzantine Fault Tolerance algorithm implemented as Indy Plenum.

Storing credential definitions, and supporting data, on the ledger ensures that a credential verifier can test the fidelity of the credential without having to talk directly to the issuer. Fidelity allows the verifier to know the identifier of the issuer and that the credential was issued to the holder who is presenting it, hasn't been tampered with, and hasn't been revoked. The ledger breaks the circuit so that issuers don't know who is using a credential or when the credential is being used, a critical privacy provision. The ledger also lowers the cost and complexity for credential issuers since they don't have to maintain an always-on API for verifiers to use.

Decentralized Discovery and Governance of the Ledger

If the ledger is the basis for decentralized discovery, then we must ensure that no single organization controls the ledger and that it is protected from being taken down or corrupted by a single entity or by multiple entities.

The Sovrin Foundation and its Technical Governance Board (TGB) has designed the ledger and its governance to ensure that the ledger is public, open, and decentralized. This design includes three main groups: Sovrin Stewards, who operate the ledger nodes; Transaction Authors, who write DIDs and other cryptographic objects to the ledger; and Transaction Endorsers, who have permission to write to the ledger on behalf of Transaction Authors under the current Permissioned Write Access policies (PDF). These policies are only transitional until the Sovrin Foundation is able to provide Public Write Access. Sovrin infrastructure is designed to be censorship resistant such that no company or special interest can control who can use the protocol. All transactions are assigned validation priority through a transparent and fair algorithm maintained by the TGB. Public authorship of Sovrin transactions on a ledger via Public Write Access policies represent the best means available to combat censorship.

One key idea in decentralized systems is that different parts of the system are under the control of different organizations. Censorship resistance requires that even though Stewards must meet certain requirements to participate, it must still be assumed that any node might be hostile because of an attack or other circumstances beyond the control of the Steward. The Hyperledger Indy distributed ledger architecture provides this important property.

Because the Sovrin Network is based on blockchain technology and run by a large number of diverse validators (Sovrin Stewards), censorship becomes extremely difficult, if not practically impossible. Even if one or several of these access points stops actively participating in the Sovrin Network, there will still be someone who will provide access, as long as the governance rules are followed.

Because transaction authoring is a public function, the use of a ledger also ensures that under Public Write Access policies people can access, write, and update identifiers without being subject to gatekeeping. Note that it is possible that a specific gatekeeper—a Sovrin Steward—might restrict access to certain people, groups, or jurisdiction as a result of a compromised server, legal restrictions in its own jurisdiction, or other circumstances beyond its control. However, because the Sovrin Network is decentralized, people will still be able to access the ledger by using another Sovrin Steward’s node.

Decentralized Identifiers and Their Properties

Decentralized identifiers, or DIDs, are a new kind of identifier that provides the means of managing relationships in a self-sovereign identity system. DIDs resolve to DID Documents. DID Documents describe the public keys, authentication protocols, and service endpoints necessary to initiate trustworthy interactions with the identified entity. A DID Document is associated with exactly one DID. The W3C Credentials Community Group has published a global DID specification that is used in the Sovrin Network (and the W3C is currently forming a full W3C DID Working Group for further standardization of DIDs).

Decentralized identifiers in Sovrin infrastructure have these important properties:

  • Non-reassignable—DIDs are permanent, persistent, and non-reassignable. Permanence ensures that the identifier always references the same entity. As a result, DIDs are more private and more secure than identifiers that can be reassigned, such as a domain name, IP address, email address, or mobile number. Permanence is vital for identity holder control and self-sovereignty.
  • Resolvable—Resolution is the act of looking up the DID Document for a specific DID as defined by the specification for that particular type of DID, called the DID method. All Sovrin DIDs use the Sovrin DID method. Taken as a whole, DID infrastructure functions as a global, decentralized key-value store where DIDs act as the keys and DID Documents are the values.
  • Cryptographically verifiable—DIDs are associated with cryptographic keys, and the entity controlling the DID can use those keys to prove ownership (a process known as DID authentication). The result of resolving a DID may be cryptographically signed to ensure its integrity. The resolution also provides one or more public keys associated with the DID. Using cryptographic keys, the owner can prove they are in control of the DID. Parties who have exchanged DIDs directly with each other—called a peer-to-peer connection—can mutually authenticate each other and encrypt their communication.
  • Decentralized—DIDs are designed to function without a central registration authority. Sovrin DIDs can be created by anyone, anywhere, and for any purpose.

The Sovrin Network uses two kinds of DIDs: public and peer. Each has a different role in the operation of the network.

Public DIDs are created by people or organizations who are issuing credentials. The DID for a credential issuer must be written to the Sovrin Ledger so that they are capable of being resolved by anyone. When someone wishes to verify a credential, they retrieve the issuer's DID from the credential definition and then resolve—look up—the public DID to retrieve the associated DID Document of the issuer. Then, they use the public key in the DID Document and the digital signature of the credential to ensure it is is valid and has not been tampered with. They can also cryptographically verify that the credential was issued to the holder and that it has not been revoked.

Peer DIDs are not written to the Sovrin Ledger because they don’t need to be publicly resolvable. Instead, identity owners can issue a peer DID directly to another identity owner for peer-to-peer identity verification. By decentralizing verification, peer DIDs transform communication between verifiable entities in important ways (for full details, see the Peer DID Method Specification).

First, peer DIDs improve security because there is no need to use correlatable identifiers, such as email addresses, phone numbers, or credit card numbers, for verification. Therefore, decentralizing identity through peer DIDs eliminates the honey pots of data that centralized identity systems create and which become recurring targets of data breaches. Even if a peer DID was hacked in some way, it would be easy to cancel. Cancelling a peer DID is like cancelling a single-use credit card number—it does not affect any other relationship except the one party it was shared with.

Second, peer DIDs increase privacy because people are no longer dependent on centralized messaging systems (like WhatsApp or iMessage) to communicate with other parties; communication is peer-to-peer and cannot be “overheard”.

Third, peer DIDs provide more reliable communication as a decentralized network is more resistant to service interruption than centralized identity systems (almost every single node on the network would have to be disrupted). Peer DIDs also make communication between entities frictionless and controllable in ways not possible within centralized systems. If we want to sever a relationship with a particular entity, there is no impact on any other entity we have a relationship with. DID messaging through the use of peer DIDs is like having a dedicated private phone for every entity you engage with.

Finally, the use of peer DIDs allows for much greater scalability of the DID resolution infrastructure, since the vast majority of DIDs are private and those are resolved on a peer-to-peer basis rather than through access to the Sovrin Ledger or some other blockchain.

Layer Two: The Agent-to-Agent Protocol

Agents are the basis for peer relationships in Sovrin infrastructure. The protocol used by agents, called DIDComm2, is defined in an open, public process inside the Hyperledger Aries project.

The Sovrin Network is designed so that personal identifying information does not need to be stored on the ledger. The design does this by using software agents that provide people with a place to hold, manage, and use keys and credentials. Sovrin identity owners usually have at least two agents, one on a device and one in the cloud3. If an identity owner has more than one device, all of their devices are likely to each have an agent.

Sovrin agents operate independently from each other in a heterarchical peer-to-peer topology. Agents communicate with each other for DID and credential sharing without an intermediary. They do not need the ledger to communicate. Communication between agents is done via peer-to-peer signed and encrypted DIDComm messages. The two agents in a peer relationship authenticate each other using the keys associated with the peer DIDs they exchanged when they established a relationship. Each agent has its own keys, and keys are never copied between agents.4

The use of device agents is highly decentralized because all keys and credentials are stored on the device at the very edges of the internet. Cloud agents, though hosted in the cloud, are also decentralized because they can be either self-hosted or run by any qualified service provider, called an agency. The cloud agent, like the edge agent, is always, wholly under the control of the person or organization who owns it. Most people using the Sovrin Network will opt to use an agency. There can be any number of agencies, and cloud agent operation is standardized so that identity owners should be able to easily switch agencies.

An agency does not have access to the data stored in a cloud agent. As a rule, cloud agent data is stored encrypted and can only be decrypted by device agents using keys stored at the edge of the network where they are safest. So, barring a coding problem that opens a security hole, there is no honey pot of information in an agency. The use of open source code for agencies should further reduce risk because the contributed code is constantly monitored and tested for quality and security by a global community of expert engineers and security professionals.

The peer-to-peer architecture of agents and their availability from multiple agencies creates a decentralized system for storing, managing, and using keys and credentials. This not only is a boon to identity owner privacy and autonomy, it also gives Sovrin infrastructure the potential to support an unlimited number of relationships.

Self-sovereign identity needs to be robust. It should be difficult for an accident or malice to wrest control of an identity away from its rightful owner, and it should be easy to fix problems if they arise. The DIDComm protocol includes strong decentralized key management and support for people to recover from accidents5 and attacks.

Layer Three: Credential Transmission

The third layer of the Sovrin technology stack is the credential transmission protocol that determines how the issuer’s agent issues credentials to the credential holder, how the credential verifier requests information from the credential holder, and how the credential holder presents a proof of information from their credentials that the verifier can trust (as explained in 1.4.2).

Credentials are defined by their issuer using a credential definition. The credential definition links the public DID of the issuer, the schema for the credential, and a revocation registry for the credential. The definition, public DID, schema, and revocation registry are all stored on a distributed ledger that is used for decentralized discovery—on the Sovrin Network, this is the Sovrin Ledger. The use of a publicly visible and verifiable credential definition provides credentials with important properties:

  1. Credentials are remotely verifiable. The public DID links the credential to its issuer, its public key, and other service information.
  2. Credentials are machine readable and understandable. The schema provides verifiers with information about the meaning and structure of the credential.
  3. Credentials can be revoked. The revocation registry allows the holder to prove to the verifier that the credential has not been revoked without the verifier needing to contact the issuer.

A single credential definition can be the root of millions of individual credentials because it links and records the public DID of the issuer, the schema, and revocation registry on the ledger. None of that information changes for credentials of the same type from the same issuer. It's like a rubber stamp that can be used to stamp many documents. By way of example, the Canadian provinces of British Columbia and Ontario have issued more than 1.4 million credentials proving official business registration for 529,000 companies using the Sovrin Network based on only a few credential definitions posted to the Sovrin Ledger.

Credential Exchange
Figure 2: Credential Exchange (click to enlarge)

Figure 2 shows an example of how the British Columbia credential issuing system operates: (1) Mary registers her Eco Tours business and receives a digital incorporation credential from the government of British Columbia. (2) Now Mary needs a loan for a new tour bus. When the bank’s online loan service asks for proof of incorporation, she presents her digital incorporation credential issued by British Columbia. Using the Sovrin Network, the bank verifies Mary’s credential and (3) uses it as part of the loan transaction.

Credential Exchange Using Zero Knowledge Proofs

Credential holders can share information from multiple credentials with minimal disclosure using Zero Knowledge Proofs (ZKPs). ZKPs are cryptographic techniques that allow users to share information without relinquishing their security and privacy. ZKPs use cryptography to prove a statement from the holder to the verifier without revealing any additional information that is not required by the verifier.

Zero Knowledge Proofs must have three properties to be usable:

  1. Completeness: If the statement is true, the verifier believes the result of the proof.
  2. Soundness: If the statement is false, the holder is unable to create a false proof to fool a verifier into thinking that it is true.
  3. Zero-knowledge: The verifier does not learn any other information about the holder other than what is in the proof.

A classic example is date of birth. Driver’s licenses and identification cards are often the primary means of proving age. However, this type of identification also contains other valuable private information, such as a person’s home address, which is frequently used in identity theft. Selective disclosure uses ZKPs to turn a digital copy of a driver’s license into a cryptographic proof of specific information in the driver’s license. It’s as if you’re creating a custom copy of your driver’s license that is every bit as reliable, and conveys the same personally identifiable information, as the real thing; but, based on who is asking, you control what information actually appears to them on that particular copy.

A Sovrin modile wallet can create a ZKP for each situation where the credential holder needs to prove their age. ZKP technology allows her to quickly, easily, and securely verify she is over 18, or 21, or 65 without actually having to share a specific date of birth.

The ZKP-based query language for credentials used by the Sovrin Network is currently implemented by open source code in the Hyperledger Aries project using the underlying crypto code of the Hyperledger Ursa project. The query language is sophisticated and designed to support a good holder experience while ensuring minimal disclosure. Attributes on a credential (also called “claims”), such as an address or social security number are individually signed by the issuer. ZKPs are created using these attributes. Using the Sovrin Network, identity holders create ZKPs to prove one or more of the following things about their attributes.

  1. Equality: if the attribute is equal to the value or an identity holder can just reveal the attribute itself in the proof.

    Example: [Are you employed?] = Sovrin ZKP: [Yes] or [Employer: IBM]

  2. Inequality: if an attribute lies in a specific range without revealing the actual value. This is helpful when dealing with something that has a numerical attribute, like age or money.

    Example: [Are you over 21] = Sovrin ZKP: [Age >= 21]

  3. Set Membership: ZKPs can prove if a value is contained in a set without revealing which value.

    Example: Do you live in Europe? = Sovrin ZKP: [Country of residence is: a European country] or [Country of residence is: not in a European country]

The Ledger in Use: What is Written, What is Not

Every credential issuer must write a credential definition to the ledger so that a verifier can look up the credential definition to ensure its integrity. Every credential issuer will also have to write a public DID. Most issuers will write revocation registries, and many will write schema definitions.

By contrast, most individuals will not need to write DIDs to the ledger or issue credentials. This is because peer DIDs are exchanged pairwise each time a new peer-to-peer relationship is formed (see also previous section: Decentralized Identifiers and Their Properties).

The following table summarizes what goes on the ledger and what does not.

Goes on the ledger Does not go on the ledger
Public DIDs and associated DID documents with verification keys and endpoints Peer DIDs
Schemas and credential definitions Issued credentials
Revocation registries Consent receipts or records of credential exchange transactions
Agent authorization policies

Layer Four: Governance

Although the Sovrin Network is decentralized, it still operates under a community-driven governance process whose goal is to maximize trust in the Sovrin Network as a global identity network. This governance process is essential to producing a system that can both meet governmental and jurisdictional requirements for data security, privacy, protection, and portability, while at the same time preventing censorship and ensuring individual sovereignty over the sharing of identity data.

The Sovrin Governance Framework (SGF) is the legal foundation of the Sovrin Network as a global identity network for self-sovereign identity. It is developed by the Sovrin Governance Framework Working Group (SGFWG), currently chaired by Sovrin Trustee Drummond Reed. Each new version is approved by the Sovrin Foundation Board of Trustees to become the official set of governance documents for the operation of the Sovrin Ledger and the Sovrin Network.

The Sovrin Network enforces rules through a mixture of open-source code and an active, open-governance process for rulemaking. This ensures that everyone can see the process for creating the rules, not just the methods by which they are enforced.

The SGF V2 was initially approved by the Sovrin Board of Trustees in March 2019. A subsequent set of revisions to add the legal support for compliance with the EU General Data Protection Regulation (GDPR) and other global data protection regulations as explained on the Sovrin Foundation’s Data Protection page was approved on December 2019. The primary documents include:

  1. The Sovrin Governance Framework Master Document (PDF)—The "constitution" of the Sovrin Network, this document defines the purpose, core principles, and core policies—and also references all other documents in the SGF V2, including all the Controlled Documents, which contain policies managed by specific subgroups within the Sovrin Foundation, listed in Appendix A.
  2. The Sovrin Glossary—A comprehensive glossary of almost 250 terms used in the Sovrin and digital identity communities throughout all the SGF V2 documents and all of Sovrin infrastructure, plus eight appendices that provide in-depth explanations of core groups of terms.
  3. The Sovrin Trust Assurance Framework (PDF)—This document defines criteria and processes for assessing the conformance of different Sovrin actors to the policies of the Sovrin Governance Framework.

The SGF V2 also includes five legal agreements:

  1. The Sovrin Steward Agreement (PDF)—between the Sovrin Foundation and a Sovrin Steward
  2. Steward Data Processing Agreement (PDF)—between the Sovrin Foundation and a Steward establishes the responsibilities of each for complying with GDPR and other data protection regulations.
  3. Transaction Author Agreement (PDF)—between the Sovrin Foundation and any person or organization initiating a write transaction to the Sovrin Ledger.
  4. Transaction Endorser Agreement (PDF) —between the Sovrin Foundation and any organization requiring permissioned write access to the Sovrin Ledger.
  5. Transaction Endorser Data Processing Agreement (PDF) —between the Sovrin Foundation and a Transaction Endorser establishes the responsibilities of each for complying with GDPR and other data protection regulations.

Lastly, the SGF V2 has seven Controlled Documents:

  1. Sovrin Governing Body Policies (PDF)—the governance policies that apply to all Sovrin Governing Bodies.
  2. Sovrin Ledger Access Policies (PDF)—governing reading and writing to the Sovrin Ledger and processing Sovrin Ledger Transaction Data.
  3. Sovrin Steward Business Policies (PDF)—governing qualification, application, activation, operation, suspension, and termination of Sovrin Stewards.
  4. Sovrin Steward Technical and Organizational Policies (PDF)—governing the security, node operation, node selection, and reporting requirements for Sovrin Stewards.
  5. Transaction Endorser Technical and Organizational Policies (PDF)—governs the security and operational policy requirements for Transaction Endorsers.
  6. Sovrin Economic Policies (PDF)—governing economic incentives, fees, and regulatory compliance.
  7. Sovrin Trust Mark Policies (PDF)—governs the use of the Sovrin Trust Mark by Stewards, agencies, and developers.

2.2 Operational Status

Anyone abiding by the Sovrin Governance Framework can use the network to issue verifiable digital credentials by writing transactions via a Transaction Endorser. Similarly, anyone can access the network for the purposes of verifying a proof of a Sovrin-based verifiable credential. Developers, organizations, and businesses working on Sovrin-based projects are currently using the Sovrin Public Ledger, including the Agent-to-Agent protocol, to issue and verify verifiable digital credentials under the current Permissioned Write Access policies. Issuers of Sovrin-based credentials, including Sovrin Stewards and Transaction Endorsers, are currently writing the information they need directly to the Sovrin Public Ledger. See Write to the Sovrin Public Ledger for information on how to get write to the ledger. Examples of these ledger writes include public decentralized identifiers (DIDs), schema, credential definitions, and other GDPR compliant pieces of public information that abide by the Sovrin Governance Framework and Transaction Endorser Agreement. Under Perimissioned Write Access, the Sovrin Foundation is collecting a fee from these organizations through a manual billing process to support the Foundation’s administration of the network.

The open-source, community-developed code for decentralized self-sovereign identity that enables the Sovrin stack is available in three Hyperledger Projects: Hyperledger Indy, Hyperledger Aries, and Hyperledger Ursa. The source code for Hyperledger Indy was originally contributed to the Linux Foundation by the Sovrin Foundation. To operate the nodes on the Sovrin Network, the Sovrin Stewards use the code housed in the Hyperledger Indy project.


The Sovrin Network is composed of a sophisticated stack of protocols, implemented in open source, backed and supported by organizations of every size around the world. The Sovrin Network is not an identity system for solving a narrow set of identity problems in a few contexts, but a metasystem, supporting the creation of millions of identity systems for any context one can imagine.

The goal of an identity metasystem, like Sovrin Network, is to connect individual identity systems and allow them to interoperate since no single system meets the needs of every digital identity scenario. By providing a set of unifying protocols and consistent user experience, the metasystem creates the framework within which these identity systems are built and operate. A sophisticated system of governance allows organizations, large and small, to participate in a regulatory-compliant network and fuel adoption while protecting the autonomy of people around the world—truly providing Identity for All.


  1. A state proof requested from a node that provides cryptographic verification that the response reflects the current state of the Sovrin Ledger.
  2. DIDComm is defined in a set of Hyperledger Aries specification documents called RFCs. See the repository README.
  3. The cloud agent, at a minimum, performs routing functions for edge agents that don't have reliable inbound IP connectivity.
  4. Hardman, Daniel. How DIDs, Keys, Credentials, and Agents Work in Sovrin, Sovrin Foundation, 2019.
  5. Hardman, Daniel. What if I lose my phone? Evernym, 2019.

Please leave comments using the sidebar.

Last modified: Fri Mar 13 13:22:20 2020.