Lots of docs

README.md

@@ -1,16 +1,24 @@
 # Codex Testnet Starter
 Hit the ground running with Codex.
 
+## Overview
+![Overview](/docs/overview.png)
+Using the Testnet Starter, you can run a (mostly preconfigured) Codex node on your machine. You always have the option to build and run Codex from sources [Here](https://github.com/codex-storage/nim-codex/).
+
 1. [How to start](#how-to-start)
-2. [How to stop](#how-to-stop)
-3. [How to stop and delete everything](#how-to-stop-and-delete-everything)
-4. [Troubleshooting](#troubleshooting)
+1. [How to get ready](#how-to-get-ready)
+1. [How to use](#how-to-use)
+1. [How to stop](#how-to-stop)
+1. [How to stop and delete everything](#how-to-stop-and-delete-everything)
+1. [Troubleshooting](#troubleshooting)
 
 
 ## [How to start](#codex-testnet-starter)
-- Have docker installed.
+- Create a public/private key pair.
+- Have Docker installed.
+- Have Discord installed.
 - Clone this repo.
-- Define variables
+- Define variables:
   ```shell
   export PRIV_KEY=9721fb80cf32275ce80ae41927130adc767d435dbb1d80114dac2ef2d7c951f0
 
@@ -18,14 +26,32 @@ Hit the ground running with Codex.
   # export GETH_VERBOSITY=4
   ```
 - `docker-compose up -d`
-- Open browser to `<GUI ENDPOINT HERE>`
 
 
+## [How to get ready](#codex-testnet-starter)
+When starting the Testnet Starter for the first time, (or restarting after a long pause) please keep in mind:
+- Your local Geth node will need time to sync.
+- Codex should automatically wait until Geth is ready. However, in some situations Codex will attempt to start and promptly crash too soon. This is a known issue. When this happens, please manually restart Codex's container when your Geth node is synced.
+
+Before you can use the marketplace functionality of Codex, you will need to obtain some tokens in the testnet.
+1. Join the Codex Discord server: [Here](LINK PENDING)
+1. Find the appropriate testnet channel.
+1. Give your public key to the bot using `set` command.
+![Bot-Set](/docs/bot-set.png)
+1. Ask it politely to mint some tokens for you using `mint` command.
+![Bot-Mint](/docs/bot-mint.png)
+(It may or may not happen in the future that testnet participation will be rewarded automatically with Discord server roles.)
+
+
+## [How to use](#codex-testnet-starter)
+Once running, Codex exposes a web-api at the API port. (default: 8080)
+To read more about how to use the API, go [Here](/USINGCODEX.md)
 
 
 ## [How to stop](#codex-testnet-starter)
 - `docker-compose down`
 
+
 ## [How to stop and delete everything](#codex-testnet-starter)
 - `docker-compose down --rmi all -v`
 

USINGCODEX.md

@@ -0,0 +1,103 @@
+# Using Codex
+
+Codex's web-API is documented: [Here](https://github.com/codex-storage/nim-codex/blob/master/openapi.yaml)
+This document will show you several useful API calls.
+
+
+## Overview
+1. [Debug](#debug)
+1. [Upload a file](#upload-a-file)
+1. [Download a file](#download-a-file)
+1. [Local data](#local-data)
+1. [Create storage availability](#create-storage-availability)
+1. [Purchase storage](#purchase-storage)
+1. [View purchase status](#view-purchase-status)
+
+
+## Debug
+An easy way to check that your node is up and running is:
+```shell
+curl --request GET \
+  --url http://localhost:8080/api/codex/v1/debug/info
+```
+This will return a JSON structure with plenty of information about your local node. It contains peer information that may be useful when troubleshooting connection issues.
+
+
+## Upload a file
+**Warning**
+Once you upload a file to Codex, other nodes in the testnet can download it. Please do not upload anything you don't want others to access, or, properly encrypt your data *first*.
+
+```shell
+curl --request POST \
+  --url http://localhost:8080/api/codex/v1/data \
+  --header 'Content-Type: application/octet-stream' \
+  -T <FILE>
+```
+
+On successful upload, you'll receive a CID. This can be used to download the file from any node in the network.
+
+
+## Download a file
+When you have a CID of data you want to download, you can use the following:
+
+```shell
+curl --request GET \
+  --url http://localhost:8080/api/codex/v1/data/<<<CID HERE>>>/network
+```
+
+Note that Codex does not store content-type or extension information.
+
+
+## Local data
+You can view which datasets are currently being stored by your node.
+```shell
+curl --request GET \
+  --url http://localhost:8080/api/codex/v1/data
+```
+
+
+## Create storage availability
+In order to start selling storage space to the network, you must configure your node with the following command. Once configured, the node will monitor on-chain requests-for-storage and will automatically enter into contracts that meet these specifications.
+```shell
+curl --request POST \
+  --url http://localhost:8080/api/codex/v1/sales/availability \
+  --header 'Content-Type: application/json' \
+  --data '{
+	"totalSize": "8000000",
+	"duration": "7200",
+	"minPrice": "10",
+	"maxCollateral": "10"
+  }'
+```
+For descriptions of each parameter, please view the [Spec](https://github.com/codex-storage/nim-codex/blob/master/openapi.yaml).
+
+
+## Purchase storage
+To purchase storag space from the network, first you must upload your file. Once you have the CID, use the following to create a request-for-storage contract.
+
+```shell
+curl --request POST \
+  --url http://localhost:8080/api/codex/v1/storage/request/<<<CID HERE>>> \
+  --header 'Content-Type: application/json' \
+  --data '{
+  "duration": "3600",
+  "reward": "1",
+  "proofProbability": "3",
+  "nodes": 2,
+  "tolerance": 1,
+  "collateral": "5",
+  "expiry": "1711703406"
+}'
+```
+For descriptions of each parameter, please view the [Spec](https://github.com/codex-storage/nim-codex/blob/master/openapi.yaml).
+
+On successful, this request will return a Purchase-ID.
+
+
+## View purchase status
+Using a Purchase-ID, you can check the status of your request-for-storage contract:
+```shell
+curl --request GET \
+  --url http://localhost:8080/api/codex/v1/storage/purchases/<<<PURCHASE ID HERE>>>
+```
+