Oracle Process Flow

Creating Oracle request
An Oracle contract can be deployed on the Ontology network to send Oracle requests and fetch data from outside world and make it accessible to other smart contracts.
In the future, all the deployed Oracle contracts will be listed on the Oracle market
The sample Oracle contract that we will be looking at here fetches sports statistics, i.e., match details.
Let's say the address of an example Oracle contract is as follows:
Test net - e0d635c7eb2c5eaa7d2207756a4c03a89790934a
Main net - a6ee997b142b002d49670ab73803403b09a23fa0
The structure of the Oracle request is of the form:
httpGet
1
operation = "CreateOracleRequest"
2
request = """{
3
		"scheduler": {
4
			"type": "runAfter",
5
			"params": "2018-06-15 08:37:18"
6
		},
7
		"tasks": [
8
			{
9
			  "type": "httpGet",
10
			  "params": {
11
				"url": "https://bitstamp.net/api/ticker/"
12
			  }
13
			},
14
			{
15
				"type": "jsonParse",
16
				"params":
17
				{
18
					"data":
19
					[
20
						{
21
							"type": "String",
22
							"path": ["timestamp"]
23
						},
24
						{
25
							"type": "String",
26
							"path": ["last"]
27
						},
28
						{
29
							"type": "Float",
30
							"decimal": 100,
31
							"path": ["open"]
32
						}
33
					 ]
34
				}
35
			}
36
		]
37
	}"""
38
args = [request, address]
Copied!
The response is as follows:
1
{
2
	"high": "5610.00000000",
3
	"last": "5518.70",
4
	"timestamp": "1542359479",
5
	"bid": "5518.12",
6
	"vwap": "5436.78",
7
	"volume": "16423.18407040",
8
	"low": "5199.80000000",
9
	"ask": "5518.69",
10
	"open": 5571.12
11
}
Copied!
Parameters: url, URL of the GET request
JsonParse
JsonParse will parse the http response with the parameter path list as key. The result will then be serialized to form a data structure, as defined by the user, and then finally written in the Oracle contract.
Here is a list of the parameters:
Parameter
Description
data
Data structure defined by the user
type
Data type, support int, float(* decimal as int), string, array, map, struct
sub_type
Sub-type of the array, map and struct
decimal
decimal places of floating point value
path
Iterator list of JSON parse key, if data is json, write key in list, if data is array, write index as string in list
Here's a complex JsonParse example:
1
var request = """{
2
		"scheduler": {
3
			"type": "runAfter",
4
			"params": "2018-06-15 08:37:18"
5
		},
6
		"tasks": [
7
			{
8
			  "type": "httpGet",
9
			  "params": {
10
				"url": "http://data.nba.net/prod/v2/20181129/scoreboard.json"
11
			  }
12
			},
13
			{
14
				"type": "jsonParse",
15
				"params":
16
				{
17
					"data":
18
					[
19
						{
20
							"type": "Array",
21
							"path": ["games"],
22
							"sub_type":
23
							[
24
								{
25
									"type": "Struct",
26
									"sub_type":
27
									[
28
										{
29
											"type": "String",
30
											"path": ["gameId"]
31
										},
32
										{
33
											"type": "String",
34
											"path": ["vTeam", "teamId"]
35
										},
36
										{
37
											"type": "String",
38
											"path": ["vTeam", "score"]
39
										},
40
										{
41
											"type": "String",
42
											"path": ["hTeam", "teamId"]
43
										},
44
										{
45
											"type": "String",
46
											"path": ["hTeam", "score"]
47
										}
48
									]
49
								}
50
							]
51
						}
52
					]
53
				}
54
			}
55
		]
56
	}"""
