Self-hosting Zephyr
Self‑Hosting Mercury Zephyr: A Step‑by‑Step Tutorial
This tutorial will walk you through the entire process of setting up a self‑hosted Zephyr environment. You’ll learn how to install and run Stellar Core (for streaming ledger events), clone and build the necessary Mercury‑Zephyr repositories, set up PostgreSQL for ingestion, and compile and run an example Zephyr program.
Prerequisites:
Familiarity with the command line, Git, and Cargo
Rust toolchain installed
PostgreSQL installed on your system
A Unix‑like environment (macOS/Linux; Windows users can adapt these instructions)
Table of Contents
1. Installing Stellar Core
Running a Stellar Core watcher node is needed to stream ledger “close metas”. These are later consumed by the Mercury‑Zephyr sync client to trigger the execution of your Zephyr programs. Ensure Stellar Core is running locally before proceeding. A tutorial on how to run Core will be provided by our team later.
2. Cloning the Repositories
You’ll need to clone the Zephyr-VM repository (using the “actor” branch) along with its required dependency repositories so that all code can interact properly.
Steps:
Note: The correct branch for rs-soroban-env
is stellar-main-2
.
3. Building the Actor Components
The actor component contains two key binaries: one that streams events (sync client) and another that processes these events (execution server). Building in the actor directory isolates these components from other workspace members.
Actor/Sync Client Binary: This binary connects to Stellar Core to receive live "close metas” and forwards them to the execution layer. Essentially, it acts as a bridge between Stellar Core and the ZVM processing logic.
Actor/Server Execution Layer Binary: This binary is responsible for processing the events received by the sync client. Upon receiving an event, it spawns subprocesses that run the Zephyr Virtual Machine (ZVM) on your local machine, executing the desired logic.
Steps:
If you encounter missing manifest or version mismatch errors, review your cloned repositories and ensure you’re on the correct branches.
4. Installing and Configuring PostgreSQL
PostgreSQL serves as the database to store ledger sequences and execution metadata.
Installation (macOS Example with Homebrew):
Creating the Database:
Setting the Environment Variable:
Set the connection string using the INGESTOR_DB
environment variable. For example:
Replace <username>
and <password>
with your PostgreSQL credentials. If you use peer authentication (common on macOS), you may omit the password:
Verify by running:
5. Editing Configuration Files
The configuration files (located in ./config/
in the Zephyr VM repository) define runtime parameters like network endpoints (testnet or pubnet), logging levels, and other settings.
Steps:
Open each configuration file in your editor.
Read comments to understand each setting.
Adjust values as needed to match your local environment (e.g., switching network endpoints or adjusting verbosity).
Save changes and restart affected components to apply the new settings.
6. Running the Actor Sync Client
The sync client is responsible for connecting to Stellar Core (or an event API) and streaming ledger “close metas” to the execution server.
Steps:
Note: If you haven’t initialized Stellar Core’s ingestion database, jump to step 7 before proceeding.
From the actor directory’s build output:
Key Points and Troubleshooting:
What to Expect: You should see log messages indicating that the WebSocket server is listening (e.g., on
ws://0.0.0.0:4000/ws
) and that ledger metas are being processed.Error Handling: If you receive an error about a missing file (for example, “No such file or directory”), review the code (around line 105 in
actor/sync/src/main.rs
) to determine which configuration file or asset is missing. Ensure that you’re running the binary from the correct working directory so that relative paths resolve correctly.Database Schema Check: An error such as “No DB schema version found, try stellar-core new-db” indicates that Stellar Core’s ingestion database has not been initialized. See the next section on initializing the DB schema.
7. Initializing the Database Schema
Before the sync client and execution server can operate, Stellar Core needs to initialize its ingestion database. This process creates the necessary tables and stores the schema version.
Steps:
Navigate to the temporary ingestion directory and run:
This command creates the database schema that the sync client checks for.
8. Building and Running an Example Zephyr WASM Program
Zephyr’s execution layer uses custom logic compiled to WebAssembly. This section shows how to compile an example Zephyr program (in this case, "zephyr-hello-ledger") and prepare it for execution.
A. Change to Supported Rust Version and Add the WASM Target
Switching to Rust 1.81 might not be necessary if you’re not using macOS.
B. Installing Mercury CLI (Optional)
Mercury CLI can be used to build the Zephyr program:
C. Building the Example Program
Change to the example directory and build the program. Theoretically, it could also be built with the Mercury CLI but as we’re investigating some issues, it’s better to use option 1:
Option 1:
Option 2:
After the build completes, verify the WASM binary’s location:
Your WASM binary should be at:
9. Starting the Multiuser Logging Service
This step builds and launches the multiuser logging service, which collects log messages from your Zephyr system and writes them into your PostgreSQL database. This helps you monitor system activity and troubleshoot issues by persisting logs for later analysis.
Steps:
Navigate to the Service Directory and build:
Run the Service with Database Connection:
Set the database connection string and start the logging service by running:
The logs will be stored in the
mercury_user_logs
table of the database.
10. Starting the Execution Server
The execution server ties together the ingestion (database), the WASM-compiled logic, and the host execution binary. It reads ledger events and spawns processes to execute the corresponding Zephyr Program code.
Steps:
Set the following environment variables and start the server:
Explanation:
INGESTOR_DB: Connects to your PostgreSQL database.
WASM_PATH: Specifies the full path to the compiled WASM binary.
BINARY_PATH: Points to the host binary (the self-hosted Zephyr-VM) used for executing the WASM module.
server start
: Instructs the server binary to begin processing ledger metas and executing your logic.
11. Verifying the Setup
What to Check:
Console Output:
The execution server should print log messages showing that it’s connected (e.g., “WebSocket server listening on ws://0.0.0.0:4000/ws”) and processing ledger metas.
Database Inspection:
Use the psql
command or a GUI tool (like pgAdmin) to connect to zephyr_db
and list the tables:
Then query the table (whose schema was created by the new-db command):
New rows should appear corresponding to each processed ledger sequence.
Conclusion
This tutorial has guided you through the complete process to self‑host Zephyr and provided an understanding of the key components involved. Feel free to refer back to this guide or ask for further clarifications as needed. Happy coding!
Last updated