diff --git a/SKETCH.md b/SKETCH.md new file mode 100644 index 0000000..a3de1b7 --- /dev/null +++ b/SKETCH.md @@ -0,0 +1,32 @@ +Audience: + - Curious: What on Earth is this + - Use: How can I use it + - Tinker: How does it technically work + - Compare: How do I compare this + - Develop: How do I develop for this + - Spec: How is it specified? + +- Guide + - Philosophy + - Small + - Regenerative + - App friendly + - Apps + - Concepts + - Keypair + - Tangle + - Account (tangle) + - Feed (tangle) + - Hub + - Invite + - Promise + - Pruning + - FAQ + - Comparisons + - How is this different from SSB? + - How is this different from Nostr? +- Build + - tools + - Implementations +- Specs + diff --git a/guide/concepts/_category_.json b/guide/concepts/_category_.json new file mode 100644 index 0000000..3b8a781 --- /dev/null +++ b/guide/concepts/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Concepts", + "position": 2, + "link": { + "type": "generated-index", + "description": "TODO" + } +} diff --git a/guide/concepts/account.md b/guide/concepts/account.md new file mode 100644 index 0000000..e4aaf15 --- /dev/null +++ b/guide/concepts/account.md @@ -0,0 +1,116 @@ +--- +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 new file mode 100644 index 0000000..8381c2e --- /dev/null +++ b/guide/concepts/feed.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 4 +--- + +# Feed + +A feed is a special type of tangle, where the root is a predictable (by any peer) message with no content. + +```mermaid +graph RL; + D--"A"-->C--"A"-->B--"A"-->A; + F-->E-->C; + G-->D & F; + +style A color:red; +``` + +Root: + +```typescript +interface Msg { + data: null // MUST be null + metadata: { + dataHash: null // MUST be null + dataSize: 0 // MUST be 0 + account: string // MUST be an ID + accountTips: null // MUST be null + tangles: {} // MUST be empty object + domain: string + v: 2 + } + pubkey: Pubkey + sig: Signature +} +``` diff --git a/guide/concepts/glossary.md b/guide/concepts/glossary.md new file mode 100644 index 0000000..886336c --- /dev/null +++ b/guide/concepts/glossary.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 8 +--- + +# Glossary + +- **Msg** = published data that is signed and shareable +- **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 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 +- **Identity tangle** = tangle with msgs that add (or remove?) asymmetric-crypto public keys +- **ID** = tangle ID of the identity tangle, refers to the "identity" of a person or a group +- **Feed** = tangle with msgs authored by (any pubkey in) an identity +- **Feed root** = a msg that is deterministically predictable and empty, so to allow others to pre-know its hash +- **Feed ID** = ID of a feed (Msg ID of the feed's root msg) + diff --git a/guide/concepts/hub.md b/guide/concepts/hub.md new file mode 100644 index 0000000..6d74eda --- /dev/null +++ b/guide/concepts/hub.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 5 +--- + +# Hub \ No newline at end of file diff --git a/guide/concepts/invite.md b/guide/concepts/invite.md new file mode 100644 index 0000000..6f85be4 --- /dev/null +++ b/guide/concepts/invite.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 6 +--- + +# Invite \ No newline at end of file diff --git a/guide/concepts/keypair.md b/guide/concepts/keypair.md new file mode 100644 index 0000000..a8921b5 --- /dev/null +++ b/guide/concepts/keypair.md @@ -0,0 +1,7 @@ +--- +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 new file mode 100644 index 0000000..87fc85c --- /dev/null +++ b/guide/concepts/message.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 9 +--- + +# Message \ No newline at end of file diff --git a/guide/concepts/overview.md b/guide/concepts/overview.md new file mode 100644 index 0000000..27aa7c2 --- /dev/null +++ b/guide/concepts/overview.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 0 +--- + +# Overview + diff --git a/guide/concepts/promise.md b/guide/concepts/promise.md new file mode 100644 index 0000000..21668b7 --- /dev/null +++ b/guide/concepts/promise.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 7 +--- + +# Promise \ No newline at end of file diff --git a/guide/concepts/tangle.md b/guide/concepts/tangle.md new file mode 100644 index 0000000..9501b19 --- /dev/null +++ b/guide/concepts/tangle.md @@ -0,0 +1,20 @@ +--- +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/intro.md b/guide/intro.md index 8a2e69d..2a9079d 100644 --- a/guide/intro.md +++ b/guide/intro.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# Tutorial Intro +# Intro Let's discover **Docusaurus in less than 5 minutes**. diff --git a/guide/philosophy/_category_.json b/guide/philosophy/_category_.json new file mode 100644 index 0000000..5f8ef32 --- /dev/null +++ b/guide/philosophy/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Philosophy", + "position": 1, + "link": { + "type": "generated-index", + "description": "TODO" + } +} diff --git a/guide/philosophy/app-friendly.md b/guide/philosophy/app-friendly.md new file mode 100644 index 0000000..ff69082 --- /dev/null +++ b/guide/philosophy/app-friendly.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 3 +--- + +# App-friendly \ No newline at end of file diff --git a/guide/philosophy/regenerative.md b/guide/philosophy/regenerative.md new file mode 100644 index 0000000..04d5200 --- /dev/null +++ b/guide/philosophy/regenerative.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 2 +--- + +# Regenerative \ No newline at end of file diff --git a/guide/philosophy/small.md b/guide/philosophy/small.md new file mode 100644 index 0000000..8d3ac35 --- /dev/null +++ b/guide/philosophy/small.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 1 +--- + +# Communities + + +> 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. + +| Small (dozens) | Medium (hundreds) | Large (thousands+) | +|---|---|---| +| | **PZP** | | +| Telegram | Discourse | Twitter / X | +| Signal | **Mastodon** | **Mastodon** | +| WhatsApp | Discord | Facebook | +| Messenger | Slack | Instagram | +| **Briar** | Matrix | Threads | +| | **SSB** | **SSB** | +| | | **Bluesky** | +| | | **Nostr** | diff --git a/guide/tutorial-basics/_category_.json b/guide/tutorial-basics/_category_.json index 2e6db55..40e3530 100644 --- a/guide/tutorial-basics/_category_.json +++ b/guide/tutorial-basics/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Basics", - "position": 2, + "position": 3, "link": { "type": "generated-index", "description": "5 minutes to learn the most important Docusaurus concepts." diff --git a/guide/tutorial-extras/_category_.json b/guide/tutorial-extras/_category_.json index a8ffcc1..832c3d1 100644 --- a/guide/tutorial-extras/_category_.json +++ b/guide/tutorial-extras/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Extras", - "position": 3, + "position": 4, "link": { "type": "generated-index" }