Alph docs update

docs/docs/alephium/collections.md

@@ -292,19 +292,19 @@ Retrieves a pool associated with the specified pool key.
 ## Fee Tiers
 
 ```rust
-Abstract Contract FeeTiers() {...}
+struct FeeTiers {
+    mut feeTiers: [FeeTier; 32]
+}
 
-Contract Invariant(mut feeTierCount: U256) extends FeeTiers(), ...{
-    ...
-    mapping[U256, FeeTier] feeTiers
-    ...
+Contract Invariant(mut feeTiers: FeeTiers, feeTierCount: U256, ...){
+    const MaxFeeTiers = 32
 }
 ```
-The `FeeTiers` Abstract Contract is designed to manage fee tiers. It utilizes a mapping data structure, where each element corresponds to a different fee tier represented by a `FeeTier` object. The provided functions allow you to add, retrieve, update, and remove fee tiers within the collection. Each fee tier is uniquely identified within the mapping, and you can perform operations on these fee tiers based on their index. The current maximal index is stored in the `feeTierCount` variable.
+The `FeeTiers` struct is designed to manage fee tiers. It utilizes an array of `FeeTier` objects. The provided functions allow you to add, retrieve, update, and remove fee tiers within the collection. You can perform operations on these fee tiers based on their index. The current highest index is stored in the `feeTierCount` variable. Our protocol stores at most 32 active fee tiers.
 
-| Type                   | Key                               | Value                                 |
-| ---------------------- | --------------------------------- | ------------------------------------- |
-| mapping[PoolKey, Pool] | The pool key of a specified pool. | Pool struct holding the pool's data. |
+| Type                   | Value                                 |
+| ---------------------- | ------------------------------------- |
+| [FeeTier; 32] | FeeTier struct holding the fee tier's data. |
 
 ### Add fee tier
 
@@ -344,7 +344,7 @@ Removes a fee tier associated with the specified FeeTier. Throws an exception if
 pub fn containsFeeTier(feeTier: FeeTier) -> Bool;
 ```
 
-Verifies if specified fee tier exist.
+Verifies if specified fee tier exists.
 
 #### Input parameters
 
@@ -558,7 +558,7 @@ The `Reserves` Abstract Contract is designed to overcome the challenge of being
 
 | Type                   | Key                               | Value                                 |
 | ---------------------- | --------------------------------- | ------------------------------------- |
-| mapping[ByteVec, ByteVec] | The ContractId of a given token. | The ContractId of the reserve containing the given token. |
+| mapping[ByteVec, ByteVec] | The ContractId of a given token. | The Contract ID of the reserve containing the given token. |
 
 ### Add reserve
 
@@ -593,7 +593,7 @@ This function employs the token[X|Y] naming convention, indicating that arrangin
 
 ```rust
 @using(updateFields = true, preapprovedAssets = true)
-fn handleReserves(caller: Address, subPath: ByteVec, tokenX: ByteVec, tokenY: ByteVec) -> (ByteVec, ByteVec);
+fn handleReserves(caller: Address, tokenX: ByteVec, tokenY: ByteVec) -> (ByteVec, ByteVec);
 ```
 
 Retrieves the ids of `Reserve`s for both tokens. If a token isn't stored in a Reserve yet allocates space for it.
@@ -603,7 +603,6 @@ Retrieves the ids of `Reserve`s for both tokens. If a token isn't stored in a Re
 | Name  | Type    | Description           |
 | ----- | ------- | --------------------- |
 | caller   | Address | Address of the user who wants to know where the Token is or will be stored. They are required to pay the eventual fee.|
-| subPath | ByteVec     | Unique path to be used in case a new Reserve has to be created.|
 | tokenX | ByteVec     | Id of the first token.|
 | tokenY | ByteVec     | Id of the second token.|
 

docs/docs/alephium/entrypoints.md

@@ -16,8 +16,8 @@ Contract Invariant(
     mut lastReserveId: ByteVec,
     mut feeTierCount: U256,
     mut poolKeyCount: U256
-) extends PoolKeyHelper(), Decimal(), FeeTiers(), PoolKeys(),
-    Pools(clamm), Ticks(), Tickmap(), Positions(clamm), FeeTierHelper(), Reserves();
+) extends PoolKeyHelper(), Decimal(), PoolKeys(), Pools(clamm),
+     Ticks(), Tickmap(), Positions(clamm), FeeTierHelper(), Reserves();
 ```
 
 This constructor method initializes the contract with the specified protocol fee and administrator.
