About XDI and Link Contracts


Hello guys, I’m having a bit of a struggle to wrap my head around link contracts and the overall role of XDI within the Sovrin architecture. I’m reading the XDI specs, and I understand its representational power, but I still don’t see where it fits.

If you could provide an explanation covering the very basics (for dummies) as well as some examples, I’d be really grateful.

These are some of the questions that come to mind:

  1. Where are link contracts stored?
  2. What is the relationship between XDI graphs and agent endpoints?
  3. How do we exactly restrict access to certain XDI graphs?
  4. Can link contracts be used for proving that a given interaction has been compliant with a defined process?
  5. What is an “XDI authority”?

…And any other relevant point that you can come up with, will be highly appreciated.



Hello Carlos,

Sorry it took a few days to respond. We spent a lot of time during the weekend discussing exactly this topic, and it also came up on today’s User Group Meeting.

Basically, XDI fits into Sovrin in two ways: As the semantic graph format for Sovrin identity containers, and as the protocol between Sovrin agents and other agents, as well as between agents and clients.

Regarding your concrete questions (I’ll answer them in a slightly different order):
2. We’re still refining some of these terms, but the way I would describe them is as follows: A Sovrin agent is an off-ledger piece of software that acts on your behalf. It enables off-ledger data sharing, requests, invitations, messaging, etc. The Sovrin agent manages your identity container. The format of the identity container is an XDI graph, and the XDI protocol is used for communication between agents and other agents, as well as between agents and clients.
3. This is exactly what XDI link contracts do. They set the permissions and policies for how data in the identity container is shared and how communication can take place. Various apps and services will make it possible to set up and manage your link contracts.

  1. Link contracts are stored inside the XDI graph. Link contracts are themselves expressed in XDI, i.e. they are part of the XDI graph just like your attributes and other data.
  2. Every interaction between agents and clients requires authorization by a link contract. The link contract can contain policies of various kinds, so yes you could say that link contracts enforce that an interaction has been compliant with a defined process or policy. And while we do not envision that link contracts and interactions themselves will be stored on the Sovrin ledger, proof that such link contracts and interactions exist can be stored on the ledger.
  3. An XDI authority is the person or organization that controls the XDI graph. Identifiers for those XDI authorities are stored on the Sovrin ledger.

We will be adding more information about Sovrin and XDI over time but please feel free to discuss this further here in the forum. Also, the topic of identity containers will be covered on the 3rd Sovrin User Group Meeting on Nov 21st.


Hey Markus,

Thank you very much for your reply. It certainly clears things up a bit more, however, I can’t confidently say I “get it” already. A few examples would surely help.

Additionally, a few other questions naturally come up:

  1. What is an identity container?
  2. What would be a classic scenario for data sharing among different agents?
  3. Since seemingly XDI graphs are going to be stored off-chain, how do we ensure that agents are sharing the correct data and that legitimate link contracts are being used?.. How do we link the verifiability of Sovrin Ledger claims with the XDI sharing integrity?

As I said, it would be really helpful to discuss a couple of examples on how to apply XDI /link-contracts to very basic use cases. I intuit that this is quite powerful technology, and that if used cleverly, it might open the door for implementing highly complex and useful functionalities around identity, but there’s still some “missing link” in my understanding of it as a whole…

Thanks again for your collaboration and patience. I’m looking forward to further explore this topic.



I’m sorry, we’re perhaps not doing a great job explaining the terminology. There are many terms that people tend to use interchangeably for more or less the same thing. E.g. “agent”, “identity container”, “personal cloud”, “personal information management system”, “personal data store”, etc.

As has been discussed also on other threads in this forum, we don’t want to store personal data on the ledger (unless you want it to be completely public). Therefore you need a place where you can store it. A place that you own and control. This place can be described using terms such as the ones above (e.g. “a Sovrin agent that holds your identity container”). Perhaps you have suggestions for terminology to describe this concept?

We also have a Sovrin Glossary that explains the key terms we are using.

And you need a data format and technology that connects all the pieces, i.e. the ledger, the agents, client applications, services, etc. This is where we think XDI can fit in.

