README.md 9.14 KB
Newer Older
Ariel's avatar
Ariel committed
1
2
3
4
5
6
# Oracle Service

# Commands

## Usage

Ariel's avatar
Ariel committed
7
```bash
Ariel's avatar
Ariel committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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:

Ariel's avatar
Ariel committed
22
    fields                list output fields
Ariel's avatar
Ariel committed
23
24
25
26
27
28
29
30
31
32
    --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
Ariel's avatar
Ariel committed
33
    - `mongo_connection`: MongoDB connection string (optional. defaults to `"mongodb://127.0.0.1:27017"`)
Ariel's avatar
Ariel committed
34
35
36
37
38
39

## Commit

To commit use the command:

```bash
Ariel's avatar
Ariel committed
40
zen-oracle.exe commit [--timestamp <timestamp>] [--notx] [--stdin] [--field <field>] [<filename>]
Ariel's avatar
Ariel committed
41
42
```

Ariel's avatar
Ariel committed
43
or the abbreviation:
Ariel's avatar
Ariel committed
44
45

```bash
Ariel's avatar
Ariel committed
46
zen-oracle.exe c [--timestamp <timestamp>] [--notx] [--stdin] [--field <field>] [<filename>]
Ariel's avatar
Ariel committed
47
48
```

Ariel's avatar
Ariel committed
49
The `commit` command has a parameter `<filename>` and the following flags:
Ariel's avatar
Ariel committed
50
51
52
53
54
55
56
57
58

- **`--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`**

Ariel's avatar
Ariel committed
59
60
61
    When this flag is used - get JSON string from standard input.

- **`--field`**, **`-f`** `<field>`
Ariel's avatar
Ariel committed
62

Ariel's avatar
Ariel committed
63
64
65
    Output only the specified field.

For the `<filename>` parameter use the name of a JSON data file you want to commit.
Ariel's avatar
Ariel committed
66
67
68

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

Ariel's avatar
Ariel committed
69
```json
Ariel's avatar
Ariel committed
70
71
72
73
74
75
76
77
{ "APPL" : 10 , "ABCD" : 12 , "WXYZ" : 123 , "XYXY" : 6456 }
```

## Attest

To attest use the command:

```bash
Ariel's avatar
Ariel committed
78
zen-oracle.exe attest [--root <root>] [--timestamp <timestamp>] [--commit <commit>] [--publickey <pk>] [--contract <cid>] [--notx] [--field <field>]
Ariel's avatar
Ariel committed
79
80
```

Ariel's avatar
Ariel committed
81
or the abbreviation:
Ariel's avatar
Ariel committed
82
83

```bash
Ariel's avatar
Ariel committed
84
zen-oracle.exe a [--root <root>] [--timestamp <timestamp>] [--commit <commit>] [--publickey <pk>] [--contract <cid>] [--notx] [--field <field>]
Ariel's avatar
Ariel committed
85
86
```

Ariel's avatar
Ariel committed
87
The `attest` command has the following flags:
Ariel's avatar
Ariel committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

- **`--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.

Ariel's avatar
Ariel committed
111
112
113
114
- **`--field`**, **`-f`** `<field>`

    Output only the specified field.

Ariel's avatar
Ariel committed
115
116
117
118
119
120
121
122
123
124
125
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
Ariel's avatar
Ariel committed
126
zen-oracle.exe query [subcommand]
Ariel's avatar
Ariel committed
127
128
```

Ariel's avatar
Ariel committed
129
or the abbreviation:
Ariel's avatar
Ariel committed
130
131

```bash
Ariel's avatar
Ariel committed
132
zen-oracle.exe q [subcommand]
Ariel's avatar
Ariel committed
133
134
135
136
137
138
139
140
```

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:

Ariel's avatar
Ariel committed
141
142
143
144
145
146
147
```bash
zen-oracle.exe query publickey
```

or the abbreviation:

```bash
Ariel's avatar
Ariel committed
148
149
150
151
152
zen-oracle.exe q p
```

### Committed Data

Ariel's avatar
Ariel committed
153
To get information about committed data by time bounds or key, run:
Ariel's avatar
Ariel committed
154

Ariel's avatar
Ariel committed
155
156
157
158
159
160
161
162
```bash
zen-oracle.exe query timebounds [--low <low>] [--high <high>] [--key <key>] [--skip <n>] [--take <n>] [count]
```

or the abbreviation:

```bash
zen-oracle.exe q t [--low <low>] [--high <high>] [--key <key>] [--skip <n>] [--take <n>] [count]
Ariel's avatar
Ariel committed
163
164
```

Ariel's avatar
Ariel committed
165
The `query timebounds`  command has the following flags:
Ariel's avatar
Ariel committed
166
167
168
169
170
171
172
173
174
175
176
177
178

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

    Lower time bound.

- **`--high`**, **`-h`** `<high>`

    Upper time bound.

- **`--key`**, **`-k`** `<key>`

    Key to search the value for.

Ariel's avatar
Ariel committed
179
180
181
182
183
184
185
186
187
188
189
190
191
- **`--skip`**, **`-s`** `<n>`

    Skip the first `<n>` items.

- **`--take`**, **`-t`** `<n>`

    Take only the first `<n>` 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 key within the given time bounds.
Ariel's avatar
Ariel committed
192
193
194
195
196

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.

Ariel's avatar
Ariel committed
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
To get information about committed values for a specific list of items, run:

```bash
zen-oracle.exe q k [--stdin] <filename>
```

The `query timekeyvalue`  command has a parameter `<filename>` and the following flags:

- **`--stdin`**, **`-i`**

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

This command takes a JSON file which is a list where each item has the following parameters:

- `**key**`

    The name of the item.

- `**low**`

    The earliest time for the item to appear.

- `**high**`

    The latest time for the item to appear (**optional** - if it's not given it's equal to `low`).

In return you'll get the same list where each item has it's committed value added to it in the `value` field, and items which weren't committed in the given time bounds are removed.

Ariel's avatar
Ariel committed
225
226
227
228
229
230
231
232
## 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>]
```

