Index and query contract events

Learn how to work with contract events in your application on Soroban in a step by step tutorial by creating a list of all transfers for a token contract.

This tutorial demonstrates how to retrieve the events emitted by Soroban contracts in order to display them in your application. This is one of the main use cases when working with network data, as events capture some specific actions from the contract and therefore in most cases are the favourite choice for developers to keep track of what happened. Below you can find a summary of the steps we went through.

Steps

The tutorial is the perfect starting point for any developer who is beginning his journey with Mercury: it will cover every step of the process from the analysis of the problem (what do we have to index) up to the creation of a frontend displaying the relevant data.

Step 1: analysis of the problem

First of we need to understand the problem and how to solve it: we want to create a list of all the transfers that happened with a certain Soroban token. We go through the token contract code and we see that the best way to capture the transfers that happened is by looking at the "transfer" event, emitted every time the contract's "transfer" function is called. Therefore we need to find the best way to record and access these events.

Step 2: create a Mercury subscription

Before accessing any kind of data with Mercury you need to create a subscription to it before. This takes 1 minute and allows us to be very efficient in what we store in order to guarantee our users the best pricing plans (more about subscriptions in the dedicated section of these docs). The subscription can be easily done through the Mercury app (the new version is coming soon) by inserting the id of the token contract and the XDR of the event topic we are interested in (in our case "transfer").

Step 3: query the data

After having created the subscription we can go ahead and perform a query to Mercury's database to retrieve the transfer events. To perform the query we have to provide our authentication token that can be easily retrieved from the app.

In the tutorial we are executing the query first from Mercury's GraphiQL playground: this can be a powerful tool to play around and craft the queries that better fit your needs.

Step 4: parse and display the data

The final step of the work is to display the queried data on a frontend. We're doing that by using a NextJs framework and creating a table that lists all the transfers. Such data is returned by our API in a base-64 encoded XDR format: therefore In order to show it in a readable manner we have to parse it using the Stellar SDK.

Conclusion

As you can see working with Mercury to access the data you need is very quick and straightforward. It can be done in a few minutes and with minimal work on your side. Be aware that in this tutorial we are working on Soroban testnet: access to mainnet data is currently given on request to some teams. Also consider that this version of the app is a work in progress and the stable one is coming soon.