Changed some texts in readme.md

README.md

@@ -5,7 +5,7 @@ trusted interactions. People, institutions, and things can use this
 protocol to interact with one another in many different ways--but
 always as peers, in patterns that are easy, powerful, secure, and private.
 
-The protocol adapts to many different circumstances. it can be used on the
+The protocol adapts to many different circumstances. It can be used on the
 internet, over sneakernet, or even with snail mail.
 
 The protocol is rooted in principles of Self-Sovereign Identity (SSI). Instead of
@@ -17,9 +17,12 @@ away.
 
 ## Safe and Empowered Digital Interactions
 
-Alice wants to interact with many different parties.
+Alice wants to be able to interact with many different parties in different ways. 
+First, she may want to act as a consumer, interacting with parties that she can obtain products or services from.
+Secondly, she may want to act as a producer, and interact with parties that she can provide her services or products to.
+A special case of the the latter is where Alice provides products called attestations or (verifiable) credentials, which are statements she wants to publish about a party or some thing (attributes).
 
-She wants to interact with minimal reliance on third parties. She wants to control her interactions such that another party cannot interfere with her interactions.
+Alice wants to be 'self sovereign' in the sense that she controls every of her interactions and other parties cannot interfere with them. 
 
 Alice's digital interactions should be safe. Safe from prying eyes. Safe from services that track her without her knowledge and consent. Safe from unwanted correlation. Compromised third parties should not be able to impersonate her, or impersonate others to her. She should be safe from apps that exploit their positions of trust. Safe from disclosing more information about herself than is needed. 
 
