Overview
Automatically top-up your VRF subscription balances using Chainlink Automation to ensure there is sufficient funding for requests. View the code on GitHub.
Objective
This example shows how to automate the process for funding VRF subscription balances. You will deploy and test a VRF subscription balance manager contract that monitors multiple subscriptions and tops them up with LINK as necessary. You can set up this contract to monitor existing VRF subscriptions. Alternatively, you will create two VRF subscriptions for testing: one that is underfunded, and another that is adequately funded. When you test the subscription balance manager contract, it only tops up the underfunded subscription.
Before you begin
Before you start this tutorial, complete the following items:
- If you are new to smart contract development, learn how to Deploy Your First Smart Contract.
- Install and configure a cryptocurrency wallet like MetaMask.
- Get Sepolia testnet LINK and ETH from faucets.chain.link.
- Gather the subscription IDs for any existing VRF subscriptions you would like to monitor. If you do not have any VRF subscriptions, you will create two for demo purposes in this tutorial.
Steps to implement
This tutorial requires you to set up the following components in VRF before you use Automation to monitor VRF subscriptions:
- Create VRF subscriptions to monitor, if you don't already have any
- Deploy VRF-compatible contracts
If you already have existing VRF subscriptions you would like to monitor, skip to the next step.
1 Create VRF subscriptions to monitor
If you don't already have existing VRF subscriptions you would like to monitor, create two VRF subscriptions for demo purposes. One subscription will be adequately funded, and the other subscription will be underfunded intentionally so that the subscription balance monitor contract can fund it.
-
Open the VRF Subscription Manager, and connect your wallet.
-
Create two subscriptions:
- Fund one subscription with 12 testnet LINK to serve as the adequately funded VRF subscription
- Fund the other subscription with 1 testnet LINK to serve as the underfunded VRF subscription
2 Deploy VRF-compatible contracts as consumers
In this section, you will deploy the same VRF contract twice. Each deployed contract will serve as a consuming contract for one of your VRF subscriptions.
-
Deploy this VRF-compatible contract for your VRF subscription:
This
VRFD20.sol
contract uses VRF to randomly assign you a Game of Thrones house. The VRF coordinator address and key hash values are hardcoded in this contract for Sepolia. If you want to use a different testnet, you must update those values before deploying the contract. -
Under the Solidity compiler tab, compile the contract.
-
Under the Deploy and run transactions tab, select Injected Provider - MetaMask for the Environment field. Make sure the
VRFD20.sol
contract is selected in the Contract field. -
Deploy the contract, passing in the subscription ID of your adequately funded subscription.
-
After the contract is deployed successfully, copy the contract address from Remix. Navigate back to the VRF Subscription Manager and add the contract address as a consumer for your adequately funded subscription.
-
Navigate back to Remix to deploy the contract once more. Change the subscription ID to the subscription ID of your intentionally underfunded subscription, and click Deploy.
-
Once more, after the contract is deployed successfully, copy the second contract address from Remix. Navigate back to the VRF Subscription Manager and add this second contract address as a consumer for your intentionally underfunded subscription.
3 Deploy the subscription balance monitor contract
In this section, you will deploy the subscription balance monitor contract, using the same address that is the admin owner for both of your VRF subscriptions. The contract will monitor any VRF subscriptions owned by this address, and fund any underfunded subscriptions using funds owned by this address.
Get required inputs for the balance monitor contract
The constructor for this contract requires the following information for the supported network that you want to deploy on:
- The LINK token address, which is found on the LINK token contracts page.
- The Automation registry address, which is found on the Automation supported networks page.
- The VRF coordinator address, which is found on the VRF Subscription Supported Networks page.
- Minimum wait period, which you can use to add buffer time between funding multiple subscription IDs. For demo purposes, you will monitor only two VRF subscriptions, so you can set this value to
60
seconds.
For Sepolia, these values are all consolidated here:
Item | Value |
---|---|
LINK token address | 0x779877A7B0D9E8603169DdbD7836e478b4624789 |
VRF Coordinator | 0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625 |
-
Open the
VRFSubscriptionBalanceMonitor.sol
contract in Remix. -
Under the Solidity compiler tab, compile the contract.
-
Under the Deploy and run transactions tab, select Injected Provider - MetaMask for the Environment field.
-
Expand the Deploy field and enter the values for Sepolia:
Item Value LINKTOKENADDRESS
0x779877A7B0D9E8603169DdbD7836e478b4624789
COORDINATORADDRESS
0x8103B0A8A00be2DDC778e6e7eaa21791Cd364625
MINWAITPERIODSECONDS
60
-
Click Deploy. MetaMask opens and prompts you to confirm the contract deployment transaction.
-
Copy the address of your newly deployed contract. You can find this in Sepolia Etherscan through the contract deployment transaction, or in Remix in the Deployed Contracts section.
4 Register the subscription balance monitor contract on Automation
In this section, you will register an upkeep on Chainlink Automation to run the subscription balance monitor contract. This enables Automation to check whether you have any underfunded VRF subscriptions, and if so, top up their balances appropriately.
Register an upkeep
Registering an upkeep on Chainlink Automation creates a smart contract that will run your VRF subscription balance monitor contract.
-
Click Register new Upkeep.
-
Select the Custom logic trigger option.
-
Copy your contract address from Remix and paste it into the Target contract address field.
-
Specify a name for your upkeep and set a Starting balance of 5 LINK for this demo. Leave the other settings at their default values.
-
Go to the Upkeep details page and copy your Forwarder address.
-
Navigate back to Remix and find the
setForwarderAddress
function. Paste your forwarder address and click click transact to run the function. MetaMask asks you to confirm the transaction.
Now that you've registered the upkeep and configured your contract with your new upkeep's forwarder address, Chainlink Automation handles the rest of the process.
5 Configure the subscription watch list
Before your contract will fund a subscription, you must set the watchList
address array with minBalancesJuels
and topUpAmountsJuels
variables. For demonstration purposes, you configure your own wallet as the top-up address. This makes it easy to see the ETH being sent as part of the automated top-up function. After you complete this tutorial, you can configure any wallet or contract address that you want to keep funded.
-
In the list of functions for your deployed contract, run the
setWatchList
function. This function requires ansubscriptionIds
array, aminBalancesJuels
array that maps to the subscriptions, and atopUpAmountsJuels
array that also maps to the subscriptions. In Remix, arrays require brackets and quotes around integer values. For this example, set the following values:- subscriptionIds:
["SUB_ID_1", "SUB_ID_2"]
- minBalancesJuels:
["2000000000000000000", "2000000000000000000"]
- topUpAmountsJuels:
["10000000000000000", "10000000000000000"]
These values tell the top up contract to top up the specified address with 0.01 LINK if the address balance is less than 2 LINK. These settings are intended to demonstrate the example using testnet faucet funds. For a production application, you might set more reasonable values that top up a smart contract with 10 LINK if the balance is less than 1 LINK.
- subscriptionIds:
-
After you configure the function values, click transact to run the function. MetaMask asks you to confirm the transaction.
-
In the functions list, click the
getWatchList
function to confirm your settings are correct.
Examine the code
This section explains how the VRFSubscriptionBalanceMonitor.sol
contract tracks your VRF subscriptions and uses Chainlink Automation to fund your underfunded subscriptions. You can view the code for the full contract on GitHub.
Tracking subscriptions
The VRFSubscriptionBalanceMonitor.sol
contract tracks your VRF subscriptions by creating a watchlist and storing attributes of each subscription required to monitor when they need funding.
The setWatchList()
function creates the watchlist of subscriptions, validates it, and then sets a Target
for each subscription. The Target
struct helps track whether a subscription is active, its minimum balance, when it was last funded, and the amount of LINK (in juels) to send to the subscription each time it is topped up.
struct Target {
bool isActive;
uint96 minBalanceJuels;
uint96 topUpAmountJuels;
uint56 lastTopUpTimestamp;
}
...
/**
* @notice Sets the list of subscriptions to watch and their funding parameters.
* @param subscriptionIds the list of subscription ids to watch
* @param minBalancesJuels the minimum balances for each subscription
* @param topUpAmountsJuels the amount to top up each subscription
*/
function setWatchList(
uint64[] calldata subscriptionIds,
uint96[] calldata minBalancesJuels,
uint96[] calldata topUpAmountsJuels
) external onlyOwner {
if (subscriptionIds.length != minBalancesJuels.length || subscriptionIds.length != topUpAmountsJuels.length) {
revert InvalidWatchList();
}
uint64[] memory oldWatchList = s_watchList;
for (uint256 idx = 0; idx < oldWatchList.length; idx++) {
s_targets[oldWatchList[idx]].isActive = false;
}
for (uint256 idx = 0; idx < subscriptionIds.length; idx++) {
if (s_targets[subscriptionIds[idx]].isActive) {
revert DuplicateSubcriptionId(subscriptionIds[idx]);
}
if (subscriptionIds[idx] == 0) {
revert InvalidWatchList();
}
if (topUpAmountsJuels[idx] <= minBalancesJuels[idx]) {
revert InvalidWatchList();
}
s_targets[subscriptionIds[idx]] = Target({
isActive: true,
minBalanceJuels: minBalancesJuels[idx],
topUpAmountJuels: topUpAmountsJuels[idx],
lastTopUpTimestamp: 0
});
}
s_watchList = subscriptionIds;
}
The getUnderfundedSubscriptions()
function assesses each subscription in the watchlist and creates a list of subscriptions that need to be funded. Using the attributes stored in the Target
struct for each subscription, this function adds a subscription to the needsFunding
list if the following conditions are met:
- The subscription is underfunded
- The owning contract has a sufficient balance to fund the subscription
- It's been long enough since the last time the subscription's balance was topped up
/**
* @notice Gets a list of subscriptions that are underfunded.
* @return list of subscriptions that are underfunded
*/
function getUnderfundedSubscriptions() public view returns (uint64[] memory) {
uint64[] memory watchList = s_watchList;
uint64[] memory needsFunding = new uint64[](watchList.length);
uint256 count = 0;
uint256 minWaitPeriod = s_minWaitPeriodSeconds;
uint256 contractBalance = LINKTOKEN.balanceOf(address(this));
Target memory target;
for (uint256 idx = 0; idx < watchList.length; idx++) {
target = s_targets[watchList[idx]];
(uint96 subscriptionBalance, , , ) = COORDINATOR.getSubscription(watchList[idx]);
if (
target.lastTopUpTimestamp + minWaitPeriod <= block.timestamp &&
contractBalance >= target.topUpAmountJuels &&
subscriptionBalance < target.minBalanceJuels
) {
needsFunding[count] = watchList[idx];
count++;
contractBalance -= target.topUpAmountJuels;
}
}
if (count < watchList.length) {
assembly {
mstore(needsFunding, count)
}
}
return needsFunding;
}
Using Automation
The VRFSubscriptionBalanceMonitor.sol
contract uses Chainlink Automation to top up underfunded subscriptions:
- In
checkUpkeep()
, it pulls the list of underfunded subscriptions. If this list is empty, it indicates that the upkeep is not needed, and Automation takes no further action. - Automation only runs
performUpkeep()
if there are underfunded subscriptions, and it tops up any subscriptions that need funding.
/**
* @notice Gets list of subscription ids that are underfunded and returns a keeper-compatible payload.
* @return upkeepNeeded signals if upkeep is needed, performData is an abi encoded list of subscription ids that need funds
*/
function checkUpkeep(
bytes calldata
) external view override whenNotPaused returns (bool upkeepNeeded, bytes memory performData) {
uint64[] memory needsFunding = getUnderfundedSubscriptions();
upkeepNeeded = needsFunding.length > 0;
performData = abi.encode(needsFunding);
return (upkeepNeeded, performData);
}
/**
* @notice Called by the keeper to send funds to underfunded addresses.
* @param performData the abi encoded list of addresses to fund
*/
function performUpkeep(bytes calldata performData) external override onlyKeeperRegistry whenNotPaused {
uint64[] memory needsFunding = abi.decode(performData, (uint64[]));
topUp(needsFunding);
}