Merge pull request #103 from pyth-network/liquidity-oracle-documentation

Liquidity oracle documentation

Author: anihamde

pyth-sdk/README.md

@@ -81,3 +81,33 @@ 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.
+
+## Adjust Prices using 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 = ...;
+// 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,
+    deposits_endpoint,
+    rate_discount_initial,
+    rate_discount_final,
+    discount_exponent).ok_or(StdError::not_found("Issue with querying collateral price"))?;
+println!("The valuation price for the collateral given {} tokens deposited is ({} +- {}) x 10^{} USD",
+         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 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.
+
+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`.