Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "How it Works" section #47

Merged
merged 8 commits into from
Sep 4, 2022
Merged

Add "How it Works" section #47

merged 8 commits into from
Sep 4, 2022

Conversation

msporny
Copy link
Member

@msporny msporny commented Aug 28, 2022

This PR adds a section called "How it Works" to the Data Integrity specification to conceptually describe how the technology described by the specification works.

There are a few images in the PR, so I'm attaching a screen shot for how the rendered diagram looks:

image

At present, the section is a bit out of place, and probably belongs more in the Introduction than in this section. I'll do an Editorial move later once we've agreed to the content.


Preview | Diff

index.html Outdated Show resolved Hide resolved
Copy link
Member

@TallTed TallTed left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly minor punctuation and grammar.

index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
Copy link

@decentralgabe decentralgabe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice work, this is easy to read and comprehensive

Copy link
Contributor

@dlongley dlongley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a good start. We'll want to make sure that the description here also cleanly maps to what happens with BBS signatures, for example. In BBS signatures, transformation occurs, but the transformed data produces N messages that are hashed and signed, i.e., there are multiple signatures. This still seems to map to me but we'll have to see if others agree, ideally from the BBS suite spec writers.

@msporny
Copy link
Member Author

msporny commented Aug 29, 2022

In BBS signatures, transformation occurs, but the transformed data produces N messages that are hashed and signed, i.e., there are multiple signatures.

Yes, I winced in the same way when I re-read the text yesterday. I do think we'll need to do some minor modifications to handle the "hash N messages" case. I'll try to put that in a revision before merging.

Copy link
Member

@iherman iherman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My comment is purely stylistic and, I admit, picky... (I approve the text regardless of taking this comment or not)

The sentence:

This process is conceptually similar to...

is trying to provide an analogy to a reader who is unfamiliar with the concept of digital signatures and/or proofs of stake. And that is fine. However, wouldn't it be better, for consistency's sake, to add a similar analogy for what a hash function means? (I guess we can get away without an analogy for the transformation bit.)

Copy link
Contributor

@mprorock mprorock left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

awesome improvement!

@msporny
Copy link
Member Author

msporny commented Sep 4, 2022

However, wouldn't it be better, for consistency's sake, to add a similar analogy for what a hash function means? (I guess we can get away without an analogy for the transformation bit.)

I have added this here: 0c83e1c

@msporny
Copy link
Member Author

msporny commented Sep 4, 2022

Editorial, multiple reviews, changes requested and made, no objections, merging.

@msporny msporny merged commit 9eddbc8 into main Sep 4, 2022
@msporny msporny deleted the msporny-add-hiw branch September 4, 2022 15:57
@msporny msporny restored the msporny-add-hiw branch September 4, 2022 16:05
@msporny msporny deleted the msporny-add-hiw branch October 1, 2022 08:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants