Hash doc method

[Oskar-van-Deventer]

Excellent work! As mentioned, I like the general approach. Here are some minor comments.

• "generator ... " Why is the separator a "-" here and not a ":"? Is there any relevant semantic difference? Am I correct in assuming that "1" is a version number? Also, are there already implementations that use the verkey-based Peer DID? If so, may the reuse of "1" create any compatibility issues?
• "multihash =" Am I correct in assuming that forward compatibility is handled by the "1220" value, and that if ever sha256 gets depricated, the multihash part of the Peer DID specification gets updated?
• "The genesis version must include at least one public key" I suggest to change this into "verification key". It is a best practice to keep the roles of verkey en enckey cleanly separated
• "Remove the id field from the DID Doc." This may be ambiguous, as DID Doc is a nested document, with 'id' at several levels, also at the keys. How do we properly identify the 'main id field' that holds the DID value?
• "lossy short form of a peer DID" I feel that there is an ambiguity here. The short form is useful for humans-reading-the-log. However, I don't see why the machine-readable log needs the short form. I can imagine there be two logs, or a parser that performs the shortening.
• "convenient regex" Please check the regex. I see the "-" character used as literal and as for "a-f". Shouldn't there be an escape character? (Sorry, my regex knowledge is rusty ...)

[dhh1128]

"generator ... " Why is the separator a "-" here and not a ":"? Is there any relevant semantic difference? Am I correct in assuming that "1" is a version number?

There was a proposal made in the DID spec working group that colons be used as separators for arguments. That would be incompatible with what we had before. The proposal was rejected, but it spooked me a bit that colon might end up having a messy conflict. Also, there is work afoot in the Sovrin/Indy space to support nested namespaces (network-of-networks) features, where the colon would be used as a namespace delimiter. So I thought switching to a different delimiter might be wise. I don't have any proof that the hyphen is dramatically better; it just seemed advisable.

Also, are there already implementations that use the verkey-based Peer DID? If so, may the reuse of "1" create any compatibility issues?

No implementations yet. If there were, we would of course have to keep "1" to maintain their features. For the time being, we can afford to have breaking changes.

"multihash =" Am I correct in assuming that forward compatibility is handled by the "1220" value, and that if ever sha256 gets depricated, the multihash part of the Peer DID specification gets updated?

Yes, exactly.

"The genesis version must include at least one public key" I suggest to change this into "verification key". It is a best practice to keep the roles of verkey en enckey cleanly separated

Good improvement. Will update.

"Remove the id field from the DID Doc." This may be ambiguous, as DID Doc is a nested document, with 'id' at several levels, also at the keys. How do we properly identify the 'main id field' that holds the DID value?

Good point. I'll see if I can come up with clearer language.

"lossy short form of a peer DID" I feel that there is an ambiguity here. The short form is useful for humans-reading-the-log. However, I don't see why the machine-readable log needs the short form. I can imagine there be two logs, or a parser that performs the shortening.

I guess my assumption was that logs are intended to be human-readable, not machine-readable. But I can see that this is not necessarily true (e.g., if someone is using Splunk). Do you have any suggestions about how to improve the wording in this section?

"convenient regex" Please check the regex. I see the "-" character used as literal and as for "a-f". Shouldn't there be an escape character? (Sorry, my regex knowledge is rusty ...)

Several regex characters have special meaning inside the square brackets of character group. The dot (.) and the question mark can appear without escaping. The hyphen means a literal hyphen if it is the first character, but a range if it is between two other characters. It doesn't need to be escaped.

[Oskar-van-Deventer]

Hi Daniel,

Your response answers all my question. Thanks!

Do you have any suggestions about how to improve the wording in this section?

I am not sure whether we would need to specify the lossy short form at all. If we do, we could use text like this. "If a log is not meant to be machine readable, but only human readable, then a lossy short form of peer DID can be used. In this case, the full DID is replaced by ... (further details ...)"

[mavarley]

+1 to this change being accepted; I think it gives flexibility to peer DIDs to be less transactional and more persistent (if required) - it lets them evolve with the relationship in which they have context.

[tplooker]

+1 to this change also, I think the added flexibility is a great property.

[coder5876]

I think it's a good idea by @kdenhartog to avoid specifying potential shortenings of the hash here. This seems more of a UX issue when presenting a DID to a user (which can hopefully be avoided in the long term).

[dhh1128]

I have removed the discussion of the short form for now. If we can think of a way to do it that is not susceptible to brute force attacks, I may add it back in, because I think brevity is a desirable option. I just got done confirming a transaction with an Ethereum multisig wallet, and although I copied and pasted the long hashes rather than retyping them, even checking the values on the screen was a bit difficult. I do agree that this is more of a UX issue than an underlying spec issue, though; maybe the UX problems should remain outside the doc. Anyway, it's gone for now.

Merging the PR as we've had substantial positive comments from collaborators and no dissenting votes.