From cf69bb87d6918a6bf8336b4e369b4df16cb20669 Mon Sep 17 00:00:00 2001 From: Jacob Karlsson Date: Thu, 11 Apr 2024 15:59:05 +0200 Subject: [PATCH] Add basic protocol intro --- README.md | 2 +- docusaurus.config.js | 10 ++--- guide/intro.md | 100 ++++++++++++++++++++++++++++++++----------- src/pages/index.js | 6 +-- 4 files changed, 85 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index af69995..3e46512 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This command starts a local development server and opens up a browser window. Mo ### Build ``` -$ npm build +$ npm run build ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. diff --git a/docusaurus.config.js b/docusaurus.config.js index e4d3ae3..0c3f202 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -7,7 +7,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula'); /** @type {import('@docusaurus/types').Config} */ const config = { title: 'PZP Wiki', - tagline: 'Dinosaurs are cool', + tagline: 'A rad p2p protocol', favicon: 'img/favicon.ico', // Set the production url of your site here @@ -85,8 +85,8 @@ const config = { }, {to: '/blog', label: 'Blog', position: 'left'}, { - href: 'https://github.com/facebook/docusaurus', - label: 'GitHub', + href: 'https://codeberg.org/pzp', + label: 'Code', position: 'right', }, ], @@ -128,8 +128,8 @@ const config = { to: '/blog', }, { - label: 'GitHub', - href: 'https://github.com/facebook/docusaurus', + label: 'Code', + href: 'https://codeberg.org/pzp', }, ], }, diff --git a/guide/intro.md b/guide/intro.md index 2a9079d..8a54374 100644 --- a/guide/intro.md +++ b/guide/intro.md @@ -2,46 +2,98 @@ sidebar_position: 1 --- -# Intro +# PZP Docs -Let's discover **Docusaurus in less than 5 minutes**. +What is "PZP": +- A local-first P2P protocol with 10 years of learnings baked in +- Message formats + Message validation + RPC methods +- If scuttlebutt is :slightly_smiling_face: then pzp is :sunglasses: -## Getting Started +What it doesn't specify: +- Disk storage -Get started by **creating a new site**. +## Features -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. +- sig-chains - you know what the messages are +- first class multi-device support +- partial replication (using lipmaa links) +- message deletion (can leave nothing, or only metadata) -### What you'll need +### How PZP is different from SSB (Secure Scuttlebutt) -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. +- Storage is designed to not grow indefinitely. By default (of course overridable) an app's storage shouldn't go above 100MB. +- Multi device/app support from the start. Every device/app has its own keypair. They're connected together into one identity using an Account tangle. The Account tangle's root message ID is the account's identifier. +- One account or even keypair can post messages concurrently (forking) without problem. Because there aren't linear feeds, everything is in tangles. +- Deletion is possible. The data contents of a message is separate from the message metadata, and only the metadata + hash of the data is signed. -## Generate a new site +### How PZP is different from Nostr -Generate a new Docusaurus site using the **classic template**. +- keys are not shared across devices +- sig-chains - you know if you're missing content in PZP -The classic template will automatically be added to your project after you run the command: +## Tangles -```bash -npm init docusaurus@latest my-website classic +Tangles control how messages are organised. They provide a way to group, and causally sort (partially), which is important for replication. + +Basics of tangles in PZP: it's a directed acyclic graph (DAG) which aims to be as linear as possible + +```mermaid +flowchart RL + +E --> D --> C --> A + D --> B --> A ``` +There are 3 sorts of tangles: -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. +- Account - a tangle which weaves (device) keys and defines capabilities / permissions of these +- Feed - a tangle where all messages are from valid devices (as defined by an Account), and scoped to a particular domain + - e.g. all post messages from "mix" + - e.g. all chess messages from "happy0" +- Thread - a tangle where multiple Accounts are collaborating on some state + - e.g. all the messages making up a "10th birthday gathering" + - e.g. all the messages in a discussion + - e.g. all the messages in a shared shopping list -The command also installs all necessary dependencies you need to run Docusaurus. +### Account Tangle -## Start your site +The account tangle starts with a message which says "This key is allowed to author messages on behalf of this account, and add further keys". -Run the development server: +Subsequent messages in this tangle may add / remove capabilities for existing / new keys. -```bash -cd my-website -npm run start -``` +Messages in this tangle are verified by checking state they're extending on -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. +### Feed Tangle + +_Domain Tangle, AccountDomain Tangle_ + + +### Thread Tangle + +All tangles have +- a root / root message +- an ID (the id of the root message of the tangle) +- have tangle-data for causal ordering + +How the tangles differ +- the Account tangle has strict validation of messages (it is only valid to write to it if you've been given permission to) +- a Feed root is deterministic! (only inputs are accountId + domain) + + +## Messages + +https://github.com/staltz/ppppp-db/blob/master/protospec.md + + +## RPC methods + +- [Replication](https://github.com/staltz/ppppp-sync/blob/master/protospec.md) + +## Other + +- [ppppp-invite](https://github.com/staltz/ppppp-invite/blob/master/protospec.md) + +- [ppppp-set](https://github.com/staltz/ppppp-set/blob/master/protospec.md) + +- [ppppp-dict](https://github.com/staltz/ppppp-dict/blob/master/protospec.md) -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/src/pages/index.js b/src/pages/index.js index dbee367..4bd8518 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -18,7 +18,7 @@ function HomepageHeader() { - Docusaurus Tutorial - 5min ⏱️ + Read the protocol docs @@ -30,8 +30,8 @@ export default function Home() { const {siteConfig} = useDocusaurusContext(); return ( + title={`${siteConfig.title}`} + description="A rad p2p protocol">