Merge pull request #307 from invariant-labs/add-error-codes

Added invariant error codes

docs/docs/aleph_zero/collections.md

@@ -4,6 +4,8 @@ title: Collections
 slug: /aleph_zero/collections
 ---
 
+This segment explores key storage structures that manage various entities within the Aleph Zero protocol. Understanding these structures is crucial for developers and integrators engaging with the protocol's data.
+
 ## Positions
 
 ```rust
@@ -151,7 +153,7 @@ pub fn add_tick(&mut self, key: PoolKey, index: i32, tick: Tick) {}
 ```
 
 - **Description**: Adds a new tick associated with a specific PoolKey and index.
-- **Parameters**: key (PoolKey), index (i32)
+- **Parameters**: key (PoolKey), index (i32), tick (Tick)
 - **Edge Cases**: None
 
 ```rust
@@ -164,7 +166,7 @@ pub fn update_tick(
 ```
 
 - **Description**: Updates an existing tick associated with a specific PoolKey and index.
-- **Parameters**: key (PoolKey), index (i32)
+- **Parameters**: key (PoolKey), index (i32), tick: (&Tick)
 - **Edge Cases**: Returns an error if the specified tick does not exist.
 
 ## Pools

docs/docs/aleph_zero/entrypoints.md

@@ -4,6 +4,10 @@ title: Entrypoints
 slug: /aleph_zero/entrypoints
 ---
 
+This section outlines the core entrypoints for the Aleph Zero smart contract, providing developers with essential methods to interact with the protocol. These entrypoints cover various aspects of the contract, including protocol fee management, fee tier administration, pool creation and management, position handling, and swap functionality.
+
+
+
 ### Constructor
 ```rust
 #[ink(constructor)]
@@ -75,7 +79,7 @@ pub fn get_fee_tier(&self, key: FeeTierKey) -> Option<()>
 #### Output parameters
 |Type|Description|
 |-|-|
-|Option<()>|An option that may contain none or an empty unit if the fee tier exists.|
+|Option<()>|An option that may contain `None` or an empty unit if the fee tier exists.|
 This function is used to verify the existence of a specified fee tier.
 
 ### Remove fee tier
@@ -192,7 +196,7 @@ pub fn transfer_position(
 |Name|Type|Description|
 |-|-|-|
 |index|u32|Index of the position in the user's position list.|
-|receiver|i32|Address of the user who will receive the position.|
+|receiver|AccountId|Address of the user who will receive the position.|
 This function changes ownership of an existing position based on the position index in the user's position list. You can only change ownership of positions that you own; otherwise, it will return an error.
 
 ### Remove position
@@ -245,8 +249,8 @@ pub fn get_position(&mut self, index: u32) -> Option<Position>
 #### Output parameters
 |Type|Description|
 |-|-|
-|Option<Position\>|An option that may contain none or a position struct with data if it exists.|
-This function returns an option that contains none if the position index is out of range or a position if it actually exists.
+|Option<Position\>|An option that may contain `None` or a position struct with data if it exists.|
+This function returns an option that contains `None` if the position index is out of range or a position if it actually exists.
 
 ### Get all positions
 ```rust

docs/docs/aleph_zero/installation.md

@@ -4,6 +4,8 @@ title: Installation
 slug: /aleph_zero/installation
 ---
 
