docs: main readme

Author: PavelNaydanov

README.md

@@ -1,83 +1,77 @@
-// TODO: Уточнить, что не подходит для реализации вестинга ребейз токенов
+# True Vesting
 
-## Foundry
+**True Vesting** is a pet project for creating decentralized vesting of an ERC-20 token. The decentralization lies in the fact that, after the token is created, its entire supply is transferred to a dedicated contract responsible for distribution. The token cannot be withdrawn by the owner or any other party. The token can only be sent to specific contracts that handle its distribution according to predefined rules.
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+Currently, only one type of distribution has been implemented—vesting. Other types can be successfully added later.
 
-Foundry consists of:
+The project does not implement full-fledged tokenomics and serves only as an example for two allocation groups: team and liquidity. Any coincidences are purely accidental.
 
--   **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
--   **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
--   **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
--   **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+_Important!_ The project i**s not designed to support vesting for rebase tokens** or tokens with dynamically changing quantities.
 
-## Documentation
+## Smart Contract Overview
 
-https://book.getfoundry.sh/
+The following smart contracts have been implemented:
+- [MetaToken.sol](./src/MetaToken.sol). The ERC-20 token contract, which we will distribute through the contract `MetaTokenDistributor.sol`.
+- [MetaTokenDistributor.sol](./src/tokenDistribution/MetaTokenDistributor.sol). A contract that will initiate various types of vesting. It can be upgraded to handle token locking, adding liquidity, sending tokens to mentors, and so on.
+- [VestingParams.sol](./src/tokenDistribution/vesting/VestingParams.sol). A contract that stores parameters for all types of vesting (in our case, two types: team and liquidity). It includes the description of allocations, a list of beneficiary addresses, and the token unlock schedule.
+- [Vesting.sol](./src/tokenDistribution/vesting/Vesting.sol). Implementation of the vesting contract. A new instance is created for each type of vesting. It organizes the token unlock process according to the established schedule.
 
-## Usage
+## Architecture
 
-### Build
+![](./images/architecture.png)
 
-```shell
-$ forge build
-```
+The smart contract architecture outlines the process of creating new vesting instances.To create a new vesting, the following deployment and smart contract call process must be executed:
 
-### Test
+1. Deploy the `VestingParams.sol` smart contract, which defines all vesting rules for all vesting types.
+2. Deploy the `MetaTokenDistributor.sol` smart contract. The distribution contract accepts and stores the address of `VestingParams.sol`.
+3. Under the hood, a `MetaToken.sol` contract for distribution will be deployed.
+4. At the time of `MetaToken.sol` deployment, its entire supply will be sent to the `MetaTokenDistributor.sol` contract.
+5. To initiate vesting, the `startVesting()` function must be called on the `MetaTokenDistributor.sol` contract.
+6. The `MetaTokenDistributor.sol` contract will request vesting parameters from the `VestingParams.sol` contract.
+7. Deploy a `Vesting.sol` contract using the minimal clone pattern.
 
-```shell
-$ forge test
-```
+_Important!_ Each type of vesting can only be initiated once and by anyone after the vesting start time has been reached.
 
-### Format
+### Maximum number of beneficiaries
 
-```shell
-$ forge fmt
-```
+The list of beneficiaries is determined at the moment of deploying the smart contract [VestingParams.sol](./src/tokenDistribution/vesting/VestingParams.sol) in the constructor. Therefore, it is important to understand the maximum number of beneficiaries that can be set in this way without exceeding the block gas limit.
 
-### Gas Snapshots
+As of 2025, the block gas limit in the Ethereum network is 36 million. In the Arbitrum network, it is significantly higher, but according to the documentation, the practical working limit is 32 million.
 
-```shell
-$ forge snapshot
-```
+To determine the actual gas consumption, you can refer to the load test [MaxBeneficiaries.t.sol](./test/tokenDistribution/vesting/loadTests/MaxBeneficiaries.t.sol). Run the test with gas profiling using `forge test -vvv --mt test_deploy_moreBeneficiaries --gas-report`.
 
-### Anvil
+The resulting table shows that for 401 beneficiaries, `19_448_973` gas will be consumed, which is optimal and will occupy approximately half of the block gas limit in Ethereum.
 
-```shell
-$ anvil
-```
+![](./images/maxBeneficiariesLimit.png)
 
-### Deploy
+Important! For deployment on other networks, it is necessary to check the documentation and review the block and transaction gas limits.
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+## Getting started
 
-### Cast
+The project is written using a [Foundry framework](https://book.getfoundry.sh/).
 
-```shell
-$ cast <subcommand>
-```
+### Usage
 
-### Help
+**Build**
 
 ```shell
-$ forge --help
-$ anvil --help
-$ cast --help
+$ forge build
 ```
 
-### Maximum number of beneficiaries
+**Test**
 
-The list of beneficiaries is determined at the moment of deploying the smart contract [VestingParams.sol](./src/tokenDistribution/vesting/VestingParams.sol) in the constructor. Therefore, it is important to understand the maximum number of beneficiaries that can be set in this way without exceeding the block gas limit.
-
-As of 2025, the block gas limit in the Ethereum network is 36 million. In the Arbitrum network, it is significantly higher, but according to the documentation, the practical working limit is 32 million.
-
-To determine the actual gas consumption, you can refer to the load test [MaxBeneficiaries.t.sol](./test/tokenDistribution/vesting/loadTests/MaxBeneficiaries.t.sol). Run the test with gas profiling using `forge test -vvv --mt test_deploy_moreBeneficiaries --gas-report`.
+```shell
+$ forge test
+```
 
-The resulting table shows that for 401 beneficiaries, `19_448_973` gas will be consumed, which is optimal and will occupy approximately half of the block gas limit in Ethereum.
+**Test coverage**
 
-![](./images/maxBeneficiariesLimit.png)
+```shell
+$ forge coverage
+```
 
-Important! For deployment on other networks, it is necessary to check the documentation and review the block and transaction gas limits.
+**Format**
 
+```shell
+$ forge fmt
+```