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
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
sponsorWallet. 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
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
- 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
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).
# Derivation Path
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
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
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
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.
# Gas Costs
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.
# Trusting the
Designated Sponsor Wallets
Sponsors should not fund a
sponsorWallet with more then 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
command. The Airnode listens for withdrawal requests and fulfills them
automatically. Therefore, the sponsor should be able to receive their funds from
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
# 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
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.