Living Whitepaper - call for action

With the heavy focus in being state of the art, Nano has and continues to undertake major changes both to its protocol and node implementation designs. At this point, the original whitepaper is outdated in several aspects.

After open-sourcing the whitepaper, we are now working on a revamp, towards a "living whitepaper" that will live in our documentation website. Feedback on this website has been overwhelmingly positive, and we believe it will be a perfect place to store an ever-evolving version of the whitepaper; hence, living.

With this living whitepaper, we also want to detail both the protocol design and node implementation. The latter is not detailed in the original whitepaper, and it provides a path to understanding design decisions for those who are not developers but still want to deepen their knowledge of Nano. Hopefully, this will also lead to more third party contributions to the codebase.

In line with our open-source approach to almost all Nano Foundation projects, people willing to contribute their knowledge of Nano (protocol and node implementation), will be able to do so via pull-requests to the whitepaper branch on the nano-docs repository.

This thread can be used to coordinate writing efforts, discussions, and avoiding redundancy.

How to contribute - a quick git tutorial for beginners

  1. See nano-docs#contributing
  2. Fork nano-docs and set it up locally. Clone from your fork, then add the main repository as upstream to pull updates as they're added: git remote add upstream
  3. Always checkout and pull updates in the whitepaper branch git checkout whitepaper && git pull upstream whitepaper
  4. The navigation panel should have the Protocol Design and (new) Node Implementation sections
  5. git checkout -b new-branch-name (your choice of name, relevant to what you will write about)
  6. Pick a topic, and start writing, or make improvements to an existing one
  7. git status , git add , git commit , git push origin new-branch-name are the minimum set of commands you will need to push the changes to your fork
  8. Visit the nano-docs repository website and you should see a popup to make a PR. The PR should merge into the whitepaper branch, not master branch.
  9. Wait for our feedback!

If git is discouraging you from contributing, but you would really like to write something, please let me know.


Reserved to coordinate ongoing efforts. If you start writing about a particular topic, let others know with a reply to this post!

Topic Assignee Status PR (s)
Protocol Design - Work @Dotcom Review 182

Quick look at the available topics. Click the image to see more (gets cropped in the preview). Note that each sub-section here is further subdivided into sub-subsections.


This looks exciting! I hope to be able to contribute as I have time. Bit busy this week, but maybe have some free time over the next few weeks.

Will there be some organization or sections claimed so people aren’t stepping on each other at the beginning?


Coordination could be done a bit in here, but we could also help highlight pages that are being worked on by making a small update at the top of that page about someone actively working on it when we see a PR come in related to it, add the PR link with it. @Dotcom what do you think of that approach?

I agree with the approach. I think the number of people working on it will be a sufficiently small group that using this thread would be enough, but doesn't hurt to do updates to the branch. However it does require a bit more git finesse to be able to merge updates from the "whitepaper" branch.

Played with the "Overview" section a little bit today, merging in the Abstract/Introduction sections from the original whitepaper. Also proposing a rename to "Introduction", since there is already an "Overview" page under "What is Nano?", and the focus of the "Protocol Design" section should be a deep-dive into all aspects of Nano:


Proposed some updates to - pulled in the original whitepaper sections, added some clarifying details, and described some of the benefits of the block-lattice design. Also added a blurb on ledger pruning and receive blocks:


Now have open PRs for:


First attempt at filling out the ORV section is now done :slight_smile: