Add docs, correct URL

serai-dex · Mar 12, 2024 · 442d8c0 · 442d8c0
1 parent d1be9ea
commit 442d8c0
Show file tree

Hide file tree

Showing 20 changed files with 94 additions and 28 deletions.
diff --git 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
diff --git a/docs/5_1_message_queue.md b/docs/5_1_message_queue.md
diff --git a/docs/5_2_processor.md b/docs/5_2_processor.md
diff --git a/docs/5_3_coordinator.md b/docs/5_3_coordinator.md
diff --git 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
@@ -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 → docs/cross_chain/index.md b/docs/3_cross_chain.md → docs/cross_chain/index.md
diff --git a/docs/4_1_genesis.md → docs/economics/genesis.md b/docs/4_1_genesis.md → docs/economics/genesis.md
diff --git a/docs/4_0_economics.md → docs/economics/index.md b/docs/4_0_economics.md → docs/economics/index.md
diff --git a/docs/4_3_post.md → docs/economics/post.md b/docs/4_3_post.md → docs/economics/post.md
diff --git a/docs/4_2_pre.md → docs/economics/pre.md b/docs/4_2_pre.md → docs/economics/pre.md
diff --git 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
@@ -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 → docs/infrastructure/index.md b/docs/5_0_infrastructure.md → docs/infrastructure/index.md
diff --git a/docs/infrastructure/message_queue.md 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
@@ -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 → docs/infrastructure/serai.md b/docs/5_4_serai.md → docs/infrastructure/serai.md
diff --git a/docs/integrating/index.md 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 → docs/validator/index.md b/docs/6_0_validator.md → docs/validator/index.md
@@ -1,6 +1,6 @@
 ---
 title: Running a Validator
 layout: default
-nav_order: 6
+nav_order: 7
 has_children: true
 ---