suggestions

Author: ozgunozerk

content/stellar-contracts/tokens/vault/vault.mdx

@@ -1,21 +1,21 @@
 ---
-title: Fungible Vault Token
+title: Fungible Token Vault
 ---
 
-[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/fungible/extensions/vault)
+[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/fungible/vault)
 
-The Fungible Vault Token implements the ERC-4626 tokenized vault standard,
+The Fungible Token Vault extends the [Fungible Token](/stellar-contracts/tokens/fungible/fungible) and implements the ERC-4626 tokenized vault standard,
 enabling fungible tokens to represent shares in an underlying asset pool. The tokenized vault standard
 is the formalized interface for yield-bearing vaults that hold underlying assets. Vault shares enable
-hyperfungible collaterals in DeFi.
+hyperfungible collaterals in DeFi and remain fully compatible with standard fungible token operations.
 
 This module allows users to deposit underlying assets in exchange for vault shares, and later redeem
 those shares for the underlying assets. The vault maintains a dynamic conversion rate between shares and
 assets based on the total supply of shares and total assets held by the vault contract.
 
 ## Overview
 
-The [Vault](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/fungible/extensions/vault) module provides a complete implementation of tokenized vaults following the ERC-4626 standard. Vaults are useful for:
+The [Vault](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/fungible/vault) module provides a complete implementation of tokenized vaults following the ERC-4626 standard. Vaults are useful for:
 
 - **Yield-bearing tokens**: Represent shares in a yield-generating strategy
 - **Liquidity pools**: Pool assets together with automatic share calculation
@@ -33,7 +33,7 @@ The vault automatically handles:
 ### Shares vs Assets
 
 - **Assets**: The underlying token that the vault manages (e.g., USDC, XLM)
-- **Shares**: The vault tokens that represent proportional ownership of the assets
+- **Shares**: The Token Vaults that represent proportional ownership of the assets
 
 When assets are deposited into a vault, shares are minted to the depositor.
 The number of shares minted depends on the current exchange rate, which is determined by:
@@ -52,7 +52,8 @@ assets = (shares × totalAssets) / totalSupply
 
 The vault uses a "virtual decimals offset" to add extra precision to share calculations.
 This helps prevent rounding errors and improves the accuracy of share-to-asset conversions,
-especially when the vault has few assets or shares.
+especially when the vault has few assets or shares. It's also a key defense mechanism against
+[inflation attacks](#inflation-precision-attacks).
 
 The offset adds virtual shares and assets to the conversion formula:
 
@@ -65,12 +66,16 @@ Values higher than 10 provide minimal practical benefits and may cause overflow
 
 ## Rounding Behavior
 
-The vault implements specific rounding behavior to protect the vault from being drained:
+The vault implements specific rounding behavior to protect against being drained through repeated rounding exploits.
+Without proper rounding, an attacker could exploit precision loss to extract more assets than they deposited by
+performing many small operations where rounding errors accumulate in their favor.
+
+To prevent this:
 
 - **Deposit/Redeem**: Rounds **down** (depositor receives slightly fewer shares/assets)
 - **Mint/Withdraw**: Rounds **up** (depositor provides slightly more assets/shares)
 
-This ensures the vault always retains a slight advantage in conversions, preventing precision attacks.
+This ensures the vault always retains a slight advantage in conversions, making such attacks unprofitable.
 
 | Operation  | Input  | Output | Rounding Direction           |
 | ---------- | ------ | ------ | ---------------------------- |
@@ -105,12 +110,14 @@ If a higher offset is required, a custom version of `set_decimals_offset()` must
 The virtual decimals offset helps protect against inflation attacks where an attacker:
 1. Deposits 1 stroop to get the first share (becoming the sole shareholder)
 2. **Donates** (not deposits) an enormous amount of assets directly to the vault contract via a direct transfer, without receiving any shares in return. This inflates the vault's total assets while keeping total shares at 1, making that single share worth an enormous amount
-3. When a legitimate user tries to deposit a normal amount (e.g., 1000 stroops), the share calculation rounds down to 0 shares because their deposit is negligible compared to the inflated vault balance. The user loses their deposit while receiving nothing
+3. When a legitimate user tries to deposit (e.g., 1000 stroops), the share calculation rounds down to 0 shares because their deposit is negligible compared to the inflated vault balance. The user loses their deposit while receiving nothing
 
 For example: If the attacker donates 1,000,000 stroops after their initial 1 stroop deposit, the vault has 1,000,001 total assets and 1 total share. A user depositing 1000 stroops would receive `(1000 × 1) / 1,000,001 = 0.000999` shares, which rounds down to 0.
 
 The offset adds virtual shares and assets to the conversion formula, making such attacks economically infeasible by ensuring the denominator is never so small that legitimate deposits round to zero.
 
+For more details about the mechanics of this attack, see the [OpenZeppelin ERC-4626 security documentation](https://docs.openzeppelin.com/contracts/5.x/erc4626#security-concern-inflation-attack).
+
 ### Custom Authorization
 
 Custom authorization logic can be implemented as needed:

src/navigation/stellar.json

@@ -62,6 +62,11 @@
 				"type": "page",
 				"name": "RWA",
 				"url": "/stellar-contracts/tokens/rwa/rwa"
+			},
+			{
+				"type": "page",
+				"name": "Vault",
+				"url": "/stellar-contracts/tokens/vault/vault"
 			}
 		]
 	},