Skip to content

Commit

Permalink
Merge pull request #100 from unification-com/readmes
Browse files Browse the repository at this point in the history 
README cleanup
  • Loading branch information
@Codegnosis
Codegnosis authored Jan 23, 2023
2 parents 7858978 + 06bacc5 commit fe46bed
Show file tree
Hide file tree
Showing 4 changed files with 205 additions and 184 deletions.
188 changes: 4 additions & 184 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand All @@ -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 <network>
```

Where `<network>` 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 <BASE> <TARGET> <TYPE> [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.
50 changes: 50 additions & 0 deletions docker/README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <BASE> <TARGET> <TYPE> [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.
80 changes: 80 additions & 0 deletions go-ooo/README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <network>
```

Where `<network>` 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.
Loading

0 comments on commit fe46bed

Please sign in to comment.