update docs (#37)

Co-authored-by: Jayant Krishnamurthy <[email protected]>

Author: jayantk

examples/terra-contract/README.md

@@ -1,85 +1,66 @@
-# Pyth SDK Example contract for Terra
+# Pyth SDK Example Contract for Terra
 
-This is an example contract that demonstrates reading the Pyth price from the Pyth on-chain contract. It is created using
-[cw-template](https://github.com/InterWasm/cw-template) which is a standard template for developing Terra contracts.
+This repository contains an example contract that demonstrates how to read the Pyth price from the Pyth on-chain contract. 
+The example [contract](src/contract.rs) has two functions: 
 
-## Development
+* `instantiate` sets the Pyth contract address and price feed id that the contract uses. 
+  This function is intended to be called once when the contract is deployed.
+  See the [Terra SDK README](../../pyth-sdk-terra/README.md) for the list of possible price feed ids. 
+* `query` queries the Pyth contract to get the current price for the configured price feed id. 
 
-Visit [Developing](./Developing.md) to learn more on how to compile and develop the contract.
+## Testnet Demo
 
-## Deploy and Query
-The javascript package in `tools` directory contains scripts for querying and deploying the example contract.
-
-If this is the first time running the code, run the below command to install required packages in the `tools` directory: 
-
-```
-npm install
-```
-
-### Testnet Demo
-In order to query the contract you can call:
+This example contract is running on Terra testnet at `terra1fm4ssxq39m355pdv2wzxggf5uxs2ase4vga9qs`.
+This contract has been instantiated to return the price of `Crypto.LUNA/USD`.
+You can query the contract from this repo by running:
 
 ```sh
+cd tools/
+# Install dependencies (if you haven't done so already)
+npm install
+# Query the contract
 npm run query -- --network testnet --contract terra1fm4ssxq39m355pdv2wzxggf5uxs2ase4vga9qs
 ```
 
-If successful the output should look like:
+If the query is successful, the output should look like:
 ```
 {
   current_price: { price: 8704350000, conf: 3150000, expo: -8 },
   ema_price: { price: 8665158600, conf: 2965370, expo: -8 }
 }
 ```
 
-If the price is not available you will get:
+If the price feed is currently not available you will see:
 ```
 rpc error: code = Unknown desc = Generic error: Current price is not available: contract query failed
 ```
 
-`terra1fm4ssxq39m355pdv2wzxggf5uxs2ase4vga9qs` is a live deployment of the example contract in testnet network. This contract
-is configured to return price of `Crypto.LUNA/USD` if it is available. If you have deployed your contract you can replace the 
-address with your contract address.
-### Deployment
+## Developing
 
-Deploying a contract in terra consists of two steps:
-1. Uploading the code. This step will give you a code id.
-2. Optionally create a new contract or migrate an existing one:
-    1. Creating a new contract which has an address with a code id as its program.
-    2. Migrating an existing contract code id to the new code id.
+If you would like to deploy a changed version of this contract, the process consists of two steps:
 
-This script can do both steps at the same time. Read below for the details.
+1. Build the WASM for the contract.
+2. Upload the code and instantiate a new contract. 
 
-#### Uploading the code
+### Build WASM
 
-First build the contracts as mentioned in [Developing](../Developing.md).
+See the [Developing instructions](Developing.md) for how to build the WASM for the contract.
+The instructions in that document will build a file called `example_terra_contract.wasm` under the `artifacts/` directory.
 
-This command will builds and saves all the contracts in the `artifact` directory.
+### Upload and Instantiate Contract
 
-Then, for example, to deploy `example_terra_contract.wasm`, run in the `tools` directory:
-
-``` sh
-npm run deploy -- --network testnet --artifact ../artifacts/example_terra_contract.wasm --mnemonic "..."
-```
-
-which will print something along the lines of:
-
-``` sh
-Storing WASM: ../artifacts/example_terra_contract.wasm (367689 bytes)
-Deploy fee:  88446uluna
-Code ID:  2435
-```
-
-If you do not pass any additional arguments to the script it will only upload the code and returns the code id. If you want to create a 
-new contract or upgrade an existing contract you should pass more arguments that are described below.
-
-#### Instantiating a new contract
-If you want instantiate a new contract after your deployment pass `--instantiate` argument to the above command.
-It will upload the code and with the resulting code id instantiates a new example contract:
+The tools directory contains a deployment script that will upload a WASM file and instantiate a new contract with it.
+You can run that script on the built WASM file as follows: 
 
 ``` sh
+cd tools/
+npm install
 npm run deploy -- --network testnet --artifact ../artifacts/example_terra_contract.wasm --mnemonic "..." --instantiate
 ```
 
+This command will deploy the contract to `testnet` and sets its owner to the wallet with the provided `mnemonic`.
+Note that you have to populate the `--mnemonic` flag with the seedphrase for a valid Terra wallet with some LUNA for the specified network.
+
 If successful, the output should look like:
 ```
 Storing WASM: ../artifacts/example_terra_contract.wasm (183749 bytes)
@@ -91,17 +72,26 @@ Instantiated Pyth Example at terra123456789yelw23uh22nadqlyjvtl7s5527er97 (0x000
 Deployed pyth example contract at terra123456789yelw23uh22nadqlyjvtl7s5527er97
 ```
 
-This scripts currently set the example contract price to `Crypto.LUNA/USD` but you can change it within `deploy.js`.
+By default, the deployment script sets the price feed to `Crypto.LUNA/USD` but you can change it in [deploy.js](tools/deploy.js).
+
+### Querying the Contract
+
+Once the contract is instantiated, you can query it by running: 
+
+```sh
+npm run query -- --network testnet --contract <contract address>
+```
 
-#### Migrating an existing contract
-If you want to upgrade an existing contract pass `--migrate --contract terra123456xyzqwe..` arguments to the above command.
-It will upload the code and with the resulting code id migrates the existing contract to the new one:
+### Migrating the Contract
+You can also migrate an existing contract by passing the `--migrate --contract terra123456xyzqwe..` arguments to the deploy command:
 
 ``` sh
 npm run deploy -- --network testnet --artifact ../artifacts/example_terra_contract.wasm --mnemonic "..." --migrate --contract "terra123..."
 ```
 
+This command will replace the code for the given contract with the specified WASM artifact.
 If successful, the output should look like:
+
 ```
 Storing WASM: ../artifacts/example_terra_contract.wasm (183749 bytes)
 Deploy fee:  44682uluna
@@ -111,16 +101,9 @@ Migrating contract terra1rhjej5gkyelw23uh22nadqlyjvtl7s5527er97 to 53227
 Contract terra1rhjej5gkyelw23uh22nadqlyjvtl7s5527er97 code_id successfully updated to 53227
 ```
 
-#### Notes
-
-You might encounter gateway timeout or account sequence mismatch in errors. In is good to double check with terra finder as sometimes
-transactions succeed despite being timed out.
-
-If that happens in the middle of an instantiation or migration. You can avoid re-uploading the code and use the resulting Code Id 
-by passing `--code-id <codeId>` instead of `--artifact` and it will only do the instantiation/migration part.
+### Troubleshooting
 
-An example is:
-
-``` sh
-npm run deploy -- --network testnet --code-id 50123 --mnemonic "..." --migrate --contract "terra123..."
-```
+When deploying the contract, you may encounter gateway timeout or account sequence mismatch errors.
+If this happens, check terra finder to determine if your transaction succeeded -- sometimes transactions succeed despite timing out.
+Note that the deployment script submits multiple transactions.
+If any of them fails, simply rerun the entire script; there is no problem re-running the successful transactions. 

examples/terra-contract/src/contract.rs

@@ -31,6 +31,8 @@ pub fn migrate(_deps: DepsMut, _env: Env, _msg: MigrateMsg) -> StdResult<Respons
     Ok(Response::new().add_attribute("method", "migrate"))
 }
 
+/// The instantiate function is invoked when the contract is first deployed.
+/// This function sets configuration values that are used by the query function.
 #[cfg_attr(not(feature = "library"), entry_point)]
 pub fn instantiate(
     deps: DepsMut,
@@ -62,6 +64,7 @@ pub fn execute(
     Ok(Response::new().add_attribute("method", "execute"))
 }
 
+/// Query the Pyth contract the current price of the configured price feed.
 #[cfg_attr(not(feature = "library"), entry_point)]
 pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
     match msg {
@@ -72,22 +75,31 @@ pub fn query(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary> {
 fn query_fetch_price(deps: Deps) -> StdResult<FetchPriceResponse> {
     let state = STATE.load(deps.storage)?;
 
+    // query_price_feed is the standard way to read the current price from a Pyth price feed.
+    // It takes the address of the Pyth contract (which is fixed for each network) and the id of the price feed.
+    // The result is a PriceFeed object with fields for the current price and other useful information.
+    // The function will fail if the contract address or price feed id are invalid.
     let price_feed = query_price_feed(
         &deps.querier,
         state.pyth_contract_addr.into_string(),
         state.price_feed_id,
     )?
     .price_feed;
 
-    // This examples throws an error if the price is not available. Price could be
-    // unavailable if the number of publishers are low or it has not been updated
-    // for a while due to network errors and etc. It is recommended that you handle
-    // the scenarios which price is not available in a better way.
-    // Make sure to read [consumer best practices](https://docs.pyth.network/consumers/best-practices)
-    // when using pyth data.
+    // Get the current price and confidence interval from the price feed.
+    // This function returns None if the price is not currently available.
+    // This condition can happen for various reasons. For example, some products only trade at specific times, or
+    // network outages may prevent the price feed from updating.
+    //
+    // The example code below throws an error if the price is not available. It is recommended that you handle
+    // this scenario more carefully. Consult the [consumer best practices](https://docs.pyth.network/consumers/best-practices)
+    // for recommendations.
     let current_price = price_feed
         .get_current_price()
         .ok_or(StdError::not_found("Current price is not available"))?;
+
+    // Get an exponentially-weighted moving average price and confidence interval.
+    // The same notes about availability apply to this price.
     let ema_price = price_feed
         .get_ema_price()
         .ok_or(StdError::not_found("EMA price is not available"))?;

examples/terra-contract/tools/deploy.js

@@ -68,15 +68,17 @@ const CONFIG = {
       name: "testnet",
     },
     pythContractAddress: "terra1wzs3rgzgjdde3kg7k3aaz6qx7sc5dcwxqe9fuc",
-    pythLunaPriceFeedId: "6de025a4cf28124f8ea6cb8085f860096dbc36d9c40002e221fc449337e065b2"
+    // Change this field to change which price feed is read by the deployed contract.
+    // The current value is the LUNA/USD price feed.
+    pythPriceFeedId: "6de025a4cf28124f8ea6cb8085f860096dbc36d9c40002e221fc449337e065b2"
   }
 }
 
 const terraHost = CONFIG[argv.network].terraHost;
 const pythContractAddress = CONFIG[argv.network].pythContractAddress;
-const pythLunaPriceFeedId = CONFIG[argv.network].pythLunaPriceFeedId;
+const pythPriceFeedId = CONFIG[argv.network].pythPriceFeedId;
+
 
-  
 const lcd = new LCDClient(terraHost);
 
 const feeDenoms = ["uluna"];
@@ -93,7 +95,7 @@ const wallet = lcd.wallet(
 
 /* Deploy artifacts */
 
-var codeId; 
+var codeId;
 
 if (argv.codeId !== undefined) {
   codeId = argv.codeId;
@@ -168,7 +170,7 @@ if (argv.instantiate) {
       .then((rs) => {
         try {
           address = /"contract_address","value":"([^"]+)/gm.exec(rs.raw_log)[1];
-        } catch (e) { 
+        } catch (e) {
           console.error("Encountered an error in parsing instantiation result. Printing raw log")
           console.error(rs.raw_log);
           throw(e);
@@ -179,7 +181,7 @@ if (argv.instantiate) {
   }
 
   const contractAddress = await instantiate(codeId, {
-    price_feed_id: Array.from(Buffer.from(pythLunaPriceFeedId, "hex")),
+    price_feed_id: Array.from(Buffer.from(pythPriceFeedId, "hex")),
     pyth_contract_addr: pythContractAddress
   });
 
@@ -209,7 +211,7 @@ if (argv.migrate) {
     feeDenoms,
     gasPrices,
   });
-  
+
   const rs = await lcd.tx.broadcast(tx);
   var resultCodeId;
   try {