SKALE Connect

SKALE Connect allows developers to access any external data source using the decentralized power of your SKALE Chain. If your dApp needs market data, weather temperatures, or Ethereum data, SKALE Connect provides a simple way to deliver this data to your Dapp.

Theory

Recipe Not ready yet but is coming very soon!

Features

• JSON RPC Request: With simple JSON-RPC request it’s possible to get outside information on-chain

• Provable Security: The data requested dat aapproval relies on the distributed nodes of the chain where each signs the result with it’s ECDSA key.

• Free of charge: It has no cost for the SKALE developers.

• Chains: This tool can be used on all SKALE Chains.

Quickstart

1. Run the following command to clone the SKALE Connect example:

   git clone https://github.com/TheGreatAxios/skale-oracle-example-js

2. Install the dependencies:

   npm install

3. Run the codebse:

   node ./index.js

4. Oracle Contracts deployed on Testnet hubs:

   Chain Name	Oracle Contract Address
   Calypso Testnet	0x3aBF627F8450242376331c0752d19c9c6F01CB88
   Europa Testnet	0x3ac975ec90aD45D52B8A9599cB7910689772593C
   Nebula Testnet	0x476a3F651d724472346bA4D6389665abC4921537
   Titan Testnet	0xC0007F195B7c49b40C6166a78B2C81Fee8f7593E

Theory

1. A client submits a JSON RPC oracle_submitRequest GET or POST request to the SKALE chain containing the request specification.

2. The SKALE daemon (skaled) distributes the request to all other nodes in the SKALE Chain and the client is presented with a receipt.

3. Each of the 16 SKALE nodes performs the request, retrieves the data, and signs the result with it’s ECDSA key.

4. The Oracle result is returned when $t+1$ nodes sign the same result, where $t$ is the maximum number of untruthful nodes. On SKALE Chains $t$ is $n\left(\frac{1}{3}\right)$.

Oracle Methods

• oracle_submitRequest (http(s))
• oracle_submitRequest (eth)
• oracle_checkResult

Supported Geth Endpoints

Besides any http/https endpoint, the Oracle supports the following Geth JSON RPC endpoint for retrieving Ethereum network data:

• eth://eth_call

JSON RPC API Reference

oracle_submitRequest (http(s))

Submits an Oracle request and returns a message receipt.

Parameters:

• cid: <uint64> - chain ID
• uri: <string> - Oracle http|https endpoint. Must begin with http:// or https://.
• time: <uint64>- Linux time of request in ms
• jsps: <array> - list of JSON pointer to the data elements to be picked from the server response. The array must have 1 - 32 elements.
• encoding: <string> - the only supported encoding is json.
• (optional) trims: <uint64> - an array of trim values used to trim endings of strings in the Oracle result. If trims array is provided, it must provide trim values for each JSON pointer requested.
• (optional) post: <string> - if provided, the Oracle will use POST instead of GET (default). The value will be posted to the endpoint.
• pow: <string> - uint64 proof of work used to protect against DoS attacks.

Developer Note

• The maximum size of a uri and jsps parameter is 1024 bytes each.
• pow must be the last parameter.

Results:

The result will be an RpcResponse JSON object with result equal to:

• <string> - a message receipt used to check later if the result is ready

Example:

// GET Request
{"cid": 1, "uri": "http://worldtimeapi.org/api/timezone/Europe/Kiev","jsps":["/unixtime", "/day_of_year", "/xxx"],"trims":[1,1,1],"time":9234567,"encoding":"json","pow":53458}

// POST Request
{"cid": 1, "uri": "https://reqres.in/api/users", "jsps":["/id"],"time":9234567,"post":"some data","encoding":"json","pow":1735}

oracle_submitRequest (eth)

Submits an Oracle request to an Ethereum API and returns a message receipt.

Developer Note

Currently only eth_call is supported.

Parameters:

• cid: <uint64> - chain ID
• uri: <string> - Oracle geth endpoint. Must begin with eth://.
• time: <uint64>- Linux time of request in ms
• ethApi: <string> - value of eth_call.
• params: <string> - params to eth_call.
• encoding: <string> - the only supported encoding is json.
• pow: <string> - uint64 proof of work used to protect against DoS attacks.

Developer Note

• The maximum size of a uri is 1024 bytes each.
• params is a json array of two elements: the first is an object consisting of from, to, data, gas. The second is a string blocknumber which can be latest for a hex string. For example:

"params":[{"to":"0x5FbDB2315678afecb367f032d93F642f64180aa3",
"from":"0x9876543210987654321098765432109876543210",
"data":"0x893d20e8", "gas":0x100000},"latest"]

• pow must be the last parameter.

Example:

// eth_call Request
{"cid":1,"uri":"https://mygeth.com:1234","ethApi":"eth_call","params":[{"from":"0x9876543210987654321098765432109876543210","to":"0x5FbDB2315678afecb367f032d93F642f64180aa3","data":"0x893d20e8","gas":"0x100000"},"latest"],"encoding":"json","time":1681494451895,"pow":61535}

oracle_checkResult

Checks whether an Oracle result has been derived. By default the result is signed by $t+1$ nodes, where $t$ is the maximum number of untruthful nodes. Each node signs using its ETH wallet ECDSA key.

If no result has been derived, ORACLE_RESULT_NOT_READY is returned. Otherwise an error is returned.

The client is supposed to wait 1 second and try again.

Parameters:

• receipt: <string> - message receipt, returned by a call to oracle_submitRequest

