diff --git a/README.md b/README.md index f025dc90c..64e35400b 100644 --- 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 index f960e9f9f..b050f14c3 100644 --- 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 index 0565b2e60..bb5435527 100644 --- 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 new file mode 100644 index 000000000..a2e4f0451 --- /dev/null +++ b/READMEs/filter.md @@ -0,0 +1,19 @@ + + +# 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 index e3c98852a..6c883e2cf 100644 --- 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 new file mode 100644 index 000000000..96f77ac24 --- /dev/null +++ b/READMEs/predictoor.md @@ -0,0 +1,60 @@ + + +# 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 new file mode 100644 index 000000000..a2e4f0451 --- /dev/null +++ b/READMEs/subgraph.md @@ -0,0 +1,19 @@ + + +# 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 new file mode 100644 index 000000000..d146705f6 --- /dev/null +++ b/READMEs/trader.md @@ -0,0 +1,64 @@ + + +# 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 index d14e3ccc6..603601440 100644 --- a/pdr_backend/predictoor/README.md +++ b/pdr_backend/predictoor/README.md @@ -1,3 +1 @@ -# Predictoor - -FIXME. This is a placeholder. Fill me in. \ No newline at end of file +See [READMEs/predictoor.md](../../READMEs/predictoor.md). diff --git a/pdr_backend/predictoor/predict.py b/pdr_backend/predictoor/predict.py index 6b11808da..47915507e 100644 --- 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 diff --git a/pdr_backend/trader/README.md b/pdr_backend/trader/README.md index baecaba4f..bb6eacc7b 100644 --- a/pdr_backend/trader/README.md +++ b/pdr_backend/trader/README.md @@ -1,50 +1 @@ -# Trader - -The main action happens in the trade function of `trade.py`. This function kicks in when there's a signal for a specific trading pair, like ETH-USDT. The topic object gives all the details about the pair. The direction parameter is a tuple: the first element shows the stake_up amount, and the second shows the total staked. - -## Trade function - -`trade.py` contains the `trade` function which is a placeholder for your trading strategy. This function is called whenever there's a new signal. When called, it receives two parameters: - -- topic: A dictionary containing details about the trading pair. -- direction: A tuple where the first element represents `stake_up` and the second denotes `total_stake`. Actions can be taken based on the proportion staked on each side and the overall staked amounts. - -By default, `trade` function only prints the incoming trading signal. You need to modify it and implement your trading strategy. - -### Topic Object - -The topic object has all the details about the pair: - -- `name` - The name of the trading pair, e.g., "ETH-USDT". -- `symbol` - Symbol of the trading pair. -- `base` - Base currency of the trading pair. -- `quote` - Quote currency of the trading pair. -- `source` - Source exchange or platform. -- `timeframe` - Timeframe for the trade signal, e.g., "5m" for 5 minutes. - -## Instructions - -### Install pdr-backend - -Follow the [installation guide](../../../READMEs/install.md) to install pdr-backend. - -### Customization - -Modify `trade.py` as explained in the [Trade function](#trade-function) section. - -### Setup environment variables - -Refer to [4.6 Usage for Backend: How to filter](../../../README.md#46-usage-for-backend-how-to-filter) - -### Run trader agent - -Run the agent by: - -```bash -python3 pdr_backend/trader/main.py -``` - -## Notes - -- The direction parameter provides two key numbers: the first represents the amount staked by predictors betting on price going up (stake_up), while the second captures the total amount staked by all predictors. As a trader, you can leverage these numbers to make informed decisions. -- As with all trading strategies, there's risk involved. Always trade responsibly. +See [READMEs/trader.md](../../READMEs/trader.md). diff --git a/pdr_backend/trader/trade.py b/pdr_backend/trader/trade.py index f2449c40d..5d94ae710 100644 --- a/pdr_backend/trader/trade.py +++ b/pdr_backend/trader/trade.py @@ -1,9 +1,25 @@ """ -Flow - FIMXE +The `trade()` function below defines your trading strategy(). -Notes on customization: - FIXME +Its default strategy is simplistic: it only prints the incoming signal. + +Therefore you _need_ to customize it. Here are details, to equip you to do this. + +`trade()` is called when there's a signal for a specific trading pair, like ETH-USDT. + +`trade()` accepts two inbound arguments, `topic` and `direction`. As a trader, your `trade()` implementation can leverage them to make informed decisions and then do trades. + +1. `topic` is a `dict` with info about the trading pair: + - `name` - The name of the trading pair, e.g., "ETH-USDT". + - `symbol` - Symbol of the trading pair. + - `base` - Base currency of the trading pair. + - `quote` - Quote currency of the trading pair. + - `source` - Source exchange or platform. + - `timeframe` - Timeframe for the trade signal, e.g., "5m" for 5 minutes. + +2. `direction` is a `tuple` of `(stake_up, total_stake)`. + - `stake_up` is the amount staked by predictoors betting on price going up (stake_up) + - `total_stake` is the total amount staked by all predictoors. """