New and improved SAFE Network Primer

A new version of the Primer is now available for your downloading delight. Completely redesigned in the lovely new livery, the fully updated Primer 2019 is fortified with PARSEC, the 20 fundamental principles, XOR-URLs, defences against common attacks and other goodness. So hurry hurry hurry and get yours today :running_man: :running_woman: (before it goes out of date).

Many thanks to all those who have helped with the rewriting, typo spotting, idiot proofing and sense checking. You know who you are. :clap: :clap:

If anyone with better web design skills than me (i.e. anyone with web design skills of any sort whatsoever) fancies creating an editable web version let me know.


Yet more amazing work by @JPL (and a few others in the background :bowing_man:). Thanks so much for your hard graft in updating this John - it’s a hugely valuable resource and yet another example of just how awesome this community is :smile: Kudos to everyone who’s been involved :+1:


A rare, and slightly Paul McCartney-esq, double thumbs-up from me on this one @JPL!!!
:+1: :+1:


Well done JPL! I used the primer when I first joined and I still refer to it when I’m looking for information. Really valuable piece of work. And love the new design, looks fab!


That primer is amazing! Seriously, brilliant work :grinning:


I could probably take a crack at making a web version but I’d need access to the source files and we’d need to figure out somewhere to host it. But the primer itself looks pretty simple format wise. It’s just a series of tables more or less. Shouldn’t be too hard to make a web version.


Absolutely fantastic update to the primer. It needs to be ‘web-ized’ and have a prominent place on the safe network, e.g. as well as on the clearnet. It is critical to have this open to help onboard.


re:hosting, I’d suggest as a static site using github pages (free) or aws s3 (practically free)


Thanks @Blindsite2k - I’ll get the files to you over the weekend. :+1:


The pdf converted to HTML is now online at Thanks to @Josh for running the site.


Was reading last night and man you put a lot of excellent irk into this John! Great resource and love the redesign to match the .tech site. Huge props


Thanks for the shout out @Nigel . To be fair the MaidSafe team put in a lot of work behind the scenes. Special mention to @dugcampbell who suggested new areas to cover and collated all the changes to the first draft as they came in from other members of the team and @Nadia who proofed the whole thing at the end.


Great team to work with. Credit should go where credit is due @dugcampbell @Nadia! Thanks for your hard work and clarification @JPL


This document is really getting better and better over time.

Just a few specific remarks:

  • chapter 6, paragraph "Clients connect via a Proxy Node": … and will allow it to connect to a section so long as it passes the Resource Proof tests and provided the network needs it. (a client doesn’t pass Resource Proof tests, only a joining Vault does).
  • chapter 6, paragraph "Self-encryption of data": … by which each chunk is encrypted using its own hash and the hashes of the two previous chunks in the same file. These encrypted chunks are then hashed again using the hashes of neighboring chunks to arrive at the XOR address where the chunk will be stored. At the same time a Data Map is created on the client device, which maps the chunk number to the XOR address of the chunk and the hash to decrypt it and its two successors, allowing the file to be recreated.
  • chapter 8, page 27, 2nd paragraph: Nodes and are continuously and rewarded according to the quality and quality of the resource they provide…
  • chapter 10, paragraph "ImmutableData": files larger than 3KB are split into chunks.
  • chapter 12, paragraph "Self-Encryption": …with each chunk encrypted using its own hash and the hashes of the two previous chunks.
  • Chapter 12: paragraph "Disjoint Sections": Those nodes know everything about the section for they are responsible for

Also two general remarks:

  • something very strange: copy&paste of paragraph text into any editor doesn’t work (but copy&paste of title text does work)
  • I find the font hard to read.

Excellent spots @tfa - I have revised the source document and will get a new PDF produced in due course.

something very strange: copy&paste of paragraph text into any editor doesn’t work (but copy&paste of title text does work)

I take it you’re referring to the website rather than the PDF? I guess this is something to do with the PDF-> HTML conversion process.

I find the font hard to read.

Nothing wrong with the font - must be your eyes :wink:


This is a superbly formatted resource and the ‘Tell me more’ sections will surely lead to more Devs taking a deep dive. I hope it’s printed on glossy paper and handed out wherever the marketing team go for talks.


Brilliant idea @dugcampbell :+1:


It’s 40 pages long with all the graphics, 32 even as raw text. That’s a lot of glossy paper and a fair sized hand out.

Let me add to that: think of the trees. If a printed paper is necessary, it is better to use (glossy) recycled paper.


A little north (like 20 miles) of my place is a large forest that extends for like 30KM in one direction planted specifically for building lumber and paper production. Its been there since before I was born and that is a long time ago, and so here we not only recycle paper (since before I was born) but also recycle that forest so that there is no net change in the number of trees existing when considering the paper, cardboard, …, structural housing lumber. Thus when I buy paper produced in my state I am not concerned to the effects on the forests.

Just a bit of trivia not asked for.