Back to QuickStarts

Automate Contract Balance Top-up

Automate the process of maintaining an Ethereum balance in your smart contract using Chainlink Automation.

Objective

Some smart contract applications require you to maintain a certain Ethereum balance to ensure optimal operation. You can automate this process using Chainlink Automation. Use these smart contracts to monitor and top-up native token balances on your smart contracts.

This Automation contract monitors and funds Ethereum addresses that developers might need to top up frequently based on a configurable threshold. You will deploy this example monitor contract and use the automation.chain.link interface to register an upkeep and run the contract. To learn the basics about Chainlink Automation, read the Chainlink Automation Overview.

For this example, use the Ethereum Sepolia testnet to simplify access to testnet funds. You will top up an address with a specific amount of testnet ETH. Later, you can use another EVM-compatible network of your choice.

Before you begin

Before you start this tutorial, complete the following items:

Steps to implement

1 Deploy the upkeep contract
  1. Open the EthBalanceMonitor.sol contract in Remix.

  2. Compile the contract in Remix.

  3. On the Deploy & Run Transactions tab in Remix, set your Environment to Injected Provider and allow Remix to connect to MetaMask.

  4. The constructor requires a minWaitPeriodSeconds value. Specify this in the Deploy fields in Remix. For this example using Ethereum Sepolia, enter the following value:

    • minWaitPeriodSeconds: 60
  5. Click Transact to deploy the contract with the defined constructor settings and accept the transaction in MetaMask. After the contract is deployed, it will appear in your Deployed Contracts list with several functions available to configure.

    Note: You will come back and set your forwarder address later. This forwarder address becomes available after you create your upkeep.

  6. Use MetaMask to Send 0.001 ETH to your contract address. The funds are used to top-up other contracts with ETH. See the Fund Your Contracts page to learn how to find your contract address and send funds to those contracts. For this example, 0.001 ETH is sufficient for demonstration purposes. In a production environment, you might store a larger amount of funds in the contract so Chainlink Automation can automatically distribute them to several different addresses as they are needed over time.

2 Configure the address watch list

Before your contract will fund an address, you must set the watchList address array with minBalancesWei and topUpAmountsWei 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.

  1. In the list of functions for your deployed contract, run the setWatchList function. This function requires an addresses array, a minBalancesWei array that maps to the addresses, and a topUpAmountsWei array that also maps to the addresses. In Remix, arrays require brackets and quotes around both addresses and integer values. For this example, set the following values:

    • addresses: ["YOUR_WALLET_ADDRESS_OR_CONTRACT_ADDRESS"]
    • minBalancesWei: ["100000000000000000000"]
    • topUpAmountsWei: ["000100000000000000"]

    These values tell the top up contract to top up the specified address with 0.0001 ETH if the address balance is less than 100 ETH. 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 ETH if the balance is less than 1 ETH.

  2. After you configure the function values, click transact to run the function. MetaMask asks you to confirm the transaction.

  3. In the functions list, click the getWatchList function to confirm your settings are correct.

3 Register the upkeep

Now that the contract is deployed, funded, and configured, register the upkeep and Chainlink Automation will automatically run the example code.

  1. Go to the automation.chain.link registration UI.

  2. Click Connect wallet in the top right of the UI to connect your wallet.

  3. After the site recognizes your wallet, click Register new Upkeep. The registration interface opens.

  4. Select the Custom logic trigger option.

  5. Copy your contract address from Remix and paste it into the Target contract address field.

  6. Click Next to go to the Upkeep details page.

  7. Specify a name for your upkeep and set a Starting balance of 2 LINK. Leave the other settings at their default values.

  8. Click Register Upkeep to complete the registration process.

  9. Go to the Upkeep details page and copy your Forwarder address.

  10. 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.

4 Check your upkeeps

The upkeep runs the checkUpkeep function in your contract, which checks the balances of all addresses in the watchList against their defined limits. If any of the addresses are below their specified minimum balances, the upkeep runs the topUp function for that specific address, which distributes the ETH in your contract to that address. Unless your wallet happens to have more than 100 testnet ETH, you will receive ETH in your wallet every 60 seconds as defined by minWaitPeriodSeconds in your contract. Check to make sure the example is running correctly:

  1. Go to automation.chain.link, view your new upkeep, and confirm that it is performing upkeeps in the History list.

  2. View your contract address and your wallet address at the Sepolia block explorer to see the transactions happening between your contract and your wallet address.

The example continues to run until your upkeep runs out of LINK, your contract runs out of ETH, or until you manually pause or cancel the upkeep.

After you are done with this example, you can run the withdraw function on your contract to withdraw any remaining testnet ETH so you can use it later. Also, you can cancel your upkeep in the Automation UI and withdraw any remaining unspent LINK.

Examine the example code

The EthBalanceMonitor contract is ownable, pauseable, and compatible with the AutomationCompatibleInterface contract:

  • Ownable: The contract has an owner address, and provides basic authorization control functions. This simplifies the implementation of user permissions and allows for transfer of ownership.
  • Pauseable: This feature allows the contract to implement a pause and unpause mechanism that the contract owner can trigger.
  • Compatible: The AutomationCompatibleInterface is necessary to create contracts that are compatible with the Chainlink Automation Network. To learn more about the AutomationCompatibleInterface and its uses and functions, read the Making Compatible Contracts guide.

Contract functions

Functions with an asterisk (*) denote features that only the owner can change. Click on each function to learn more about its parameters and design patterns:

Function NameDescription
setWatchList*Addresses to watch minimum balance and how much to top it up.
setForwarderAddress*Updates your upkeep's forwarder address, which is available after you create your upkeep.
setMinWaitPeriodSeconds*Updates the global minimum period between top ups.
topUpUsed by performUpkeep. This function will only trigger top up if conditions are met.

Below are the feed functions in EthBalanceMonitor:

Read Function NameDescription
getUnderfundedAddressesView function used in checkUpkeep to find underfunded balances.
getForwarderAddressViews the upkeep's forwarder address.
getMinWaitPeriodSecondsViews the global minimum period between top ups.
getWatchListViews addresses to watch minimum balance and how much to top it up.
getAccountInfoProvides information about the specific target address, including the last time it was topped up. This function is external only.

setWatchList Function

Parameters

NameDescriptionSuggested Setting
addressesThe list of addresses to watch(not applicable)
minBalancesWeiThe minimum balances for each address5000000000000000000 (5 ETH)
topUpAmountsWeiThe amount to top up each address5000000000000000000 (5 ETH)

Only the owner can setWatchList. Each of the parameters should be set with distinct requirements for each address.

setForwarderAddress Function

Parameters

NameDescription
forwarderAddressUnique forwarder address used to secure your upkeep

Only the forwarderAddress can performUpkeep. Your upkeep's forwarder address can be found on the Chainlink Automation app after you create the upkeep. Only the owner can set a new forwarderAddress after deployment.

setMinWaitPeriodSeconds Function

Parameters

NameDescriptionSuggested Setting
periodMinimum wait period (in seconds) for addresses between funding3600 (1 hour)

period denotes the length of time between top ups for a specific address. This is a global setting that prevents draining of funds from the contract if the private key for an address is compromised or if a gas spike occurs. However, only the owner can set a different minimum wait period after deployment.

topUp Function

Parameters

NameDescription
needsFundingList of addresses to fund (addresses must be pre-approved)

Any address can trigger the topUp function. This is an intentional design pattern that shows how easy it is to make an existing contract compatible with Chainlink Automation while maintaining an open interface. All validations are performed before the funding is triggered. If the conditions are not met, any attempt to top up will revert.

Get the latest Chainlink content straight to your inbox.