A sponsor is an entity (individual, business, etc.). Sponsors create relationships between requesters and sponsorWallets. They do so by sponsoring requesters and deriving sponsorWallets for Airnodes they want their requesters to call.
Making the relationship:
- A sponsor "sponsors" a requester.
- A sponsor "derives" a sponsorWallet for a desired Airnode.
Making a request.
- The now "sponsored" requester makes a request of an Airnode. Parameters passed to the Airnode include the
- The Airnode verifies that the sponsor of the requester is the sponsor that derived the
sponsorWalletassociated with the Airnode.
- The Airnode uses the respective sponsor's
sponsorWalletto fulfill the request, meaning that the sponsor covers the gas cost.
How a requester refers to the sponsor.
A requester can have multiple sponsors that have sponsored it. While making a request, the requester provides the
sponsorAddressthat it wants to have the request fulfilled by. The AirnodeRrpV0.sol protocol contract checks if the requester is sponsored, and if so, emits the request event.
Next Airnode derives the
sponsorWalletaddress using the provided
sponsorAddress, then checks if this matches the
sponsorWalletaddress provided in the request. Airnode will ignore the request if the two do not match. This is done this way because deriving the
sponsorWalletaddress from the
sponsorAddresson-chain is not feasible.
A sponsor is identified by a
sponsorAddress which is usually the default account
m/44'/60'/0'/0/0 of a BIP 44 wallet owned by the sponsor. The sponsor can use a different address from the wallet if desired such as
Note that a sponsor could use multiple addresses from multiple wallets. Below are some example reasons why one would want to have multiple
sponsorAddress identities on-chain:
- To keep separate
sponsorWalletsfor two separate use-cases for easier accounting.
- To duplicate transaction queues for a single use-case and increase response throughput.
Each Airnode can keep a unique
sponsorWallet for a sponsor. The wallet is identified by a
sponsorAddress/airnodeAddress pair. A sponsor must take action to derive a
sponsorWallet for a particular Airnode. Requesters, that have been sponsored by a sponsor, can specify their requests be fulfilled by the
sponsorWallet designated to the sponsor. This allows the sponsor to cover the gas cost of request fulfillments by the Airnode since the sponsor must send funds to this wallet before making the request.
Requests from the same
sponsorWallet are performed sequentially to respect the transaction nonce. A single Airnode run will only attempt to serve five oldest requests to prevent timeout issues. For high volatility use cases it is recommended to use multiple sponsors (and thus sponsor wallets) as the requests from different sponsor wallets are performed in parallel.
Wallet and Protocols
A sponsorWallet derived for a particular sponsor depends on the Airnode protocol (RRP, the forthcoming PSP protocol, etc.). This means that a sponsorWallet address derived for a particular sponsor will be different for each protocol. This is intentional and allows a particular sponsor to only fund a particular protocol (e.g. only RRP).
Each sponsor is identified by a
sponsorAddress, and their sponsor wallets are designated implicitly by a derivation path. For the RRP protocol the derivation path for a
sponsorWallet starts with
m/44'/60'/0'/1/.... Other branches will be used to derive the sponsor wallets for other protocols.
Understanding Derivation Paths
It is not important to understand derivation paths, you can simply use the addresses the admin CLI derives for you.
The general path for connecting to the base Ethereum set of addresses looks like this:
m/44’/60’/0’/0. This sequence is broken down into different sections and changes based on what is being worked with. The sequence goes:
m’ / purpose’ / coin_type’ / account’ / change / address_index. The
change part of the BIP44 derivation path is used to determine which protocol a sponsor wallet path will be for. Here (
m/44'/60'/0'/1/...) has been reserved for the RRP protocol where the value of
change is 1.
An Ethereum address is 20 bytes-long, which makes it 160 bits. Each index in the HD wallet non-hardened derivation path goes up to 2^31. This requires the division of these 160 bits into six 31 bit-long chunks, therefore derivation path for a sponsor wallet of a requester using the RRP protocol would be:
m/44'/60'/0'/1/... /1st least significant 31-bits of the sponsor address (sponsor && 0x7FFFFFFF)… /2nd least significant 31-bits of the sponsor address (sponsor >> 31 && 0x7FFFFFFF)… /3rd least significant 31-bits of the sponsor address (sponsor >> 62 && 0x7FFFFFFF)… /4th least significant 31-bits of the sponsor address (sponsor >> 93 && 0x7FFFFFFF)… /5th least significant 31-bits of the sponsor address (sponsor >> 124 && 0x7FFFFFFF)… /6th least significant 31-bits of the sponsor address (sponsor >> 155 && 0x7FFFFFFF)
Anyone can use the xpub that the Airnode has announced (through off-chain channels) and the sponsor's
sponsorAddress to derive a
sponsorWallet address for a specific Airnode–sponsor pair. In other words, a sponsor can calculate the address of their respective sponsor wallet for an Airnode and have requesters use it to make requests right away.
sponsorWallet scheme allows the sponsor to cover the fulfillment gas costs, it is just as easy to have the Airnode cover the gas costs. In this case the Airnode funds the
sponsorWallet, instead of the sponsor. Furthermore, this scheme allows hybrid use-cases where the Airnode covers the fulfillment gas costs for one sponsor (e.g., because they have made a special service agreement with them), while requiring others to cover their own fulfillment gas costs.
Designated Sponsor Wallets
Sponsors should not fund a
sponsorWallet with more than they can trust the Airnode with, as the Airnode controls the private key to the
sponsorWallet. The deployer of such Airnode undertakes no custody obligations, and the risk of loss or misuse of any excess funds sent to the
sponsorWallet remains with the sponsor.
The risk mentioned above becomes negligible when:
- The Airnode is a first-party oracle, because first-party oracles are trustworthy
- The Airnode is being used for a high value use-case, which already implies a high level of trust
If the sponsor does not trust the Airnode at all, they can fund the sponsor wallet just enough to cover a single fulfillment for each request to the Airnode. Therefore, this scheme both supports the traditional per-call payments, but also allows the protocol to leverage the trustworthiness of Airnodes to reduce unnecessary gas costs caused by microtransactions.
If the sponsor decides not to use a particular
sponsorWallet going forward, they can make a request to withdraw funds from it, see the request-withdrawal command. The Airnode listens for withdrawal requests and fulfills them automatically. Therefore, the sponsor should be able to receive their funds from their
sponsorWallet in a few minutes notice. The
sponsorWallet does not get deleted, and can be used in the future simply by funding it again.
Airnode will drop any pending API calls associated with a
sponsorWallet once a withdrawal is requested.
Sponsoring a Requester
A sponsor specifies the public address (
sponsorAddress) of an account from a mnemonic it owns and the on-chain
requesterAddress of a requester to "sponsor a requester". This sponsorship is know to have, and be defined by, a
This sponsorship allows the requester to use the sponsor's
sponsorWallet for a particular Airnode to cover gas costs incurred by the Airnode in response to a request. Learn more about sponsorships.
Use the Admin CLI tool to sponsor a requester. An example can be seem in the Requesters and Sponsors doc.
Derive a Sponsor Wallet
When a sponsor wishes to access an Airnode (via a requester) it must create a
sponsorWallet for the Airnode. Requesters that have been sponsored by the same sponsor, can specify their requests be fulfilled by the
sponsorWallet belonging to the sponsor. A sponsor uses a sponsorAddress and the xpub of a particular Airnode to derive a sponsorWallet for the Airnode. The sponsor must also provide the airnodeAddress because it will be used to verify that the provided
xpub belongs to the Airnode wallet before deriving a child sponsor wallet address.
Use the Admin CLI tool to derive a
sponsorWallet. An example can be seem in the Requesters and Sponsors doc.