search

ssbc / scuttlebutt-protocol-guide

Protocol documentation for Secure Scuttlebutt
https://ssbc.github.io/scuttlebutt-protocol-guide/
241 stars 31 forks source link

Metafeed docs feedback #54

Closed staltz closed 2 years ago

staltz commented 2 years ago

@soapdog https://soapdog.github.io/scuttlebutt-protocol-guide/#metafeeds

Overall structure (sections, paragraphs, order of sentences, structuring of content, diagrams) is perfect! I only found corrections to grammar, tiny technical details etc. Here they are:

A metafeed is a special kind of feed that holds metadata information about multiple feeds. There can be only one active metafeed per identity, and it is only record metadata information about other feeds. Using metafeeds do not break compatibility with clients that only support the legacy feed format. Clients, for compatibility reasons, will always have a main feed in the format described above. They may support multiple additional feeds beyond that main feed, those additional feeds which will be organised and using a metafeed.

I changed this one the most because it's the introduction and we have to emphasize the tree-structure of metafeeds and shouldn't give the impression that there is only one metafeed.

A metafeed is a special kind of feed that only publishes metadata information 
concerning other feeds, called the <i>subfeeds</i>. A metafeed can also contain 
other metafeeds as subfeeds, so they form a tree structure. There can only be 
one <i>root metafeed</i> at the top of this tree. Using metafeeds do not 
break compatibility with clients that only support the classic feed format. 
Clients, for compatibility reasons, have a <i>main classic feed</i> alongside 
the root metafeed. They may support multiple additional feeds beyond that 
<i>main feed</i>, those additional feeds which will be organised and using a 
metafeed.
-Metafeeds use a different format than the legacy feed, this new format is 
+Metafeeds use a different format than the classic feed, this new format is 
-called bendy butt. It still is an append-only log of cryptographically signed 
+called Bendy Butt. It still is an append-only log of cryptographically signed 
 messages, but it is not tied to JSON or V8 engine internals like the old format 
 messages, but it is not tied to JSON or V8 engine internals like the old format 
-thus making it easier to implement it using other programming languages.
+thus making it easier to implement in other programming languages.

Would be good to use the term "classic" to keep it consistent with specs and implementations elsewhere, and we're not yet deprecating that format, so let's not call it legacy yet.

-A Bendy Butt Message is a Bencoded payload containing a collection with the 
+A Bendy Butt Message is a Bencoded list containing a collection with the 
 following five elements, in this specific order.

"payload" is not a Bencode term, it's just what we call it internally in the code, the Bencode term is a "list".

-id
+ID

Everywhere applicable.

SSB-BFE

The first time this is mentioned it should be a link inline. See e.g. when "Secret Handshake key exchange" is mentioned for the first time, it's a link to the PDF.

I also think you can rename SSB-BFE to BFE everywhere. And the first time it's mentioned, write Binary Field Encodings (BFE) and subsequent mentions are just BFE.

contentSection:

-If the message is not encrypted, This is a Bencoded dictionary containing 
+If the message is not encrypted, This is a Bencoded list containing 
 SSB-BFE encoded payload and signature. If it is SSB-BFE encrypted data, 
-then upon decryption it becomes a Bencoded dictionary of SSB-BFE encoded 
+then upon decryption it becomes a Bencoded list of SSB-BFE encoded 
 data and the signature for the payload.

There are other places where it suggests it's a Bencode dictionary, but it really is a list:

contentSection = [content, contentSignature]

content is a dictionary

type 

-Is a SSB-BFE string. It can only be one of metafeed/add/existing, 
+Is a BFE string. It can only be one of metafeed/add/existing, 
-metafeed/add/derived, metafeed/update, metafeed/seed, or metafeed/tombstone.
+metafeed/add/derived, or metafeed/tombstone.

Very important to note that metafeed/seed is publish on the classic main feed, not on the bendy butt feeds.

The supported types are:

 * metafeed/add/existing: Used to add an existing feed to the metafeed.
 * metafeed/add/derived: Used to add a derived feed to the metafeed.
-* metafeed/update: Used to update a feed information.
-* metafeed/seed: Used to record the cryptographic seed used to generate the metafeed identity. More about this later.
 * metafeed/tombstone: Used to flag that a feed is no longer in use.
-A feed let other peers know that it supports metafeeds by announcing its own 
+A classic main feed can let other peers know that it supports metafeeds by announcing its own 
-metafeed as a message of type metafeed/announce on its main feed.
+metafeed as a message of type metafeed/announce.
-This message is ignored by clients that do not support metafeeds thus 
+This message is ignored by existing apps that do not support metafeeds,
-guaranteeing that metafeeds do not break legacy clients. Clients that 
+such that adding a metafeed is harmless to existing apps. Clients that 
 support metafeeds will discover new metafeeds and subfeeds by looking for 
 such announcements.
-The sample diagram below shows a root feed, a metafeed and the 
+The sample diagram below shows a classic main feed, a root metafeed and the 
 associated subfeeds.
-Traditionally, SSB replicates feeds by fetching the whole feed...
+Traditionally, Scuttlebutt replicates feeds by fetching the whole feed...

To keep the document consistent, so far it has been referring to the protocol as "Scuttlebutt" and there is actually no mention of "SSB" in upstream master.