From 06bacc57a97aaa9addf56fbe024527c6b7985bc7 Mon Sep 17 00:00:00 2001 From: Codegnosis Date: Mon, 23 Jan 2023 11:28:03 +0000 Subject: [PATCH] readme cleanup --- README.md | 188 +------------------------------------- docker/README.md | 50 ++++++++++ go-ooo/README.md | 80 ++++++++++++++++ smart-contracts/README.md | 71 ++++++++++++++ 4 files changed, 205 insertions(+), 184 deletions(-) create mode 100644 docker/README.md create mode 100644 go-ooo/README.md create mode 100644 smart-contracts/README.md diff --git a/README.md b/README.md index 3848546..250bf5d 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ [![npm version](http://img.shields.io/npm/v/@unification-com/xfund-router.svg?style=flat)](https://npmjs.org/package/@unification-com/xfund-router "View this project on npm") ![sc unit tests](https://github.com/unification-com/xfund-router/actions/workflows/test-contracts.yml/badge.svg) +[![Latest go-ooo Release](https://img.shields.io/github/v/release/unification-com/xfund-router?display_name=tag)](https://github.com/unification-com/xfund-router/releases/latest) A suite of smart contracts to enable price data from external sources (such as Finchains.io, or supported DEXs) to be included in your smart contracts. The suite comprises of: @@ -13,9 +14,8 @@ to be included in your smart contracts. The suite comprises of: a designated Provider) 3) The Provider Oracle software, run by data providers -The remainder of this `README` is aimed at developers who wish to develop and test the suite itself. -For an integration guide, and how to use the suite in your own smart contracts, please -see the [Documentation](docs/index.md) +For an end-user integration guide, and how to use the suite in your own smart contracts, please +see the [OoO Documentation](https://docs.unification.io/ooo) ## Repo Overview @@ -27,184 +27,4 @@ This repo consists of a few different packages and applications: | `go-ooo` | Go implementation of the OoO Provider Oracle | | `smart-contracts` | OoO Router smart contracts and end-user contract SDK | -## Development and Testing - -### Prerequisites - -#### NodeJS -The `openzeppelin/test-environment` packages and dependencies require -NodeJS <= `v12.18.3` in order to correctly install. -We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS -installations. - -#### Yarn - -[Yarn](https://classic.yarnpkg.com/en/docs/install) is recommended for package management. - -#### Go - -Go v1.18+ is required to compile the `go-ooo` application. - -### Compile Contracts - -All smart contract code is in the `smart-contracts` directory. - -```bash -cd smart-contracts -``` - -Run: - -```bash -yarn install -``` - -to install the Node packages and dependencies - -Run: -```bash -npx truffle compile -``` - -to compile smart contracts - -### Unit Tests - -To run all tests: - -```bash -yarn test -``` - -Test Coverage - -```bash -yarn run coverage -``` - -Running unit test coverage will take a long time. Results are saved to -`smart-contracts/converage.json` and `smart-contracts/coverage` - -### Development Environment - Testing & Interaction - -The repo contains a complete, self-contained `ganache-cli` development environment, which can be used -to test contracts, developing and testing Consumer contracts and testing the `go-ooo` Provider Oracle app. - -**Note**: the NodeJS implementation of the `provider-oracle` is deprecated. - -#### Docker Dev Environment - -To run the development environment, from the repo root directory, run - -```bash -make dev-env -``` - -This will run a local `ganache-cli` chain, deploy the Router and demo consumer contract, and also initialise -the accounts with some Dev xFUND. The chain's RPC endpoint will be exposed on `http://127.0.0.1:8545`, and can be -accessed via the `truffle-config`'s `develop` network. - -#### Running `go-ooo` - -The OoO app code is in the `go-ooo` directory - -```bash -cd go-ooo -``` - -First, build the Go application: - -```bash -make build -``` - -`go-ooo` will need initialising before it can run: - -```bash -./build/go-ooo init -``` - -Where `` is one of `dev`, `rinkeby`, `mainnet` or `polygon`. Using `dev` will configure `go-ooo` for the Docker -development environment. - -This will save the default configuration to `$HOME/.go-ooo`, with the initial values for the `dev` network. -This config location can be changed using the `--home` flag to specify a custom location, e.g. - -```bash -./build/go-ooo init dev --home $HOME/.go-ooo_dev -``` - -This initialisation script will ask whether you want to import an exisitng private key, or generate a new one. -You can enter anything for the account name. For the purposes of quick testing, the Docker development environment -initialises by pre-registering account #3 on the `ganache-cli` chain as a Provider Oracle. The private key to import is: - -`0x646f1ce2fdad0e6deeeb5c7e8e5543bdde65e86029e2fd9fc169899c440a7913` - -Make a note of the generated decryption password - this will be required to run the application (to decrypt the keystore) -and to execute any admin commands. For the sake of simplicity, save it to `$HOME/.go-ooo/pass.txt` - -The application should now have the default configuration saved to `$HOME/.go-ooo/config.toml`. It will use `sqlite` as -the default database, but can easily be configured for PostgreSQL. - -#### Registering a new Oracle Provider - -If `go-ooo` has been initialised for a network other than `dev`, and using a key other than the pre-defined test key, -then registration as an Oracle Provider is required. First, ensure the wallet being used has funds on the target -chain, then run the registration admin command: - -```bash -./build/go-ooo admin register [FEE] --home /path/to/.go-ooo --pass /path/to/pass.txt -``` - -Where `[FEE]` is your fee, for example `1000000` for 0.001 xFUND. - -#### Start the Oracle - -Now, you can start the Provider Oracle: - -```bash -./build/go-ooo start -``` - -This will prompt you for the decryption password, and start the application. If you saved the password, you can pass the -path to the file using the `--pass` flag, e.g. - -```bash -./build/go-ooo start --home $HOME/.go-ooo_dev --pass $HOME/.go-ooo_dev/pass.txt -``` - - - -#### Requesting Data - -The development environment is deployed with a pre-configured and deployed demo Consumer contract, along with a script -for requesting and waiting for data. This script can be called using `docker exec`: - -```bash -docker exec -it ooo_dev_env /root/xfund-router/request.sh [SUBTYPE] [SUPP1] [SUPP2] -``` - -For example querying Finchains tracked data: - -```bash -docker exec -it ooo_dev_env /root/xfund-router/request.sh BTC GBP PR AVC 1H -``` - -This will request data using the OoO endpoint `BTC.GBP.PR.AVC.1H`, which is the mean GBP price of Bitcoin for the -past hour, using the Chauvenet Criterion to remove statistical outliers. - -Or and Ad-Hoc request: - -```bash -docker exec -it ooo_dev_env /root/xfund-router/request.sh BONE WETH AD -``` - -See the [OoO API Guide](docs/guide/ooo_api.md) for more information on endpoint construction. - -#### Dev Notes - -Verify contracts on Etherscan after deployment - from the `smart-contracts` dir set `ETHERSCAN_API` in `.env`, then run: - -```bash -npx truffle run verify [ContractName] --network=[network] -``` +See each directory's respective `README` for more info aimed at developers. diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..b36d7a2 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,50 @@ +# Docker Dev Environment + +A full Docker environment for testing the OoO smart contracts and `go-ooo`. + +This is a complete, self-contained `ganache-cli` development environment, which can be used +to test contracts, developing and testing Consumer contracts and testing the `go-ooo` Provider Oracle app. + +## Running + +To run the development environment, from the **repo root directory**, run + +```bash +make dev-env +``` + +This will run a local `ganache-cli` chain, deploy the Router and demo consumer contract, and also initialise +the accounts with some Dev xFUND. The chain's RPC endpoint will be exposed on `http://127.0.0.1:8545`, and can be +accessed via the `truffle-config`'s `develop` network. + +## Interaction + +**Note**: Both this Docker environment and [`go-ooo`](../go-ooo/README.md) must be running (on this `dev` network) in +order to test data requests. + +#### Requesting Data + +The development environment is deployed with a pre-configured and deployed demo Consumer contract, along with a script +for requesting and waiting for data. This script can be called using `docker exec`: + +```bash +docker exec -it ooo_dev_env /root/xfund-router/request.sh [SUBTYPE] [SUPP1] [SUPP2] +``` + +For example querying Finchains tracked data: + +```bash +docker exec -it ooo_dev_env /root/xfund-router/request.sh BTC GBP PR AVC 1H +``` + +This will request data using the OoO endpoint `BTC.GBP.PR.AVC.1H`, which is the mean GBP price of Bitcoin for the +past hour, using the Chauvenet Criterion to remove statistical outliers. + +Or and Ad-Hoc request: + +```bash +docker exec -it ooo_dev_env /root/xfund-router/request.sh BONE WETH AD +``` + +See the [OoO API Guide](https://docs.unification.io/ooo/guide/ooo_api.html) for more information on endpoint +construction. diff --git a/go-ooo/README.md b/go-ooo/README.md new file mode 100644 index 0000000..abca872 --- /dev/null +++ b/go-ooo/README.md @@ -0,0 +1,80 @@ +# go-ooo + +The Go implementation of the OoO Provider application, required to be run by providers to serve data + +## Development and Testing + +### Prerequisites + +#### Go + +Go v1.18+ is required to compile the `go-ooo` application. + +## Running + +First, build the Go application: + +```bash +make build +``` + +`go-ooo` will need initialising before it can run: + +```bash +./build/go-ooo init +``` + +Where `` is one of `dev`, `goerli`, `mainnet` or `polygon`. Using `dev` will configure `go-ooo` for the Docker +[development environment](../docker/README.md). + +This will save the default configuration to `$HOME/.go-ooo`, with the initial values for the `dev` network. +This config location can be changed using the `--home` flag to specify a custom location, e.g. + +```bash +./build/go-ooo init dev --home $HOME/.go-ooo_dev +``` + +This initialisation script will ask whether you want to import an exisitng private key, or generate a new one. +You can enter anything for the account name. For the purposes of quick testing, the Docker development environment +initialises by pre-registering account #3 on the `ganache-cli` chain as a Provider Oracle. The private key to import is: + +`0x646f1ce2fdad0e6deeeb5c7e8e5543bdde65e86029e2fd9fc169899c440a7913` + +Make a note of the generated decryption password - this will be required to run the application (to decrypt the keystore) +and to execute any admin commands. For the sake of simplicity, save it to `$HOME/.go-ooo/pass.txt` + +The application should now have the default configuration saved to `$HOME/.go-ooo/config.toml`. It will use `sqlite` as +the default database, but can easily be configured for PostgreSQL. + +#### Registering a new Oracle Provider + +If `go-ooo` has been initialised for a network other than `dev`, and using a key other than the pre-defined test key, +then registration as an Oracle Provider is required. First, ensure the wallet being used has funds on the target +chain, then run the registration admin command: + +```bash +./build/go-ooo admin register [FEE] --home /path/to/.go-ooo --pass /path/to/pass.txt +``` + +Where `[FEE]` is your fee, for example `1000000` for 0.001 xFUND. + +#### Start the Oracle + +Now, you can start the Provider Oracle: + +```bash +./build/go-ooo start +``` + +This will prompt you for the decryption password, and start the application. If you saved the password, you can pass the +path to the file using the `--pass` flag, e.g. + +```bash +./build/go-ooo start --home $HOME/.go-ooo_dev --pass $HOME/.go-ooo_dev/pass.txt +``` + +## Docker Developer Environment + +If the [Developer Environment](../docker/README.md) is running, these will have been deployed automatically, along with +a number of funded test accounts for both an OoO Provider and end-users. The `dev` network provider above should be +pre-registered in the Router smart contract. diff --git a/smart-contracts/README.md b/smart-contracts/README.md new file mode 100644 index 0000000..f503a63 --- /dev/null +++ b/smart-contracts/README.md @@ -0,0 +1,71 @@ +# Smart Contracts + +Smart contracts required to run the OoO network, including the Router, demo consumer and end-user SDK contracts + +## Development and Testing + +### Prerequisites + +#### NodeJS + +The `openzeppelin/test-environment` packages and dependencies require +NodeJS <= `v12.18.3` in order to correctly install. +We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS +installations. + +#### Yarn + +[Yarn](https://classic.yarnpkg.com/en/docs/install) is recommended for package management. + +### Compile Contracts + +All smart contract code is in the `smart-contracts` directory. + +```bash +cd smart-contracts +``` + +Run: + +```bash +yarn install +``` + +to install the Node packages and dependencies + +Run: +```bash +npx truffle compile +``` + +to compile smart contracts + +### Unit Tests + +To run all tests: + +```bash +yarn test +``` + +Test Coverage + +```bash +yarn run coverage +``` + +Running unit test coverage will take a long time. Results are saved to +`./converage.json` and `./coverage` + +## Docker Developer Environment + +If the [Developer Environment](../docker/README.md) is running, these will have been deployed automatically, along with +a number of funded test accounts for both an OoO Provider and end-users + +#### Dev Notes + +Verify contracts on Etherscan after deployment - from the `smart-contracts` dir set `ETHERSCAN_API` in `.env`, then run: + +```bash +npx truffle run verify [ContractName] --network=[network] +``` \ No newline at end of file