navbar

Aerisweather WeatherData Oracle Docs

pragma solidity ^0.5.0;

import "./OracleAPI.sol";

/**
 * @title Example contract using WeatherData oracle
 * @author TruSource
 * @notice Example contract using WeatherData oracle
 * @dev Demonstrates usage of OracleAPI and building queryParams
 */
contract Example is OracleAPI {
    event LogResult(bytes32 queryId, Oracle.Oracle.Operations operationId, uint256 statusCode, string result);

    constructor(address resolverAddress) public OracleAPI (resolverAddress) public {}

    /**
     * @notice Make getAlerts query
     * @dev Make getAlerts query, queryId is returned to be used to handle query result
     */
    function getAlerts() external {
        Buffer.buffer memory optionalQueryParams = createBuffer();

        // Optional
        addString(optionalQueryParams, "p", "55403");

        trusource_getAlerts("closest", optionalQueryParams);
    }

    /**
     * @dev Handle query result using queryId, operationId and statusCode
     * @param queryId unique id for query
     * @param operationId id for operation
     * @param statusCode HTTP response status code
     * @param result query result
     */
    function trusource_callback(
        bytes32 queryId,
        Oracle.Oracle.Operations operationId,
        uint256 statusCode,
        string calldata result
    ) external checkAddress checkQueryId(queryId) {
        if (operationId == Oracle.Oracle.Operations.getAlerts) {
            emit LogResult(queryId, operationId, statusCode, result);
            return;
        }
    }
}

WeatherData have partnered with TruSource to provide users with data on the Ethereum blockchain. Users can access data from WeatherData endpoints detailed in these docs by signing up for WeatherData via the TruSource website.

Dependencies

Before starting ensure the following requirements are met.

Example Project

To start, clone the WeatherData example truffle project. Alternatively use the WeatherData truffle box, ensure you are in a new and empty directory and run the following

truffle unbox TruSource/Aerisweather-WeatherData

Looking at the project, the contract, Example.sol, demonstrates the usage of the operations exposed by the oracleAPI.sol. A reduced version of Example.sol is shown on the right, the getAlerts function uses the getAlerts operation by calling the trusource_getAlerts function defined in OracleAPI.sol.

Do it Yourself

When writing a contract that uses the WeatherData oracle, several important conditions have to be met.

Firstly, the contract should inherit the OracleAPI.

contract Example is OracleAPI

The constructor should accept a resolver address argument which is passed to the base contract using a OracleAPI modifier.

constructor(address resolverAddress) OracleAPI (resolverAddress) public {}

The contract must then implement a trusource_callback method.

function trusource_callback(bytes32 queryId, Oracle.Oracle.Operations operationId, uint256 statusCode, string calldata result) external checkAddress checkQueryId(queryId)

The implementation should use the checkAddress and checkQueryId(queryId) modifiers.

Callback Function

The trusource_callback method is called by TruSource, with the query return passed as one of the arguments.

trusource_callback(bytes32 queryId, Oracle.Oracle.Operations operationId, uint256 statusCode, string calldata result) external checkAddress checkQueryId(queryId)

Parameter Description
queryId Unique id to identify each query
operationId Unique id to identify each operation
statusCode HTTP status code
result API call response as string

Optional Query Parameters

/**
 * @notice Make getAlerts query
 * @dev Make getAlerts query, queryId is returned to be used to handle query result
 */
function getAlerts() external {
    Buffer.buffer memory optionalQueryParams = createBuffer();

    // Optional
    addString(optionalQueryParams, "p", "55403");

    trusource_getAlerts("closest", optionalQueryParams);
}

Some operations will allow for optional query parameters. Mutable byte buffers are used and query parameter keys and values are CBOR encoded using the solidity-cborutils library.

Use the addString or addUInt helpers to construct the query parameter buffer.

For example, lets assume the getAlerts operation allows optional query parameters. To construct the query parameters ?p=55403, first initialise a buffer variable.

Buffer.buffer memory queryParams = createBuffer();

Then add the keys and values.

addString(queryParams, "p", "55403");

Options String

An options string can be passed along with a call to every operation. The format of the string is as follows

identifier/options

The following identifiers are currently supported.

