Introduction

Introduction to Mercury's Cloud Execution Environment

If you seek to build your own indexing experience with full and potentially low-level customizability without having to run any infrastructure, you are in the right place!

If you need an indexer to perform simple tasks such as retrieve events or data entry changes of a certain contract(s), Mercury already has built-in predefined indexing patterns that are less expensive and easier to set up: Subscriptions

If you're still on this page, it means that you're looking to build a customized solution with:

• Custom API layout.

• Aggregations & multi-step workflows.

• Alerts.

• Bots.

• Monitoring.

• Contract calls and simulation.

All of this and more is possible through Mercury's cloud execution environment and the Zephyr Virtual Machine (ZephyrVM).

What's Zephyr: Mercury's cloud execution environment

Powered by the ZephyrVM, Mercury's cloud execution environment is an omni-comprehensive gateway to the Stellar Network data, with a particular focus on Soroban (Stellar's smart contract platform).

It addresses any specific data-related need a developer or application could have, allowing for seamless access to the whole network's data (Stellar ledger and ledger metas) and endless customization on what to do with such data: ingestion logic, database interactions, and external interactions (outside of the environment) through web requests. All without having to run any infrastructure as Zephyr programs are hosted on Mercury's cloud environment.

Our cloud execution environment removes the barrier of setting up and maintaining your Stellar node(s). You can run your code directly on our infrastructure, alongside our nodes. This grants you seamless access to both the ledger, ledger close data, and a performant database and API – all within the same environment. Essentially, you can build fully customizable indexing logic while leveraging the fastest and most real-time way to retrieve Stellar data. All on our cloud environment.

How Zephyr works: an overview

Setting up a Zephyr project means creating a Rust program that, through the built-in Zephyr VM host functions, has access to everything in the Stellar ledger and ledger metas (for each ledger close).

You can leverage this environment to access any kind of live or past data you need, aggregate or manipulate it as you like, and finally store it in your fully customizable tables on our database, making it readily available for you or your application to query.

Zephyr programs also allow for external interactions (through web requests) and the possibility of calling and simulating contract calls directly from the program. Coupling that with seamless data access, it allows to build, all in one place, any kind of data-driven application like bots or alert systems.

On top of that, Zephyr allows you to create custom callable APIs (which are server-less functions), that leverage access to network data and tables. These can be used as custom RPC-alike endpoints (like for simulation), on-demand getLedger API, to query and compose stored data on Mercury, and many more.

Mercury Cloud VS Mappings

Zephyr programs are very different from the mapping-based indexing offered mostly on other chains (Subgraph for instance). In Mercury, your programs are actual compiled programs executed in a specialized VM.

This means that these have:

• much more granular and low-level access to the network data.

• access to a wider range of data (i.e. the ledger itself, the whole close meta).

• more control over how you access previously stored data.

• tap into external services (alerts, monitoring, bots, sending txs, etc).

... and many other features that are possible due to the flexibility offered by running the code as a program in a specialized VM instead of simply using a handlers-alike workflow.

Additionally, as you'll learn exploring the docs, relying on the VM allows for abstracting many pieces of the workflow from the implementor, making writing Zephyr programs simple and straightforward.

This is a novel concept in the space of indexing, and aligns very well, especially with Soroban: our codebase is completely written in rust allowing us and you to leverage existing SDF-maintained tooling. As we will see, our team has been able to hardwire Soroban into Zephyr.

Zephyr Virtual Machine

The Zephyr Virtual Machine (ZephyrVM) is a WebAssembly VM built by xyclooLabs to allow servers to execute arbitrary and untrusted code:

• in a sandboxed environment.

• with integrated tooling and VM functions that smoothen the developer experience (creating a Zephyr program is much easier than building your indexer!).

Initially, the development of the ZephyrVM was aimed at enabling Mercury users to craft their customized indexing, which is still the case. However, our vision has grown and so has the codebase.

At the current state of development, Zephyr can already be used to:

• Create customized indexers.

• Set up complex alert systems.

• Monitor the activity and correct execution of soroban contracts.

• Directly access the Stellar ledger without limitations.

• Build bots.

Mainly, anything you can think of that involves network data can be achieved within a ZephyrVM execution.

Soroban VM

The ZephyrVM has also built-in support with Soroban. And when we say built-in we really mean it: we've modified Soroban's host and macros to link the Soroban host and functions directly within our virtual machine and run in our host environment.

This means that through the Zephyr SDK, you can use the Soroban SDK as if you were within a Soroban Smart contract:

let map = z_env.read_contract_entries_to_env(&env, contract_id).unwrap();
    let top_holders: Vec<i128> = map.iter().filter_map(|entry| {
        if DataKey::Balance(addr) == entry.0.try_into_val(&env).unwrap() {
            // do something
        }
...

This is all from within a Zephyr program, making working with Soroban primitive structures (which are actually just integers on the client!) and functionality much easier.

New Feature Requests

Throughout this documentation, you'll learn about what the Zephyr VM and SDK offer to help you shape the perfect indexer for your use case, including web requests, ledger access, XDR readers, etc, but if you learn that there are functionalities you need that aren't available yet, please file an issue on https://github.com/xycloo/rs-zephyr-toolkit/issues, chances are that we're either already working on it or will push it down our pipeline. Again, we want Zephyr to allow developers to do anything they require!

---

That said, let's get started with Zephyr.