Ariel's avatar
Ariel committed
233
or the abbreviation:
Ariel's avatar
Ariel committed
234
235
236
237
238

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

Ariel's avatar
Ariel committed
239
The `audit` command has a parameter `<item>` and the following flags:
Ariel's avatar
Ariel committed
240
241
242
243
244
245
246
247
248
249
250
251
252

- **`--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.

Ariel's avatar
Ariel committed
253
For the `<item>` parameter use the name of a JSON file which contains items for which you want to get audit paths in the given commit.
Ariel's avatar
Ariel committed
254
255
256

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

Ariel's avatar
Ariel committed
257
```json
Ariel's avatar
Ariel committed
258
259
260
261
262
263
264
265
266
267
268
{ "APPL" : 10 , "ABCD" : 12 , "WXYZ" : 123 , "XYXY" : 6456 }
```

## Server

To run the server use the command:

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

Ariel's avatar
Ariel committed
269
or the abbreviation:
Ariel's avatar
Ariel committed
270
271
272
273
274
275
276

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

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

Ariel's avatar
Ariel committed
277
278
279
280
281
282
283
284
285
286
287
288
The `server` command supports the following flags:

- `**--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`)

Ariel's avatar
Ariel committed
289
290
291
292
293
294
The server has the following endpoints:

### `attest`

Use the `attest` endpoint to ask for an attestation message body.

Ariel's avatar
Ariel committed
295
This **GET** request has the following parameters:
Ariel's avatar
Ariel committed
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314

- **`root`**

    Root of the committed Merkle tree.

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

    Commit ID of the committed data.

- **`pk`**

    Public key of the recipient address.

- **`cid`**

    Contract ID of the recipient contract.

315
316
317
318
- **`address`**

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

Ariel's avatar
Ariel committed
319
320
321
322
323
324
325
326
You have to use either **`commit`** or both **`root`** and **`timestamp`**.

You can only have at most 1 recipient (either `**pk**` or `**cid**`).

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

### `query`

Ariel's avatar
Ariel committed
327
Use the `query` URI endpoint to check if a commitment is provided by the oracle service and get a list of items committed by the service.
Ariel's avatar
Ariel committed
328

Ariel's avatar
Ariel committed
329
This **GET** request has the following parameters:
Ariel's avatar
Ariel committed
330
331
332
333
334
335
336
337
338
339
340
341

- **`low`**

    Lower time bound.

- **`high`**

    Upper time bound.

- **`key`**

    Key to search the value for.
Ariel's avatar
Ariel committed
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387

- `**skip**`

    Skip the first `<n>` items.

- `**take` (mandatory)**

    Take only the first `<n>` items (after the skip if there is one).

### `count`

Use the `count` URI endpoint to get the number of items committed by the service.

This **GET** request has the following parameters:

- **`low`**

    Lower time bound.

- **`high`**

    Upper time bound.

- **`key`**

    Key to search the value for.

### `getValues`

Use the `getValues` URI endpoint to get the values of a list of items.

This **POST** request takes a JSON body which is a list where each item has the following parameters:

- `**key**`

    The name of the item.

- `**low**`

    The earliest time for the item to appear.

- `**high**`

    The latest time for the item to appear (**optional** - if it's not given it's equal to `low`).

In return you'll get the same list where each item has it's committed value added to it in the `value` field, and items which weren't committed in the given time bounds are removed.