Oracle: Call any API from a smart contract

Overview

An oracle is a midpoint that makes HTTP requests from contracts to off-chain endpoints. Unlike traditional oracle networks - midpoints allow developers to define arbitrarily complex requests with components such as parameters/headers defined on-chain, multistep authentication workflows, private off-chain data for keys, and cross-chain functionality.

We will create a contract to request a summary of any Wikipedia article. We will use the Startpoint Called source, the Make HTTP Request task, and the Transact to EVM Function task.

StartpointCalledSource:

1. Listens for the caller to send the title of a wikipedia article

2. Extracts the title and sends it to MakeHttpRequestTask

MakeHttpRequestTask:

1. Makes a request to the Wikimedia API

2. Extracts the summary from the HTTP response

3. Sends the summary to the TranasctToEvmFunctionTask

TransactToEvmFunctionTask:

1. Submits the summary via a transaction to an on-chain function defined by the developer

Midpoint

$ npm install -g midpoint-cli

$ midpoint init blank my-oracle

1 . StartpointCalledSource

$ midpoint add-source startpointCalledSource oracle-source

We define the Startpoint Called source so that contract can make a midpoint request.

{
    "startpointCalledSource": {
        "whitelist": [
            {
                "chainId": "5",
                "contractAddress": "0xDDb539E3c742f3DFA8eB3cf0f7122214f805B962"
            }
        ],
        "variables": [
            {
                "name": "article",
                "datatype": "string"
            }
        ],
        "extracts": [
            {
              "name": "Midpoint_ID",
              "from": "Midpoint_ID"
            },
            {
              "name": "Request_ID",
              "from": "Request_ID"
            }
        ]
    }
}

2. MakeHTTPRequestTask

$ midpoint add-task makeHttpRequest call-wikipedia

We define the Make HTTP Request Task to make the call to the Wikipedia endpoint.

{
    "makeHttpRequest": {
        "method": "GET",
        "urlRaw": "https://en.wikipedia.org/api/rest_v1/page/summary/{{article}}",
        "urlType": "raw",
        "extracts": [
            {
                "name": "wikipediaSummary",
                "from": "body.extract"
            }
        ]
    }
}

3. TransactToEVMFunction

$ midpoint add-task transactToEvmFunctionTestnet callback

We define the Transact to EVM FunctionTask to send the summary back to the contract.

{
   "transactToEvmFunctionTestnet":{
      "chainId":"5",
      "contractAddress":"0xDDb539E3c742f3DFA8eB3cf0f7122214f805B962",
      "functionName":"requestedWikipediaSummary",
      "arguments":[
         {
            "name":"midpointId",
            "datatype":"uint64",
            "value":"{{Midpoint_ID}}"
         },
         {
            "name":"requestId",
            "datatype":"uint64",
            "value":"{{Request_ID}}"
         },
         {
            "name":"wikipediaSummary",
            "datatype":"string",
            "value":"{{wikipediaSummary}}"
         }
      ]
   }
}

4. Define Path

We define our path file.

oracle-source => call-wikipedia
call-wikipedia => callback

5. Deploy Contract

/*
 * SPDX-License-Identifier: MIT
 * Midpoint Sample Storage Contract v3.0.0
 *
 * This is a contract generated at 2023-02-28 20:07:34 for testing requests to midpoint 160. 
 * This contract is intended to serve as a guide for interfacing with a midpoint and should not be used
 * as is in a production environment.
 * For more information on setting up a midpoint and using this contract see docs.midpointapi.com
 */

pragma solidity>=0.8.0;

interface IMidpoint {
    function callMidpoint(uint64 midpointId, bytes calldata _data) external returns(uint64 requestId);
}

contract TestMidpointOracleContract {
    // These events can be removed without impacting the functionality of your midpoint
    event RequestForWikipediaSummaryMade(string article);
    event WikipediaSummaryReceived(uint64 Request_ID, uint64 Midpoint_ID, string wikipedia_summary);
    
    // A verified startpoint for Goerli Testnet
    address constant startpointAddress = 0x795c5292b9630d473d568079b73850F29344403c;
    
    // A verified midpoint transact to EVM function EOA for Goerli Testnet
    address constant whitelistedCallbackAddress = 0xC0FFEE4a3A2D488B138d090b8112875B90b5e6D9;
    
    // The globally unique identifier for your midpoint
    uint64 constant midpointID = 160;
    
    // Mapping of Request ID to a flag that is checked when the request is satisfied
    // This can be removed without impacting the functionality of your midpoint
    mapping(uint64 => bool) public request_id_satisfied;
    
    // Mappings from Request ID to each of your results
    // This can be removed without impacting the functionality of your midpoint
    mapping(uint64 => string) public request_id_to_wikipedia_summary;
    
    /*
     * This function makes a call to your midpoint with On-Chain Variables specified as function inputs. 
     * 
     * Note that this is a public function and will allow any address or contract to call midpoint 160.
     * Configure your midpoint to permit calls from this contract when testing. Before using your midpoint
     * in a production environment, ensure that calls to 'callMidpoint' are protected.
     * Any call to 'callMidpoint' from a whitelisted contract will make a call to your midpoint;
     * there may be multiple places in this contract that call the midpoint or multiple midpoints called by the same contract.
     */ 

    function getWikipediaSummary(string memory article) public {
        // This packs together all of the On-Chain Variables for your midpoint into a single bytestring
        bytes memory args = abi.encodePacked(article, bytes1(0x00));
        
        // This makes the call to your midpoint
        uint64 requestId = IMidpoint(startpointAddress).callMidpoint(midpointID, args);

        // This logs that the call has been made, and can be removed without impacting your midpoint
        emit RequestForWikipediaSummaryMade(article);
        request_id_satisfied[requestId] = false;
    }
    
   /*
    * This function is the callback target specified in your midpoint callback definition. 
    * Note that the callback is placed in the same contract as the call to callMidpoint for simplicity when testing.
    * The callback does not need to be defined in the same contract as the request or live on the same chain.
    */

   function requestedWikipediaSummary(uint64 midpointId, uint64 requestId, string memory wikipediaSummary) public {
       // Only allow a verified callback address to submit information for your midpoint.
       require(tx.origin == whitelistedCallbackAddress, "Invalid callback address");
       // Only allow requests that came from your midpoint ID
       require(midpointID == midpointId, "Invalid Midpoint ID");
       
       // This stores each of your response variables. This is where you would place any logic associated with your callback.
       // Your midpoint can transact to a callback with arbitrary execution and gas cost.
       request_id_to_wikipedia_summary[requestId] = wikipediaSummary;
       
       // This logs that a response has been received, and can be removed without impacting your midpoint
       emit WikipediaSummaryReceived(requestId, midpointId, wikipediaSummary);
       request_id_satisfied[requestId] = true;
   }
}

6. Publish Midpoint

$ midpoint publish