From 86cc6f6fbbffba98c23e413060b2c25d5e7978ef Mon Sep 17 00:00:00 2001 From: Andre Staltz Date: Mon, 6 Nov 2023 13:05:24 +0200 Subject: [PATCH] August update all over the place --- guide/concepts/account.md | 116 ----------------- guide/concepts/feed.md | 139 ++++++++++++++++++++- guide/concepts/glossary.md | 3 +- guide/concepts/hub.md | 8 +- guide/concepts/invite.md | 7 +- guide/concepts/keypair.md | 7 -- guide/concepts/message.md | 16 ++- guide/concepts/overview.md | 1 + guide/concepts/peer.md | 15 +++ guide/concepts/promise.md | 5 - guide/concepts/replication.md | 5 + guide/concepts/tangle.md | 20 --- guide/philosophy/sufficiency.md | 7 ++ guide/philosophy/{small.md => villages.md} | 5 +- 14 files changed, 194 insertions(+), 160 deletions(-) delete mode 100644 guide/concepts/account.md delete mode 100644 guide/concepts/keypair.md create mode 100644 guide/concepts/peer.md delete mode 100644 guide/concepts/promise.md create mode 100644 guide/concepts/replication.md delete mode 100644 guide/concepts/tangle.md create mode 100644 guide/philosophy/sufficiency.md rename guide/philosophy/{small.md => villages.md} (73%) diff --git a/guide/concepts/account.md b/guide/concepts/account.md deleted file mode 100644 index e4aaf15..0000000 --- a/guide/concepts/account.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Account - -An account is a special type of tangle, where the messages describe which keypairs are part of the same "account". - -```mermaid -graph RL; - D--"A"-->C--"A"-->B--"A"-->A; - F-->E-->C; - G-->D & F; - -style A color:red; -``` - -Msgs in an account tangle are special because they have empty `account` and `accountTips` fields. - -```typescript -interface Msg { - data: AccountData - metadata: { - dataHash: ContentHash - dataSize: number - account: 'self' // MUST be the string 'self' - accountTips: null // MUST be null - tangles: { - [accountTangleId: string]: { - depth: number // maximum distance (positive integer) from this msg to the root - prev: Array // list of msg hashes of existing msgs, unique set and ordered alphabetically - } - } - domain: string // alphanumeric string, at least 3 chars, max 100 chars - v: 3 - } - pubkey: Pubkey - sig: Signature -} - -type AccountData = - | { action: 'add', add: AccountAdd } - | { action: 'del', del: AccountDel } - -// "add" means this keypair can validly add more keypairs to the account tangle -// "del" means this keypair can validly revoke other keypairs from the account -// "box" means the peer with this keypair should get access to the box keypair -type AccountPower = 'add' | 'del' | 'box' - -type AccountAdd = { - key: Key - nonce?: string // nonce required only on the account tangle's root - consent?: string // base58 encoded signature of the string `:account-add:` where `` is the account's ID, required only on non-root msgs - accountPowers?: Array // list of powers granted to this key, defaults to [] -} - -type AccountDel = { - key: Key -} - -type Key = - | { - purpose: 'sig' // digital signatures - algorithm: 'ed25519' // libsodium crypto_sign_detached - bytes: string // base58 encoded string for the public key being added - } - | { - // WIP!! - purpose: 'box' // asymmetric encryption - algorithm: 'x25519-xsalsa20-poly1305' // libsodium crypto_box_easy - bytes: string // base58 encoded string of the public key - } -``` - -Examples of `accountData`: - -- Registering the first signing pubkey: - ```json - { - "action": "add", - "add": { - "key": { - "purpose": "sig", - "algorithm": "ed25519", - "bytes": "3JrJiHEQzRFMzEqWawfBgq2DSZDyihP1NHXshqcL8pB9" - }, - "nonce": "6GHR1ZFFSB3C5qAGwmSwVH8f7byNo8Cqwn5PcyG3qDvS" - } - } - ``` -- Registering a subaccount: - ```json - { - "action": "add", - "add": { - "key": { - "purpose": "subaccount", - "algorithm": "tangle", - "bytes": "6yqq7iwyJEKdofJ3xpRLEq" - } - } - } - ``` -- Revoking a signing pubkey: - ```json - { - "action": "del", - "del": { - "key": { - "purpose": "sig", - "algorithm": "ed25519", - "bytes": "3JrJiHEQzRFMzEqWawfBgq2DSZDyihP1NHXshqcL8pB9" - } - } - } - ``` diff --git a/guide/concepts/feed.md b/guide/concepts/feed.md index 8381c2e..3ce2087 100644 --- a/guide/concepts/feed.md +++ b/guide/concepts/feed.md @@ -1,9 +1,144 @@ --- -sidebar_position: 4 +sidebar_position: 30 --- # Feed +:::note Definition +**A feed is an evolving set of interlinked messages intended for continuous replication in a gossip network.** +::: + +In computer science terms, it's an Directed Acyclic Graph (DAG) with only one source node, where all the "nodes" are messages, and "edges" are references that each message contains of other messages. + +```mermaid +graph RL; + D--"A"-->C--"A"-->B--"A"-->A; + F-->E-->C; + G-->D & F; + +style A color:red; +``` + +The root is... + +The tangle is identified by the hash of its root message. + + +# Account + +An account is a special type of tangle, where the messages describe which keypairs are part of the same "account". + +```mermaid +graph RL; + D--"A"-->C--"A"-->B--"A"-->A; + F-->E-->C; + G-->D & F; + +style A color:red; +``` + +Msgs in an account tangle are special because they have empty `account` and `accountTips` fields. + +```typescript +interface Msg { + data: AccountData + metadata: { + dataHash: ContentHash + dataSize: number + account: 'self' // MUST be the string 'self' + accountTips: null // MUST be null + tangles: { + [accountTangleId: string]: { + depth: number // maximum distance (positive integer) from this msg to the root + prev: Array // list of msg hashes of existing msgs, unique set and ordered alphabetically + } + } + domain: string // alphanumeric string, at least 3 chars, max 100 chars + v: 3 + } + pubkey: Pubkey + sig: Signature +} + +type AccountData = + | { action: 'add', add: AccountAdd } + | { action: 'del', del: AccountDel } + +// "add" means this keypair can validly add more keypairs to the account tangle +// "del" means this keypair can validly revoke other keypairs from the account +// "box" means the peer with this keypair should get access to the box keypair +type AccountPower = 'add' | 'del' | 'box' + +type AccountAdd = { + key: Key + nonce?: string // nonce required only on the account tangle's root + consent?: string // base58 encoded signature of the string `:account-add:` where `` is the account's ID, required only on non-root msgs + accountPowers?: Array // list of powers granted to this key, defaults to [] +} + +type AccountDel = { + key: Key +} + +type Key = + | { + purpose: 'sig' // digital signatures + algorithm: 'ed25519' // libsodium crypto_sign_detached + bytes: string // base58 encoded string for the public key being added + } + | { + // WIP!! + purpose: 'box' // asymmetric encryption + algorithm: 'x25519-xsalsa20-poly1305' // libsodium crypto_box_easy + bytes: string // base58 encoded string of the public key + } +``` + +Examples of `accountData`: + +- Registering the first signing pubkey: + ```json + { + "action": "add", + "add": { + "key": { + "purpose": "sig", + "algorithm": "ed25519", + "bytes": "3JrJiHEQzRFMzEqWawfBgq2DSZDyihP1NHXshqcL8pB9" + }, + "nonce": "6GHR1ZFFSB3C5qAGwmSwVH8f7byNo8Cqwn5PcyG3qDvS" + } + } + ``` +- Registering a subaccount: + ```json + { + "action": "add", + "add": { + "key": { + "purpose": "subaccount", + "algorithm": "tangle", + "bytes": "6yqq7iwyJEKdofJ3xpRLEq" + } + } + } + ``` +- Revoking a signing pubkey: + ```json + { + "action": "del", + "del": { + "key": { + "purpose": "sig", + "algorithm": "ed25519", + "bytes": "3JrJiHEQzRFMzEqWawfBgq2DSZDyihP1NHXshqcL8pB9" + } + } + } + ``` + +# Moot feeds + A feed is a special type of tangle, where the root is a predictable (by any peer) message with no content. ```mermaid @@ -32,4 +167,4 @@ interface Msg { pubkey: Pubkey sig: Signature } -``` +``` \ No newline at end of file diff --git a/guide/concepts/glossary.md b/guide/concepts/glossary.md index 211e2f1..a278b1a 100644 --- a/guide/concepts/glossary.md +++ b/guide/concepts/glossary.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 80 --- # Glossary @@ -8,6 +8,7 @@ sidebar_position: 8 - **Msg hash** = hash(msg.metadata) - **Tangle** = any single-root DAG of msgs that can be replicated by peers - **Tangle Root** = the origin msg of a tangle +- **Tangle Affix** = any msg in a tangle that is not the root - **Tangle Tips** = tangle msgs that are not yet referenced by any other msg in the tangle - **Tangle ID** = Msg hash of the tangle's root msg - **Account tangle** = tangle with msgs that add (or remove?) asymmetric-crypto public keys diff --git a/guide/concepts/hub.md b/guide/concepts/hub.md index 6d74eda..e91e088 100644 --- a/guide/concepts/hub.md +++ b/guide/concepts/hub.md @@ -1,5 +1,9 @@ --- -sidebar_position: 5 +sidebar_position: 50 --- -# Hub \ No newline at end of file +# Hub + +:::note Definition +**A hub is a server that allow clients to communicate with each other via end-to-end encrypted tunnels. Hubs and clients form a fluid multi-star topology.** +::: \ No newline at end of file diff --git a/guide/concepts/invite.md b/guide/concepts/invite.md index 6f85be4..07e8523 100644 --- a/guide/concepts/invite.md +++ b/guide/concepts/invite.md @@ -1,5 +1,8 @@ --- -sidebar_position: 6 +sidebar_position: 60 --- -# Invite \ No newline at end of file +# Invite + + +## Promise \ No newline at end of file diff --git a/guide/concepts/keypair.md b/guide/concepts/keypair.md deleted file mode 100644 index a8921b5..0000000 --- a/guide/concepts/keypair.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Keypair - -Asymmetric cryptographic keypair that identifies the current peer. \ No newline at end of file diff --git a/guide/concepts/message.md b/guide/concepts/message.md index 87fc85c..0e4e52b 100644 --- a/guide/concepts/message.md +++ b/guide/concepts/message.md @@ -1,5 +1,17 @@ --- -sidebar_position: 9 +sidebar_position: 20 --- -# Message \ No newline at end of file +# Message + +:::note Definition +**A message is a JSON encoded data structure that is signed by a peer and intended for replication in a gossip network.** +::: + +## Data + +## Metadata + +## Public key + +## Signature diff --git a/guide/concepts/overview.md b/guide/concepts/overview.md index 27aa7c2..fd9d570 100644 --- a/guide/concepts/overview.md +++ b/guide/concepts/overview.md @@ -4,3 +4,4 @@ sidebar_position: 0 # Overview +**In PZP, [peers](./peer) publish [messages](./message) on [feeds](./feed) that are [replicated](./replication) by other peers in a gossip network of [hubs](./hub). To join the network, a peer must be [invited](./invite).** diff --git a/guide/concepts/peer.md b/guide/concepts/peer.md new file mode 100644 index 0000000..993f2bb --- /dev/null +++ b/guide/concepts/peer.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 10 +--- + +# Peer + +:::note Definition +**A peer is a participant in a gossip network, identified by a self-certifying cryptographic keypair.** +::: + + + +## Keypair for SHSe + +Asymmetric cryptographic keypair that identifies the current peer. diff --git a/guide/concepts/promise.md b/guide/concepts/promise.md deleted file mode 100644 index 21668b7..0000000 --- a/guide/concepts/promise.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 7 ---- - -# Promise \ No newline at end of file diff --git a/guide/concepts/replication.md b/guide/concepts/replication.md new file mode 100644 index 0000000..038854c --- /dev/null +++ b/guide/concepts/replication.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 45 +--- + +# Replication diff --git a/guide/concepts/tangle.md b/guide/concepts/tangle.md deleted file mode 100644 index 9501b19..0000000 --- a/guide/concepts/tangle.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Tangle - -A tangle is a set of interlinked messages published by a peer. In computer science terms, it's an Directed Acyclic Graph (DAG) with only one source node, where all the "nodes" are messages, and "edges" are links between messages. - -```mermaid -graph RL; - D--"A"-->C--"A"-->B--"A"-->A; - F-->E-->C; - G-->D & F; - -style A color:red; -``` - -The root is... - -The tangle is identified by the hash of its root message. \ No newline at end of file diff --git a/guide/philosophy/sufficiency.md b/guide/philosophy/sufficiency.md new file mode 100644 index 0000000..ce619d2 --- /dev/null +++ b/guide/philosophy/sufficiency.md @@ -0,0 +1,7 @@ +--- +sidebar_position: 1 +--- + +# Sufficiency + +Aim at "good enough" on all relevant criteria, instead of "best" on any one. \ No newline at end of file diff --git a/guide/philosophy/small.md b/guide/philosophy/villages.md similarity index 73% rename from guide/philosophy/small.md rename to guide/philosophy/villages.md index 8d3ac35..174578c 100644 --- a/guide/philosophy/small.md +++ b/guide/philosophy/villages.md @@ -2,10 +2,9 @@ sidebar_position: 1 --- -# Communities +# Villages - -> We are not trying to fix social media, we are trying to make it irrelevant. We want to bring back villages and networks of friendships as a essential component in society. +> We are not trying to fix social media, we are trying to make it less central in our lives. As a replacement, we want to increase the role of villages, networks of friends, and small communities in society. | Small (dozens) | Medium (hundreds) | Large (thousands+) | |---|---|---|