NAV Navbar

Rhombus API Reference

Rhombus divides oracles into two broad buckets: how the oracle is activated and how the oracle replies. Our API for running oracles has predictable, resource-oriented functions.

Activation Methods

Periodic oracles

When a contract needs regularly updated information, a periodic Rhombus oracle is often the best solution. The oracle checks the data sources at regular intervals and updates the on-chain information whenever significant changes to that information have occurred.

Asynchronous oracles

A contract may require information on an ad-hoc basis. A client would initiate these requests from their smart contract. A request may contain a number of parameters but should also contain a Unique ID (UID) tied to their oracle. Additionally, a nonce may be supplied to ensure that replies match requests.

Reply Methods

Lighthouse contract

Rhombus has a pre-written contract that we can deploy to decouple your oracle from your contract. They are fast to deploy and easily observed before committing to integrating the data.

Features of a lighthouse contract

Direct delivery

Code Example

The gold spot price must be written directly to the gold exchange contract

function setSpotPrice(uint spotPrice, uint nonce);

setSpotPrice function signature is specified prior to delivery so the Rhombus oracle can call it properly.

Where the Rhombus oracle is the sole information provider, it may be more efficient to write directly to your contract. The oracle can provide one or more data items as well as a nonce which helps serialize replies.

Getting Started

Below we'll demonstrate sample integrations with both Direct and Lighthouse delivery oracles.

Direct Delivery

pragma solidity ^0.4.24;

import "";

contract FundRaiser is RhombusClient {

    struct Donation {
        address donor;
        uint    amountInUSD;

    Donation[] public donations;
    address public constant alice =  0x31EFd75bc0b5fbafc6015Bd50590f4fDab6a3F22;

    event Raised(address donor, uint USDraised);

    // On receiving a donation (in ether), we ask the Rhombus ETH to USD oracle
    // to convert the amount but forward the amount to our favourite charity,
    // Alice's Food Kitchen.

    function () public payable {
        if (msg.value == 0)
        Donation memory thisDonation;
        thisDonation.donor = msg.sender;
        uint pos = donations.push(thisDonation);
        emitDoubleUint(0, pos-1, msg.value);

    // On receiving the USD value, the donation amount is updated and an event
    // emitted. This function can only be called with valid, unused nonces.

    function postUSDvalue(uint index, uint USDvalue) public onlyRhombus {
        require(index < donations.length, "Invalid Index");
        Donation storage d = donations[index];
        require(d.amountInUSD == 0, "Record already updated");
        d.amountInUSD = USDvalue;
        emit Raised(d.donor, d.amountInUSD);


Alice's food kitchen has fallen on hard times so she launches a fundraiser on the ethereum blockchain.

Alice want's to thank each participant for their donation not in ETH terms but in USD terms. Rhombus, sympathetic to her needs, has agreed to provide an ETH/USD oracle.

On receiving a donation, the donor's address is logged and the oracle is asked to convert the eth value to USD. The donation is forwarded to Alice.

The oracle executes a direct reply to the contract's postUSDvalue function which causes the donations log to be updated and a Raised event to be emitted which Alice can monitor to publish a thank you note.

Lighthouse Delivery

pragma solidity ^0.4.24;

import "";

contract TenCentsAMinute {

    ILighthouse  public myLighthouse;
    mapping(address => uint) public balances;
    mapping(address => uint) public expiry;
    uint public spentFees;
    address public constant alice =  0x31EFd75bc0b5fbafc6015Bd50590f4fDab6a3F22;

    constructor(ILighthouse _myLighthouse) public {
        myLighthouse = _myLighthouse;

    function() public payable {
        balances[msg.sender] += msg.value;

    function buyTime(uint minutesToBuy) public {
        require(minutesToBuy != 0, "nothing to buy");
        uint tenCentsOfETH;
        bool ok;
        (tenCentsOfETH,ok) = myLighthouse.peekData();
        uint fee = tenCentsOfETH * minutesToBuy;
        require(fee / minutesToBuy == tenCentsOfETH,"Overflow");
        require(fee < balances[msg.sender],"Not enough funds");
        expiry[msg.sender] = now + minutesToBuy * 1 minutes;
        spentFees += fee;

    function inPaidTime() public view returns (bool) {
        return now < expiry[msg.sender];

    function withdrawFees() public {
        require(alice == msg.sender, "Unauthorised");
        spentFees = 0;

Alice's petting zoo also operates a video feed service that allows you to watch videos of the animals for a nominal fee of ten cents a minute.

Since Alice is an ethereum fan, she controls the payments using an ethereum smart contract but that means she gets payments in ether not cents.

Rhombus, well known supporters of petting zoos worldwide, agree to provide a lighthouse supplying regularly updated data for the value of ten cents in eth.

The contract that Alice wrote provides a function inPaidTime() that can be called by the camera's streaming code to query whether the user has paid for their video time.