Copied!
A part of the raw HTTP response is:
1
{
2
	"numGames": 3,
3
	"games": [{
4
			"gameId": "0021800316",
5
			"vTeam": {
6
				"teamId": "1610612744",
7
				"score": "128"
8
			},
9
			"hTeam": {
10
				"teamId": "1610612761",
11
				"score": "131"
12
			}
13
		},
14
		{
15
			"gameId": "0021800317",
16
			"vTeam": {
17
				"teamId": "2610612744",
18
				"score": "96"
19
			},
20
			"hTeam": {
21
				"teamId": "2610612761",
22
				"score": "131"
23
			}
24
		},
25
		{
26
			"gameId": "0021800318",
27
			"vTeam": {
28
				"teamId": "3610612744",
29
				"score": "128"
30
			},
31
			"hTeam": {
32
				"teamId": "3610612761",
33
				"score": "131"
34
			}
35
		}
36
	]
37
}
Copied!
Here, the raw HTTP response is parsed and then a structure is created based on the data structure, which is then serialized.
An application smart contract calls the Oracle contract to fetch the result and then deserializes it as follows:
1
[
2
    [
3
        ["0021800316", "1610612744", "128", "1610612761", "131"],
4
        ["0021800317", "2610612744", "128", "2610612761", "131"],
5
        ["0021800318", "3610612744", "128", "3610612761", "131"]
6
    ]
7
]
Copied!
Scheduler
This option is used to fix the time when a contract or task will be executed. It's format is as follows:
1
{
2
    "type": "",
3
    "params": "",
4
}
Copied!
Currently it only supports one execution method, runAfter. 
runAfter is used to specify a time when the task is to be run. For example, this can be used to send scores to the user after a game has ended. If the type field is left empty, the task will be run immediately. While the params field is used to specify the time in this format: YYYY-MM-DD HH:MM:SS
Example - "2018-06-15 08:37:18"
httpPost
The request format is as follows:
1
operation = "CreateOracleRequest"
2
request = """{
3
        "scheduler": {
4
            "type": "runAfter",
5
            "params": "2018-06-15 08:37:18"
6
        },
7
        "tasks":[
8
            {
9
              "type": "httpPost",
10
              "params": {
11
                "url": "https://api.random.org/json-rpc/1/invoke",
12
                "contentType": "application/json-rpc",
13
                "body": "{\\"jsonrpc\\": \\"2.0\\",\\"method\\": \\"generateSignedIntegers\\",\\"params\\": {\\"apiKey\\": \\"c7511065-c88d-4f28-af4f-293c91ad20d9\\",\\"n\\": 6,\\"min\\": 1,\\"max\\": 10,\\"replacement\\": false,\\"base\\": 10},\\"id\\": 1}"
14
              }
15
            },
16
            {
17
                "type": "jsonParse",
18
                "params":
19
                {
20
                    "data":
21
                    [
22
                        {
23
                            "type": "Array",
24
                            "path": ["result", "random", "data"],
25
                            "sub_type":
26
                                [
27
                                    {
28
                                        "type": "Int"
29
                                    }
30
                                ]
31
                        }
32
                    ]
33
                }
34
            }
35
        ]
36
    }"""
