Illustration: The zoo of the secrets


Hi all,

Recently I started to create diagrams from existing features of Storj to get better understanding.

Each of the diagrams visualizes one specific aspect of Storj architecture.

To make it easier to discuss them / suggest modifications or add any related questions, I am starting to upload them to here. Feel free to add any questions / comments here.

(ps: diagrams contains the original source embeded, which also can be found at GitHub - storj/illustrated: Diagrams to understand Storj architecture and internals better.)


It’s almost unreadable on dark theme

Thanks for the report. I regenerated it with solid background. Should be fine now.

I also added a link to the original svg, which may be better to view it in full resolutions…


This is really nice @elek !

A few comments:

  • In the “What is macaroon?” section one of the boxes reads caveat[0], caveat[1],..., and the next one: sign(sign(sign(secret, head), caveat[1]), caveat[2]). Where is caveat[0] gone?
  • An important property of macaroons is that each caveat is a restriction of the previous caveat in the chain. It would be great if there is a way to illustrate this too.
  • In the “What is grant” section:
    • We usually use the term “access grant”, not just “grant”.
    • The description “All-in-one information + permission grant to read a file” is not completely accurate. The permission to read the file is the Macaroon, also known as API Key. The access grant includes the API key, but also the encryption key, and the satellite info (as correctly illustrated in the box below). So perhaps the description should read like “All-in-one information about the satellite + permission to access data + how to decrypt it”.
    • DisallowPaths[] should be AllowedPaths[]. The logic is that the more specific the allowed paths are, the more restricted the access to data is.

@elek - this is fantastic. nice work.

Thanks, @kaloyan the useful feedback.

  • Fixed the small problems (AllowedPaths, grant → access grant).
  • I simplified the description of the access grant: “Everything to read/write an object”. Removed the confusing part and realized that all the other information is part of the diagram (parts of the grant)

Adding more information about the caveat restrictions is tricky. I would prefer to keep all the diagrams at the same size, which is more or less one slide.

So I tried to simplify the signature information here (but mention the capability of restriction) and explain the caveat restriction process in a new diagram. (The blue reference can be a link later. Not here, but in SVG versions…)

Please let me know if you have any more suggestion to improve these…


The separate illustration for macaroons definitely makes it clearer. Thanks!