Fix #51: Add local README for each stakeholder (PR #63)

Finish #51: Add local README for each stakeholder Changes in this PR - Add predictoor README - Refactor existing READMEs. Now everything works together harmoniuosly - Add placeholders for remote networks
oceanprotocol · Aug 21, 2023 · 4f571c8 · 4f571c8
1 parent 42fdba7
commit 4f571c8
Show file tree

Hide file tree

Showing 12 changed files with 219 additions and 117 deletions.
diff --git a/README.md b/README.md
@@ -5,23 +5,25 @@ SPDX-License-Identifier: Apache-2.0
 
 # pdr-backend: Predictoor Backend
 
-## What's pdr-backend
+## Quickstart (per Stakeholder)
 
-pdr-backend implements all of the agents of the Predictoor ecosystem.
+- If you are a **predictoor**, do [Predictoor README](READMEs/predictoor.md)
+- If you are a **trader**, do [Trader README](READMEs/trader.md)
+- If you are a **frontend dev** working on predictoor.ai: do [Frontend-Dev README](READMEs/frontend-dev.md)
+- If you are a **backend dev** working on `pdr-backend` itself: do [Backend-Dev README](READMEs/backend-dev.md)
+
+## About
+
+The `pdr-backend` repo implements all of the agents of the Predictoor ecosystem.
 
 Each agent has a directory:
 - `predictoor` - agent that submits individual predictions
-- `trader` - agent that buys aggregated predictions & trades
+- `trader` - agent that buys aggregated predictions, then trades
 - `trueval` - agent that reports true values to contract
 - `dfbuyer` - agent that buys aggregate predictions on behalf of Data Farming
 
 Other directories:
 - `utils` - tools for use by any agent
 
-## How to use pdr-backend
-
-- If you are a **predictoor**, see [Predictoor README](pdr_backend/predictoor/README.md)
-- If you are a **trader**, do [Trader README](pdr_backend/trader/README.md)
-- If you are a **frontend dev** working on predictoor.ai: do [Frontend-Dev README](READMEs/frontend-dev.md)
-- If you are a **backend dev** working on `pdr-backend` itself: do [Backend-Dev README](READMEs/backend-dev.md)
+The `predictoor` and `trader` agents are meant to be customized by predictoor and trader stakeholders, respectively.
 
diff --git a/READMEs/backend-dev.md b/READMEs/backend-dev.md
@@ -5,36 +5,34 @@ SPDX-License-Identifier: Apache-2.0
 
 # Usage for Backend Devs
 
-## 1. Introduction
+This is for backend devs working on `pdr-backend` itself.
 
-This is for backend devs working on `pdr-backend` itself
+## Contents
 
