Add KERI-related terms to terminology.md #66
Conversation
|
I suggest that these basic terms (AID, KEL, etc.) should be defined briefly with |
|
Yes, let's use the KERI wiki glossary as much as we can: https://github.com/WebOfTrust/WOT-terms/wiki |
spec/terminology.md
Outdated
| [[def: method-specific identifier, MSI]] | ||
| ~ The `method-specific-id` part of DID Syntax, as defined in [DID Core](https://www.w3.org/TR/did-core/#did-syntax). See section [Method-Specific Identifier](#method-specific-identifier). | ||
| [[def: authentic chained data container (ACDC), ACDC]] | ||
| ~ a variant of [the Verifiable Credential (VC) specification](https://www.w3.org/TR/vc-data-model/). Some of the major distinguishing features of ACDCs include normative support for chaining, use of composable JSON Schema, multiple serialization formats, support for Ricardian contracts, support for chain-link confidentiality compact formats for resource constrained applications, simple partial disclosure mechanisms and simple selective disclosure mechanisms. ACDCs inherit the security model derived from [[ref: KERI]]. |
There was a problem hiding this comment.
@nkongsuwan given the feedback to link to the spec or to the wiki and given your definition here, what solution are you leaning towards?
According to Stephen we should have a short description and then link to something, see the discussion here #65 (comment)
Could link to https://trustoverip.github.io/tswg-acdc-specification/draft-ssmith-acdc.html#name-introduction
AND/OR
Could link to https://github.com/WebOfTrust/WOT-terms/wiki/authentic-chained-data-container
There was a problem hiding this comment.
Is there a specific format that I should follow? I was previously looking at W3C formats for examples.
spec/terminology.md
Outdated
| ~ A self-managing identifier that is self-certifying (i.e., self-authenticating) and cryptographically bound to a [[ref: key event log]] ([[ref: KEL]]). An AID is either non-transferable or transferable. A non-transferable AID does not support key rotation while a transferable AID support key rotation using a key [[ref: pre-rotation]] mechanism that enables the AID to persist in spite of the evolution of its key state. | ||
|
|
||
| [[def: compact Event Streaming Representation (CESR), CESR]] | ||
| ~ A dual text-binary encoding format that has the unique property of text-binary concatenation composability. The composability property enables the round trip conversion en-masse of concatenated primitives between the text domain and binary domain while maintaining the separability of individual primitives. |
There was a problem hiding this comment.
Could we do something that is more understandable? Perhaps:
The text-binary data format in which the KERI events for the DID are stored. The benefit of the CESR format for the did:webs DID Method is the KERI events are additive (appended to the end of the file), which allows a resolver that has cached the KERI event data (state and events) to continue processing following their last processed event versus always starting from the beginning of the log. See the CESR Specification for more details about the format.
There was a problem hiding this comment.
How about "An encoding format that enables round-trip text-binary conversion of concatenated cryptographic primitives and general data types"?
- CESR is not just for KERI key events. The essence of CESR is to allow cryptographic primitives to be concatenated with general data types such that they can be converted back and forth between binary and text.
- I think the property that "a resolver can cache key event data" is not unique to CESR.
spec/terminology.md
Outdated
|
|
||
| [[def: DID document]] | ||
| ~ As defined by [DID Core](https://www.w3.org/TR/did-core/#dfn-did-documents). See section [DID Documents](#did-documents). | ||
|
|
||
| [[def: direct replay mode]] | ||
| ~ an operational mode of the [[ref: KERI]] protocol where a controller and a verifier of an [[ref: AID]] exchange the [[ref: KEL]] of the AID directly. Upon reception of the KEL, the verifier sends a key event receipt, which includes the verifier's signature, to the controller as an acknowledgment. The signed key event receipt attests that the verifier received and verified the key event message. |
There was a problem hiding this comment.
I think it is relevant as direct mode AIDs are mentioned multiple times. I will call it just "direct mode" instead of "direct replay mode" to avoid confusion.
spec/terminology.md
Outdated
| @@ -3,17 +3,74 @@ | |||
| ::: todo | |||
| ::: | |||
|
|
|||
| [[def: method-specific identifier, MSI]] | |||
| ~ The `method-specific-id` part of DID Syntax, as defined in [DID Core](https://www.w3.org/TR/did-core/#did-syntax). See section [Method-Specific Identifier](#method-specific-identifier). | |||
| [[def: authentic chained data container (ACDC), ACDC]] | |||
There was a problem hiding this comment.
ACDCs are mentioned multiple times, so we might as well put it in the terminology. I can remove it if you think it is unnecessary.
spec/terminology.md
Outdated
| ~ A key establishment event that provides the incepting information needed to derive an [[ref: AID]] and establish its initial [[ref: key state]]. | ||
|
|
||
| [[def: indirect replay mode]] | ||
| ~ An operational mode of the [[ref: KERI]] protocol where the [[ref: KEL]] of an [[ref: AID]] is promulgated to a verifier using witnesses that are disignated by the AID's controller. |
There was a problem hiding this comment.
Relevant to did:webs?
Typo in “designated”. And I’m not sure I would use the “promulgated”, but perhaps that’s just me.
There was a problem hiding this comment.
I think it is relevant.
Promulgation is the term used by Sam in the whitepaper, but I agree it is not a commonly used term in English dictionaries. I will change it to "discovered by a verifier via witnesses".
spec/terminology.md
Outdated
| ~ An operational mode of the [[ref: KERI]] protocol where the [[ref: KEL]] of an [[ref: AID]] is promulgated to a verifier using witnesses that are disignated by the AID's controller. | ||
|
|
||
| [[def: interaction event]] | ||
| ~ A key non-establishment event that anchors external data to the [[ref: key state]] of an [[ref: AID]] as established by the most recent prior establishment event. |
There was a problem hiding this comment.
Given that this spec. is about did:webs and not about AIDs, I wondering if the ref here should be to the DID vs. to the AID. I recognize that AIDs are one of the basis's for the DID, and are important to define and use, but I think in this spec, the “non-key events” are more relevant to use the use of the DID than the use of the AID.
It might be worth having an appendix that covers the AID - DID relationship, but in the terminolgy of this spec, I think we should be focused on the DID.
spec/terminology.md
Outdated
| ~ A key non-establishment event that anchors external data to the [[ref: key state]] of an [[ref: AID]] as established by the most recent prior establishment event. | ||
|
|
||
| [[def: key event]] | ||
| ~ A serialized data structure of an entry in the [[ref: key event log]]([[ref: KEL]]) for an [[ref: AID]]. A key event is either establishment or non-establshment. An establishment event changes the [[ref: key state]] of an AID while a non-establishment event does not. |
There was a problem hiding this comment.
I think this should written from the viewpoint of the impact on the DID of the event. However, even saying that, this description should (I think) be talking about the inception event, the rotation event, and multi-sig events.
From this, I don’t understand what “establishment” and “non-establishment” events are, nor how they impact the DID/DIDDoc.
There was a problem hiding this comment.
I will remove "establishment" and "non-establishment" from the terminology as well as simplify the descriptions for all three types of key events.
spec/terminology.md
Outdated
| [[def: method-specific identifier, MSI]] | ||
| ~ The `method-specific-id` part of DID Syntax, as defined in [DID Core](https://www.w3.org/TR/did-core/#did-syntax). See section [Method-Specific Identifier](#method-specific-identifier). | ||
|
|
||
| [[def: out-of-band introduction (OOBI), OOBI]] |
There was a problem hiding this comment.
Is a did:webs and OOBI, or is there more to an OOBI than gaining access to the Event Log?
There was a problem hiding this comment.
The did:webs is used to get a DID document and CESR stream. The OOBI protocol is used much more broadly. For example, OOBIs are used to establish a connection between the two agents of two controllers. They are also used between issuer, holder, and verifier before they exchange ACDCs using the IPEX protocol.
spec/terminology.md
Outdated
| ~ An identifier that is content-addressable and self-referential. A SAID is uniquely and cryptographically bound to a serialization of data that includes the SAID as a component (or field) in that serialization. | ||
|
|
||
| [[def: transaction event log, TEL]] | ||
| ~ As defined by KERI. |
There was a problem hiding this comment.
Isn’t there more that we can provide about this to help a did:webs specification reader? This is a pretty important concept, as it is what makes verifiable the events other than key events.
There was a problem hiding this comment.
yes, see my remark here: #66 (comment)
There was a problem hiding this comment.
How about "A verifiable append-only log of transaction data that are cryptographically anchored to a [[ref: KEL]]. The transaction events of a TEL may be used to establish the issuance or revocation state of [[ref: ACDC]]s."?
|
I apologize to everyone for the late reply. I have closed this PR and will submit another PR that addresses the above comments. Note: I accidentally messed up the commits of this PR. Apparently, I had no idea what I was doing, so I will just create a new PR. |
Should the definitions be gather in Terminology or scattered throughout the document?