Airnode is a first-party oracle that can push off-chain API data to an on-chain contract. While dApp developers will find dAPIs popular and the most useful aspect of an Airnode's capabilities, there is the option for developers to access Airnode data using its request-response protocol (RRP). The AirnodeRrpV0.sol➚ protocol contract facilitates RRP and is designed to be flexible and is meant to serve a variety of use cases. See the Airnode requester examples➚ for potential design patterns.
It starts with a requester
A requester is a smart contract that can trigger an Airnode RRP request. To do so, the requester needs to be sponsored and make the request using a matching sponsor wallet. See Requesters and Sponsors on how to sponsor a requester and derive the sponsor wallet.
A simplified understanding
In the diagram below, any typical smart contract is called a requester if it makes a request of Airnode's RRP protocol. It makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to the event logs. The off-chain Airnode then accesses the event logs, gets the API data and performs a callback to the requester.
In summary, the requester will do two things.
makeTemplateRequest()on the AirnodeRrpV0.sol contract, which returns a
- Add a
myFulfill()function (call it what you like) to your requester where the off-chain Airnode can send the requested data when ready. The data includes the same
requestIdas the one returned at the time of making the request.
In the diagram below a requester makes a request to the on-chain RRP protocol contract (AirnodeRrpV0.sol) that adds the request to its event logs. During its run cycle the off-chain Airnode accesses the event logs, gets the requested data from the the API provider, then performs a callback to the requester.
The requester (myContract.sol) makes a request to the RRP protocol contract (AirnodeRrpV0.sol) by calling
makeFullRequest()which adds the request to the event logs and returns a
requestIdto the requester.
Airnode retrieves the on-chain request from the event logs.
Airnode gathers response data from the API specified in the request.
Airnode performs a callback to a named function
myFulfill()in myContract.sol via the AirnodeRrpV0.sol function
fulfill()with the requested data and the
See the guide Making an RRP Request and learn how to make a RRP request of an Airnode.
A deeper dive
This section, through its detailed illustration, builds on the previous section (A simplified understanding) in an attempt to further illustrate and explain the mechanics of how an Airnode response to a request made by a requester.
Airnode RRP consists of two parts: the off-chain Airnode (a.k.a. "the node") deployed as self hosted or cloud provider functions (e.g., AWS) and the on-chain protocol contract AirnodeRrpV0.sol.
A requester makes a request to the AirnodeRrpV0 protocol contract which adds the
requestIdto storage, emits the request to the event logs and returns the
requestIdto the requester. The request is retrieved by the Airnode during its next run cycle. It then verifies the requester is authorized by checking authorizer contracts assigned to the Airnode.
If the request is authorized, Airnode proceeds to respond. It first gathers the requested data from the API and calls the
fulfill()function in AirnodeRrpV0, which removes the pending
requestIdfrom storage and makes a callback to
myFulfill(). The gas costs associated with the response are covered by the sponsor of the requester.