identifier Description
json Parse json response
fixedNum reformat floating point return as fixed number

Multiple options can be specified. For example, both response parsing and a fixed number response:

json/parse.json.response/fixedNum/4

Response Parsing

Example response

{
  "posts": [
    {
      "id": 1,
      "title": "hello",
      "rating": 4.75
    }
  ],
  "profile": {
    "name": "typicode"
  }
}

This is useful when an operation returns a json response and a single value is required in the contract. Take the example response on the right as an example.

Assuming the title of the first post is required, the option string would be constructed as

json/posts.0.title

Fixed point number response

Solidity does not yet support floating point numbers, fixed point number representations are commonly used instead within smart contracts. When constructing the string pass an integer to represent decimal multiplier.

For example, if the following options string was used for the example response (4.75)

json/posts.0.rating/fixedNum/2

The response would be "475". The parseInt can then be used to parse the string as a uint256.

Local Testing

The WeatherData example and any user projects using the WeatherData oracle can be tested locally with a local server that can mimic the TruSource servers that will fetch and respond with data to contracts running on local ganache blockchains.

  1. Start an Ethereum client. We will use ganache-cli.

    npx ganache-cli

    Note: the client needs to support WebSockets (do not use truffle develop for this reason).

    For other options, see Truffle - Choosing an Ethereum client.

  2. Migrate the smart contracts, in a 2nd terminal

    truffle migrate

  3. Start the TruSource local server. It will listen for events, fetch and return data to requesting contracts.

    npm start

  4. Using the provided Truffle script ./server/calls.js, call functions in Example.sol. This will execute a set of contracts calls, testing each operation with provided example arguments. In a 3rd terminal

    truffle exec server/calls.js

Authentication

The WeatherData operations require authentication, an .env-template file will be found at the root of the truffle project, rename this file to .env and populate the following environment variables

CLIENT_ID

CLIENT_SECRET

Sign up for the free tier of WeatherData API to acquire the credentials.

Network Testing

ropsten migrations

const yourContract = artifacts.require("yourContract");

module.exports = (deployer, network) => {
  if (network === "ropsten") {
    const resolverAddress = "0xad37cb4958440397809aa18c3530191b6a85b781";
    deployer.deploy(yourContract, resolverAddress);
  }
};
network Resolver Address Oracle Address
ropsten 0xad37cb4958440397809aa18c3530191b6a85b781 0x4570c56d5a90573c253954c3bbadd92d08918edf

The WeatherData oracle is currently deployed on the networks shown in the table.

To use the WeatherData oracle on a given network, you must deploy your contract and provide the resolver address as a constructor argument.

For all contract calls that make a call to the WeatherData oracle, Trusource will make a call to the trusource_callback function in your contract with the result.

The truffle migrations for ropsten is demonstrated.

To deploy your contract to a live network, update the migrations as shown, a do the following within the WeatherData truffle box:

  1. Uncomment line 4 to 12 in truffle-config.js.

  2. Set the SEED_PHRASE (mnemonic) and ETHEREUM_RPC_URL environment variables in .env.

  3. Migrate the contracts.

    truffle migrate --network <network-name>

  4. Whitelist the contract that will call the WeatherData API at trusource.io.

Operations

getAlerts

/**
 * @notice Make getAlerts query
 * @dev Make getAlerts query, queryId is returned to be used to handle query result
 */
function getAlerts() external {
    Buffer.buffer memory optionalQueryParams = createBuffer();

    // Optional
    addString(optionalQueryParams, "p", "55403");

    trusource_getAlerts("closest", optionalQueryParams);
}

OracleAPI Method

trusource_getAlerts(string memory action )

trusource_getAlerts(string memory action string memory options)

