|
| 1 | +--- |
| 2 | +title: Overview |
| 3 | + |
| 4 | +slug: /vara/overview |
| 5 | +--- |
| 6 | + |
| 7 | +This section provides an overview of the structural organization of the Invariant Protocol program project on Vara. The project is meticulously structured to enhance readability, maintainability, and efficiency. The architecture is designed to consolidate data within a single program, minimizing fees and simplifying interactions. |
| 8 | + |
| 9 | +## Contract Architecture |
| 10 | + |
| 11 | +To optimize gas usage, we centralize data and entrypoints in a singular program, reducing expenses associated with 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 program, we eliminate the intricacies of managing external programs, while smart mapping intelligently conserves storage resources and bolsters system efficiency. Gas checks are used within entrypoints, that work with GRC-20 token, to ensure that the state remains consistent and tokens are not lost in the process. |
| 12 | + |
| 13 | +## Project Structure |
| 14 | + |
| 15 | +The following presents the project's overall structure, supplying insights into the logical segmentation into modules: |
| 16 | + |
| 17 | +``` |
| 18 | +📦protocol-vara |
| 19 | + ┣ 📂src |
| 20 | + ┃ ┣ 📂contracts |
| 21 | + ┃ ┃ ┣ 📂collections |
| 22 | + ┃ ┃ ┣ 📂logic |
| 23 | + ┃ ┃ ┣ 📂storage |
| 24 | + ┃ ┣ 📂e2e |
| 25 | + ┃ ┣ 📂test_helpers |
| 26 | + ┃ ┣ 📜lib.rs |
| 27 | + ┣ 📂calc |
| 28 | + ┃ ┣ 📂decimal |
| 29 | + ┃ ┣ 📂math |
| 30 | + ┃ ┣ 📂traceable_result |
| 31 | + ┣ 📂io |
| 32 | + ┣ 📂state |
| 33 | + ┣ 📂fungible-token |
| 34 | + ┗ 📂xtask |
| 35 | +``` |
| 36 | + |
| 37 | +### Contracts |
| 38 | + |
| 39 | +Within this directory, we house our contract structures, collections, and associated logic. These components are pivotal in facilitating the seamless operation of our program. |
| 40 | + |
| 41 | +#### Storage |
| 42 | + |
| 43 | +The "Storage" directory houses indispensable data structures crucial for program 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 allow for maintaining and organizing information related to the exchange. For example, the "Tick" structure encapsulates details regarding the distribution of liquidity relative to price. The "Position" structure furnishes details about the user's position, such as the price range, size of liquidity, accumulated fees, and more. The "Pool" structure provides real-time information about the pool's status, including the current price (square root of the price), active liquidity, and collected fees. |
| 44 | + |
| 45 | +#### Collections |
| 46 | + |
| 47 | +Our "Collections" directory is dedicated to collections of data that leverage structs with mappings or vectors. These collections helps us manage data in a structured manner. 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). |
| 48 | + |
| 49 | +#### Logic |
| 50 | + |
| 51 | +The "Logic" folder hosts a suite of mathematical calculations which are primarily designed for conducting test calculations and supporting our SDK. It is noteworthy that optimization efforts for these calculations need not be exhaustive, as they are intended for off-chain use and will not be executed on the blockchain. |
| 52 | + |
| 53 | +### Test Helpers |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +### e2e |
| 58 | + |
| 59 | +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. |
| 60 | + |
| 61 | +### Calc |
| 62 | +The "Calc" directory contains packages vital to low level calculations performed within the contract. |
| 63 | + |
| 64 | +#### Decimal |
| 65 | + |
| 66 | +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. [Decimal](https://github.com/invariant-labs/decimal) is also an open-source project. |
| 67 | + |
| 68 | +#### Math |
| 69 | + |
| 70 | +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. |
| 71 | + |
| 72 | +#### Traceable Result |
| 73 | + |
| 74 | +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. |
| 75 | + |
| 76 | +### IO |
| 77 | + |
| 78 | +All structures necessary for communication with the program are stored within "IO" directory. |
| 79 | + |
| 80 | +### State |
| 81 | + |
| 82 | +"State" folder's purpose is to allow for creation of new meta functions to extend existing state queries by defining new filers. |
| 83 | + |
| 84 | +### Fungible Token |
| 85 | + |
| 86 | +The "Fungible Token" directory is solely for the implementation of a basic [GRC-20 token](https://wiki.gear-tech.io/docs/developing-programs/standards/grc20), 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 GRC-20 tokens. This detail is essential for implementing transfers in entrypoints and conducting thorough end-to-end tests to validate the protocol. |
| 87 | + |
| 88 | +### Xtask |
| 89 | + |
| 90 | +Folder contains utility tool for downloading newest gear node binary for `gclient` tests. |
| 91 | +### Source Code Access |
| 92 | + |
| 93 | +For a detailed exploration of our program structures, collections, and associated logic, please refer to the corresponding [Source Code Repository](https://github.com/invariant-labs/protocol-vara). This repository contains the complete and up-to-date implementation of our program architecture. Here lies the comprehensive project structure, which can be represented as follows. |
| 94 | + |
| 95 | +### Lib |
| 96 | + |
| 97 | +The "src/lib.rs" file comprises all entrypoints, storage, and high level program logic, serving as the heart of our protocol's functionality. |
| 98 | + |
| 99 | +``` |
| 100 | +📦protocol-vara |
| 101 | +┣ 📂src |
| 102 | +┗ ┣ 📂test_helpers |
| 103 | + ┃ ┣ 📜mod.rs |
| 104 | + ┃ ┣ 📂snippets |
| 105 | + ┃ ┣ 📂token |
| 106 | + ┃ ┗ 📂entrypoints |
| 107 | + ┣ 📂contracts |
| 108 | + ┃ ┣ 📂collections |
| 109 | + ┃ ┃ ┣ 📜fee_tiers.rs |
| 110 | + ┃ ┃ ┣ 📜pools.rs |
| 111 | + ┃ ┃ ┣ 📜positions.rs |
| 112 | + ┃ ┃ ┣ 📜pool_keys.rs |
| 113 | + ┃ ┃ ┣ 📜tickmap.rs |
| 114 | + ┃ ┃ ┗ 📜ticks.rs |
| 115 | + ┃ ┣ 📂logic |
| 116 | + ┃ ┃ ┣ 📜liquidity_result.rs |
| 117 | + ┃ ┃ ┗ 📜mod.rs |
| 118 | + ┃ ┗ 📂storage |
| 119 | + ┃ ┣ 📜fee_tier.rs |
| 120 | + ┃ ┣ 📜pool_key.rs |
| 121 | + ┃ ┣ 📜pool.rs |
| 122 | + ┃ ┣ 📜position.rs |
| 123 | + ┃ ┣ 📜state.rs |
| 124 | + ┃ ┗ 📜tick.rs |
| 125 | + ┗ 📂e2e |
| 126 | + ┗ 📂gtest |
| 127 | + ┣ 📜add_fee_tier.rs |
| 128 | + ┣ 📜change_fee_receiver.rs |
| 129 | + ┣ 📜change_protocol_fee.rs |
| 130 | + ┣ 📜claim.rs |
| 131 | + ┣ 📜create_pool.rs |
| 132 | + ┣ 📜cross_both_sides.rs |
| 133 | + ┣ 📜cross.rs |
| 134 | + ┣ 📜get_pool.rs |
| 135 | + ┣ 📜get_pools.rs |
| 136 | + ┣ 📜init.rs |
| 137 | + ┣ 📜interaction_with_pool_on_remove_fee_tier.rs |
| 138 | + ┣ 📜limits.rs |
| 139 | + ┣ 📜liquidity_gap.rs |
| 140 | + ┣ 📜max_tick_cross.rs |
| 141 | + ┣ 📜multiple_swap.rs |
| 142 | + ┣ 📜position_list.rs |
| 143 | + ┣ 📜position_slippage.rs |
| 144 | + ┣ 📜position.rs |
| 145 | + ┣ 📜protocol_fee.rs |
| 146 | + ┣ 📜remove_fee_tier.rs |
| 147 | + ┣ 📜slippage.rs |
| 148 | + ┣ 📜swap_route.rs |
| 149 | + ┗ 📜swap.rs |
| 150 | +
|
| 151 | +``` |
0 commit comments