@@ -33,55 +36,78 @@ For a more detailed discussion on these principles, see [Self-Sovereign Privacy
 
 ## Three Dimensions of Self Sovereign Identity
 
-There are three orthogonal dimensions to Alice's digital identity: (1) her _**relationships**_, (2) her _**attributes**_, and (3) her _**agents**_. Separating these three dimensions allows for a clear understanding of how they interact. Conflating them confuses the proper role of actors and systems and weakens security.
+There are three orthogonal dimensions to Alice's digital identity: (1) her _**relationships**_, (2) her _**knowledge**_ (which includes _**attributes**_), and (3) her _**agents**_. Separating these three dimensions allows for a clear understanding of how they interact. Conflating them confuses the proper role of actors and systems and weakens security.
 
 
 ### Relationships
 
-In Sovrin, identifiers are not shared across contexts. This helps protect privacy by limiting unwanted or cross-context correlation. Identifiers can be thought of as correlation handles. Correlation handles, like identifiers, are very useful within a context. Because identifiers are not shared across contexts, Alice uses a different identifier for every relationship she has. Because each relationship, or "pairing," has a different identifier, you can say that Sovrin uses pairwise identifiers.
+A Sovrin relationship is a group of at least two parties, i.e. people and/or organizations. Things are excluded, as they are always owned by a party, and therefore are to be considered Agents (see further down).
 
-Sovrin's identifiers are DIDs. DID stands for Decentralized Identifier. (For more information, see the DID specification here: https://w3c-ccg.github.io/did-spec/).
+A Sovrin relationship is represented by a set of two or more DIDs (Decentralized IDentifiers), each of which is generated by (or better: on behalf of) the party that it identifies. We say that the party owns the DIDs that it generates. (For more information, see the DID specification here: https://w3c-ccg.github.io/did-spec/).
 
-Sovrin supports groups. It can be said that a pair is just another group, a group of two. There are cases where an identifier is well known, as in the case of a public corporation. The corporation can have one or more "public" DIDs. This holds true to the constraint that identifiers are not shared across contexts, because the context of these DIDs is a public one. This is an exceptional case. Even though a person is free to create a public DID, it's important not to attach to that DID a reputation that must be carried into other contexts.
+In Sovrin, DIDs are not shared across relationships. In other words: if I am part of two relationships, I have generated a DID for each of them.
+This helps protect privacy by limiting unwanted or cross-context correlation. Identifiers can be thought of as correlation handles. Correlation handles, like identifiers, are very useful within a context. Because each relationship, or "pairing," has a different identifier, you can say that Sovrin uses pairwise identifiers.
 
+There are cases where a DID is well known, as in the case of a public corporation. A corporation can have one or more "public" DIDs. This holds true to the constraint that identifiers are not shared across contexts, because the context of these DIDs is a public one. This is an exceptional case. Even though a person is free to create a public DID, it is important not to attach to that DID a reputation that must be carried into other contexts.
 
-### Attributes
+### Knowledge
 
-In Sovrin, a person has two types of attributes. The first type is assertions about oneself, like "my name is Alice," or, "my favorite color is yellow." The second are asserted by others. For example, a driver license with my address on it. Essentially, this is an assertion made by the State of California that I live at this address.
+Sovrin recognizes that Alice has her own knowledge about the world she lives in. This knowledge is specific to Alice: Bob also has specific knowledge of the world he lives in. Bob's knowledge may or may not be the same, overlap, or even conflict with that of Alice.
 
-The party asserting some attributes about another is called an **Issuer**. When Alice holds a driver license, she can share that with Bob and Bob can examine it. If Bob believes that that driver license is authentic, and Bob trusts the State of California in its address verification processes, Bob can rely on the fact that Alice lives at 123 Oak Street.
+Alice obtains her knowledge (learns) from her interactions with other parties and with the world itself. For example, when she meets Bob, who says he knows about a taxi driver called Dave, she has gained knowledge: she learned about the (alledged) existence of a person that she did not yet know about, and she learned some attributes: his name, and his profession. People learn a lot from information that others provide (hearsay).
 
-A **Credential** is a generic term to refer to a collection of attributes. A driver license is a credential. A credential allows Alice to prove to Bob that another party asserts some attributes about Alice.
+Alice also learns from her own observations and experience. For example, when she listens to Carol sing in an opera, she will learn about her singing capabilities.
 
+Alice's knowledge consists of (a) knowledge about entities (people, organizations, things) that exist, and (b) properties (observations/judgements/rumors/names/etc.) that she attributes to such entities. Alice uses 'identifiers', i.e. bitstrings that Alice chooses herself, to represent the entities she knows to exist. Alice uses her identifiers to distinguish between these entities. Alice uses 'attributes' to represent the observations, judgements, rumors, names, characteristics etc. that she attributes to an entity.
+
+Alice's knowledge includes knowledge about herself. She uses the identifier 'I' to represent herself to herself, and as with any other identifier, she can attribute all sorts of observations/judgements/rumors to her 'I'. 
+
+Sidenote: the identifier 'I' is used by many other (English speaking) people to refer to themselves. This shows that identifiers can only be dereferenced (i.e.: related to some entity) by the party  that 'owns' this identifier, i.e. in the context in which they belong. That explains an important privacy preserving property of DID-pairs/groups: the parties that have a DID in a DID group will know who the other party/parties in the group are. Parties that are not part of the group can only identify the party whose public DID is in the group. They have no clue as to which party to associate with a non-public DID.
+
+One purpose for which Alice uses her knowledge is to make judgements and decisions. She does so by combining attributes of entities, using her own kind(s) of logic. The quality of such decisions depends on the quality of such logic(s), her proper understanding of the meaning of these attributes, and the truthfulness of the attribution. The higher the quality, the lower the risks associated with making incorrect decisions. This is obviously useful when interacting with others.
+
+When Alice wanted a ride, she called Dave to see whether or not she would ask him to provide that ride. One of the things she wanted to make sure is that she would actually arrive at her destination in one piece. So, she needs assurance that Dave can drive safely. How does she come to reach this conclusion?
+
+First, Alice decides that if a person has passed his driver test, he is capable of driving safely. Also, she decides to trust the department of motor vehicles (DMV) of any US state to have verified that the person they issue a driver license to, has actually passed its driver test. Finally, she decides that she is capable of determining whether or not the driver license is authentic. So, if Dave produces a driver license that is issued by the State of California, Alice can determine its authenticity, and conclude that she can safely ask him to provide the ride.
+
+A party that asserts some attributes about others is called an **Issuer**. A **Credential** is a generic term to refer to a collection of attributes. The DMV of the State of California thus is an issuer of credentials called driver licenses. A credential allows its holder to prove to others what the issuer asserts about the holder.
 
 ### Agents
 
-In the physical world, we can speak with our mouths, sign documents with our hands, hear with our ears. In the digital world, we have software and hardware that we use to accomplish the digital equivalent. These bits of running code that operate on our behalf are called, Agents.
+In the physical world, we can speak with our mouths, sign documents with our hands, hear with our ears. In the digital world, we have software and hardware that we use to accomplish the digital equivalent. These bits of running code that operate on our behalf in the digital world are called, Agents.
 
 My mobile phone can run an agent. My notebook computer can run an agent. I can ask a service provider to host an agent in the cloud.
 
-The important thing to note is an agent is owned by one person or entity. Even if I have an agent hosted by a service provider, it's still my agent.
+The important thing to note is that an agent represents one party. Even if an agent is hosted by a service provider, it still represents me. This means that every agent that represents me, must work with data (identifiers, attributes) that represent a part of my knowledge. If an agent receives data from an agent that represents someone else, such data will always be associated with the party that issued that data. This way, my agent can work with data from others without running the risk of messing up any decisions it takes.
 
-Some agents have endpoints. These agents can serve as simple message proxies or perform more sophisticated actions.
+Some agents have endpoints, which means that they can be contacted by other agents at any time. These agents can serve as simple message proxies or perform more sophisticated actions.
 
-There are two types of agents: Edge Agents, and Cloud Agents. 
+There are two types of agents: Edge Agents, and Cloud Agents. Edge Agents are Agents that the entity it represents usually has immediate control over, such as an agent that runs on a mobile phone or a notebook computer. Cloud Agents are Agents that the entity it represents usually does not have immediate control over, such as an agent that a service provider has agreed to host for me in the cloud.
 
 <!--TODO: reconcile with description found elsewhere--> 
 
 Agents hold keys which are authorized for certain types of activity. This allows the Agent owner to assign low privileges to lower trust Cloud Agents, and higher privileges to higher trust Edge Agents. Some privileges may require multiple keys held by different agents, including agents of trusted associates, to perform certain types of activities. For example, perhaps a funds transfer of greater than $10,000 USD would require two of four keys (phone, tablet, notebook, and Alice's partner, Bob).
 
+My Agents are capable of accessing (digital representations of) my knowledge. This allows them to act on my behalf. In particular, it allows them to:
+
+- help me act as a consumer, as I interact with parties from which I want to obtain certain products (or services). As my agent interacts with an agent of the product provider (e.g. a web-shop), it can present my knowledge (e.g. a name, a postal address etc.), as well as credentials (attestations) that are part of my knowledge (even though others have issued them). This helps the web-shop decide whether or not to accept my order. Conversely, my agent may 'know' that whenever it contacts an agent of another organization, it should require the web shop to provide a credential that proves it represents a real organization, e.g. by showing a credential issued by (an agent that represents) the chamber of commerce.
+- help me to act as a service provider. Agents that have an endpoint can be contacted by other agents at any time, e.g. a web service that implements an online shop. My web-shop agent will need to access my knowledge about the products I sell, the price I charge, etc. A special case of me as a service provider is where I act in the role of Issuer. Whenever an agent contacts my 'issuer agent' (i.e. the agent that represents me in the digital domain in my function as Issuer), the latter must be capable of tapping into my knowledge about the entity that is the subject of the credential that I am asked to issue. Also, it will need to decide whether or not to provide this service (of issuing a credential for that entity), just as any other service providing agent would do. A common way to do this is to identify (and authenticate) the party that the requesting agent represents.
+
+
 Reference diagrams found here: [DIDs, Credentials and Agents slides](https://docs.google.com/presentation/d/1oz1uB7y4J6GuqlmzyRmqrAwNiQQaWXs1LuHfFayAnwI) 
 
 <!--TODO: pull diagrams into this doc.--> 
 
 ## The Intersections of Dimensions
 
 
-### The Relationship-Attribute Plane
+### The Relationship-Knowledge Plane
+
+Because Relationships and Knowledge are orthogonal, an Issuer does not issue credentials to a particular DID. Remember that the meaning of DIDs is limited to a relationship, and Credentials should be usable in different relationships without sharing correlation handles across relationships or contexts.
 
-Because Relationships and Attributes are orthogonal, an Issuer does not issue credentials to a particular DID. Remember DIDs are contextual to a relationship, and Credentials should be usable in different relationships without sharing correlation handles across relationships or contexts.
+Rather, credentials should be issued in such a way that they can 'live in the knowledge' of a specific party, and that agents (e.g. web-shops) to which credentials are provided can ascertain that every credential has 'lived in the knowledge' of a single party; in other words: every such credential was issued to that specific party.
 
-Sovrin Credentials allow for an individual to dynamically generate proofs from one or more credentials as needed for any relationship, without correlation handles. This is not to say that cross-context correlation can't be done with shared attributes, but the control is in a person's hands, and the protocol does not leak correlation handles.
+Sovrin Credentials cater for this by allowing for an agent (that represents a party) to dynamically generate proofs from one or more credentials as needed for any relationship, without correlation handles. This is not to say that cross-context correlation can't be done with shared attributes, but the control is in a person's hands, and the protocol does not leak correlation handles.
 
 
 ### The Relationship-Agent Plane