improve some documentation

Author: anihamde

pyth-sdk/README.md

@@ -82,19 +82,21 @@ println!("0.1 BTC and 0.05 ETH are worth: ({} +- {}) x 10^{} USD",
 
 This operation can be useful for pricing, e.g., an LP token that is backed by two underlying currencies.
 
-## Liquidity-related Pricing Measures
+## Adjust Prices using Liquidity
 
-A variety of measures should be taken for protocols looking to mitigate liquidity-related risks. To limit deposits and borrows, protocols could simply derive their limit from the off-chain liquidity estimates and then store those values in contract state. No explicit interaction with the Pyth SDK would be needed in this simple case.
-
-To adjust the price at which collateral is valued based on the liquidity information, a protocol can combine the current Pyth price and their estimate of liquidity:
+Applications can adjust Pyth prices to incorporate market impact and liquidity for large positions, since the effective transaction price for large positions differs from the midprice and top-of-book price. Suppose the application wants to value the effective execution price on selling 100 BTC, based on the fact that 1000 BTC sell at a 10% discount (90% of the midprice). Based on assuming the market impact is constant with respect to amount sold, the application can combine the current Pyth price and its liquidity views to calculate the adjusted price:
 
 ```rust
 let btc_usd: Price = ...;
-let deposits: u64 = ...;
-let deposits_endpoint: u64 = ...;
-let rate_discount_initial: u64 = ...;
-let rate_discount_final: u64 = ...;
-let discount_exponent: i32 = ...;
+// deposits is the total number of tokens deposited in the protocol
+let deposits: u64 = 100;
+// deposits_endpoint represents the token deposits at which rate_discount_final kicks in
+let deposits_endpoint: u64 = 1000;
+// rate_discount_initial and _final are percentages, expressed in fixed point as x * 10^discount_exponent.
+// E.g. 50 with discount_exponent = -2 is 50%.
+let rate_discount_initial: u64 = 100;
+let rate_discount_final: u64 = 90;
+let discount_exponent: i32 = 2;
 
 let price_collateral: Price = btc_usd.get_collateral_valuation_price(
     deposits,
@@ -106,24 +108,6 @@ println!("The valuation price for the collateral given {} tokens deposited is ({
          deposits, price_collateral.price, price_collateral.conf, price_collateral.expo);
 ```
 
-Here, `deposits` indicates the total amount of collateral deposited. `get_collateral_valuation_price` takes in the total deposits in the protocol and interpolates between (`0`, `rate_discount_inital`) and (`deposits_endpoint`, `rate_discount_final`) to linearly caclulate the discount at `deposits`. As a note, this function scales the price depending on the provided discount and deposit inputs, but it does not alter the confidence.
-
-To adjust the price at which a borrow position is valued, a protocol can similarly combine the current Pyth price and their estimate of liquidity:
+Here, `deposits` indicates the total amount of collateral deposited. `get_collateral_valuation_price` takes in the total deposits in the protocol and linearly interpolates between (`0`, `rate_discount_inital`) and (`deposits_endpoint`, `rate_discount_final`) to calculate the discount at `deposits`. As a note, this function scales the price depending on the provided discount and deposit inputs, but it does not alter the confidence.
 
-```rust
-let btc_usd: Price = ...;
-let borrows: u64 = ...;
-let borrows_endpoint: u64 = ...;
-let rate_premium_initial: u64 = ...;
-let rate_premium_final: u64 = ...;
-let premium_exponent: i32 = ...;
-
-let price_borrow: Price = btc_usd.get_borrow_valuation_price(
-    borrows,
-    borrows_endpoint,
-    rate_premium_initial,
-    rate_premium_final,
-    premium_exponent).ok_or(StdError::not_found("Issue with querying borrow price"))?;
-println!("The valuation price for the borrow given {} tokens borrowed is ({} +- {}) x 10^{} USD",
-         borrows, price_borrow.price, price_borrow.conf, price_borrow.expo);
-```
+To adjust the price at which a borrow position is valued, a protocol can similarly combine the current Pyth price and their estimate of liquidity, but using the `get_borrow_valuation_price` function now in place of `get_collateral_valuation_price`.