diff --git a/docs/docs/aleph_zero/collections.md b/docs/docs/aleph_zero/collections.md index 68e88ac8..9f4457c0 100644 --- a/docs/docs/aleph_zero/collections.md +++ b/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 diff --git a/docs/docs/aleph_zero/entrypoints.md b/docs/docs/aleph_zero/entrypoints.md index 2c5adf35..d12ac08a 100644 --- a/docs/docs/aleph_zero/entrypoints.md +++ b/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 #### Output parameters |Type|Description| |-|-| -|Option|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|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 diff --git a/docs/docs/aleph_zero/installation.md b/docs/docs/aleph_zero/installation.md index 01891e08..6892cd50 100644 --- a/docs/docs/aleph_zero/installation.md +++ b/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)) diff --git a/docs/docs/aleph_zero/invariant_errors.md b/docs/docs/aleph_zero/invariant_errors.md new file mode 100644 index 00000000..030e0888 --- /dev/null +++ b/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 | diff --git a/docs/docs/aleph_zero/main_structure.md b/docs/docs/aleph_zero/main_structure.md deleted file mode 100644 index c965c9e1..00000000 --- a/docs/docs/aleph_zero/main_structure.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Main structure - -slug: /aleph_zero/main_structure ---- - -In order to maintain minimal fees, we consolidate all data within a single contract. This streamlined approach significantly reduces the expenses associated with creating pools and positions. This efficiency not only minimizes costs but also simplifies the overall process, making it more accessible and user-friendly. By conducting all state changes and positioning all entrypoints exclusively within this one contract, we eliminate the complexities of interacting with and monitoring numerous external contracts. The vast majority of our data is intelligently stored using mapping, which not only preserves precious storage resources but also enhances the overall efficiency of our system. \ No newline at end of file diff --git a/docs/docs/aleph_zero/project_structure.md b/docs/docs/aleph_zero/project_structure.md index c86e2fda..66da9477 100644 --- a/docs/docs/aleph_zero/project_structure.md +++ b/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 ``` diff --git a/docs/docs/aleph_zero/storage.md b/docs/docs/aleph_zero/storage.md index c6faa61c..60c546e9 100644 --- a/docs/docs/aleph_zero/storage.md +++ b/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 diff --git a/docs/docs/aleph_zero/types.md b/docs/docs/aleph_zero/types.md index a0c8469f..518a82b4 100644 --- a/docs/docs/aleph_zero/types.md +++ b/docs/docs/aleph_zero/types.md @@ -4,22 +4,55 @@ 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, } @@ -27,35 +60,41 @@ pub struct SqrtPrice { ### 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); ``` \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index d27eae09..c8358516 100644 --- a/docs/sidebars.js +++ b/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',