# Oracle Service

## Commands

### Usage

```javascript
USAGE: zen-oracle.exe [--help] [<subcommand> [<options>]]

SUBCOMMANDS:

    commit, c <options>   commit an item or a data set
    query, q <options>    query for committed data
    attest, a <options>   attest on committed data
    audit, p <options>    get the audit path for a committed item
    server, s <options>   create a web server

    Use 'zen-oracle.exe <subcommand> --help' for additional information.

OPTIONS:

    --help                display this list of options.
```

### Environmental Variables

1. Make sure all the environment variables are provided and correct
   * `zen_path` : path of the oracle committer
   * `zen_wallet_password`: password of the f# wallet
   * `zen_node_uri`: uri of the node
   * `oracle_api`: `uri:port` api port for oracle requests
   * `mongo_connection`: MongoDB (optional. defaults to "mongodb://127.0.0.1:27017")

### Commit

To commit use the command:

```bash
zen-oracle.exe commit [--timestamp <timestamp>] [--notx] [--stdin] [<file>]
```

or the shorthand

```bash
zen-oracle.exe c [--timestamp <timestamp>] [--notx] [--stdin] [<file>]
```

This command has a parameter `<file>` and the following flags:

* **`--timestamp`**, **`-t`** `<timestamp>`

  Time of the committed data (in milliseconds since the Unix epoch - 00:00:00 UTC on 1 January 1970).
* **`--notx`**, **`-x`**

  Don't create a commitment transaction, just return the message body.
* **`--stdin`**, **`-i`**

  When this flag is used - get JSON string from standard input (can't be used along with `-f`).

For the `<file>` parameter use the name of a JSON data file you want to commit.

The JSON file should be a record with names and values, like this:

```bash
{ "APPL" : 10 , "ABCD" : 12 , "WXYZ" : 123 , "XYXY" : 6456 }
```

### Attest

To attest use the command:

```bash
zen-oracle.exe attest [--root <root>] [--timestamp <timestamp>] [--commit <commit>] [--publickey <pk>] [--contract <cid>] [--notx]
```

or the shorthand

```bash
zen-oracle.exe a [--root <root>] [--timestamp <timestamp>] [--commit <commit>] [--publickey <pk>] [--contract <cid>] [--notx]
```

This command has the following flags:

* **`--root`**, **`-r`** `<root>`

  Root of the committed Merkle tree.
* **`--timestamp`**, **`-t`** `<timestamp>` Time of the committed data (in milliseconds since the Unix epoch - 00:00:00 UTC on 1 January 1970).
* **`--commit`**, **`-c`** `<commit>`

  Commit ID of the committed data.
* **`--publickey`**, **`-p`** `<pk>`

  Public key of the recipient address.
* **`--contract`**, **`-d`** `<cid>`

  Contract ID of the recipient contract.
* **`--notx`**, **`-x`**

  Don't create an attestation transaction, just return the message body.
* **`--address,`**&#x20;

  Address of the recipient (either a contract address or a public key hash address)

You have to use either **`--commit`** or both **`--root`** and **`--timestamp`**.

You can only have at most 1 recipient (either **`publickey`** or **`contract`**).

If you don't provide a recipient the attestation token will be sent to the sender.

### Query

To query use the command:

```bash
zen-oracle.exe query
```

or the shorthand

```bash
zen-oracle.exe q
```

There are 2 things you can query for - the **oracle public key** or information about **committed data**.

#### Oracle Public Key

To get the public key of the oracle run:

```javascript
zen-oracle.exe q p
```

#### Committed Data

To get information about committed data run:

```javascript
zen-oracle.exe q t [--low <low>] [--high <high>] --key <key>
```

This command has the following flags:

* **`--low`**, **`-l`** `<low>`

  Lower time bound.
* **`--high`**, **`-h`** `<high>`

  Upper time bound.
* **`--key`**, **`-k`** `<key>`

  Key to search the value for.
* **`--skip`**, **`-s`** *`<n>`*

  Skip the first *\<n>* items.
* **`--take`**, **`-t`** *`<n>`*

  Take only the first items (after the skip if there is one).
* **`--count`**, **`-c`**

  Return the total amount of items satisfying the query.

It will provide you information about all the values committed by the server for the given keys within the given time bounds.

If no key is provided it will provide information about all the values within the time bounds regardless of keys.

If no time bounds are provided it will provide information about all the values committed by the server for the given keys, regardless of time bounds.

### Audit Path

To get an audit path in the Merkle tree of a committed data set use the command:

```bash
zen-oracle.exe audit [--commit <commit>] [--root <root>] [--stdin] [<item>]
```

or the shorthand

```bash
zen-oracle.exe p [--commit <commit>] [--root <root>] [--stdin] [<item>]
```

This command has a parameter `<item>` and the following flags:

* **`--commit`**, **`-c`** `<commit>`

  Commit hash.
* **`--root`**, **`-r`** `<root>`

  Root hash.
* **`--stdin`**, **`-i`**

  When this flag is used - get item's JSON string from standard input.

For the  parameter use the name of a JSON file which contains items for which you want to get audit paths in the given commit.

The JSON file should be a record with names and values, like this:

```bash
{ "APPL" : 10 , "ABCD" : 12 , "WXYZ" : 123 , "XYXY" : 6456 }
```

### Server

To run the server use the command:

```bash
zen-oracle.exe server
```

or the shorthand

```bash
zen-oracle.exe s
```

The server will run on a port specified with the `zen_api` environment variable.

### Database Structure&#x20;

The `server` command supports the following flags:

#### Collections

* `--bind`, `-b` `<address>`&#x20;

  API port
* `--chain`, **`-c`** `<chain>`&#x20;

  Node chain
* `--origin`, `-o` `<origin>`&#x20;

  CORS origin
* `--maxtake`, `-l` *`<n>`*&#x20;

  Maximum size of take (default: `1000`)
* `--maxbodysize`, `-s` *`<n>`*&#x20;

  Maximum size of body for the `getValues` endpoint (default: `1000`)

The oracle service uses the following MongoDB collections, within the `oracle` database:

#### `Commits`

The commits the server have made, sorted by `commitId`.

fields:

* `commitId` - commit ID of the commit
* `timestamp` - (in milliseconds since the Unix epoch - 00:00:00 UTC on 1 January 1970)
* `root` - hash of the root of the committed Merkle tree
* `items` - list of committed items

#### `Items`

The committed items, sorted by `name`.

fields:

* `name` - name of the item
* `root` - hash of the root of the Merkle tree this item was committed in
* `commitId` - commit ID of the commit
* `timestamp` - (in milliseconds since the Unix epoch - 00:00:00 UTC on 1 January 1970)
* `item` - serialization of item
* `proof` - proof of inclusion of the item in the committed Merkle tree, which contains:
  * `index` - index of the item in the Merkle tree
  * `path` - audit path of the item in the Merkle tree

#### `TimeCommits`

The commits (given by root and commit ID) sorted by `timestamp`.

This collection purpose is to make fast querying by timestamp.

fields:

* `timestamp` - (in milliseconds since the Unix epoch - 00:00:00 UTC on 1 January 1970)
* `root` - hash of the root of the committed Merkle tree
* `commitId` - commit ID of the commit

#### `PublicKey`

The public key of the oracle in the blockchain.

fields:

* `pk` - the public key of the oracle in the blockchain

For the api follow the link here.

{% content-ref url="oracles-api" %}
[oracles-api](https://docs.zenprotocol.com/apps/oracle/oracles-api)
{% endcontent-ref %}