Tweaks and simplifications

Author: timothymcmackin

docs/tutorials/oracles/application.md

@@ -5,7 +5,7 @@ title: "Part 4: Automating pricing decisions"
 Now that your contract can use pricing data, you can act on that data to make trading decisions.
 In this section, you set up a simple off-chain application to monitor prices and use the contract to buy and sell its simulated token.
 
-You can access the smart contract in many ways, but a simple way is to use Node.JS application because Pyth provides a Node SDK that simplifies getting pricing data from Hermes.
+You can access the smart contract in many ways, but a simple way is to use a Node.JS application because Pyth provides a Node SDK that simplifies getting pricing data from Hermes.
 The application that you create in this section also uses the [Viem](https://viem.sh/) EVM toolkit to interact with Etherlink.
 
 1. In the same directory as your `contracts` folder, create a directory named `app` to store your off-chain application.
@@ -41,7 +41,7 @@ This setting allows programs to import JSON files easily.
    ```
 
    These dependencies include the Pyth and Viem toolkits and the compiled ABI of your contract.
-   You may need to change the path to your contract if you put it in a different place relative to this file.
+   You may need to change the path to your compiled contract if you put the contract in a different place relative to this file.
 
 1. Add these constants to access the environment variables you set, or edit this code to hard-code the values:
 
@@ -116,7 +116,7 @@ Viem (in `view/chains`) has built-in objects that represent Etherlink Mainnet an
    const delaySeconds = (seconds: number) => new Promise(res => setTimeout(res, seconds*1000));
    ```
 
-1. Add this function to get current price data from Hermes, just like the `curl` command you used in previous sections:
+1. Add this function to get current price update data from Hermes, just like the `curl` command you used in previous sections:
 
    ```javascript
    // Utility function to call Hermes and return the current price of one XTZ in USD
@@ -147,7 +147,7 @@ Viem (in `view/chains`) has built-in objects that represent Etherlink Mainnet an
    }
    ```
 
-1. Add a`run` function to contain the main logic of the application:
+1. Add a `run` function to contain the main logic of the application:
 
    ```javascript
    const run = async () => {
@@ -165,11 +165,9 @@ Viem (in `view/chains`) has built-in objects that represent Etherlink Mainnet an
    // Check balance first
    let balance = await getBalance();
    console.log("Starting balance:", balance);
-   let cash = await getCash();
-   console.log("Starting cash in contract:", cash, "XTZ");
    // If not enough tokens, initialize balance with 5 tokens in the contract
    if (balance < 5) {
-     console.log("Initializing account with 5 tez");
+     console.log("Initializing account with 5 tokens");
      const initHash = await contract.write.initAccount([myAccount.address]);
      await publicClient.waitForTransactionReceipt({ hash: initHash });
      balance = await getBalance()
@@ -191,31 +189,34 @@ Viem (in `view/chains`) has built-in objects that represent Etherlink Mainnet an
      console.log("\n");
      console.log("Iteration", i++);
      let baselinePrice = await getPrice(connection);
-     console.log("Baseline price:", baselinePrice);
+     console.log("Baseline price:", baselinePrice, "USD to 1 XTZ");
+     const oneUSDBaseline = Math.ceil((1/baselinePrice) * 10000) / 10000; // Round up to four decimals
+     console.log("Or", oneUSDBaseline, "XTZ to 1 USD");
 
      const updatedPrice = await alertOnPriceFluctuations(baselinePrice, connection);
-     console.log("Price changed:", updatedPrice);
+     console.log("Price changed:", updatedPrice, "USD to 1 XTZ");
      const priceFeedUpdateData = await connection.getLatestPriceUpdates([XTZ_USD_ID]);
-     if (baselinePrice > updatedPrice) {
+     const oneUSD = Math.ceil((1/updatedPrice) * 10000) / 10000; // Round up to four decimals
+
+     if (baselinePrice < updatedPrice) {
        // Buy
-       console.log("Price went down; time to buy");
-       const oneUSD = Math.ceil((1/updatedPrice) * 100) / 100; // Round up to two decimals
+       console.log("Price of USD relative to XTZ went down; time to buy");
        console.log("Sending", oneUSD, "XTZ (about one USD)");
        const buyHash = await contract.write.buy(
          [[`0x${priceFeedUpdateData.binary.data[0]}`]] as any,
          { value: parseEther(oneUSD.toString()), gas: 30000000n },
        );
        await publicClient.waitForTransactionReceipt({ hash: buyHash });
-       console.log("Bought one token");
-     } else if (baselinePrice < updatedPrice) {
-       console.log("Price went up; time to sell");
+       console.log("Bought one token for", oneUSD, "XTZ");
+     } else if (baselinePrice > updatedPrice) {
+       console.log("Price of USD relative to XTZ went up; time to sell");
        // Sell
        const sellHash = await contract.write.sell(
          [[`0x${priceFeedUpdateData.binary.data[0]}`]] as any,
          { gas: 30000000n }
        );
        await publicClient.waitForTransactionReceipt({ hash: sellHash });
-       console.log("Sold one token");
+       console.log("Sold one token for", oneUSD, "XTZ");
      }
      balance = await getBalance();
    }
@@ -225,16 +226,7 @@ Viem (in `view/chains`) has built-in objects that represent Etherlink Mainnet an
    If the price of USD relative to XTZ went down, it's cheaper to buy the simulated token, so the code buys one.
    If the price of USD went up, it sells a token.
 
-1. After the loop, add this code to cash out so you don't leave your sandbox XTZ locked in the contract:
-
-   ```javascript
-   // Cash out
-   console.log("Cashing out");
-   // Call the cashout function to retrieve the XTZ you've sent to the contract (for tutorial purposes)
-   await contract.write.cashout();
-   ```
-
-The complete application looks like this:
+The complete program looks like this:
 
 ```javascript
 import { HermesClient, PriceUpdate } from "@pythnetwork/hermes-client";
@@ -322,7 +314,7 @@ const run = async () => {
   console.log("Starting balance:", balance);
   // If not enough tokens, initialize balance with 5 tokens in the contract
   if (balance < 5) {
-    console.log("Initializing account with 5 tez");
+    console.log("Initializing account with 5 tokens");
     const initHash = await contract.write.initAccount([myAccount.address]);
     await publicClient.waitForTransactionReceipt({ hash: initHash });
     balance = await getBalance()
@@ -336,78 +328,93 @@ const run = async () => {
     console.log("\n");
     console.log("Iteration", i++);
     let baselinePrice = await getPrice(connection);
-    console.log("Baseline price:", baselinePrice);
+    console.log("Baseline price:", baselinePrice, "USD to 1 XTZ");
+    const oneUSDBaseline = Math.ceil((1/baselinePrice) * 10000) / 10000; // Round up to four decimals
+    console.log("Or", oneUSDBaseline, "XTZ to 1 USD");
 
     const updatedPrice = await alertOnPriceFluctuations(baselinePrice, connection);
-    console.log("Price changed:", updatedPrice);
+    console.log("Price changed:", updatedPrice, "USD to 1 XTZ");
     const priceFeedUpdateData = await connection.getLatestPriceUpdates([XTZ_USD_ID]);
-    if (baselinePrice > updatedPrice) {
+    const oneUSD = Math.ceil((1/updatedPrice) * 10000) / 10000; // Round up to four decimals
+
+    if (baselinePrice < updatedPrice) {
       // Buy
-      console.log("Price went down; time to buy");
-      const oneUSD = Math.ceil((1/updatedPrice) * 100) / 100; // Round up to two decimals
+      console.log("Price of USD relative to XTZ went down; time to buy");
       console.log("Sending", oneUSD, "XTZ (about one USD)");
       const buyHash = await contract.write.buy(
         [[`0x${priceFeedUpdateData.binary.data[0]}`]] as any,
         { value: parseEther(oneUSD.toString()), gas: 30000000n },
       );
       await publicClient.waitForTransactionReceipt({ hash: buyHash });
-      console.log("Bought one token");
-    } else if (baselinePrice < updatedPrice) {
-      console.log("Price went up; time to sell");
+      console.log("Bought one token for", oneUSD, "XTZ");
+    } else if (baselinePrice > updatedPrice) {
+      console.log("Price of USD relative to XTZ went up; time to sell");
       // Sell
       const sellHash = await contract.write.sell(
         [[`0x${priceFeedUpdateData.binary.data[0]}`]] as any,
         { gas: 30000000n }
       );
       await publicClient.waitForTransactionReceipt({ hash: sellHash });
-      console.log("Sold one token");
+      console.log("Sold one token for", oneUSD, "XTZ");
     }
     balance = await getBalance();
   }
-
-  // Cash out
-  console.log("Cashing out");
-  // Call the cashout function to retrieve the XTZ you've sent to the contract (for tutorial purposes)
-  await contract.write.cashout();
 }
 
 run();
+
 ```
 
 To run the off-chain application, run the command `npx ts-node src/checkRate.ts`.
 The application calls the `buy` and `sell` function based on real-time data from Hermes.
 Here is the output from a sample run:
 
 ```
-Baseline price: 0.53016063
-Price changed: 0.53005698
-Price went down; time to buy
-Sending 1.89 XTZ (about one USD)
-Bought one more token
+Starting balance: 0
+Initializing account with 5 tez
+Initialized account. New balance is 5
+
+
+Iteration 0
+Baseline price: 0.5179437100000001 USD to 1 XTZ
+Or 1.9308 XTZ to 1 USD
+Price changed: 0.5177393 USD to 1 XTZ
+Price of USD relative to XTZ went up; time to sell
+Sold one token for 1.9315 XTZ
+
+
+Iteration 1
+Baseline price: 0.51764893 USD to 1 XTZ
+Or 1.9319 XTZ to 1 USD
+Price changed: 0.51743925 USD to 1 XTZ
+Price of USD relative to XTZ went up; time to sell
+Sold one token for 1.9326 XTZ
 
 
 Iteration 2
-Baseline price: 0.52988309
-Price changed: 0.53
-Price went up; time to sell
-Sold one token
+Baseline price: 0.51749921 USD to 1 XTZ
+Or 1.9324 XTZ to 1 USD
+Price changed: 0.51762153 USD to 1 XTZ
+Price of USD relative to XTZ went down; time to buy
+Sending 1.932 XTZ (about one USD)
+Bought one token for 1.932 XTZ
 
 
 Iteration 3
-Baseline price: 0.53
-Price changed: 0.53010189
-Price went up; time to sell
-Sold one token
+Baseline price: 0.51766628 USD to 1 XTZ
+Or 1.9318 XTZ to 1 USD
+Price changed: 0.51781075 USD to 1 XTZ
+Price of USD relative to XTZ went down; time to buy
+Sending 1.9313 XTZ (about one USD)
+Bought one token for 1.9313 XTZ
 
 
 Iteration 4
-Baseline price: 0.53015637
-Price changed: 0.52978122
-Price went down; time to buy
-Sending 1.89 XTZ (about one USD)
-Bought one token
-
-Cashing out
+Baseline price: 0.51786312 USD to 1 XTZ
+Or 1.9311 XTZ to 1 USD
+Price changed: 0.51770622 USD to 1 XTZ
+Price of USD relative to XTZ went up; time to sell
+Sold one token for 1.9316 XTZ
 ```
 
 Now you can use the pricing data in the contract from off-chain applications.

docs/tutorials/oracles/environment.md

@@ -81,13 +81,13 @@ Before you begin, make sure that you have these programs installed:
      --fund $ADDRESS
    ```
 
-   This command starts the node in sandbox mode and sends 10,000 to your address.
+   This command starts the node in sandbox mode and sends 10,000 XTZ to your address.
    This sandbox state starts with the current state of Etherlink Testnet but is a separate environment, so you can't use it to deploy contracts or make transactions on Testnet.
 
 1. Wait for the node to download teh snapshot of Etherlink Testnet and synchronize with the current state.
 This can take a few minutes depending on your connection and how old the most recent snapshot is.
 
-   The sandbox environment is ready when the EVM node's log logs the level of the new head block, as in this example:
+   The sandbox environment is ready when the EVM node's log shows the level of the new head block, as in this example:
 
    ```
    Jun 16 14:26:32.041 NOTICE │ head is now 19809131, applied in 10.681ms
@@ -115,3 +115,5 @@ This can take a few minutes depending on your connection and how old the most re
    As with Ethereum, Etherlink records its native token (XTZ) in units of 10^18, also referred to as wei.
 
 Now you can use Foundry to work with Etherlink in a local sandbox environment.
+In the next section, you will create a contract and deploy it to this sandbox.
+Continue to [Part 2: Getting information from the Pyth oracle](/tutorials/oracles/get_data).

docs/tutorials/oracles/get_data.md

@@ -4,17 +4,18 @@ title: "Part 2: Getting information from the Pyth oracle"
 
 Getting price information from the Pyth oracle takes a few steps:
 
-1. The off-chain caller gets current price data from Hermes, Pyth's service that listens for price updates and provides them to off-chain applications via a REST API.
+1. The off-chain caller gets price update data from Hermes, Pyth's service that listens for price updates and provides them to off-chain applications via a REST API.
+This data contains the information that Pyth needs to provide a current price to on-chain applications.
 
-1. The off-chain caller uses that price data to calculate the fee that Pyth charges to provide that price data to smart contracts.
+1. The off-chain caller sends that update data to the smart contract.
 
-1. The off-chain caller sends that price data and the fee to the smart contract.
+1. Based on the update data, smart contract calculates the fee that Pyth charges to provide that price data to smart contracts.
 
 1. The smart contract calls Pyth's on-chain application and pays the fee.
 
 1. The Pyth on-chain application gets the price data from Hermes and provides it to the smart contract.
 
-1. The smart contract stores the price data.
+1. The smart contract stores the updated price data.
 
 ## Getting oracle data in a contract
 
@@ -23,13 +24,13 @@ Follow these steps to create a contract that uses the Pyth oracle in the way des
 1. Create a directory to store your work in:
 
    ```bash
-   mkdir -p etherlink_pyth/contracts
-   cd etherlink_pyth/contracts
+   mkdir -p etherlink_defi/contracts
+   cd etherlink_defi/contracts
    ```
 
-   Later you will create a folder named `etherlink_pyth/app` to store the off-chain portion of the tutorial application.
+   Later you will create a folder named `etherlink_defi/app` to store the off-chain portion of the tutorial application.
 
-1. Create an empty Foundry project in the `etherlink_pyth/contracts` folder:
+1. Create an empty Foundry project in the `etherlink_defi/contracts` folder:
 
    ```bash
    forge init
@@ -95,7 +96,7 @@ Follow these steps to create a contract that uses the Pyth oracle in the way des
    }
    ```
 
-   This function receives price data that an off-chain caller got from Hermes.
+   This function receives price update data that an off-chain caller got from Hermes.
    It uses this data and the Pyth on-chain application to get the cost of the on-chain price update.
    Finally, it passes the fee and the price data to Pyth.
 
@@ -186,7 +187,7 @@ contract TutorialContract {
 ## Testing the data
 
 To test the contract and how it gets data from Pyth, you can write Foundry tests that use a mocked version of Pyth.
-You set the exchange rate in the mocked version of Pyth and use tests to verify that the contract gets that exchange rate correctly.
+In these steps, you set the exchange rate in the mocked version of Pyth and use tests to verify that the contract gets that exchange rate correctly:
 
 1. Create a test file named `test/TutorialContract.t.sol` and open it in any text editor.
 
@@ -220,7 +221,7 @@ You set the exchange rate in the mocked version of Pyth and use tests to verify
    This stub imports your contract and creates an instance of it in the`setUp` function, which runs automatically before each test.
    It creates a mocked version of Pyth for the purposes of the test.
 
-1. Replace the `// Test functions go here` with this utility function:
+1. Replace the `// Test functions go here` comment with this utility function:
 
    ```solidity
    // Utility function to create a mocked Pyth price update for the test
@@ -466,7 +467,7 @@ The addresses of Pyth applications are listed at https://docs.pyth.network/price
 
 1. Set the `DEPLOYMENT_ADDRESS` environment variable to the address of the deployed contract.
 
-1. Call the contract by getting the latest Hermes data, sending it and the update fee to the `updateAndGet` function, and then calling the `getPrice` function, as described in the next steps.
+1. Call the contract by getting update data from Hermes, sending it and the update fee to the `updateAndGet` function, and then calling the `getPrice` function, as described in the next steps.
 
    Because the price data goes stale after 60 seconds, you need to run these commands within 60 seconds.
    You can put them in a single shell script to run at once or you can copy and paste them quickly.
@@ -512,9 +513,11 @@ The addresses of Pyth applications are listed at https://docs.pyth.network/price
       For example, assume that the response is `0x0000000000000000000000000000000000000000000000001950f85eb8a92984`.
       This hex number corresponds to 1824230934793759108 wei, or about 1.82 XTZ.
       This means that 1.82 XTZ equals 1 USD, so one XTZ is equal to 1 / 1.82 USD, or about 0.55 USD.
+      You can paste the hex number that you get in response to a hex to decimal converter such as https://www.rapidtables.com/convert/number/hex-to-decimal.html.
 
 If the commands failed, verify that the `curl` command to get the Hermes data succeeds; it should write a long string of hex code to the file `price_update.txt`.
 Also make sure that the environment variables are correct and that you are copying and pasting the commands into your terminal correctly.
 
 Now you have a smart contract that can get up-to-date price information from Pyth.
-In the next section, you expand the smart contract to buy and sell based on that information.
+In the next section, you expand the smart contract to buy and sell based on that information.
+Continue to [Part 3: Using price data to buy and sell tokens](/tutorials/oracles/tokens).