@@ -143,11 +143,11 @@ This action is only available to the administrator.
 :::
 
 ```rust
-@using(preapprovedAssets = true)
+@using(preapprovedAssets = true, updateFields = true)
 pub fn addFeeTier(feeTier: FeeTier) -> ();
 ```
 
-This function enables the addition of a new fee tier, which users can subsequently utilize when creating pools.
+This function enables the addition of a new fee tier, which users can subsequently utilize when creating pools. Up to 32 fee tiers can exist.
 
 #### Input parameters
 
@@ -163,6 +163,8 @@ This function enables the addition of a new fee tier, which users can subsequent
 | `InvalidTickSpacing`  | Fails if the tick spacing is invalid.                        |
 | `FeeTierAlreadyExist` | Fails if the fee tier already exists.                        |
 | `InvalidFee`          | Fails if fee is invalid.                                     |
+| `FeeTierLimitReached` | Fails if the maximal number of fee tiers (32) already exists.|
+
 
 ### Fee Tier exists
 
@@ -254,14 +256,14 @@ This function employs the token[0|1] naming convention, indicating that arrangin
 pub fn createPool(token0: ByteVec, token1: ByteVec, feeTier: FeeTier, initSqrtPrice: U256, initTick: I256) -> ();
 ```
 
-This function creates a pool based on a pair of tokens and the specified fee tier. Only one pool can exist with a specific combination of two tokens and a fee tier.
+This function creates a pool based on a pair of tokens and the specified fee tier. Only one pool can exist with an unique combination of two tokens and a fee tier.
 
 #### Input parameters
 
 | Name            | Type      | Description                                                            |
 | --------------- | --------- | ---------------------------------------------------------------------- |
-| token0         | AccountId | Address of the first token in the pair.                          |
-| token1         | AccountId | Address of the second token in the pair.                         |
+| token0 | ByteVec   | Contract ID of the first token in the pair.|
+| token1         | ByteVec | Contract ID of the second token in the pair.                         |
 | feeTier        | FeeTier   | The fee tier to be applied.                                            |
 | initSqrtPrice | U256 | The square root of the price for the initial pool related to initTick. |
 | initTick       | I256       | The initial tick value for the pool.                                   |
@@ -304,19 +306,33 @@ This function retrieves a pool based on PoolKey. It returns false as the first t
 | Bool | If true the pool was found and retrieved successfully, false otherwise.|
 | Pool | A struct containing pool data. |
 
-### Get pools
+### Get pools for a token pair
+
+:::info token sorting
+
+This function employs the token[0|1] naming convention, indicating that arranging these tokens in ascending order by `contractId` is not necessary.
+
+:::
 
 ```rust
-pub fn getPools() -> ByteVec;
+pub fn getAllPoolsForPair(token0: ByteVec, token1: ByteVec) -> ByteVec;
 ```
 
-This function retrieves listed pool keys.
+This function retrieves all pools for the given token pair.
+
+#### Input parameters
+
+| Name     | Type      | Description                                    |
+| -------- | --------- | ---------------------------------------------- |
+| token0 | ByteVec   | Contract ID of the first token in the pair.|
+| token1 | ByteVec   | Contract ID of the second token in the pair.|
+
 
 #### Output parameters
 
 | Type          | Description                                            |
 | ------------- | ------------------------------------------------------ |
-| ByteVec | ByteVec containing all pool keys that indicate all pools listed. |
+| ByteVec | ByteVec containing all pools for a given key pair that indicate all pools listed. |
 
 ## Position
 
@@ -694,27 +710,28 @@ Retrieves the amount of liquidity ticks of a specified pool.
 | Type | Description                          |
 | ---- | ------------------------------------ |
 | u32  | Number of ticks on a specified pool. | -->
-<!-- 
+
 ## Tickmap
 
 ### Get tickmap
 
 ```rust
