From bba8b42dee54050dacfd59636f656b5bc8096643 Mon Sep 17 00:00:00 2001 From: Marios Isaakidis Date: Sun, 21 Jun 2020 21:38:58 -0400 Subject: [PATCH] Refactor /specification markdown --- docs/.vuepress/config.js | 1 + docs/guide/tech/specification.md | 63 ++++++++++++++++---------------- 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index caf4930..c96f0b6 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -48,6 +48,7 @@ module.exports = { { text: 'Guide', link: '/guide/' }, ], repo: 'https://github.com/bitonproject', + repoLabel: 'Source Code', lastUpdated: 'Last Updated', smoothScroll: true, } diff --git a/docs/guide/tech/specification.md b/docs/guide/tech/specification.md index b497af7..f19f2a6 100644 --- a/docs/guide/tech/specification.md +++ b/docs/guide/tech/specification.md @@ -3,17 +3,17 @@ ## Versioning -```biton.VERSION = “biton” || bitonCrypto.VERSION || “_” || biton.TRANSPORT``` +`biton.VERSION = "biton" || bitonCrypto.VERSION || "_" || biton.TRANSPORT` -This document outlines the specification for ```biton0_BitTorrent```. +This document outlines the specification for `biton0_BitTorrent`. ## Notation -* x || y is the concatenation of x and y without a separator. -* x |& y concatenates x and y with an ampersand character ('&') as separator. You must use this concatenation when a field is optional. In that case, we write no bytes for the empty fields, but still add the separators. -* \[ ] denotes byte (uint8_t) arrays. -* s[:n] is the first n bytes of s. +* `x || y` is the concatenation of x and y without a separator. +* `x |& y` concatenates x and y with an ampersand character ('&') as separator. You must use this concatenation when a field is optional. In that case, we write no bytes for the empty fields, but still add the separators. +* `\[ ]` denotes byte (uint8_t) arrays. +* `s[:n]` is the first n bytes of s. * All numeric fields in the wire protocol are transmitted as Big Endian (Network byte order) values. * For fields of variable length, we write the field length followed by the field value. @@ -21,11 +21,11 @@ This document outlines the specification for ```biton0_BitTorrent```. ## bitonCrypto.VERSION = 0 * Proxying based on NoiseSocket and the noise-c library - * ```bitonCrypto.NOISE_PROTOCOL = NOISE_*_25519_ChaChaPoly_Blake2b``` + * `bitonCrypto.NOISE_PROTOCOL = NOISE_*_25519_ChaChaPoly_Blake2b` * Chunks encrypted with libsodium crypto_secretstream - * ```bitonCrypto.secretstream = secretstream_xchacha20poly1305``` + * `bitonCrypto.secretstream = secretstream_xchacha20poly1305` * Generic hash algorithm - * ```bitonCrypto.hash = Blake2b_256``` + * `bitonCrypto.hash = Blake2b_256` ## biton client address @@ -36,45 +36,44 @@ identity = bitonCrypto.base58.encode(keypair.public) peerId = WebTorrent.VERSION_PREFIX[:8] || identity[:12] ``` -> Example: for```identity = BkZgDsGD94DtZ83BwsHgce4Q4j2qr5PQGpjPQnPj8BGs```: -``` peerId = -WW0008-BkZgDsGD94Dt``` in utf8, -or ```peerId = 2d5757303030382d426b5a674473474439344474``` in hex. +> Example: for`identity = BkZgDsGD94DtZ83BwsHgce4Q4j2qr5PQGpjPQnPj8BGs`: +` peerId = -WW0008-BkZgDsGD94Dt` in utf8, +or `peerId = 2d5757303030382d426b5a674473474439344474` in hex. ## biton swarm address -```swarmId = bitonCrypto.hash( biton.VERSION |& networkMagic |& swarmSecret |& swarmPath )[:20]``` +`swarmId = bitonCrypto.hash( biton.VERSION |& networkMagic |& swarmSecret |& swarmPath )[:20]` -* ```bitonVersion = “biton” || bitonCrypto.VERSION``` (e.g. “biton0”) -* ```networkMagic```: 4 “magic” bytes for specifying a network (e.g. [0, 0, 0, 0] for the main network, and [0x74, 0x65, 0x73, 0x74] for the test network) -* ```swarmSeed```: the secret seed for connecting to a private swarm (e.g. “orbit#biton”, or null for global swarms) -* ```swarmPath```: the path from root to the corresponding node in the CAN partition tree, or null for the root swarm +* `bitonVersion = “biton” || bitonCrypto.VERSION` (e.g. `"biton0"`) +* `networkMagic`: 4 “magic” bytes for specifying a network (e.g. `[0, 0, 0, 0]` for the main network, and `[0x74, 0x65, 0x73, 0x74]` for the test network) +* `swarmSeed`: the secret seed for connecting to a private swarm (e.g. `"orbit#biton"`, or null for global swarms) +* `swarmPath`: the path from root to the corresponding node in the CAN partition tree, or null for the root swarm - -> Example: ```swarmId = bitonCrypto.hash ( “biton0” |& [0, 0, 0, 0] |& null |& 0x5 )[:20]``` +> Example: `swarmId = bitonCrypto.hash ( "biton0" |& [0, 0, 0, 0] |& null |& 0x5 )[:20]` ## biton data chunk address -* ```chunkHash = bitonCrypto.hash(chunk)``` -* ```chunkId = bitonCrypto.hash(biton.VERSION |& networkMagic |& swarmSecret |& chunkHash)``` -* Mesospore wire header: ```sporeId = spore.VERSION || networkMagic || chunkId || capabilities || chunk``` +* `chunkHash = bitonCrypto.hash(chunk)` +* `chunkId = bitonCrypto.hash(biton.VERSION |& networkMagic |& swarmSecret |& chunkHash)` +* Mesospore wire header: `sporeId = spore.VERSION || networkMagic || chunkId || capabilities || chunk` -Chunks are 1KB or 32KB parts of a bitonCrypto.secretstream +Chunks are 1KB or 32KB parts of a `bitonCrypto.secretstream` -> Example: ```sporeId = “spore0” || [0, 0, 0, 0] || chunkId || capabilities || chunk``` +> Example: `sporeId = "spore0" || [0, 0, 0, 0] || chunkId || capabilities || chunk` ## Wire message format -```“5biton” || version || networkMagic || command || command headers || payload``` +`"5biton" || version || networkMagic || command || command headers || payload` | Field size (bytes) | Description | Data type | Comments | |--------------------|:-----------:|:---------:|:--------:| -| 6 | Protocol | char[6] | protocol name length, followed by protocol name in ASCII```5biton``` | +| 6 | Protocol | char[6] | protocol name length, followed by protocol name in ASCII (`5biton`) | | 1 | Crypto version | uint8_t | 1 byte of zero (\[0]) for bitonCrypto.VERSION = 0 | -| 4 | Destination network magic bytes | uint32_t | Magic bytes for specifying biton network. Main net is 4 bytes of 0 [0, 0, 0, 0]. Test net is [0x74, 0x65, 0x73, 0x74] | +| 4 | Destination network magic bytes | uint32_t | Magic bytes for specifying biton network. Main net is 4 bytes of 0 `[0, 0, 0, 0]`. Test net is `[0x74, 0x65, 0x73, 0x74]` | | 1 | biton command | uint8_t | | | variable | Command headers | \[ ] | | | variable | Payload | \[ ] | Must be padded to one of the supported payload lengths (1KB or 32KB) | @@ -82,8 +81,8 @@ Chunks are 1KB or 32KB parts of a bitonCrypto.secretstream ## BitTorrent transport -* Referred to as ```biton*_BitTorrent``` -* WebTorrent extension implementing ```BEP 10``` -* Extended message ID is ```biton``` -* bencode for serialization -* Only load extension on wires to peers in biton swarms +* Referred to as `biton*_BitTorrent` +* WebTorrent extension implementing [`BEP 10`](http://www.bittorrent.org/beps/bep_0010.html) +* Extended message ID is `biton` +* Serialization using [`bencode`](https://www.bittorrent.org/beps/bep_0003.html) +* Only load extension on wires of peers in biton swarms