Subscriptions

Learn about Mercury subscriptions.

You can now use the Mercury web app

Mercury is designed to be as lightweight yet as insightful as possible. It is built with the idea that developers know which data they’re going to need before deploying to production: you subscribe to network data with specific characteristics such as contract events, contract data changes, account entries, operations, balances, and state expiration, and from that moment Mercury will start storing and organizing related data in its database.

With that in mind, a subscription enables you to "unlock" a subset of network data that from that ledger will be loaded into the database. You can then start querying the data from our GraphQL API.

Data Retention

Mercury currently implements a retention window for the following data structures:

• contract events [retention_window = 2 months].

This will allow you to retrieve events that were emitted after subscription_time - retention_window where the retention window will likely be in the order of months. The goal of data retention is to make the experience better for developers and services working with Mercury.

Everything on Mercury is a balance between user experience and efficiency, so if you have any requests let us know in the discord server.

Example

To better explain the concept of subscriptions, let's take a look at a fairly common example.

Let's assume that you have a liquidity pool contract and want to monitor the yield accrued for the pool. Let's assume that you go for an event-based approach and that the contract emits a yield accrued event as events.publish((symbol_short!("yield"), from), yield_amount) when the pool earns yield. To start querying these events you'll have to make a subscription first, and the payload of the subscription looks like

{
    "contract_id" : "CONTRACT_ID",
    "topic1": "YIELD_XDR_BASE64"
}

Where YIELD_XDR_BASE64 is the base64-encoded XDR representation for the ScVal::Symbol(ScSymbol("yield")) scval.

Precision

More specifically, the degree of precision of the data you subscribe to can vary depending on how your subscription payload looks like. The above subscription will only index events CONTRACT_ID that have YIELD_XDR_BASE64 as the first topic. In the next chapter, you will find out that you can either make the payload more generic (all events for a contract), or more specific (only events that match 2, 3, or 4 topics).

---

Now that you have a bit of context around subscriptions, let's take a look at the subscriptions API definitions.