docs: update documentation

README.md

@@ -2,9 +2,50 @@
 
 ## Description
 
+
+This repository contains two token rewards models:
+- XDEFIDistribution (Staking v1 since end of 2021)
+- XDEFIVault (Staking v2 to be deployed Q2 2023)
+
+
+## XDEFIVault (vXDEFI Staking contract)
+
+The main features of the XDEFIVault smart contract are:
+
+* ERC-20 Token Wrapper: The contract wraps an underlying ERC20 token and creates a new token called vXDEFI. This allows users to interact with the underlying token through the vXDEFI token.
+
+* ERC-4626 Compliance: The contract is compliant with the ERC4626 standard (EIP-4626). This standard extends the ERC20 token standard to support snapshots, which allows for efficient querying of historical token balances.
+
+* ERC-20Permit Compliance: The contract supports the ERC20Permit standard (EIP-2612), which allows users to permit another address to spend tokens on their behalf without the need for an initial approval transaction. This feature enables gas savings and a more streamlined user experience.
+
+* EIP-712 Domain: The contract defines an EIP-712 domain for structured data hashing and signing. This is used by the ERC20Permit standard for off-chain approvals and other cryptographic operations. The domain includes the contract name, version, chain ID, contract address, and a unique salt value derived from the contract deployment.
+
+These features make the XDEFIVault smart contract a versatile token wrapper with support for advanced token interactions, such as off-chain approvals and efficient historical balance lookups.
+
+### How vXDEFI Works
+
+The vXDEFI token is designed to represent a share of the underlying XDEFI tokens held in the smart contract. Here's a step-by-step explanation of the process, along with examples:
+
+1. **Minting vXDEFI**: When a user wants to convert XDEFI tokens into vXDEFI tokens, the current ratio between the total supply of vXDEFI and the total XDEFI balance in the smart contract is used to determine the conversion rate. 
+
+   For example, let's assume the contract has 1000 vXDEFI tokens and 2000 XDEFI tokens. If a user deposits 1 XDEFI token, they will receive 0.5 vXDEFI tokens (1 XDEFI * (1000 vXDEFI / 2000 XDEFI) = 0.5 vXDEFI).
+
+2. **Redeeming XDEFI**: When a user wants to withdraw their XDEFI tokens, the same ratio is used to determine how many XDEFI tokens they receive for their vXDEFI tokens.
+
+   In the same example, if a user wants to redeem 0.5 vXDEFI tokens, they would receive 1 XDEFI token (0.5 vXDEFI * (2000 XDEFI / 1000 vXDEFI) = 1 XDEFI).
+
+3. **Accruing Value**: As swap fees are generated on the XDEFI platform, a portion of the fees (in XDEFI tokens) will be sent to the smart contract, increasing the total XDEFI balance. This will cause the value of each vXDEFI token to grow, as the ratio between total vXDEFI and total XDEFI changes in favor of vXDEFI holders.
+
+   For example, if 100 XDEFI tokens are added to the contract as swap fees, the new balance would be 2100 XDEFI tokens and 1000 vXDEFI tokens. The updated conversion rate would now be 2.1 XDEFI per vXDEFI (2100 XDEFI / 1000 vXDEFI = 2.1).
+
+By following this mechanism, the vXDEFI token allows users to participate in the XDEFI ecosystem and benefit from the swap fees generated on the platform. As more fees are collected, the underlying value of each vXDEFI token will increase, incentivizing users to hold and participate in the ecosystem.
+
+
+## XDEFIDistribution [deprecated]
+
 This contract provides a mechanism for users to lock XDEFI, resulting in non-fungible locked positions, since each position is only un-lockable in its entirety after a certain time. Locked positions have a right to withdraw at least the respective amount of XDEFI deposited, as well as a portion of XDEFI that was airdropped to this contract, and thus dispersed to all locked positions. This portion is based on the relative portion of locked XDEFI in comparison to all locked XDEFI, and the bonus multiplier of the locked position, which is assigned at lock-time, based on the lock duration. Further, the locked and unlocked positions exist as NFTs with a number of "credits", in which several can be merged/burned to consolidate them into one NFT.
 
-## Features and Functionality
+### Features and Functionality
 
 -   Users can lock in an amount of XDEFI for a duration and cannot unlock/withdraw during the specified duration.
 -   Lock durations and their respective bonus multiplier are definable by the admin, and can be changed. 0-second durations cannot be enabled. "No bonus" is effectively a bonus multiplier of 1x, which still receives a "normal" share of future distributed rewards. Changes to the lock durations do not retroactively affect existing locked positions.
@@ -39,6 +80,11 @@ This contract is a stateless helper for read-only functionality, intended to hel
     -   an array of respective locked position info for each tokenId
     -   an array of respective withdrawable amounts for each tokenId
 
+
+### XDEFIVault
+
+...
+
 ## Testing and deployment
 
 Setup with `npm install` or `npm ci`.