From 442d8c02fce9345a348dded42d38eef645a43482 Mon Sep 17 00:00:00 2001 From: Luke Parker Date: Mon, 11 Mar 2024 20:00:01 -0400 Subject: [PATCH] Add docs, correct URL --- README.md | 2 +- docs/2_amm.md | 5 ---- docs/5_1_message_queue.md | 6 ----- docs/5_2_processor.md | 6 ----- docs/5_3_coordinator.md | 6 ----- docs/_config.yml | 3 +-- docs/amm/index.md | 17 +++++++++++++ .../index.md} | 0 docs/{4_1_genesis.md => economics/genesis.md} | 0 docs/{4_0_economics.md => economics/index.md} | 0 docs/{4_3_post.md => economics/post.md} | 0 docs/{4_2_pre.md => economics/pre.md} | 0 docs/index.md | 6 ++++- docs/infrastructure/coordinator.md | 19 ++++++++++++++ .../index.md} | 0 docs/infrastructure/message_queue.md | 25 +++++++++++++++++++ docs/infrastructure/processor.md | 19 ++++++++++++++ .../{5_4_serai.md => infrastructure/serai.md} | 0 docs/integrating/index.md | 6 +++++ docs/{6_0_validator.md => validator/index.md} | 2 +- 20 files changed, 94 insertions(+), 28 deletions(-) delete mode 100644 docs/2_amm.md delete mode 100644 docs/5_1_message_queue.md delete mode 100644 docs/5_2_processor.md delete mode 100644 docs/5_3_coordinator.md create mode 100644 docs/amm/index.md rename docs/{3_cross_chain.md => cross_chain/index.md} (100%) rename docs/{4_1_genesis.md => economics/genesis.md} (100%) rename docs/{4_0_economics.md => economics/index.md} (100%) rename docs/{4_3_post.md => economics/post.md} (100%) rename docs/{4_2_pre.md => economics/pre.md} (100%) create mode 100644 docs/infrastructure/coordinator.md rename docs/{5_0_infrastructure.md => infrastructure/index.md} (100%) create mode 100644 docs/infrastructure/message_queue.md create mode 100644 docs/infrastructure/processor.md rename docs/{5_4_serai.md => infrastructure/serai.md} (100%) create mode 100644 docs/integrating/index.md rename docs/{6_0_validator.md => validator/index.md} (84%) diff --git a/README.md b/README.md index 900de39d7..4a8ac4d5d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Bitcoin, Ethereum, DAI, and Monero, offering a liquidity-pool-based trading experience. Funds are stored in an economically secured threshold-multisig wallet. -[Getting Started](docs/Getting%20Started.md) +[Getting Started](spec/Getting%20Started.md) ### Layout diff --git a/docs/2_amm.md b/docs/2_amm.md deleted file mode 100644 index e3f14cc24..000000000 --- a/docs/2_amm.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Automatic Market Makers -layout: default -nav_order: 2 ---- diff --git a/docs/5_1_message_queue.md b/docs/5_1_message_queue.md deleted file mode 100644 index b4d7b548c..000000000 --- a/docs/5_1_message_queue.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Message Queue -layout: default -nav_order: 1 -parent: Infrastructure ---- diff --git a/docs/5_2_processor.md b/docs/5_2_processor.md deleted file mode 100644 index 3654bd154..000000000 --- a/docs/5_2_processor.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Processor -layout: default -nav_order: 2 -parent: Infrastructure ---- diff --git a/docs/5_3_coordinator.md b/docs/5_3_coordinator.md deleted file mode 100644 index 854cafc82..000000000 --- a/docs/5_3_coordinator.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Coordinator -layout: default -nav_order: 3 -parent: Infrastructure ---- diff --git a/docs/_config.yml b/docs/_config.yml index 6822eeac2..4db467205 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,5 +2,4 @@ title: Serai Documentation description: Documentation for the Serai protocol. theme: just-the-docs -url: https://serai.exchange/docs -baseurl: /docs +url: https://docs.serai.exchange diff --git a/docs/amm/index.md b/docs/amm/index.md new file mode 100644 index 000000000..ef48ceead --- /dev/null +++ b/docs/amm/index.md @@ -0,0 +1,17 @@ +--- +title: Automatic Market Makers +layout: default +nav_order: 2 +--- + +*text on how AMMs work* + +Serai uses a symmetric liquidity pool with the `xy=k` formula. + +Concentrated liquidity would presumably offer less slippage on swaps, and there are +[discussions to evolve to a concentrated liquidity/order book environment](https://github.com/serai-dex/serai/issues/420). +Unfortunately, it effectively requires active management of provided liquidity. +This disenfranchises small liquidity providers who may not have the knowledge +and resources necessary to perform such management. Since Serai is expected to +have a community-bootstrapped start, starting with concentrated liquidity would +accordingly be contradictory. diff --git a/docs/3_cross_chain.md b/docs/cross_chain/index.md similarity index 100% rename from docs/3_cross_chain.md rename to docs/cross_chain/index.md diff --git a/docs/4_1_genesis.md b/docs/economics/genesis.md similarity index 100% rename from docs/4_1_genesis.md rename to docs/economics/genesis.md diff --git a/docs/4_0_economics.md b/docs/economics/index.md similarity index 100% rename from docs/4_0_economics.md rename to docs/economics/index.md diff --git a/docs/4_3_post.md b/docs/economics/post.md similarity index 100% rename from docs/4_3_post.md rename to docs/economics/post.md diff --git a/docs/4_2_pre.md b/docs/economics/pre.md similarity index 100% rename from docs/4_2_pre.md rename to docs/economics/pre.md diff --git a/docs/index.md b/docs/index.md index 99aa98318..2246e51c9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,4 +4,8 @@ layout: home nav_order: 1 --- -Documentation for Serai. +Serai is a cross-chain decentralized exchange, integrating Bitcoin, Ethereum, +and Monero. + +This documentation site is still under active development and may have missing +sections, errors, and typos. diff --git a/docs/infrastructure/coordinator.md b/docs/infrastructure/coordinator.md new file mode 100644 index 000000000..2d69e0965 --- /dev/null +++ b/docs/infrastructure/coordinator.md @@ -0,0 +1,19 @@ +--- +title: Coordinator +layout: default +nav_order: 3 +parent: Infrastructure +--- + +The coordinator is a local service which communicates with other validators' +coordinators. It provides a verifiable broadcast layer for various consensus +messages, such as agreement on external blockchains, key generation and signing +protocols, and the latest Serai block. + +The verifiable broadcast layer is implemented via a blockchain, referred to as a +Tributary, which is agreed upon using Tendermint consensus. This consensus is +not as offered by Tendermint Core/CometBFT, as used in the Cosmos SDK +(historically/presently), yet by our own implementation designed to be used as a +library and not as another daemon. Tributaries are ephemeral, only used by the +current validators, and deleted upon the next epoch. All of the results from it +are verifiable via the external network and the Serai blockchain alone. diff --git a/docs/5_0_infrastructure.md b/docs/infrastructure/index.md similarity index 100% rename from docs/5_0_infrastructure.md rename to docs/infrastructure/index.md diff --git a/docs/infrastructure/message_queue.md b/docs/infrastructure/message_queue.md new file mode 100644 index 000000000..fa8e0f8ef --- /dev/null +++ b/docs/infrastructure/message_queue.md @@ -0,0 +1,25 @@ +--- +title: Message Queue +layout: default +nav_order: 1 +parent: Infrastructure +--- + +The Message Queue is a microservice to authenticate and relay messages between +services. It offers just three functions: + +1) Queue a message. +2) Receive the next message. +3) Acknowledge a message, removing it from the queue. + +This ensures messages are delivered between services, with their order +preserved. This also ensures that if a service reboots while handling a message, +it'll still handle the message once rebooted (and the message will not be lost). + +The Message Queue also aims to offer increased liveliness and performance. +If services directly communicated, the rate at which one service could operate +would always be bottlenecked by the service it communicates with. If the +receiving service ever went offline, the sending service wouldn't be able to +deliver messages until the receiver came back online, halting its own work. By +defining a dedicated microservice, with a lack of complex logic, it's much less +likely to go offline or suffer from degraded performance. diff --git a/docs/infrastructure/processor.md b/docs/infrastructure/processor.md new file mode 100644 index 000000000..fb542cad1 --- /dev/null +++ b/docs/infrastructure/processor.md @@ -0,0 +1,19 @@ +--- +title: Processor +layout: default +nav_order: 2 +parent: Infrastructure +--- + +The processor performs several important tasks with regards to the external +network. Each of them are documented in the following sections. + +# Key Generation + +# Scanning + +# Signing Batches + +# Planning Transactions + +# Cosigning diff --git a/docs/5_4_serai.md b/docs/infrastructure/serai.md similarity index 100% rename from docs/5_4_serai.md rename to docs/infrastructure/serai.md diff --git a/docs/integrating/index.md b/docs/integrating/index.md new file mode 100644 index 000000000..764441e25 --- /dev/null +++ b/docs/integrating/index.md @@ -0,0 +1,6 @@ +--- +title: Integrating with Serai +layout: default +nav_order: 6 +has_children: true +--- diff --git a/docs/6_0_validator.md b/docs/validator/index.md similarity index 84% rename from docs/6_0_validator.md rename to docs/validator/index.md index 81db7be3c..a652fd16b 100644 --- a/docs/6_0_validator.md +++ b/docs/validator/index.md @@ -1,6 +1,6 @@ --- title: Running a Validator layout: default -nav_order: 6 +nav_order: 7 has_children: true ---