Updated readme

Author: Logic-gate-sys

README.md

@@ -1,39 +1,45 @@
--- The fundamental idea is to create a system where users can deposit an underlying asset (for example, ETH or a stablecoin like WETH) into a central smart contract, which we'll refer to as the Vault.
- In exchange for their deposit, users receive rebase tokens. These rebase tokens are special; they represent the user's proportional share of the total underlying assets held within the Vault, including any interest or rewards that accrue over time.
+# Rebase Token Protocol
 
-# The defining characteristic of a rebase token is how its supply adjusts, directly impacting a holder's balance.
+## Overview
 
-Dynamic Balances: The balanceOf(address user) function, a standard ERC20 view function, will be designed to return a dynamic value. This means that when a user queries their balance, it will appear to increase over time, reflecting their share of accrued interest or rewards. In our specific implementation, this increase will be calculated linearly with time.
+This protocol enables users to deposit an underlying asset (such as ETH or a stablecoin like WETH) into a central smart contract, referred to as the **Vault**. In return, users receive **rebase tokens** that represent their proportional share of the total underlying assets held within the Vault, including any accrued interest or rewards.
 
-balanceOf is a View Function (Gas Efficiency): It's crucial to understand that the balanceOf function shows the user's current theoretical balance, including dynamically calculated interest. However, calling balanceOf itself does not execute a state-changing transaction on the blockchain. It doesn't mint new tokens with every call, as that would incur gas costs for simply viewing a balance. This design is critical for gas efficiency.
+## Key Features
 
-State Update on Interaction: The actual minting of the accrued interest (i.e., updating the user's on-chain token amount) will occur strategically before a user performs any state-changing action with their tokens. These actions include:
+### Dynamic Balances
 
-Depositing more underlying assets (minting more rebase tokens).
+- The `balanceOf(address user)` function, following the ERC20 standard, returns a **dynamic value**. User balances increase over time, reflecting their share of accrued interest or rewards.
+- The increase in balance is calculated **linearly with time** in this implementation.
+- Importantly, `balanceOf` is a **view function**—it does not trigger state changes or mint new tokens on each call, ensuring **gas efficiency**.
 
-Withdrawing/redeeming their underlying assets (burning rebase tokens).
+### State Updates on Interaction
 
-Transferring their rebase tokens to another address.
+- Accrued interest is **minted** and user balances are updated **only** when a user performs a state-changing action, such as:
+  - Depositing additional assets (minting more rebase tokens)
+  - Withdrawing or redeeming assets (burning rebase tokens)
+  - Transferring rebase tokens
+  - (Future) Bridging tokens to another chain
+- Before executing any of these actions, the contract calculates and mints the interest accrued since the user’s last interaction, updating their on-chain balance before proceeding.
 
-(In the future) Bridging their tokens to another chain.
+## Interest Rate Mechanism
 
-The mechanism works as follows: When a user initiates one of these actions, the contract will first check the time elapsed since their last interaction. It then calculates the interest accrued to that user during this period, based on their specific interest rate (more on this below). These newly calculated interest tokens are then minted to the user's recorded balance on-chain. Only after this balance update does the contract proceed to execute the user's original requested action (e.g., transfer, burn) with their now up-to-date balance.
+- The protocol features a **global interest rate**, managed by an owner or governance mechanism, which determines the base rate for interest accrual.
+- **Decreasing Global Rate:** The global interest rate can **only decrease** over time; it cannot be increased once set.
+- **User-Specific Interest Rate Snapshot:** On a user’s first deposit, the contract snapshots the current global interest rate, which becomes the fixed rate for that deposit.
+- **Incentivizing Early Adopters:** Early users lock in higher interest rates, as subsequent deposits use the (potentially lower) global rate at the time of deposit.
+- **Multiple Deposits:** Additional deposits by the same user accrue interest based on the prevailing global rate at the time of each deposit. The handling of multiple deposits and associated rates will be detailed in the contract implementation.
 
-# Our interest rate mechanism is designed to incentivize early participation in the protocol.
+## Yield Source
 
-Global Interest Rate: The protocol will feature a global interest rate. This rate, potentially managed by an owner or a governance mechanism, determines the base rate at which interest accrues for the entire protocol at any given moment.
+While the Vault’s underlying assets could be deployed in DeFi strategies (e.g., staking, lending, liquidity provision) to generate yield, in this initial version, the "interest" is primarily a function of the rebase mechanism itself, designed to incentivize adoption by rewarding holders with additional tokens.
 
-Decreasing Global Rate (Key Feature): A critical design choice is that this global interest rate can only decrease over time. It cannot be increased by the owner once set or lowered.
+---
 
-User-Specific Interest Rate Snapshot: When a user makes their first deposit into the Vault, the Rebase Token contract takes a snapshot of the current global interest rate. This snapshot becomes the user's individual, fixed interest rate for that specific deposit.
+## Known Vulnerabilities
 
-Incentivizing Early Adopters: This design directly rewards early users. Because the global interest rate can only decrease, users who deposit earlier effectively lock in a higher interest rate for their initial capital compared to users who deposit later, when the global rate might have been reduced.
+1. **Interest Rate Lock-In:** When a user makes an initial deposit and later deposits additional amounts, their original (potentially higher) interest rate is applied to all holdings, granting early adopters disproportionate benefits.
+2. **Compounding Interest:** Since interest is derived by multiplying a growth factor with `balanceOf()`, the system compounds interest rather than accumulating it linearly.
 
-Handling Subsequent Deposits: If an existing user makes additional deposits at a later time, those new deposits would likely accrue interest based on the (potentially lower) global interest rate prevailing at the time of the new deposit. The exact mechanics for handling multiple deposits from the same user and their associated rates will be detailed during contract implementation.
+---
 
-Conceptual Source of Yield: While the underlying assets in the Vault could theoretically be deployed in various DeFi strategies (e.g., staking, lending, liquidity provision) to generate yield, for this initial version, the "interest" is primarily a function of the rebase mechanism itself, designed to increase token adoption by directly rewarding token holders with more tokens.
-
-
----------------- Vulnerabilities identified --------------------------------------------
-1.  When user deposit and amount and comes back to deposite another amount, their intial interest rate is applied instead of the recent adjusted interest rate. : this gives early adopters insane amount of benefit
-2. Because interest is derived by multiplying with the growth factor and the balanceOf(), it compounds rather than accumulating linearly
+*This document is a work in progress. Please review and contribute to ongoing discussions regarding protocol design and