Merge pull request #110 from balancer/token-scaling

Token Scaling page

docs/concepts/vault/token-scaling.md

@@ -9,7 +9,7 @@ Working with fixed-point math in Solidity presents a unique set of challenges th
 
 In an effort to abstract this complexity, the Vault manages decimal and rate scaling internally, scaling all token balances and input values prior to being sent to the [Pool](/concepts/explore-available-balancer-pools/).
 By doing this, we ensure consistency of rounding direction across all [Custom Pool](/build-a-custom-amm/build-an-amm/create-custom-amm-with-novel-invariant.html) implementations, removing a significant
-amount of complexity from the pool and allowing it to focus primarily on it's invariant implementation.
+amount of complexity from the pool and allowing it to focus primarily on its invariant implementation.
 
 ## Decimal scaling
 
@@ -57,18 +57,18 @@ to better understand how the vault manages token scaling.
 
 With the successful rollout of [The Merge](https://ethereum.org/roadmap/merge) and the adoption of [ERC-4626](https://docs.openzeppelin.com/contracts/4.x/erc4626), the ecosystem has seen a proliferation of yield bearing tokens. Recognizing the pivotal role that LSTs will play in the liquidity landscape moving forward, Balancer seeks to position itself as the definitive yield-bearing hub in DeFi.
 
-To facilitate the adoption of yield bearing liquidity, Balancer abstracts the complexity of managing LSTs by centralizing all rate scaling in the vault, providing all pools with uniform rate scaled balances and input values by default, drastically reducing LVR and ensuring that YB yield is not captured by arbitrage traders.
+To facilitate the adoption of yield bearing liquidity, Balancer abstracts the complexity of managing LSTs by centralizing all rate scaling in the vault, providing all pools with uniform rate scaled balances and input values by default, drastically reducing LVR and ensuring that yield is not captured by arbitrage traders.
 
 ### What is a token rate
 The classical example of a token with a rate is Lido's [wstETH](https://help.lido.fi/en/articles/5231836-what-is-lido-s-wsteth). As [stETH](https://help.lido.fi/en/articles/5230610-what-is-steth) accrues value from staking rewards, the exchange rate of wstETH -> stETH grows over time.
 
 ### How does the Balancer Vault utilize token rates
 
-Besides [decimal scaling](#decimal-scaling) a tokens rate is taken into account in Balancer under in the following scenarios:
-- price computation as part of Stable & boosted pools
-- Yield fee computation when tokens with a rate are part of pools
+Besides [decimal scaling](#decimal-scaling) a token's rate is taken into account in Balancer in the following scenarios:
+- Price computation as part of Stable and Boosted pools
+- Yield fee computation on tokens with rates
 
-A token's rate is defined as a 18 decimal fixed point number. It represents a factor of value difference relative to it's underlying. For example a rate of 11e17 of rETH means that 1reth has the value of 1.1 eth.
+A token's rate is defined as an 18-decimal fixed point number. It represents the ratio of the token's value relative to that of its underlying. For example, a rate of 1.1e18 of rETH means that 1 rETH has the value of 1.1 ETH.
 
 
 ### Creating a pool with tokens that have rates
@@ -77,12 +77,12 @@ On pool [register](https://github.com/balancer/balancer-v3-monorepo/blob/main/pk
 To define a token with a rate, specify the token type as  `TokenType.WITH_RATE`. Additionally, you must provide a `rateProvider` address that implements the [`IRateProvider`](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/interfaces/contracts/vault/IRateProvider.sol) interface. Refer to [Token types](/concepts/vault/token-types.html) for a detailed explanation on each token type.
 
 ### Rate scaling usage
-Rate scaling technically is used on every `swap`, `addLiqudity` & `removeLiquidity` operations. If the token has been registered as a `TokenType.WITH_RATE` an external call to the Rate Provider is made via `getRate` if the `TokenType.STANDARD` is selected the rate is set as `1e18`. These rates are used to upscale the `amountGiven` as part of the Vault's primitives.
+Rate scaling is used on every `swap`, `addLiqudity` and `removeLiquidity` operation. If the token was registered as `TokenType.WITH_RATE`, an external call to the Rate Provider is made via `getRate`. If the `TokenType.STANDARD` was selected, the rate is always `1e18`. These rates are used to upscale the `amountGiven` in the Vault primitives.
 :::info
-1. Calling a swap has amount as [`amountGivenRaw`](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/interfaces/contracts/vault/VaultTypes.sol#L183)
+1. With a swap, the known token amount is given in native decimals as [`amountGivenRaw`](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/interfaces/contracts/vault/VaultTypes.sol#L183)
 2. [`AmountGivenRaw` is upscaled](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/Vault.sol#L303-L320)
 3. [`AmountGivenScaled18`](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/Vault.sol#L358) is forwarded to the pool.
-4. Rates are [undone](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/Vault.sol#L378) before returning either `amountIn` or `amountOut`.
+4. Rates are [undone](https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/vault/contracts/Vault.sol#L378) before calculating and returning either `amountIn` or `amountOut`.
 :::
 You can read more on the [Rate Providers page](/concepts/core-concepts/rate-providers.html).
 
@@ -92,6 +92,6 @@ The term `liveBalances` is used internally to refer to balances that have been:
 
 1. [Decimal scaled](/concepts/vault/token-scaling.html#decimal-scaling) - Upscaled to 18 decimals
 2. [Rate scaled](/concepts/vault/token-scaling.html#rate-scaling) - Adjusted for token rates
-3. [Yield fee](/concepts/vault/yield-fee.html) - Had yield fees deducted.
+3. [Yield fee adjusted](/concepts/vault/yield-fee.html) - Had yield fees deducted.
 
-Any token balances sent to the pool will always be in live balance form. This ensures consistency across all tokens and removes the burden of token scaling from the pools logic.
+Any token balances sent to the pool will always be in live balance form. This ensures consistency across all tokens and removes the burden of token scaling from the pool logic.