Oracle Service

Commands

Usage

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:

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

or the shorthand

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:

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

Attest

To attest use the command:

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

or the shorthand

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,

  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:

zen-oracle.exe query

or the shorthand

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:

zen-oracle.exe q p

Committed Data

To get information about committed data run:

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:

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

or the shorthand

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:

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

Server

To run the server use the command:

zen-oracle.exe server

or the shorthand

zen-oracle.exe s

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

Database Structure

The server command supports the following flags:

Collections

• --bind, -b <address>

  API port

• --chain, -c <chain>

  Node chain

• --origin, -o <origin>

  CORS origin

• --maxtake, -l <n>

  Maximum size of take (default: 1000)

• --maxbodysize, -s <n>

  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.

Oracle's API