Now let me try to provide a few examples:

  1. Decentralized address book: This could be a useful application that allows me and you to connect and then always stay up-to-date on our current contact information. If my phone number changes, you receive a notification on your app screen. In this example, our identifiers, cryptographic keys, and some other information are stored on the ledger. Our private data (address, phone number) is NOT stored on the ledger, they are stored in your “identity container”. Your “Sovrin agent” does the following: It enforces link contracts, i.e. it only allows access to my phone number and address to the people I want to share them with. And it sends out a notification to you when some of my data changes. The data is exchanged between my agent and your agent, it does not touch the ledger.

  2. Sharing data with a business on the web: You interact with a website online, and the website asks you for some information (e.g. credit card, or a proof that you are over 21y). Using the same mechanisms as in example #1, you can share personal data with the website. Again, only your identifiers and cryptographic information are stored on the ledger, but the actual data connection and sharing is handled by your Sovrin agent and by the link contracts.

  3. Receiving data: In several countries, there are movements to “give data back to the user”. E.g. a bank or government may hold certain records about you, and offers to return this data to you, so that it then truly belongs to you in a self-sovereign way. In this scenario, your Sovrin agent helps to set up a connection from the bank/government to your identity container, and a link contract allows them to send you data that belongs to you. Again, the Sovrin ledger doesn’t see any of this data, it only contains the identifiers and keys that make it possible for the Sovrin agent and client applications to set up link contracts and send/receive data.

Hope these examples help a bit. One of the strengths of Sovrin is that all of the above happens in a very privacy preserving way, using things such as pairwise identifiers, anonymous credentials, etc. This is all described in more detail in the Sovrin whitepapers.

Please keep questions/comments coming :slight_smile:


Thanks for your help, Markus. These examples surely clear things up a great deal… I still want to deepen on this subject, so we can build awesome applications over self-sovereign identity.

A few questions arise out of these examples, nevertheless.

I clearly see how agents and link contracts can be sure to be dealing with the right entities by relying on the Sovrin Ledger. Yet I don’t see how the entities on the Sovrin Ledger can be sure to be dealing with legitimate behavior from agents and link contracts:

  1. How do we use the ledger in order to establish some sort of protocol that ensures that link contracts are being correctly enforced by agents?

  2. How do we ensure that the correct information (no more, no less) was shared between agents? Is it advisable to use the ledger to store some sort of “proof of sharing”: some sort of “hash” that identity owners (and auditors) can use to prove that data privacy is being effectively preserved and the sharing process is being done correctly?

In other words, we trust the Sovrin Ledger because of the well-designed architecture that works underneath, the consensus protocols that support it, and the trust there is on the Sovrin Foundation. However, agents and clients add another layer of “potentially byzantine” (or maybe just vulnerable) nodes on the system.

…How do we make sure that all the pieces are fitting the way they should?



It is impossible to have a technological guarantee that agents will always behave 100% correctly (enforce link contracts, share only data they are supposed to share, etc.). There has to be a certain amount of trust between an individual and their “agency”, i.e. the institution that hosts their agent. You may want to self-host your agent. Of course you can move your agent from one place to the other, and things will continue to work.

There are however still a few architectural mechanisms that will make sure things work “correctly”:

  • As you already indicated, certain proofs can be stored on the ledger. E.g. a proof that a link contract has been created, or a proof that certain data was shared, or a proof that messages were sent and received between agents. If my agent A shares data with your agent B, and both agents store a proof of this transaction on the ledger, then neither agent will later be able to deny that the transaction has happened.
  • There will also be a Sovrin trust framework that will set principles and rules for all actors in the network, and enforce them through a mix of technical measures and non-technical actions in the Sovrin Foundation’s human governance layer.




Just as I thought, there is definitely an important role for the Sovrin Trust Framework in this matter. Standardizing agent structure and workflow is undoubtedly paramount.

…On another subject, I was wondering about these transaction “proof” claims, althought I’m not sure yet if they might be regarded as claims. This leads me to the question: is any record stored on the ledger a claim? I there a basic structure already defined on which fields and attributes should be in a claim?

Thanks again for your collaboration.