Merge pull request #319 from invariant-labs/update-installation-overv…

…iew-types

Adjusted description

docs/docs/aleph_zero/installation.md

@@ -4,42 +4,48 @@ title: Installation
 slug: /aleph_zero/installation
 ---
 
-This section provides detailed instructions on how to install the Invariant protocol on Aleph Zero, including prerequisites and steps for setting up the development environment. 
+This section provides detailed instructions on how to install the Invariant protocol on Aleph Zero, including prerequisites and steps for setting up the development environment.
 
 ## Prerequisites
 
-* Rust & Cargo ([rustup](https://www.rust-lang.org/tools/install))
-* cargo-contract ([cargo-contract](https://github.com/paritytech/cargo-contract))
-* substrate-contracts-node ([substrate-contracts-node](https://github.com/paritytech/substrate-contracts-node))
-* ink! ([ink!](https://use.ink/getting-started/setup))
+- Rust & Cargo ([rustup](https://www.rust-lang.org/tools/install))
+- cargo-contract ([cargo-contract](https://github.com/paritytech/cargo-contract))
+- substrate-contracts-node ([substrate-contracts-node](https://github.com/paritytech/substrate-contracts-node))
 
 ### Rust & Cargo
+
 ```bash
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
 ### cargo-contract
+
 ```bash
 rustup component add rust-src && cargo install --force --locked cargo-contract
 ```
 
 ### substrate-contracts-node
+
 ```bash
 cargo install contracts-node --git https://github.com/paritytech/substrate-contracts-node.git
 ```
+
 ## Build protocol
 
-* Clone repository
+- Clone repository
+
 ```
 git clone [email protected]:invariant-labs/protocol-a0.git
 ```
 
-* Build contract
+- Build contract
+
 ```
 cargo contract build
 ```
 
-* Run tests
+- Run tests
+
 ```
 cargo test --features e2e-tests
 ```

docs/docs/aleph_zero/overview.md

@@ -12,7 +12,7 @@ To optimize gas usage, we centralize data and entrypoints in a singular contract
 
 ## Project structure
 
-The following presents the project's overall structure, supplying insights into the logical segmentation into modules/
+The following presents the project's overall structure, supplying insights into the logical segmentation into modules:
 
 ```
 📦protocol-a0
@@ -24,46 +24,46 @@ The following presents the project's overall structure, supplying insights into
  ┣ 📂decimal
  ┣ 📂math
  ┣ 📂test_helpers
- ┣ 📂tests
+ ┣ 📂e2e
  ┣ 📂token
  ┗ 📂traceable_result
 ```
 
-### Contracts
+### [Decimal](https://github.com/invariant-labs/decimal)
 
-Within this directory, we house our contract structures, collections, and associated logic. These components are pivotal in facilitating the seamless operation of our contract.
+Contained within the "Decimal" directory is a specialized decimal library. This library serves as the foundation for creating custom data types and executing precise mathematical calculations, ensuring accuracy and reliability in our contract.
 
-#### Collections
+### Math
 
-Our "Collections" directory is dedicated to collections of data that leverage structs with mappings or vectors. These collections play a crucial role in organizing and managing data in a structured manner, enhancing the overall functionality and performance of our contract.
+The "Math" directory serves as a repository for core mathematical functions, constants, and custom data types that are meticulously crafted using the Decimal library. These mathematical components are indispensable for performing complex calculations in our contract. This directory includes crucial types like Liquidity and SqrtPrice. For an in-depth understanding of the mathematical specifications implemented in our project, please refer to our comprehensive [Math Specification Document](https://invariant.app/math-spec-a0.pdf). This document provides detailed insights into the design choices, algorithms, and methodologies underpinning our mathematical components.
 
-#### Logic
+### Contracts
 
-The "Logic" folder hosts a suite of specialized mathematical computations crucial for managing the relationship between tokens and liquidity.
+Within this directory, we house our contract structures, collections, and associated logic. These components are pivotal in facilitating the seamless operation of our contract.
 
 #### Storage
 
-The "Storage" directory is home to the essential data structures utilized for contract storage. These structures are instrumental in securely and efficiently storing critical information within our contract.
+The "Storage" directory houses indispensable data structures crucial for contract storage. These structs are specifically crafted to facilitate the sharing of the state of the exchange within the CLAMM model. Notable examples of these structs include Tick, Pool, and others. These data structures play a pivotal role in maintaining and organizing information related to the exchange, ensuring efficient and organized handling of data within the CLAMM model. For instance, the "Tick" struct encapsulates crucial pricing information, while the "Pool" struct manages liquidity pools.
 
-### [Decimal](https://github.com/invariant-labs/decimal)
+#### Collections
 
-Contained within the "Decimal" directory is a specialized decimal library. This library serves as the foundation for creating custom data types and executing precise mathematical calculations, ensuring accuracy and reliability in our contract.
+Our "Collections" directory is dedicated to collections of data that leverage structs with mappings or vectors. These collections play a crucial role in organizing and managing data in a structured manner, enhancing the overall functionality and performance of our contract. Within our collection interface, we enforce a tightly defined set of operations available for all data collections. Each collection implements the same basic methods, allowing for consistent data management regardless of the underlying data structures (vectors or mappings).
 
-### Math
+#### Logic
 
-The "Math" directory serves as a repository for core mathematical functions, constants, and custom data types that are meticulously crafted using the Decimal library. These mathematical components are indispensable for performing complex calculations in our contract. For an in-depth understanding of the mathematical specifications implemented in our project, please refer to our comprehensive [Math Specification Document](https://invariant.app/math-spec-a0.pdf). This document provides detailed insights into the design choices, algorithms, and methodologies underpinning our mathematical components.
+The "Logic" folder hosts a suite of mathematical calculations which are primarily designed for conducting test calculations and supporting our Software Development Kit (SDK). It is noteworthy that optimization efforts for these calculations need not be exhaustive, as they are intended for offline use and will not be executed on the blockchain.
 
 ### Test Helpers
 
-Our "Test Helpers" directory is equipped with macros designed to streamline end-to-end testing processes. These macros are instrumental in simplifying and enhancing the efficiency of our testing procedures, ensuring the robustness of our contract.
+The "Test Helpers" directory contains macros designed for efficient end-to-end testing. These macros abstract low-level calls and transaction building, allowing developers to focus solely on verifying expected logic during tests. This minimizes code repetition, simplifies the testing interface, and ensures a clear and concise testing environment.
 
-### Tests
+### e2e
 
-Within the "Tests" subfolder of our repository, you'll find a comprehensive collection of end-to-end (e2e) tests meticulously crafted to validate and verify the expected behaviors of our protocol. These tests play a pivotal role in ensuring the reliability and robustness of our system.
+The "e2e" subfolder in our repository hosts an extensive suite of end-to-end (e2e) tests meticulously designed to validate and verify expected behaviors within our protocol. These tests cover entrypoints for both basic and edge cases, ensuring thorough examination of the protocol's functionality across a spectrum of scenarios.
 
 ### Token
 
-The "Token" directory is dedicated to the implementation of a fundamental PSP22 token. This token serves as a foundational element in our end-to-end tests, enabling us to simulate production-ready token interactions and transactions.
+The "Token" directory is solely for the implementation of a basic PSP22 token, serving as a key element in our end-to-end tests. It enables us to simulate production-ready token interactions and transactions, with the exchange operating specifically on PSP22 tokens. This detail is essential for implementing transfers in entrypoints and conducting thorough end-to-end tests to validate the protocol.
 
 ### Traceable Result
 
@@ -111,7 +111,7 @@ For a detailed exploration of our contract structures, collections, and associat
 ┃ ┣ 📜snippets.rs
 ┃ ┣ 📜token.rs
 ┃ ┗ 📜entrypoints.rs
-┃ 📂tests
+┃ 📂e2e
 ┃ ┣ 📜add_fee_tier.rs
 ┃ ┣ 📜change_fee_receiver.rs
 ┃ ┣ 📜change_protocol_fee.rs

docs/docs/aleph_zero/types.md

@@ -4,16 +4,19 @@ title: Types
 slug: /aleph_zero/types
 ---
 
-This segment introduces key data types integral to understanding and working with the Aleph Zero protocol. These types play a pivotal role in expressing and managing various aspects of the protocol's functionality.
+This segment introduces key data types essential for understanding and working with the Aleph Zero protocol. Additionally, it's important to note that these types are defined based on decimals, holding numerical values, and serving as fundamental types in the storage layer.
 
 ## Defining Decimal:
+
 We have implemented a custom decimal system, which is detailed in our repository [here](https://github.com/invariant-labs/decimal). The structure of the decimal is outlined below in Rust syntax:
+
 ```rust
 #[decimal(#scale, #big_type)]
 pub struct DecimalName {
   pub v: #underlying_type
 }
 ```
+
 - **#scale**: An `integer` that determines the number of decimal places.
 - **#big_type**: The type to which it will be extended in intermediate operations (default is U256).
 - **DecimalName**: The name of the struct.
@@ -35,66 +38,94 @@ Creating a decimal value:
 ```rust
 let my_decimal = Decimal::new(12042);
 ```
-In this example, the result of creation should be interpreted as 12.042, calculated as `12042 * 10^-3`, considering the specified scale of 3.
 
-|Name|Decimals|Primitive type|Big type|Description|
-|-|-|-|-|-|
-|SqrtPrice|24|u128|U256|Square root of price value|
-|FeeGrowth|28|u128|U256|Accumulated amount of fees per unit of liquidity|
-|FixedPoint|12|u128|U256|Number with fixed number of decimal places|
-|Liquidity|6|u128|U256|Amount of virtual liquidity|
-|Percentage|12|u64|U256|A numerical percentage value|
-|SecondsPerLiquidity|24|u128|U256|Measures the time in seconds per unit of liquidity|
-|TokenAmount|0|u128|U256|Quantity of specific token|
+In this example, the result of creation should be interpreted as 12.042, calculated as `12042 * 10^-3`, considering the specified scale of 3.
 
 ## Definitions
 
+These decimal types are integral to the protocol, offering a granular level of precision for various calculations. They play key roles in pricing, fee accumulation, liquidity representation, percentage metrics, time measurements, and token quantity tracking, contributing to the robust functionality of the Aleph Zero protocol.
+
+| Name                | Decimals | Primitive type | Big type | Description                                        |
+| ------------------- | -------- | -------------- | -------- | -------------------------------------------------- |
+| TokenAmount         | 0        | u128           | U256     | Quantity of specific token                         |
+| SqrtPrice           | 24       | u128           | U256     | Square root of price value                         |
+| FixedPoint          | 12       | u128           | U256     | Number with fixed number of decimal places         |
+| Liquidity           | 6        | u128           | U256     | Amount of virtual liquidity                        |
+| Percentage          | 12       | u64            | U256     | A numerical percentage value                       |
+| FeeGrowth           | 28       | u128           | U256     | Accumulated amount of fees per unit of liquidity   |
+| SecondsPerLiquidity | 24       | u128           | U256     | Measures the time in seconds per unit of liquidity |
+
+### TokenAmount
+
+The TokenAmount type stores **integer** token amounts.
+
+```rust
+#[decimal(0)]
+pub struct TokenAmount(pub u128);
+```
+
 ### SqrtPrice
 
+The SqrtPrice type stores the **square root** of the y-to-x token ratio.
+
 ```rust
 #[decimal(24)]
 pub struct SqrtPrice {
     pub v: u128,
 }
 ```
 
-### FeeGrowth
-```rust
-#[decimal(28)]
-pub struct FeeGrowth {
-    pub v: u128,
-}
-```
 ### FixedPoint
+
+FixedPoint is a type used for precise arithmetic calculations, with half the accuracy of SqrtPrice.
+
 ```rust
 #[decimal(12)]
 pub struct FixedPoint {
     pub v: u128,
 }
 ```
+
 ### Liquidity
+
+The liquidity type represents a value that indicates the ability to exchange. Liquidity is determined by the product of the amount of tokens X, the amount of tokens Y, or the sum of X and Y, and the level of concentration. It is associated with a specific price range. As a result, it can be either active or inactive, depending on whether the current price is within or outside the liquidity range.
+
 ```rust
 #[decimal(6)]
 pub struct Liquidity {
     pub v: u128,
 }
 ```
+
 ### Percentage
+
+The type represents a percentage and is used to simplify interest calculations for various types.
+
 ```rust
 #[decimal(12)]
 pub struct Percentage {
     pub v: u64,
 }
 ```
+
+### FeeGrowth
+
+FeeGrowth is used to calculate the fee amount within a specified price range. FeeGrowth represents TokenAmount in X or Y per unit of liquidity.
+
+```rust
+#[decimal(28)]
+pub struct FeeGrowth {
+    pub v: u128,
+}
+```
+
 ### SecondsPerLiquidity
+
+SecondsPerLiquidity represents the time difference denominated in seconds per liquidity unit.
+
 ```rust
 #[decimal(24)]
 pub struct SecondsPerLiquidity {
     pub v: u128,
 }
 ```
-### TokenAmount
-```rust
-#[decimal(0)]
-pub struct TokenAmount(pub u128);
-```