-#[ink(message)]
-fn get_tickmap(&self, pool_key: PoolKey, center_tick: i32) -> Vec<(u16,u64)>;
+pub fn getTickmapSlice(poolKey: PoolKey, lowerBatch: U256, upperBatch: U256, xToY: Bool) -> ByteVec
 ```
 
-Retrieves tickmap chunks for a specified pool.
+Retrieves a slice of tickmap batches for a specified pool. The value of `lowerBatch` should be less than `upperBatch`.
 
 #### Input parameters
 
 | Name        | Type    | Description                                      |
 | ----------- | ------- | ------------------------------------------------ |
 | pool_key    | PoolKey | A unique key that identifies the specified pool. |
-| center_tick | i32     | Center tick index.                               |
+| lowerBatch | U256     | Index of the lower tickmap batch.                |
+| upperBatch | U256     | Index of the upper tickmap batch.                |
+| xToY | Bool | If `xToY` is `true` return batches from `lowerBatch` to `upperBatch`, else the other way around.
 
 #### Output parameters
 
 | Type            | Description                                       |
 | --------------- | ------------------------------------------------- |
-| Vec<(u16,u64)/> | Vector containing tickmap chunks index and value. | -->
+| ByteVec| ByteVec containing tickmap chunk index and value. |

docs/docs/alephium/installation.md

@@ -69,8 +69,8 @@ sudo apt-get update
 sudo apt-get install docker-compose-plugin
 ```
 
-
-## Build Protocol
+## Protocol
+### Build 
 
 #### Clone repository
 