Results:

The result repeats JSON elements from the corresponding Oracle request, plus includes a set of additional elements:

• rslts: <array>- string results
• sigs : <array>- ECDSA signatures where $t$ signatures are not null.

Example:

// Response
{"cid":1, "uri":"http://worldtimeapi.org/api/timezone/Europe/Kiev","jsps":["/unixtime", "/day_of_year", "/xxx"],"trims":[1,1,1],"time":1642521456593, "encoding":"json","rslts":["164252145","1",null],"sigs":["6d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","7d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","8d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","9d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","1050daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","6d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f",null,null,null,null,null,null,null,null,null,null]}

// Response
{"cid":1,"uri":"https://mygeth.com:1234",,"ethApi":"eth_call","params":[{ "from":"0x9876543210987654321098765432109876543210","to":"0x5FbDB2315678afecb367f032d93F642f64180aa3","data":"0x893d20e8","gas":"0x100000"},"latest"],"encoding":"json","time":1681494451895, "rslts":["0x000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266"],"sigs"["6d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","7d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","8d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","9d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","1050daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f","6d50daf908d97d947fdcd387ed4bdc76149b11766f455b31c86d5734f4422c8f",null,null,null,null,null,null,null,null,null,null]}

 ORACLE_SUCCESS  0
 ORACLE_UNKNOWN_RECEIPT  1
 ORACLE_TIMEOUT 2
 ORACLE_NO_CONSENSUS  3
 ORACLE_UNKNOWN_ERROR  4
 ORACLE_RESULT_NOT_READY 5
 ORACLE_DUPLICATE_REQUEST 6
 ORACLE_COULD_NOT_CONNECT_TO_ENDPOINT 7
 ORACLE_ENDPOINT_JSON_RESPONSE_COULD_NOT_BE_PARSED 8
 ORACLE_INTERNAL_SERVER_ERROR 9
 ORACLE_INVALID_JSON_REQUEST 10
 ORACLE_TIME_IN_REQUEST_SPEC_TOO_OLD 11
 ORACLE_TIME_IN_REQUEST_SPEC_IN_THE_FUTURE 11
 ORACLE_INVALID_CHAIN_ID 12
 ORACLE_REQUEST_TOO_LARGE 13
 ORACLE_RESULT_TOO_LARGE 14
 ORACLE_ETH_METHOD_NOT_SUPPORTED 15
 ORACLE_URI_TOO_SHORT 16
 ORACLE_URI_TOO_LONG 17
 ORACLE_UNKNOWN_ENCODING 18
 ORACLE_INVALID_URI_START 19
 ORACLE_INVALID_URI 20
 ORACLE_USERNAME_IN_URI 21
 ORACLE_PASSWORD_IN_URI 22
 ORACLE_IP_ADDRESS_IN_URI 23
 ORACLE_UNPARSABLE_SPEC 24
 ORACLE_NO_CHAIN_ID_IN_SPEC 25
 ORACLE_NON_UINT64_CHAIN_ID_IN_SPEC 26
 ORACLE_NO_URI_IN_SPEC 27
 ORACLE_NON_STRING_URI_IN_SPEC 28
 ORACLE_NO_ENCODING_IN_SPEC 29
 ORACLE_NON_STRING_ENCODING_IN_SPEC 30
 ORACLE_TIME_IN_SPEC_NO_UINT64 31
 ORACLE_POW_IN_SPEC_NO_UINT64 32
 ORACLE_POW_DID_NOT_VERIFY 33
 ORACLE_ETH_API_NOT_STRING 34
 ORACLE_ETH_API_NOT_PROVIDED 35
 ORACLE_JSPS_NOT_PROVIDED  36
 ORACLE_JSPS_NOT_ARRAY  37
 ORACLE_JSPS_EMPTY  38
 ORACLE_TOO_MANY_JSPS  39
 ORACLE_JSP_TOO_LONG  40
 ORACLE_JSP_NOT_STRING  41
 ORACLE_TRIMS_ITEM_NOT_STRING  42
 ORACLE_JSPS_TRIMS_SIZE_NOT_EQUAL 43
 ORACLE_POST_NOT_STRING 44
 ORACLE_POST_STRING_TOO_LARGE 45
 ORACLE_NO_PARAMS_ETH_CALL 46
 ORACLE_PARAMS_ARRAY_INCORRECT_SIZE 47
 ORACLE_PARAMS_ARRAY_FIRST_ELEMENT_NOT_OBJECT 48
 ORACLE_PARAMS_INVALID_FROM_ADDRESS 49
 ORACLE_PARAMS_INVALID_TO_ADDRESS 50
 ORACLE_PARAMS_ARRAY_INCORRECT_COUNT 51
 ORACLE_BLOCK_NUMBER_NOT_STRING 52
 ORACLE_INVALID_BLOCK_NUMBER 53
 ORACLE_MISSING_FIELD 54
 ORACLE_INVALID_FIELD 55
 ORACLE_EMPTY_JSON_RESPONSE 56
 ORACLE_COULD_NOT_PROCESS_JSPS_IN_JSON_RESPONSE 57
 ORACLE_NO_TIME_IN_SPEC 58
 ORACLE_NO_POW_IN_SPEC 59
 ORACLE_HSPS_TRIMS_SIZE_NOT_EQUAL 60
 ORACLE_PARAMS_NO_ARRAY 61
 ORACLE_PARAMS_GAS_NOT_UINT64 62