Added Eth Price Tracking Use Case Tutorial Page

docs/build-with-powerloom/snapshotter-node/full-node/getting-started.md

@@ -6,19 +6,19 @@ sidebar_position: 2
 Snapshotter (Full Node) has a complex architecture with multiple moving parts. The easiest way to get started is by using the Docker-based setup, recommended for most users.
 
 :::info
-#### You can use powerloom to build extensive data applications. Our Devnet is live. Read more about Devnet [here](../../devnet/getting-started.md) 
+#### You can use Powerloom to build extensive data applications. Our Devnet is live. Read more about Devnet [here](../../devnet/getting-started.md) 
 :::
 
 ## System Requirements
 
 1. Latest version of `docker` (`>= 20.10.21`) and `docker-compose` (`>= v2.13.0`)
 
-2. At least 4 core CPU, 8GB RAM and 50GB SSD - make sure to choose the correct spec when deploying to Github Codespaces.
+2. At least 4 core CPU, 8GB RAM, and 50GB SSD - make sure to choose the correct spec when deploying to Github Codespaces.
 
 3. IPFS node
-    - While we have __included__ a node in our autobuild docker setup, IPFS daemon can hog __*a lot*__ of resources - it is not recommended to run this on a personal computer unless you have a strong internet connection and dedicated CPU+RAM.
+    - While we have __included__ a node in our autobuild Docker setup, IPFS daemon can hog __*a lot*__ of resources - it is not recommended to run this on a personal computer unless you have a strong internet connection and dedicated CPU+RAM.
 
-    - 3rd party IPFS services that provide default IFPS interface like Infura are now supported.
+    - 3rd party IPFS services that provide default IPFS interface like Infura are now supported.
 
 4. RPC URL for `Ethereum mainnet` or the chain you're working on. 
 
@@ -65,8 +65,8 @@ Extending existing use cases or building your own use cases requires a slightly
 
 1. **Forking the Computes and Config templates** - For an optimized development process, it's recommended to fork the templates for [snapshotter-computes](https://github.com/PowerLoom/snapshotter-computes) and [snapshotter-configs](https://github.com/PowerLoom/snapshotter-configs/). Our system utilizes the Git submodule architecture to manage these components efficiently. For a deeper understanding of how these elements integrate and function within our larger system, please refer to our [architecture documentation](../architecture.md). This approach ensures a streamlined and cohesive development workflow.
 
-   - Snapshotter Configs: https://github.com/PowerLoom/snapshotter-computes
-   - Snapshotter Computes: https://github.com/PowerLoom/snapshotter-configs 
+   - Snapshotter Configs: https://github.com/PowerLoom/snapshotter-configs
+   - Snapshotter Computes: https://github.com/PowerLoom/snapshotter-computes
 
    Once the above branches are forked, you should have the above two repositories in your profile. 
 
@@ -81,7 +81,7 @@ Extending existing use cases or building your own use cases requires a slightly
 
     - Ensure the following required variables are filled:
 
-    - `SOURCE_RPC_URL`: The URL for Ethereum RPC (Local node/Infura/Alchemy) service.
+    - `SOURCE_RPC_URL`: The URL for the Ethereum RPC (Local node/Infura/Alchemy) service.
     - `SIGNER_ACCOUNT_ADDRESS`: The address of the signer account. This is your whitelisted address on the protocol. **Using a burner account is highly recommended**
     - `SIGNER_ACCOUNT_PRIVATE_KEY`: The private key corresponding to the signer account address.
     - Configure `SNAPSHOT_CONFIG_REPO` and `SNAPSHOT_CONFIG_REPO_BRANCH` to point to your forked snapshotter-configs repository.