@@ -96,11 +96,25 @@ cd alephium-stack && make start-devnet
 npm run compile
 ```
 
-#### Run tests
+### Test
+
+##### All
 
 ```bash
 npm run test
 ```
+
+##### Contracts
+
+```bash
+npm run test:contract
+```
+
+##### SDK
+
+```bash
+npm run test:sdk
+```
 <!-- TODO-ALEPHIUM: describe SDK installation -->
 <!-- ## Build SDK
 

docs/docs/alephium/invariant_errors.md

@@ -36,6 +36,7 @@ This section outlines error codes essential for maintaining the integrity of Inv
 | ChunkNotFound | 25 | Unable to retrieve the state of the specified chunk in tickmap. |
 | InvalidTickmapBit | 26 | An illegal operation on a tickmap bit has been requested. |
 | PositionNotFound | 27 | Unable to retrieve the state of the specified position. |
+| FeeTierLimitReached | 28 | The maximal number of fee tiers (32) already exists.|
 | SqrtPriceOutOfRange | 7001 | SqrtPrice not in the MinSqrtPrice <= sqrtPrice <= MaxSqrtPrice range. |
 
 <!-- | CastOverflow | 100001 | Internal overflow during cast from U512 to U256. |

docs/docs/alephium/overview.md

@@ -96,7 +96,21 @@ Meanwhile the functions suite simplifies transaction building, allowing develope
 
 ### Test
 
-The "test" 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.
+The "test" directory hosts an extensive suite of tests, and is further split into these subdirectories:
+
+```
+📂test
+ ┣ 📂contract
+ ┃ ┣ 📂e2e
+ ┃ ┗ 📂unit
+ ┗ 📂sdk
+   ┣ 📂e2e
+   ┗ 📂unit
+```
+
+The split into "contract" and "sdk" subdirectories is motivated by division of responsibility between different levels of abstraction in our protocol.  
+In the "contract" directory the tests anticipate even the most malicious behaviors meant to harm our contract, they are meant to validate behaviors in all cases. These tests cover entrypoints for both basic and edge cases, ensuring thorough examination of the protocol's functionality across a spectrum of scenarios. The "sdk" directory contains tests that validate and verify expected behaviors and edge cases pertaining to the usage of our SDK.  
+These directories are further split into "e2e" - a suite of end-to-end (e2e) tests that pertain to entry points users can directly interact with in a meaningful way, and "unit" - tests that focus on individual building blocks of the software, ensuring that each component functions correctly in isolation and indirectly supports user interactions.
 
 ### Source Code Access
 
@@ -108,7 +122,6 @@ For a detailed exploration of our contract structures, collections, and associat
  ┣ 📂alephium-stack
  ┣ 📂contracts
  ┃ ┣ 📂collections
- ┃ ┣ ┣ 📜fee_tiers.ral
  ┃ ┣ ┣ 📜pool_keys.ral
  ┃ ┣ ┣ 📜pools.ral
  ┃ ┣ ┣ 📜positions.ral
@@ -128,8 +141,8 @@ For a detailed exploration of our contract structures, collections, and associat
  ┃ ┣ 📂storage
  ┃ ┣ ┣ 📜batch.ral
  ┃ ┣ ┣ 📜fee_tier.ral
- ┃ ┣ ┣ 📜pool.ral
  ┃ ┣ ┣ 📜pool_key.ral
+ ┃ ┣ ┣ 📜pool.ral
  ┃ ┣ ┣ 📜position.ral
  ┃ ┣ ┣ 📜reserve.ral
  ┃ ┣ ┗ 📜tick.ral
@@ -138,6 +151,7 @@ For a detailed exploration of our contract structures, collections, and associat
  ┃ ┗ 📜invariant.ral
  ┣ 📂src
  ┃ ┣ 📜consts.ts
+ ┃ ┣ 📜fungible-token.ts
  ┃ ┣ 📜index.ts
  ┃ ┣ 📜invariant.ts
  ┃ ┣ 📜math.ts
@@ -146,33 +160,42 @@ For a detailed exploration of our contract structures, collections, and associat
  ┃ ┣ 📜testUtils.ts
  ┃ ┗ 📜utils.ts
  ┗ 📂test
-   ┣ 📜add_fee_tier.test.ts
-   ┣ 📜change_fee_receiver.test.ts
-   ┣ 📜change_protocol_fee.test.ts
-   ┣ 📜claim.test.ts
-   ┣ 📜clamm.test.ts
-   ┣ 📜create_pool.test.ts
-   ┣ 📜cross_both_side.test.ts
-   ┣ 📜cross.test.ts
-   ┣ 📜interaction_with_pool_on_removed_fee_tier.test.ts
-   ┣ 📜invariant.test.ts
-   ┣ 📜limits.test.ts
-   ┣ 📜liquidity_gap.test.ts
-   ┣ 📜log.test.ts
-   ┣ 📜math.test.ts
-   ┣ 📜max_tick_cross.test.ts
-   ┣ 📜multiple_swap.test.ts
-   ┣ 📜position_list.test.ts
-   ┣ 📜position_slippage.test.ts
-   ┣ 📜position.test.ts
-   ┣ 📜protocol_fee.test.ts
-   ┣ 📜remove_fee_tier.test.ts
-   ┣ 📜reserve.test.ts
-   ┣ 📜reserves.test.ts
-   ┣ 📜slippage.test.ts
-   ┣ 📜swap.test.ts
-   ┣ 📜tickmap.test.ts
-   ┣ 📜token.test.ts
-   ┗ 📜uints.test.ts
-
+   ┣ 📂contract
+   ┃ ┣ 📂e2e
+   ┃ ┃ ┣ 📜add-fee-tier.test.ts
+   ┃ ┃ ┣ 📜change-fee-receiver.test.ts
+   ┃ ┃ ┣ 📜change-protocol-fee.test.ts
+   ┃ ┃ ┣ 📜claim.test.ts
+   ┃ ┃ ┣ 📜create-pool.test.ts
+   ┃ ┃ ┣ 📜cross-both-side.test.ts
+   ┃ ┃ ┣ 📜cross.test.ts
+   ┃ ┃ ┣ 📜interaction-with-pool-on-removed-fee-tier.test.ts
+   ┃ ┃ ┣ 📜limits.test.ts
+   ┃ ┃ ┣ 📜liquidity-gap.test.ts
+   ┃ ┃ ┣ 📜max-tick-cross.test.ts
+   ┃ ┃ ┣ 📜multiple-swap.test.ts
+   ┃ ┃ ┣ 📜position-list.test.ts
+   ┃ ┃ ┣ 📜position-slippage.test.ts
+   ┃ ┃ ┣ 📜position.test.ts
+   ┃ ┃ ┣ 📜protocol-fee.test.ts
+   ┃ ┃ ┣ 📜remove-fee-tier.test.ts
+   ┃ ┃ ┣ 📜reserves.test.ts
+   ┃ ┃ ┣ 📜slippage.test.ts
+   ┃ ┃ ┗ 📜swap.test.ts
+   ┃ ┗ 📂unit
+   ┃   ┣ 📜clamm.test.ts
+   ┃   ┣ 📜log.test.ts
+   ┃   ┣ 📜reserve.test.ts
+   ┃   ┣ 📜tickmap.test.ts
+   ┃   ┣ 📜token.test.ts
+   ┃   ┗ 📜uints.test.ts
+   ┗ 📂sdk
+     ┣ 📂e2e
+     ┃ ┣ 📜fungible-token.test.ts
+     ┃ ┣ 📜get-tickmap.test.ts
+     ┃ ┣ 📜invariant.test.ts
+     ┃ ┣ 📜pool-with-alph.test.ts
+     ┃ ┗ 📜query-on-pair.test.ts
+     ┗ 📂unit
+       ┗ 📜math.test.ts
 ```