Create the Project

Create a Mercury Account and get your Token

To do anything with Mercury you first need to create an account. This can be done from Mercury's app. Once you're done, make sure to save somewhere your API token, unique to your account and needed to access your Zephir program.

The token can always be found on the dashboard's homepage under the Active Subscriptions section and is renewed every 7 days.

For simplicity, you can load your mercury API token as a variable in your current shell. For example:

export MERCURY_JWT="your_api_token_here"

Installing the Mercury CLI

The Mercury CLI, which currently supports only Zephyr functionalities, is an essential tool for interacting with Mercury's cloud execution environment. While it's technically possible to use the API, we recommend using the CLI for easier development.

To install the CLI simply run:

cargo install mercury-cli

This should install the CLI, you can verify with

mercury-cli --version

Setting up the project

The mercury-cli takes care of setting up the project for us:

mercury-cli new-project --jwt value --name zephyr-hello-world

This will create the starting point for our Zephyr program: set up the Cargo.toml, add some compiler flags, a starting point in the lib.rs and create the zephyr.toml.

Set the --jwt value to whatever (soon to be fixed). As of now we noted that the command will return an error on the terminal: it should be fine, just check if the crate was crated in your directory.

Zephyr.toml

Every time you deploy your zephyr program, the zephyr toml gives the instructions to the backend of creating the tables it defines. In case these tables exist already they will be dropped. As a result, make sure that if you have already deployed and have ingested data and need to make only an update to the code logic, remove the tables from your zephyr.toml and place them in a copy of it.

As the last step for setting up our Zephyr program, we need to create and define a zephyr.toml configuration file. That is needed if your program will read from or write to some tables that you define.

This configuration mainly defines the tables your program will read from/write to and their structure. A more detailed explanation about zephyr.toml files can be found at Understanding Zephyr.toml And Database Interactions, but here's an example configuration taken from the quickstart.

name = "zephyr-hello-world"

[[tables]]
name = "test"

[[tables.columns]]
name = "hello"
col_type = "BYTEA"

The above file means that we are creating a table "test" with "hello" as the only column and declaring that we may write to/read from it during the execution of our Zephyr program.

Note that col_type = "BYTEA" means that we can only store bytes in the database. Currently, this is the only supported data type (even though it will support built-in types in the future). That said, we recommend writing XDR structures to the database to ease decoding the client side with the existing Stellar tooling.

Cargo.toml

It's temporatily needed to manually git-source the zephyr-sdk dependency:

[dependencies]
zephyr-sdk = { git="https://github.com/xycloo/rs-zephyr-toolkit" }