+This section provides detailed instructions on how to install the Invariant protocol smart contract on Aleph Zero, including prerequisites and steps for setting up the development environment.
+
 ## Prerequisites
 
 * Rust & Cargo ([rustup](https://www.rust-lang.org/tools/install))

docs/docs/aleph_zero/invariant_errors.md

@@ -0,0 +1,27 @@
+---
+title: Invariant Errors
+
+slug: /aleph_zero/invariant_errors
+---
+
+This section outlines error codes essential for maintaining the integrity of Aleph Zero operations. These codes provide insights into specific issues encountered during interactions with the platform.
+
+| ErrorCode                      | Description                                                               |
+|--------------------------------|---------------------------------------------------------------------------|
+| NotAdmin                     | Unauthorized user attempts to invoke an admin-only message                     |
+| PoolAlreadyExist               | Attempted creation of a pool with same tokens (order does not matter) and same fee tier that already exists                           |
+| PoolNotFound                   | Unable to retrieve the state of the specified pool                        |
+| InvalidTickIndexOrTickSpacing  | Attempt to create a tick with an out-of-bounds index or incorrect spacing |
+| PositionNotFound               | Unable to retrieve the state of the specified position                    |
+| TickNotFound                   | Unable to retrieve the state of the specified tick                        |
+| FeeTierNotFound                | Unable to retrieve the state of the specified fee tier                    |
+| AmountIsZero                   | Attempted swap with zero tokens on input or output depending of swap direction|
+| WrongLimit                     | Attempted swap with an incorrect price limit                              |
+| PriceLimitReached              | Swap would exceed the specified limit                                     |
+| NoGainSwap                     | User would receive zero tokens after the swap                             |
+| InvalidTickSpacing             | Attempted creation of a fee tier with incorrect tick spacing              |
+| FeeTierAlreadyAdded            | Fee tier is already added                                                 |
+| NotFeeReceiver                | Unauthorized user attempts to withdraw protocol fee                            |
+| ZeroLiquidity                  | Attempted opening of a position with zero liquidity                       |
+| TransferError                  | PSP22 token transfer could not be performed                                           |
+| TokensAreSame               | Attempted creation of a pool with exactly the same tokens                 |

docs/docs/aleph_zero/project_structure.md

@@ -4,6 +4,12 @@ title: Project Structure
 slug: /aleph_zero/project_structure
 ---
 
+This section provides an overview of the structural organization of the Invariant protocol smart contract project on Aleph Zero. The project is meticulously structured to enhance readability, maintainability, and efficiency. The architecture is designed to consolidate data within a single contract, minimizing fees and simplifying interactions.
+
+## Contract Architecture
+
+To optimize cost-effectiveness, we centralize data in a singular contract, reducing expenses tied to pool and position creation. This streamlined approach not only cuts costs but also simplifies processes, enhancing accessibility. By concentrating state changes and entrypoints within this central contract, we eliminate the intricacies of managing external contracts, while smart mapping intelligently conserves storage resources and bolsters system efficiency.
+
 ## Simplified
 
 ```
@@ -31,8 +37,7 @@ Our "Collections" directory is dedicated to collections of data that leverage st
 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.
 
 ### Math
-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.
-
+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.
 ### 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.
 
@@ -42,6 +47,10 @@ The "Token" directory is dedicated to the implementation of a fundamental PSP22
 ### Traceable Result
 In the "Traceable Result" directory, you will find a comprehensive library comprising data structures used in debugging processes. In the event of an error, this library generates a detailed stack trace, providing valuable insights that aid in the identification and resolution of issues, thereby promoting the reliability and stability of our contract.
 
+
+### Source Code Access
+For a detailed exploration of our contract structures, collections, and associated logic, please refer to the corresponding [Source Code Repository](https://github.com/invariant-labs/protocol-a0). This repository contains the complete and up-to-date implementation of our contract architecture.
+
 ## Extended
 
 ```

docs/docs/aleph_zero/storage.md

@@ -4,6 +4,8 @@ title: Storage
 slug: /aleph_zero/storage
 ---
 
+This section provides an in-depth exploration of key data structures integral to the Aleph Zero protocol's storage mechanism. Understanding these structures is fundamental for developers and integrators working with the protocol.
+
 ## FeeTier
 
 ```rust

docs/docs/aleph_zero/types.md

@@ -4,58 +4,97 @@ 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.
 
-|Name|Description|
-|-|-|
-|SqrtPrice|Square root of price value|
-|FeeGrowth|Accumulated amount of fees|
-|FixedPoint|Number with fixed number of decimal places|
-|Liquidity|Amount of virtual liquidity|
-|Percentage|Represents values as fractions of 100|
-|SecondsPerLiquidity|Measures the time inside/outside liquidity|
-|TokenAmount|Quantity of specific token|
+## 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.
+- **#underlying_type**: The underlying numeric type.
+
+### Examples
+
+Creating a custom decimal type with 3 decimal places:
+
+```rust
+#[decimal(3)]
+pub struct Decimal {
+  pub v: u128
+}
+```
+
+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|
+|FixedPoint|12|u128|U256|Number with fixed number of decimal places|
+|Liquidity|6|u128|U256|Amount of virtual liquidity|
+|Percentage|12|u64|U256|Represents values as fractions of 100|
+|SecondsPerLiquidity|24|u128|U256|Measures the time inside/outside liquidity|
+|TokenAmount|0|u128|U256|Quantity of specific token|
 
 ## Definitions
 
 ### SqrtPrice
 
 ```rust
+#[decimal(24)]
 pub struct SqrtPrice {
     pub v: u128,
 }
 ```
 
 ### FeeGrowth
 ```rust
+#[decimal(28)]
 pub struct FeeGrowth {
     pub v: u128,
 }
 ```
 ### FixedPoint
 ```rust
+#[decimal(12)]
 pub struct FixedPoint {
     pub v: u128,
 }
 ```
 ### Liquidity
 ```rust
+#[decimal(6)]
 pub struct Liquidity {
     pub v: u128,
 }
 ```
 ### Percentage
 ```rust
+#[decimal(12)]
 pub struct Percentage {
     pub v: u64,
 }
 ```
 ### SecondsPerLiquidity
 ```rust
+#[decimal(24)]
 pub struct SecondsPerLiquidity {
     pub v: u128,
 }
 ```
 ### TokenAmount
 ```rust
+#[decimal(0)]
 pub struct TokenAmount(pub u128);
 ```

docs/sidebars.js

@@ -63,7 +63,7 @@ module.exports = {
       type: 'category',
       label: 'Aleph Zero',
       collapsed: true,
-      items: ['aleph_zero/project_structure', 'aleph_zero/main_structure','aleph_zero/installation','aleph_zero/entrypoints', 'aleph_zero/collections','aleph_zero/storage','aleph_zero/types']
+      items: ['aleph_zero/project_structure','aleph_zero/installation','aleph_zero/entrypoints', 'aleph_zero/collections','aleph_zero/storage','aleph_zero/types', 'aleph_zero/invariant_errors']
     },
     'faq',
     'resources',