37
args = [request, address]
Copied!
The raw HTTP response is:
1
{
2
    "jsonrpc": "2.0",
3
    "result": {
4
        "random": {
5
            "method": "generateSignedIntegers",
6
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
7
            "n": 6,
8
            "min": 1,
9
            "max": 6,
10
            "replacement": true,
11
            "base": 10,
12
            "data": [
13
                2,
14
                4,
15
                4,
16
                1,
17
                5,
18
                3
19
            ],
20
            "completionTime": "2013-09-30 14:58:03Z",
21
            "serialNumber": 69260
22
        },
23
        "signature": "BxHxajeRg7Q+XGjBdFS1c7wkZbJgJlverfZ5TVDyzCKqo2K5A4pD+54EMqmysRYwkL3w2NS2DFLVrsyO1o96bW9BGp5zjjrEegz9mB+04iOTaRwmdQnLJAj/m3WRptA+qzodPCTaqud8YWBifqWCM34q98XwjX+nlahyHVHT9vf5KO0YVkD/yRI1WN5M/qX21chVvSxhWdmIrdCkrovGnysFq8SzCRNhpYx+/1P+YT2IKsH8jth9z82IAz1ANVh918H/UdpuD1dR7TD6nk3ntRgGrIiu2qqVzFi8A7/6viVgRqtffE4KVZY6O9mUJ+sGkF5Ohayms7LHSFy1VC8wMbMgwod+A8nr5yzjAC4SCUkT1bKAyWNF3SdVcLtvWdcf97Ew6RjohzCW4Vs3jUlh6jF/pj3b3++U3lBHCh43IIonw8MQ7afwpqP12yvyDym1isNjhMKYjmzWRerSvnsMyQIH8xFW7IHt2g/0qnzJgABFmUNBRKJPCD9CMgjh60sSwW7EyrGMy7/qisfE0IU74P/F7KCty/g1jIlXX5/O1lQjwY34wnoP0NXL08QteukRZZUfJQnscx1NGE+HX1c9bMBI8LC0ZFYFk+uY6ib/0rCV5OcLLE9PihCdC8WoI1x3bobr8tbtfgnXMTjogxwVXiiSN1TMnTIWlJ+KM5eSWrw=",
24
        "bitsUsed": 16,
25
        "bitsLeft": 932400,
26
        "requestsLeft": 199991,
27
        "advisoryDelay": 1000
28
    },
29
    "id": 1
30
}
Copied!
An application contract deserializes the result as follows:
1
[
2
    [
3
        2,
4
        4,
5
        4,
6
        1,
7
        5,
8
        3
9
    ]
10
]
Copied!
The HTTP post example above fetches a random number from random.org. This Ontology Oracle packages a more convenient method randomOrg to get a signed random number.
The request is as follows:
1
operation = "CreateOracleRequest"
2
request = """{
3
        "scheduler": {
4
            "type": "runAfter",
5
            "params": "2018-06-15 08:37:18"
6
        },
7
        "tasks": [
8
            {
9
              "type": "randomOrg",
10
              "params": {
11
                "method": "GenerateSignedIntegers",
12
                "n": 10,
13
                "min": 1,
14
                "max": 10,
15
                "replacement": false
16
              }
17
            },
18
            {
19
                "type": "jsonParse",
20
                "params":
21
                {
22
                    "data":
23
                    [
24
                        {
25
                            "type": "Array",
26
                            "path": ["data"],
27
                            "sub_type":
28
                                [
29
                                    {
30
                                        "type": "Int"
31
                                    }
32
                                ]
33
                        },
34
                        {
35
                            "type": "String",
36
                            "path": ["signature"]
37
                        }
38
                    ]
39
                }
40
            }
41
        ]
42
    }"""
43
args = [request, address]
Copied!
Here is the list of parameters:
Parameter
Description
n
Number of random numbers
min
Lower limit for random numbers
max
Upper limit for random numbers
replacement
true: random number can occur multiple times, false: numbers are unique
The response is:
1
type SignedIntegerData struct {
2
	Raw          json.RawMessage `json:"raw"`
3
	HashedApiKey string          `json:"hashedApiKey"`
4
	SerialNumber int             `json:"serialNumber"`
5
	Data         []int           `json:"data"`
6
	Signature    string          `json:"signature"`
7
}
Copied!
Unsigned random numbers can also be generated as follows:
1
operation = "{
2
        "scheduler": {
3
            "type": "runAfter",
4
            "params": "2018-06-15 08:37:18"
5
        },
6
        "tasks": [
7
            {
8
              "type": "randomOrg",
9
              "params": {
10
                "method": "GenerateIntegers",
11
                "n": 10,
12
                "min": 1,
13
                "max": 10,
14
                "replacement": false
15
              }
16
            },
17
            {
18
                "type": "jsonParse",
19
                "params":
20
                {
21
                    "data":
22
                    [
23
                        {
24
                            "type": "Array",
25
                            "path": ["data"],
26
                            "sub_type":
27
                                [
28
                                    {
29
                                        "type": "Int"
30
                                    }
31
                                ]
32
                        },
33
                        {
34
                            "type": "String",
35
                            "path": ["completionTime"]
36
                        }
37
                    ]
38
                }
39
            }
40
        ]
41
    }"""
42
args = [request, address]
Copied!
Parameter
Description
n
Number of random numbers
min
Lower limit for random numbers
max
Upper limit for random numbers
replacement
true: random number can occur multiple times, false: numbers are unique
The response is as follows:
1
type IntegerData struct {
2
	Data           []interface{} `json:"data"`
3
	CompletionTime string        `json:"completionTime"`
4
}
Copied!
Result of Oracle request
The transaction hash txhash can be used to fetch the result of the on-chain Oracle request. The request format is:
1
operation = "GetOracleOutcome"
2
args = txhash
Copied!
Sample Code
Please follow this link to refer to Oracle contract template.
Please follow this link to refer to an application contract that uses Oracle.
ONTOLOGY ELEMENTS - Previous
Ontology Oracle
Next - GUIDES & TUTORIALS
Development Guides
Last modified 2yr ago
Copy link
Contents
Creating Oracle request
Result of Oracle request
Sample Code