Round based datafeed oracles on Algorand

Abstract

The following document introduces conventions for building round based datafeed oracles on Algorand using the ABI defined in ARC-4

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.

Comments like this are non-normative.

An ARC-21 oracle MUST have an associated smart-contract implementaing the ABI interface described below.

ABI Interface

Round based datafeed oracles allow smart-contracts to get data with relevancy to a specific block number, for example the ALGO price at a specific round.

The associated smart contract MUST implement the following ABI interface:

1
{
2
  "name": "ARC_0021",
3
  "desc": "Interface for a round based datafeed oracle",
4
  "methods": [
5
    {
6
      "name": "get",
7
      "desc": "Get data from the oracle for a specific round",
8
      "args": [
9
        { "type": "uint64", "name": "round", "desc": "The desired round" },
10
        { "type": "byte[]", "name": "user_data", "desc": "Optional: Extra data provided by the user. Pass an empty slice if not used." }
11
      ],
12
      "returns": { "type": "byte[]", "desc": "The oracle's response. If the data doesn't exist, the response is an empty slice." }
13
    },
14
    {
15
      "name": "must_get",
16
      "desc": "Get data from the oracle for a specific round. Panics if the data doesn't exist.",
17
      "args": [
18
        { "type": "uint64", "name": "round", "desc": "The desired round" },
19
        { "type": "byte[]", "name": "user_data", "desc": "Optional: Extra data provided by the user. Pass an empty slice if not used." }
20
      ],
21
      "returns": { "type": "byte[]", "desc": "The oracle's response" }
22
    },
23
    /** Optional */
24
    {
25
      "name": "get_closest",
26
      "desc": "Get data from the oracle closest to a specified round by searching over past rounds.",
27
      "args": [
28
        { "type": "uint64", "name": "round", "desc": "The desired round" },
29
        { "type": "uint64", "name": "search_span", "desc": "Threshold for number of rounds in the past to search on." }
30
        { "type": "byte[]", "name": "user_data", "desc": "Optional: Extra data provided by the user. Pass an empty slice if not used." }
31
      ],
32
      "returns": { "type": "(uint64,byte[])", "desc": "The closest round and the oracle's response for that round. If the data doesn't exist, the round is set to 0 and the response is an empty slice." }
33
    },
34
    /** Optional */
35
    {
36
      "name": "must_get_closest",
37
      "desc": "Get data from the oracle closest to a specified round by searching over past rounds. Panics if no data is found within the specified range.",
38
      "args": [
39
        { "type": "uint64", "name": "round", "desc": "The desired round" },
40
        { "type": "uint64", "name": "search_span", "desc": "Threshold for number of rounds in the past to search on." }
41
        { "type": "byte[]", "name": "user_data", "desc": "Optional: Extra data provided by the user. Pass an empty slice if not used." }
42
      ],
43
      "returns": { "type": "(uint64,byte[])", "desc": "The closest round and the oracle's response for that round." }
44
    }
45
  ]
46
}

Method boundaries

All of get, must_get, get_closest and must_get_closest functions MUST NOT use local state.
Optional arguments of type byte[] that are not used are expected to be passed as an empty byte slice.

Rationale

The goal of these conventions is to make it easier for smart-contracts to interact with off-chain data sources.

Security Considerations

None.