@@ -108,28 +108,28 @@ Extending existing use cases or building your own use cases requires a slightly
    ```
 
    :::note
-   This is a one time step and resets the codebase to the latest version of the branch. If you have made any changes to the codebase, make sure to commit them before running this command.You need to run this command only once after cloning the repository.
+   This is a one time step and resets the codebase to the latest version of the branch. If you have made any changes to the codebase, make sure to commit them before running this command. You need to run this command only once after cloning the repository.
    :::
 
 - **Running the Node** - Run  `./build.sh` (ideally in a `screen`) to start the Snapshotter Node
 
 
 ## Troubleshooting Errors
 
-If the `.env` is filled up correctly, all services will execute one by one. The logs do fill up quick. So, remember to [safely detach](https://linuxize.com/post/how-to-use-linux-screen/) from screen when not using it. If you see the following error, 
+If the `.env` is filled up correctly, all services will execute one by one. The logs do fill up quickly. So, remember to [safely detach](https://linuxize.com/post/how-to-use-linux-screen/) from the screen when not using it. If you see the following error, 
 
     powerloom_depoy-pooler-1           | Snapshotter identity check failed on protocol smart contract
     powerloom_depoy-pooler-1 exited with code 1
 
-your snapshotter address is not registered. Make you have registered for our [devnet program](https://airtable.com/appr3wKRsn4VoOvpi/pagxxT6QcL0OwGH0e/form) and your burner wallet has been added. 
+your Snapshotter address is not registered. Make you have registered for our [devnet program](https://airtable.com/appr3wKRsn4VoOvpi/pagxxT6QcL0OwGH0e/form) and your burner wallet has been added. 
 
 Refer to our [troubleshooting guide](./troubleshooting.md) if you encounter any other issues with your node.
 
 ## Stopping the Node
 1. To shutdown services, just press `Ctrl+C` (and again to force).
 
 :::note
-If you don't keep services running for extended periods of time, this will affect consensus and we may be forced to de-activate your snapshotter account.
+If you don't keep services running for extended periods of time, this will affect consensus and we may be forced to deactivate your snapshotter account.
 :::
 
 2. If you see issues with data, you can do a clean *reset* by running the following command before restarting step 1:

docs/build-with-powerloom/use-cases/existing-implementations/eth_price_tracking.md

@@ -0,0 +1,152 @@
+---
+sidebar_position: 3
+---
+# ETH Price Tracker
+
+## Introduction
+This guide provides a detailed walkthrough for setting up a price tracker for the Ethereum token, from hereon referred to as ETH.
+
+:::tip
+Prerequisites: Before we dive into the implementation of ETH price tracker, you must follow all the steps to 
+[setup your Devnet Node](/docs/build-with-powerloom/devnet/getting-started)
+:::
+### Scenario: ETH Price Tracking
+
+We aim to capture real-time changes in ETH's price conversion ratio. Watch the tutorial below for a detailed walkthrough.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/wn4zK8ONLt4?start=40" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+## Steps to Implement this Use Case
+
+### Cloning the Deploy Repository
+Clone repository against the respective branch (main by default). Open the terminal and run the below command to clone the deploy repo in a directory named `powerloom_deploy`.
+
+```bash
+git clone https://github.com/PowerLoom/deploy.git --single-branch powerloom_deploy --branch devnet && cd powerloom_deploy
+```
+
+### Configuring The Node - Copy env.example to .env
+
+#### Required variables
+
+
+- `SOURCE_RPC_URL` : The URL for the Ethereum RPC (Local node/Infura/Alchemy) service. Set the RPC URL to Ethereum mainnet to snapshot the data source contracts on it.
+- `SIGNER_ACCOUNT_ADDRESS` : The address of the signer account. This should be an unused "burner" address that does not need to have any token balance. You can create a new burner wallet from our [tool](https://devnet-mint.powerloom.dev/burner).
+- `SIGNER_ACCOUNT_PRIVATE_KEY` : The private key corresponding to the signer account address.
+- `SLOT_ID` : Enter your Devnet Slot ID. 
+
+:::info 
+Unless it is a customized need or instructed by us, the below need not be changed or modified from the values already supplied in `env.example`
+:::
+
+- `SNAPSHOT_CONFIG_REPO`=[https://github.com/powerloom/snapshotter-configs](https://github.com/PowerLoom/snapshotter-configs/tree/eth_price_monitor)
+- `SNAPSHOT_CONFIG_REPO_BRANCH`=eth_price_monitor
+- `SNAPSHOTTER_COMPUTE_REPO`=[https://github.com/powerloom/snapshotter-computes](https://github.com/powerloom/snapshotter-computes/tree/eth_price_monitor)
+- `SNAPSHOTTER_COMPUTE_REPO_BRANCH`=eth_price_monitor
+- `PROTOCOL_STATE_CONTRACT` : The contract address for the protocol state.
+- `RELAYER_HOST`: The host address for the relayer.
+- `NAMESPACE` : The unique key used to identify your project namespace.
+- `PROST_CHAIN_ID` : The Devnet chain ID.
+- `PROST_RPC_URL` : The URL for the PROST RPC service.
+- `POWERLOOM_REPORTING_URL` : The URL for reporting to Powerloom.
+
+#### Optional
+
+- `IPFS URL` : The URL for the IPFS (InterPlanetary File System) service in HTTP/HTTPS (e.g. `https://ipfs.infura.io:5001`) multiaddr format (e.g. `/dns/ipfs.infura.io/tcp/5001/https`)
+- `IPFS_API_KEY`: The API key for the IPFS service (if required).
+- `IPFS_API_SECRET`: The API secret for the IPFS service (if required).
+- `SLACK_REPORTING_URL`: The URL for reporting to Slack.
+- `WEB3_STORAGE_TOKEN`: The token for Web3 Storage. You can generate or retrieve this token from your [API token page](https://web3.storage/) after signing up for a free plan at web3.storage.
+
+### Snapshot Building
+
+:::info
+It is recommended to look at the docs on [snapshot generation](/docs/protocol/specifications/snapshotter/snapshot-build).
+:::
+
+Snapshotter node has a simple interface as part of `GenericProcessorSnapshot` class that business logic specific computes need to implement. The rest of the heavy lifting around reliable submissions and finalization is taken care of by the rest of the features of the node.
+
+In this case, `EthPriceProcessor` located in [`snapshotter/modules/computes`](https://github.com/PowerLoom/snapshotter-computes/blob/eth_price_monitor/eth_price_tracking.py) is the sole compute class for ETH price tracking. This class implements the [`GenericProcessorSnapshot`](https://github.com/Powerloom/pooler/blob/main/snapshotter/utils/callback_helpers.py) interface, most notably the `compute()` callback. This callback is where we build the snapshots.
+
+
+```python reference
+https://github.com/PowerLoom/snapshotter-computes/blob/eth_price_monitor/eth_price_tracking.py#L1-L45
+```
+
+`get_eth_price_usd()` is located in [`snapshotter/modules/computes`](https://github.com/PowerLoom/snapshotter-computes/blob/eth_price_monitor/eth_price_tracking.py) and is a utility function that calculates the price of ETH as a weighted average of its price conversion ratios against DAI, USDC and USDT in the corresponding Uniswap V2 pair contracts. The weights assigned are relative to the total liquidity locked against the W(rapped)ETH token across the three pair contracts.
+
+```python reference
+https://github.com/PowerLoom/pooler/blob/main/snapshotter/utils/snapshot_utils.py#L140-L154
+```
+
+### Set Up the Codebase
+
+Setup the codebase by running the `bootstrap.sh` command in the terminal. Developers may use different shells, such as `bash` or `zsh`. Adjust the command accordingly.
+
+For bash:
+
+```bash
+bash bootstrap.sh
+```
+or
+```zsh
+zsh bootstrap.sh
+```
+
+### Run the Snapshotter Node
+
+
+```bash
+bash build.sh
+```
+or
+```zsh
+zsh build.sh
+```
+
+Once your node is running, the [core API server](/docs/build-with-powerloom/snapshotter-node/core-api/) can be found on [http://localhost:8002](http://localhost:8002). It comes with an easy to use SwaggerUI at [http://localhost:8002/docs](http://localhost:8002/docs) to test out the endpoints to retrieve snapshotted data, or monitor the node status among other things.
+
+![endpoints](/images/endpoints.png)
+
+The snapshotted data as generated by the compute module referred above is retrieved from  `/data/{epoch_id}/{project_id}` endpoint. It requires two parameters
+
+- `epoch_id (int)`: the [epoch ID](/docs/Protocol/Specifications/Epoch) against which it will fetch the snapshotted data.
+- `project_id (str)`: refer to [project id generation](docs/Protocol/Specifications/Snapshotter/snapshot-build) to know more. In this example, it is the concatenation of the the first element in the tuple [returned from the snapshot compute module's implementation of `compute()`](#snapshot-building) along with the project type prefix as found in the [corresponding config for this snapshotter node](#forking-the-computes-and-config-templates). 
+
+```python reference
+https://github.com/PowerLoom/snapshotter-configs/blob/8ed08b19272005f5c45b1af1ff9fd0ab5195bbc6/projects.example.json#L4
+```
+
+:::info
+To learn more about the details of the first element in the tuple being returned from `compute()` being considered as the data source in project ID generation, refer to the docs on [Data Source Specification: Bulk Mode](/docs/Protocol/Specifications/Snapshotter/snapshot-build#data-source-specification-bulk-mode)
+:::
+
+## Verifying snapshotted data
+
+As the node continues snapshotting data, the quickest way to check the snapshotted data is to check against `epoch_id` and `project_id` returned in the logs. Copy these values and paste them in the endpoint to retrieve project data in the [SwaggerUI exposed against the core API](#run-the-snapshotter-node).
+
+![endpoints](/images/docker.png)
+
+For example, in the screenshot above, the `epoch_id` is `100792`. Hit execute. The corresponding snapshotted data to this specific `epoch_id` displays the price of ETH as `3067.935921`. 
+
+As the `epoch_id` moves ahead to `100793`, we find the above endpoint reflects the latest price captured of ethereum as `3068.034792`
+
+![endpoints](/images/eth-price-one-snapshot.png)
+![endpoints](/images/eth-price-two-snapshot.png)
+
+### How to program this
+
+1. Define the correct project ID against which data has to be fetched
+
+```python
+project_type = "eth:price_tracking"  # from https://github.com/PowerLoom/snapshotter-configs/blob/eth_price_monitor/projects.example.json#L4
+project_namespace = "DEVNET"  # from https://github.com/PowerLoom/deploy/blob/95ceb83a97a16279816c406eef484245df483fb1/env.example#L25
+data_source = "example"  # from https://github.com/PowerLoom/snapshotter-computes/blob/15059013c6c17327d1c0d413d3885c23a6383305/eth_price_tracking.py#L45
+project_id = f'{project_type}:{data_source}:{project_namespace}'
+```
+2. Fetch the last finalized epoch from the API endpoint `http://localhost:8002/last_finalized_epoch/{project_id}`
+3. Fetch the data against this epoch ID from the API endpoint `http://localhost:8002/data/{epoch_id}/{project_id}`
+
+## Reach out to us
+
+For any sort of support or clarification, reach out to us on our [discord developer channel](https://discord.com/channels/777248105636560948/1180479966434054165).