Merge pull request #4 from 0xSpaceShard/fix/concepts-and-definitions

fix: arch and new concepts

docs/concepts/epoch.md

@@ -0,0 +1,12 @@
+---
+id: epoch
+title: Epoch
+sidebar_position: 3
+---
+
+# Epoch
+
+On Nimbora, keeping track of each processed batch is crucial. Since Starknet and Ethereum are asyncronous in their essence, we need a mechanism to syncronize the contracts state between both chains. To achieve that, each processed and closed batch send from L2 to L1 contains an epoch. This way we ensure that:
+
+- Batches are processed in the correct order.
+- No batch can be processed more than once.

docs/concepts/overview/overview.md → docs/concepts/overview.md

@@ -18,7 +18,9 @@ At the moment, Nimbora supports compatibility with [Argent X wallet](https://www
 
 ## Transaction processing and batching
 
-When the Nimbora Pooling Manager contract receives requests, it opens a new batch and adds those requests until the batch is full. Once the bach is full, the contract will empack all the requests and send them to the L1 Pooling contract. This message will take some time to be verified on L1 depending on the network congestion, but it should not take more than 12h. Once the block is validated on L1, the message is ready to be consumend by the L1 Pooling Contract.
+When the Nimbora [L2 Pooling Manager](/docs/contracts/architecture/L2_arch.md#pooling-manager) contract receives a requests, it opens a new batch and accumulates those requests until the batch is full. Once the batch is full, the contract will empack all the requests and send them to the [L1 Pooling Manager](/docs/contracts/architecture/L1_arch.md#pooling-manager) contract. This message will take some time to be verified on L1 depending on the network congestion, but it should not take more than 12h. Once the block is validated on L1, the message is ready to be consumed by the L1 Pooling Contract.
+
+When consuming the message, the L1 Pooling Manager will get the assets to be handled from the Starkgate Bridge and deposit them within the strategies. Finally, the L1 Pooling Manager will generate a report to inform the L2 Pooling Manager that the deposits were made correctly.
 
 ## Where can I get help?
 

docs/concepts/reports.md

@@ -0,0 +1,22 @@
+---
+id: reports
+title: Reports
+sidebar_position: 2
+---
+
+# Reports
+
+The reports exist within both L1 and L2 Pooling Manager contracts and they are the means of communication between those two contracts.
+
+## L1 Reports
+
+From the L1 Pooling Manager perspective, reports represent messages received by the L1 Pooling Manager contract and it contains relevant data regarding the strategy status.
+More specifically, contains the L1 strategy address, L1 net asset value (deposited asset's value), the amount to be deposited or withdrawn to/from the strategy and finally the status of the L1 strategy process.
+
+With this information, the L1 Pooling Manager is able to communicate with the Starkgate bridge in order to fetch and bridge assets to and from L2. and it is also able to target the strategy it needs to interact with.
+
+## L2 Reports
+
+From the L2 Pooling Manager perspective, reports represent incoming messages from L1. This data is used to process and update L2 startegies (Token Manager and Token contracts) according to the new L1 strategy status. Once the data integrity is verified, it fetches bridge assets in order to, later, tansfers it to users and updates the strategy data.
+
+This report is crucial for syncronizing L1 strategies data with the L2 contract state and it ensures only valid data is processed, all while contract's state remains consistent with L1.

docs/concepts/strategies/_category_.json

@@ -1,5 +1,5 @@
 {
     "label": "Strategies",
-    "position": 2,
+    "position": 4,
     "collapsed": false
 }

docs/contracts/architecture/L1_arch.md

@@ -8,11 +8,11 @@ sidebar_position: 2
 
 ### Pooling Manager
 
-The pooling manager plays an intermediate role with L1 strategies and L2 communication. The contract receives a payload of data, containing all the information required to cover L2 strategy requests: deposit more in a strategy, inform the underlying NAV, or withdraw some assets.
+The pooling manager plays an intermediate role with L1 strategies and L2 communication. The contract receives L2 user's requests, to deposit or withdraw their assets from the strategies. Also, it generates [reports](/docs/concepts/reports.md) based on the user's actions on the different strategies and sends this information back to the [L2 Pooling Manager](/docs/contracts/architecture/L2_arch.md#pooling-manager).
 
-### Strategy handler
+### Strategy
 
-The strategy handler is an adapter used to interact with strategies, it receives data of payload similar for each handler and processes the request before returning the new NAV of the strategy and potentially some ETH to bridge.
+The Strategy contract handles commands from the L1 Pooling Manager and connects it to the targeted strategies. There will be one Strategy Contract addapter for each strategy Nimbora supports. This design enables full scalability regardless of the amount of strategies the platform handles or future integrations.
 
 Nimbora Yield DEX off-chain services allow for the indexing and processing L1 and L2 reports. For more details, please check this link.
 

docs/contracts/architecture/L2_arch.md

@@ -8,18 +8,20 @@ sidebar_position: 3
 
 ### Pooling Manager
 
-The pooling manager plays an intermediate role with L2 strategies and L1 communication. The idea is to significantly reduce gas costs on L1 by hashing all of the data and mutualizing bridge transfer. He is also responsible for registering all available strategies and is the only one able to process reports. although he is processing all at once, he is also able to process only one report individually so a broken strategy has no impact on others.
+The pooling manager plays an intermediate role with L2 Token Manager and L1 communication. The idea is to significantly reduce gas costs on L1 transactions by packing user's requests and mutualizing bridge transfer. It is also responsible for registering all available strategies and processes incoming strategy [reports](/docs/concepts/reports.md) from L1. 
+
+This design enables isolation between startegies thus, if one strategy report fails, it will not affect other strategies.
 
 ### Pooling Factory
 
-The pooling factory is the contract used to deploy new “strategy packages”: token, and token manager, those contracts are the same for any strategy.
+The Pooling Factory is a contract able to deploy new Strategies on L2. When it does, it generates two contracts for each strategy. One Token Manager contract and on Token contract. Also, it makes sure that this two newly deployed contracts are linked to the correct strategy on L1, enabling users to interact with it.
 
-### N-yield Token Manager
+### Token Manager
 
-The token manager contains all the logic for token accountability through a strategy report, setting the share price at each epoch. It is also the entry point for deposit and withdraw, only this contract can mint or burn tokens.
+The token manager contains all the logic for strategy accountability. This is achieved through the strategy [reports](/docs/concepts/reports.md). Setting the share price at each epoch and working as an entry point for deposit and withdraw the Token Manager is the principal contract users will interact with in order to use Nimbora.
 
-### N-yield Token
+### Token
 
-The Nimbora yield token represents the l1 strategy yield-bearing token, increasing in value at each epoch. Once minted, it can be used in DeFi through the Starknet ecosystem.
+The Token contract represents users's share of the L1 strategy pool, increasing in value at each epoch. Since the Token contract is based on the ERC20 standard, it can be used in DeFi through the Starknet ecosystem.
 
 ![l2_arch](/content/L2_arch.png)

package.json

@@ -22,8 +22,8 @@
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
     "react": "^18.0.0",
-    "react-feather": "^2.0.10",
     "react-dom": "^18.0.0",
+    "react-feather": "^2.0.10",
     "theme": "^0.1.0"
   },
   "devDependencies": {

src/pages/index.js

@@ -244,8 +244,6 @@ export default function Home() {
             }}
           >
             <h1 style={{ fontWeight: 600 }}> Welcome to Nimbora Docs</h1>
-            <HideMedium>
-            </HideMedium>
           </div>
 
           <Row>