trusource_getAlerts(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getAlerts(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Operation Query Parameters

Optional query parameters need to be CBOR encoded and be passed as a bytes array. See optional query parameters for more details.

Parameter Required
p false

Options

An options string can be provided, see options string for more details.

getCountries

/**
 * @notice Make getCountries query
 * @dev Make getCountries query, queryId is returned to be used to handle query result
 */
function getCountries() external {
    trusource_getCountries("us");
}

OracleAPI Method

trusource_getCountries(string memory action )

trusource_getCountries(string memory action string memory options)

trusource_getCountries(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getCountries(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getForecasts

/**
 * @notice Make getForecasts query
 * @dev Make getForecasts query, queryId is returned to be used to handle query result
 */
function getForecasts() external {
    trusource_getForecasts("seattle,wa");
}

OracleAPI Method

trusource_getForecasts(string memory action )

trusource_getForecasts(string memory action string memory options)

trusource_getForecasts(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getForecasts(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getLightningSummary

/**
 * @notice Make getLightningSummary query
 * @dev Make getLightningSummary query, queryId is returned to be used to handle query result
 */
function getLightningSummary() external {
    trusource_getLightningSummary("atlanta,ga");
}

OracleAPI Method

trusource_getLightningSummary(string memory action )

trusource_getLightningSummary(string memory action string memory options)

trusource_getLightningSummary(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getLightningSummary(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getObservations

/**
 * @notice Make getObservations query
 * @dev Make getObservations query, queryId is returned to be used to handle query result
 */
function getObservations() external {
    trusource_getObservations("55403");
}

OracleAPI Method

trusource_getObservations(string memory action )

trusource_getObservations(string memory action string memory options)

trusource_getObservations(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getObservations(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getPhrasesSummary

/**
 * @notice Make getPhrasesSummary query
 * @dev Make getPhrasesSummary query, queryId is returned to be used to handle query result
 */
function getPhrasesSummary() external {
    trusource_getPhrasesSummary("toronto,canada");
}

OracleAPI Method

trusource_getPhrasesSummary(string memory action )

trusource_getPhrasesSummary(string memory action string memory options)

trusource_getPhrasesSummary(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getPhrasesSummary(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getPlacesPostalcodes

/**
 * @notice Make getPlacesPostalcodes query
 * @dev Make getPlacesPostalcodes query, queryId is returned to be used to handle query result
 */
function getPlacesPostalcodes() external {
    trusource_getPlacesPostalcodes("55403");
}

OracleAPI Method

trusource_getPlacesPostalcodes(string memory action )

trusource_getPlacesPostalcodes(string memory action string memory options)

trusource_getPlacesPostalcodes(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getPlacesPostalcodes(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getSunmoonMoonphases

/**
 * @notice Make getSunmoonMoonphases query
 * @dev Make getSunmoonMoonphases query, queryId is returned to be used to handle query result
 */
function getSunmoonMoonphases() external {
    trusource_getSunmoonMoonphases("minneapolis,mn");
}

OracleAPI Method

trusource_getSunmoonMoonphases(string memory action )

trusource_getSunmoonMoonphases(string memory action string memory options)

trusource_getSunmoonMoonphases(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getSunmoonMoonphases(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

getSunmoon

/**
 * @notice Make getSunmoon query
 * @dev Make getSunmoon query, queryId is returned to be used to handle query result
 */
function getSunmoon() external {
    trusource_getSunmoon("minneapolis,mn");
}

OracleAPI Method

trusource_getSunmoon(string memory action )

trusource_getSunmoon(string memory action string memory options)

trusource_getSunmoon(string memory action Buffer.buffer memory optionalQueryParams)

trusource_getSunmoon(string memory action Buffer.buffer memory optionalQueryParams, string memory options)

Operation Path Parameters

Parameter
action

Options

An options string can be provided, see options string for more details.

OracleAPI

Helper functions enabling the use of optional query parameters for some operations and response parsing are provided.

addInt

CBOR encode a string key and uint value pair and add to buffer.

addUint(Buffer.buffer memory param, string memory key, string memory value)

Parameter Description
param buffer object to which the encoded key and value will be added to
key query parameter key of type string
value query parameter value of type uint

addString

CBOR encode a string key and string value pair and add to buffer.

addString(Buffer.buffer memory param, string memory key, string memory value)

Parameter Description
param buffer object to which the encoded key and value will be added to
key query parameter key of type string
value query parameter value of type string

parseInt

Parse a the string response within trusource_callback as uint256.

parseInt(string memory str)

Parameter Description
str string representation of uint

createBuffer

Initialises and returns buffer set to defaultBufferSize of 256.

createBuffer()