dApps on Ethereum have grown in complexity, depth, and breadth in the past few years. One missing piece is the efficient querying of historical block information. With standard Ethereum JSON-RPC methods, developers either need to maintain centralized databases containing large swaths of the blockchain history, or repeatedly query blocks across long time periods in order to scrap the entire transaction history of a particular address. These two options complicate the process in which users like wallet providers supply information such as the history of a particular user's interactions on the blockchain. Without easy access to this information, developers must rely on expensive, slow methods that limit the feature set of their apps.
While building historical queries into dApps has traditionally been complicated, time-consuming, and error-prone, the Alchemy Transfers API allows for developers to query historical wallet activity, token transfers, and other account-driven transactions in a simple transaction.
In this tutorial, we’ll look at an example of how, with just a few lines of code, your dApp can integrate the power of the Alchemy Transfers API.
For our pre-packaged example, we’ll create a dApp dashboard that tracks transaction activity for a particular address, processes it in the backend, and then pushes it in real-time to the frontend.
Problem Statement: 🐕
Instead of sending burnt tokens to 0xdead, which is recommended for most token burning, creators of Akita Inu (AKITA) and Shiba Inu (SHIBA) chose to gift Vitalik Buterin with large swaths of their dog-themed tokens. However, rather than leaving the meme tokens untouched, Vitalk instead chose to sell tokens in batches to Uniswap, swapping them for ETH, and donated both the ETH proceeds and the rest of the tokens that could not be sold to a whole host of charities. Check out this article for more info.
One of the lucky recipients of this windfall was the Gitcoin community multisig account (multisig stands for multi-signature, which is a specific type of digital signature that makes it possible for two or more users to sign in to access / control the funds in a single wallet address). With the market valuation of the AKITA token transfer at ~$450 million, no single market would be able to absorb a single sale of the tokens, and if the multisig attempted to do so, the price of AKITA would plummet. As such, the Gitcoin community decided to implement a token “rescue” process that would burn 13 AKITA tokens for every 1 AKITA sold off to the open market.
Our example dashboard follows along with the story of AKITA and its rescue process by tracking the total number of AKITA tokens held in the Gitcoin multisig and the total number of tokens that have been burnt as part of the rescue contract.
The dashboard that we create performs two functions. Upon refresh of page or user click, the webapp fires off a request to Alchemy, querying the Gitcoin multisig address and the “rescue” smart contract. After receiving the response, the dashboard parses the JSON object and processes it. Ultimately, the website frontend displays the processed items.
Option 1: Building the dApp using Heroku
1. Set Up Github Repo & Heroku
a) Make a clone of the existing Github Repository
Navigate to your command line and type:
b) Install Heroku-CLI and verify/install dependencies
In this tutorial, we utilize Heroku for hosting a server and website; if you choose to use Heroku, be sure to follow all of the following steps. If you want to use another provider, see Option 2: Build Project From Scratch
- Download Heroku-CLI based on your OS. Make sure you download the correct version based on what kind of computer environment you are using!
- After installation, navigate into the file that you just git cloned and run the following command in your command line to login to your Heroku account.
Follow the commands to login into your Heroku account. If you don't have a Heroku account, you can sign up for one for free!
- Let's confirm that you have downloaded the correct version of Node. In your command line run:
After running the command, you will either see a version number appear or you will instead get an error message telling you that you do not have Node installed.
Note that Heroku requires users to have any version of Node greater than 10 installed. If you don’t have it or have an older version, install a more recent version of Node.
- Lastly, let's confirm that we also have npm installed properly.
Again in your command line, run the following command:
npm is installed with Node, so check that it’s there. If you don’t have it, install a more recent version of Node.
c) Initiate Heroku
Now that we have confirmed that Heroku has all the dependencies it needs to run, let's create our Heroku app by running the following command:
You should then see something like this pop up:
Make sure you take note of the URL that pops up http://xxxxxxxxx.herokuapp.com/. We'll be using it since it's the URL of our sample dashboard!
For more detailed instructions on setting up your environment to be configured for Heroku, check out the official Heroku docs.
2. Create a Free Alchemy Account
If you don’t already have one, you’ll first need to create an account on Alchemy. The free version will work fine for getting started!
3. Integrate Alchemy Transfers API
For our Akita Token Rescue dashboard, this is the specific request that we use:
4. Insert Alchemy API Key
Navigate to the main.py to find where your API key is being used. Note that to get an Alchemy API key you will need to create an App in the Alchemy dashboard.
NOTE: For this tutorial, we require using an app that is pointed towards the Ethereum mainnet since our contract is deployed on mainnet.
Our Heroku app is configured to accept the Alcehmy API key as an environment variable to encourage safe, best practices. Once you get your API key after creating an account, run the following command in the same file directory that you previously ran heroku create to set your environment variables within Heroku itself.
NOTE: When you copy your key from the dashboard you should get a full url like this: https://eth-mainnet.alchemyapi.io/v2/kXtBl52Cr0hNbOn0rI2up7lhUiGk_2eS
Your key is just the last portion in the URL: kXtBl52Cr0hNbOn0rI2up7lhUiGk_2eS
Your Heroku environment variables should look similar to this:
5. Deploy Heroku App!
Now, we're in the final steps! Confirm that you are navigated to the file that your Heroku project lives within. Once there, run the following commands to save your changes on Git and deploy the app.
With that, we have pushed all changes to Heroku and are now able to view our dashboard live. Open the Heroku app at the URL that your project has been pushed to.
Note that upon refreshing the page, we see that the dashboard's data is updated. Likewise, if we click on the "Refresh Data" button, we find that the balances displayed also change if someone has interacted with the rescue contract.
And now, with everything in place, you can test out your dApp!
🎉 Congratulations on your dApp deployment! Feel free to edit your app, point the target address at other interesting contracts / public figures, or make the frontend more spiffy!
Option 2: Build the dApp From Scratch
In this tutorial, we provide a generalized setup for a Python webapp that allows you to query the Alchemy Transfers API, process the JSON response, and then push the data to the frontend.
1-2. Complete Steps 2 & 3 from the Heroku Project.
3. Configure your App with your Alchemy API Key
HINT: You'll need to install the dotenv package if you haven't already. Follow these steps to learn more.
Congrats! You've set up your API key!
4. Create Backend Processing Script
For this tutorial, we use Python / React for sending our API requests, decoding the JSON response, and for processing it.
a) Install necessary dependencies
Our tutorial is primarily built with Python and we use Flask to power our app. Make sure that you have the follow dependencies in your environment to follow along.
Then, run the following command to install the packages:
b) Create a file called main.py
This is where our backend processing script will live. We'll also add a few installations and define our Alchemy key variable at the top:
c) Define Web3 functions
Note that we include the ERC20 ABI in this code snippet in order to properly read the AKITA balance of the Gitcoin multisig wallet.The Contract Application Binary Interface (ABI) is the standard way to interact with contracts in the Ethereum ecosystem and we use the ERC20 ABI to interact with ERC20 contracts such as the AKITA contract.
d) Define Alchemy Transfer function
To understand the parameter breakdown, read more above.
NOTE: We parse our JSON response by using the imported Python package json to help us easily sort through the response and filter for the desired fields. To get a better idea of what this response looks like raw, try the Alchemy Composer App or try executing an Alchemy API call from Postman.
e) Configure Flask routing
Whenever the "Refresh Data" button is triggered, we fire off a request to the Alchemy API which in turn gives us our updated data. Note that lines 7-10 and 14-18 are duplicated to ensure that our website refreshes its data whenever we first load in as we visit it, whenever someone refreshes the site, or when a user clicks the "Refresh Data" button.
5. Create dApp Dashboard Frontend
With our Python script ready, we’ll now build our dashboard. Our example client is extremely simple. Of course, you’ll want to integrate this code into your dApp as appropriate with a different target address and different graphics!
Our dashboard is a simple HTML page that displays any information that was processed by the Python scripts in the background.
a) Create your index.html file
This is the file where we will store all of our frontend code.
b) Create "Refresh Data" Button
This piece of code "POSTS" a trigger to the Python script, we created previously. This lets us know when the user has click the "Refresh Data" button and executes the Python code.
c) Create UI Elements that our Python Script Can Push Data To
After deploying this webapp in your desired environment, it should look like the following!
This is a simple example, but there are many ways you can expand on this to build dashboards and dApp for your users.
Fork 🍴, build 🏗️, and design 📝off this repo!
Blockchain has evolved quickly, but not all developer features are easy or intuitive to use. In particular, the querying of historical transaction information is something that has plagued development. However, with the Alchemy Transfers API, your users can stay informed and confident about understanding their transaction activity both in the present and the past!
Ready to start using Alchemy Transfers? Create a free Alchemy account and get started today!