-## 2. Install pdr-backend
+- [Install](#install)
+- [Local Usage](#local-usage)
+- [Remote Testnet Usage](#remote-testnet-usage)
+- [Remote Mainnet Usage](#remote-mainnet-usage)
 
-Follow instructions in [install.md](install.md).
+## Install
 
-## 3. Install barge
+First, [install pdr-backend](install.md).
 
-Follow instructions in [barge.md "install"](barge.md#install-barge).
+Then, [install barge](barge.md#install-barge).
 
-## 4. Run barge
+## Local Usage
 
-We'll use barge to run just these components:
-- local chain (ganache)
-- predictoor-related smart contracts deployed to chain
-
-(We'll run predictoor agents directly as we develop against them.)
+### Local Usage: Testing
 
 In barge console:
 ```console
+# Run barge with just predictoor contracts, but no agents
 ./start_ocean.sh --predictoor
 ```
 
-## 5. Set up environment
-
-Start a new console and:
-```
-# Setup env
+Open a new console and:
+```console
+# Setup virtualenv
 cd pdr-backend
 source venv/bin/activate
 
@@ -43,17 +41,7 @@ export ADDRESS_FILE="${HOME}/.ocean/ocean-contracts/artifacts/address.json"
 export RPC_URL=http://127.0.0.1:8545
 export SUBGRAPH_URL="http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph"
 export PRIVATE_KEY="0xef4b441145c1d0f3b4bc6d61d29f5c6e502359481152f869247c7a4244d45209"
-```
-
-## 6. Usage
-
-
-## 6.1 Usage: Testing
 
-In a console, first ensure environment is set up (see previous section).
-
-Then in the console:
-```console
 #run a single test
 pytest pdr_backend/utils/test/test_constants.py::test_constants1
 
@@ -64,7 +52,7 @@ pytest pdr_backend/utils/test/test_constants.py
 pytest
 ```
 
-### 6.2 Usage: Run a custom agent
+### Local Usage: Run a custom agent
 
 Let's say you want to change the trader agent, and use off-the-shelf agents for everything else. Here's how.
 
@@ -80,37 +68,20 @@ Open a new console and:
 ```console
 # Set envvars
 # (copy and paste the envvar-setting code above)
+# (export ADDRESS_FILE=...)
 
 # run trader agent
 python3 pdr_backend/trader/main.py
 ```
 
-### 6.3 Usage: Places to customize
-
-Here are possible places to customize:
-- [`pdr_backend/trueval/trueval.py`](pdr_backend/trueval/trueval.py) - to submit real data, not random
-- [`pdr_backend/predictoor/predict.py`](pdr_backend/predictoor/predict.py) - to submit real predictions, not random
-- [`pdr_backend/trader/trade.py`](pdr_backend/trader/trade.py) - to actually trade
-
-
-### 6.4 Usage: How to observe
-
-Relax & watch as predictoor submits random predictions , trueval submits random true_vals for each epoch and trader signals trades.
-
-You can query [subgraph](http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph/graphql) and see [this populated data PR](https://github.com/oceanprotocol/ocean-subgraph/pull/678) here for entities 
-
-
-### 6.5 Usage: How to filter
+Relax & watch as the predictoor agent submits random predictions, trueval submits random true_vals for each epoch and trader signals trades.
 
-Here are additional envvars used to filter:
+You can query predictoor subgraph for detailed run info. See [subgraph.md](subgraph.md) for details.
 
-- PAIR_FILTER = if we do want to act upon only same pair, like  "BTC/USDT,ETH/USDT"
-- TIMEFRAME_FILTER = if we do want to act upon only same timeframes, like  "5m,15m"
-- SOURCE_FILTER = if we do want to act upon only same sources, like  "binance,kraken"
-- OWNER_ADDRS = if we do want to act upon only same publishers, like  "0x123,0x124"
+### 3.5 Usage: How to filter
 
 
-### 7. Release Process
+### 4. Release Process
 
 Follow instructions in [release-process.md](release-process.md).
 

diff --git a/READMEs/barge.md b/READMEs/barge.md
@@ -3,6 +3,8 @@ Copyright 2023 Ocean Protocol Foundation
 SPDX-License-Identifier: Apache-2.0
 -->
 
+# Barge
+
 ## Contents
 
 Installation

diff --git a/READMEs/filter.md b/READMEs/filter.md
@@ -0,0 +1,19 @@
+<!--
+Copyright 2023 Ocean Protocol Foundation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Using Predictoor Subgraph
+
+### Querying
+
+You can query [subgraph](http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph/graphql) and see [this populated data PR](https://github.com/oceanprotocol/ocean-subgraph/pull/678) here for entities.
+
+### Filtering
+
+Here are additional envvars used to filter:
+
+- PAIR_FILTER = if we do want to act upon only same pair, like  "BTC/USDT,ETH/USDT"
+- TIMEFRAME_FILTER = if we do want to act upon only same timeframes, like  "5m,15m"
+- SOURCE_FILTER = if we do want to act upon only same sources, like  "binance,kraken"
+- OWNER_ADDRS = if we do want to act upon only same publishers, like  "0x123,0x124"
diff --git a/READMEs/frontend-dev.md b/READMEs/frontend-dev.md
@@ -17,6 +17,7 @@ Follow instructions in [barge.md "install"](barge.md#install-barge).
 
 In barge console:
 ```console
+# run barge with all agents
 ./start_ocean.sh --predictoor --with-pdr-trueval --with-pdr-trader --with-pdr-predictoor --with-pdr-publisher --with-pdr-dfbuyer
 ```
 

diff --git a/READMEs/predictoor.md b/READMEs/predictoor.md
@@ -0,0 +1,60 @@
+<!--
+Copyright 2023 Ocean Protocol Foundation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Usage for Predictoors
+
+This is for predictoors - people who are running `predictoor` agents to submit individual predictions.
+
+## Contents
+
+- [Install](#install)
+- [Local Usage](#local-usage)
+- [Remote Testnet Usage](#remote-testnet-usage)
+- [Remote Mainnet Usage](#remote-mainnet-usage)
+
+## Install
+
+First, [install pdr-backend](install.md).
+
+Then, [install barge](barge.md#install-barge).
+
+## Local Usage
+
+In barge console:
+```console
+#run barge with all agents except predictoor
+./start_ocean.sh --predictoor --with-pdr-trueval --with-pdr-trader --with-pdr-publisher --with-pdr-dfbuyer
+```
+
+Open a new console and:
+```
+# Setup virtualenv
+cd pdr-backend
+source venv/bin/activate
+
+# Set envvars
+export ADDRESS_FILE="${HOME}/.ocean/ocean-contracts/artifacts/address.json"
+export RPC_URL=http://127.0.0.1:8545
+export SUBGRAPH_URL="http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph"
+export PRIVATE_KEY="0xef4b441145c1d0f3b4bc6d61d29f5c6e502359481152f869247c7a4244d45209"
+
+# run predictoor agent
+python3 pdr_backend/predictoor/main.py
+```
+
+Relax & watch as the predictoor agent submits random predictions, trueval submits random true_vals for each epoch and trader signals trades.
+
+You can query predictoor subgraph for detailed run info. See [subgraph.md](subgraph.md) for details.
+
+The agent predicts according to the `predict()` function in [`pdr_backend/predictoor/predict.py`](../pdr_backend/predictoor/predict.py). Its default strategy is simplistic (random predictions). So you need to customize it. The docstring at the top of `predict.py` provides more info.
+
+## Remote Testnet Usage
+
+FIXME
+
+## Remote Mainnet Usage
+
+FIXME
+
diff --git a/READMEs/subgraph.md b/READMEs/subgraph.md
@@ -0,0 +1,19 @@
+<!--
+Copyright 2023 Ocean Protocol Foundation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Using Predictoor Subgraph
+
+### Querying
+
+You can query [subgraph](http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph/graphql) and see [this populated data PR](https://github.com/oceanprotocol/ocean-subgraph/pull/678) here for entities.
+
+### Filtering
+
+Here are additional envvars used to filter:
+
+- PAIR_FILTER = if we do want to act upon only same pair, like  "BTC/USDT,ETH/USDT"
+- TIMEFRAME_FILTER = if we do want to act upon only same timeframes, like  "5m,15m"
+- SOURCE_FILTER = if we do want to act upon only same sources, like  "binance,kraken"
+- OWNER_ADDRS = if we do want to act upon only same publishers, like  "0x123,0x124"
diff --git a/READMEs/trader.md b/READMEs/trader.md
@@ -0,0 +1,64 @@
+<!--
+Copyright 2023 Ocean Protocol Foundation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Usage for Traders
+
+This is for traders - people who are running `trader` agents that buy aggregated predictions, then trade.
+
+## Contents
+
+- [Install](#install)
+- [Local Usage](#local-usage)
+- [Remote Testnet Usage](#remote-testnet-usage)
+- [Remote Mainnet Usage](#remote-mainnet-usage)
+
+
+## Install
+
+First, [install pdr-backend](install.md).
+
+Then, [install barge](barge.md#install-barge).
+
+## Local Usage
+
+In barge console:
+```console
+#run barge with all agents except trader
+./start_ocean.sh --predictoor --with-pdr-trueval --with-pdr-predictoor --with-pdr-publisher --with-pdr-dfbuyer
+```
+
+Open a new console and:
+```
+# Setup virtualenv
+cd pdr-backend
+source venv/bin/activate
+
+# Set envvars
+export ADDRESS_FILE="${HOME}/.ocean/ocean-contracts/artifacts/address.json"
+export RPC_URL=http://127.0.0.1:8545
+export SUBGRAPH_URL="http://172.15.0.15:8000/subgraphs/name/oceanprotocol/ocean-subgraph"
+export PRIVATE_KEY="0xef4b441145c1d0f3b4bc6d61d29f5c6e502359481152f869247c7a4244d45209"
+
+# run trader agent
+python3 pdr_backend/trader/main.py
+```
+
+Relax & watch as the predictoor agent submits random predictions, trueval submits random true_vals for each epoch and trader signals trades.
+
+You can query predictoor subgraph for detailed run info. See [subgraph.md](subgraph.md) for details.
+
+The agent trades according to the `trade()` function in [`pdr_backend/trader/trade.py`](../pdr_backend/trader/trade.py). Its default strategy is simplistic; you need to customize it. The docstring at the top of `trade.py` provides more info.
+
+## Remote Testnet Usage
+
+FIXME
+
+## Remote Mainnet Usage
+
+FIXME
+
+## Final note
+
+As with all trading strategies, there's risk involved. Always trade responsibly. Nothing in this README or related should be considered financial advice.
diff --git a/pdr_backend/predictoor/README.md b/pdr_backend/predictoor/README.md
@@ -1,3 +1 @@
-# Predictoor
-
-FIXME. This is a placeholder. Fill me in.
+See [READMEs/predictoor.md](../../READMEs/predictoor.md).
diff --git a/pdr_backend/predictoor/predict.py b/pdr_backend/predictoor/predict.py
@@ -16,7 +16,6 @@
    - predicted_value:  boolean, up/down
    - predicted_confidence:   int, 1 -> 100%. This sets the stake (STAKE_AMOUNT * predicted_confidence/100) that you are willing to put in your prediction.
 
-
   You need to change the function code and do some of your stuff. Now, it's just doing some random predictions
 
 ## About BLOCKS_TILL_EPOCH_END
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,8 @@ Copyright 2023 Ocean Protocol Foundation @@
     SPDX-License-Identifier: Apache-2.0
     -->
+    # Barge
     ## Contents
     Installation
@@ Expand Down @@