From 2ba0ee88e4ed8897dcb698612e03a9814819217a Mon Sep 17 00:00:00 2001
From: hopeyen <hopey1118@gmail.com>
Date: Wed, 1 Jun 2022 14:25:43 -0700
Subject: [PATCH] docs: CLI script usage

---
 docs/src/usage.md | 64 ++++++++++++++++++++++++++++-------------------
 1 file changed, 38 insertions(+), 26 deletions(-)

diff --git a/docs/src/usage.md b/docs/src/usage.md
index 0a0f517..f52b6cb 100644
--- a/docs/src/usage.md
+++ b/docs/src/usage.md
@@ -1,58 +1,70 @@
 # Usage
 
-## ActionQueue
-
-Set indexer-service flag `--serve-network-subgraph` to `true` so optimiser can pull data from the network subgraph at the indexer-service's network endpoint.
-If you would like to keep it false, you can instead supply an API url to `indexer_service_network_url`.
+## CLI script
 
 1. Download the [*allocationopt* script](https://raw.githubusercontent.com/graphprotocol/AllocationOpt.jl/main/scripts/allocationopt). For example, using `curl` or `wget`. Make sure you use the raw file!
-2. Make the *allocationopt* script executable.
 
+2. On MacOS, if you have already added Julia path to `usr/local/bin`, you would need to change shebang of downloaded script to `#!/usr/local/bin/julia`.
+
+Linux (Default)
 ```bash
-$ chmod +x allocationopt
+#!/usr/bin/julia 
+```
+MacOS 
+```bash
+#!/usr/local/bin/julia
 ```
 
-3. Run the *allocationopt* script with the *actionqueue* option. If this doesn't work, check that the shebang in the allocationopt file points to your julia executable.
+3. Make the *allocationopt* script executable. 
+```bash
+$ chmod +x allocationopt
+```
 
+4. A simple check here, make sure you have Comonicon package added to Julia environment. 
 ```bash
 $ ./scripts/allocationopt --help
-$ ./scripts/allocationopt actionqueue "0x6ac85b9d834b51b14a7b0ed849bb5199e04c05c5" test/example.csv 0.0 10 http://localhost:18000 http://localhost:7600/network
 ```
 
-3. On Linux, you can further simplify the use of this script by symlinking it to your *.local/bin*
+5. On Linux, you can further simplify the use of this script by symlinking it to your *.local/bin*
 
 ```
 $ mkdir -p ~/.local/bin
 $ cd ~/.local/bin
 $ ln -s ~/projects/AllocationOpt.jl/scripts/allocationopt .  # Change to the path to the allocationopt script for you
 ```
-
 You should now be able to run the *allocationopt* script from anywhere! Similarly to how you'd run *ls*.
 
-## Indexer Rules
+6. Optimiser queries network subgraph data to optimize. We recommend making queries to network subgraph served by your own indexer service, alternatively you can supply an API url to `indexer_service_network_url` from decentralized gateway or hosted service. 
 
-If you don't have the action queue set up yet, you can also run the optimiser by telling it to generate indexing rules.
+To provide network subgraph to optimiser, set indexer-service flag `--serve-network-subgraph` to `true`. We might incorporate bearer Auth token checks in the future. 
 
-1. Download the [*allocationopt* script](https://raw.githubusercontent.com/graphprotocol/AllocationOpt.jl/main/scripts/allocationopt). For example, using `curl` or `wget`. Make sure you use the raw file!
-2. Make the *allocationopt* script executable.
+7. Populate your preferred lists (whitelist, blacklist, pinnedlist, frozenlist) into a CSV and remember its file path
 
-```bash
-$ chmod +x allocationopt
-```
 
-3. Run the *allocationopt* script with the *rules* option. If this doesn't work, check that the shebang in the allocationopt file points to your julia executable.
+## ActionQueue
+
+This command requires a URL to indexer management server and a URL to make graph network subgraph queries.
+
+Run the *allocationopt* script with the *actionqueue* option.
 
 ```bash
-$ ./scripts/allocationopt --help
-$ ./scripts/allocationopt rules "0x6ac85b9d834b51b14a7b0ed849bb5199e04c05c5" test/example.csv 0.0 10 http://localhost:18000
+$ ./scripts/allocationopt actionqueue "0x6ac85b9d834b51b14a7b0ed849bb5199e04c05c5" test/example.csv 0.0 10 http://localhost:18000 http://localhost:7600/network
 ```
+If this doesn't work, check that the shebang in the allocationopt file points to your julia executable. 
 
-3. On Linux, you can further simplify the use of this script by symlinking it to your *.local/bin*
+Upon success, you should see a 'Done!' printed; on the indexer service side, requests from our tool is logged, and you can use indexer CLI `actions` commands to check and approve actions. 
 
-```
-$ mkdir -p ~/.local/bin
-$ cd ~/.local/bin
-$ ln -s ~/projects/AllocationOpt.jl/scripts/allocationopt .  # Change to the path to the allocationopt script for you
+## Indexer Rules
+
+If you don't have the action queue set up yet, you can also run the optimiser by telling it to generate indexing rules. 
+
+Indexer still need to pay attention to how the agent reacts to these rules, and reallocation is broken into 2 separate rules: indexer must send `close` transaction before sending `allocate`.
+
+Run the *allocationopt* script with the *rules* option. The URL passed in should be an API URL
+
+```bash
+$ ./scripts/allocationopt --help
+$ ./scripts/allocationopt rules "0x6ac85b9d834b51b14a7b0ed849bb5199e04c05c5" test/example.csv 0.0 10 http://localhost:7600/network
 ```
 
-You should now be able to run the *allocationopt* script from anywhere! Similarly to how you'd run *ls*.
+If this doesn't work, check that the shebang in the allocationopt file points to your julia executable.