main is the development branch. When building applications or running examples, use the latest release instead.

Hyli

Hyli is the new proof-powered L1 to build the next generation of apps onchain.

This repository hosts the Rust client for the Hyli chain.

---

📎 Useful Links

• 🌐 Hyli Website
• 📚 Hyli Documentation
• 📨 Telegram

---

🚀 Getting Started

With Cargo

Start a Single-Node Devnet

To launch a single-node devnet (consensus disabled) for building and debugging smart contracts:

cargo build
HYLE_RUN_INDEXER=false cargo run

Note: if you need sp1 verifier, enable the feature: sp1

cargo run -F sp1

Run with Indexer

To run the indexer, you can use the --pg node argument:

cargo run -- --pg

It will start a postgres server for you, and will close it (with all its data) whenever you stop the node. This is usefull during development.

If you want data persistance, you can run the PostgreSQL server:

# Start PostgreSQL with default configuration:
docker run -d --rm --name pg_hyli -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres

and then in the hyli root:

cargo run

Configuration

You can configure Hyli using environment variables or a configuration file:

Using a Configuration File

Copy the default configuration file to the directory where the node will run:

cp ./src/utils/conf_defaults.toml config.toml

If a file named config.toml is present, it will be automatically loaded at node startup.

Using Environment Variables

Examples of configuration via environment variables:

HYLE_RUN_INDEXER=false
HYLE_CONSENSUS__SLOT_DURATION=100

---

🐳 Getting Started with Docker

Build Locally

# Build the dependency image, this is a cache layer for faster iteration builds
docker build -f Dockerfile.dependencies -t hyle-dep .
# Build the node image
docker build -t hyle .

Build Locally on MacOS (Apple Silicon)

🧰 Requirements for buildx users

If you are building for an architecture different than your host machine (e.g., building arm64 on an amd64 host), make sure to set up your environment accordingly:

# 1. Enable Docker BuildKit (recommended)
export DOCKER_BUILDKIT=1

# 2. Create and use a buildx builder (only needed once)
docker buildx create --use --name hyle-builder
docker buildx inspect --bootstrap

# 3. Install QEMU for cross-platform builds
docker run --privileged --rm tonistiigi/binfmt --install all

# Build the dependency image, this is a cache layer for faster iteration builds
docker buildx build --platform linux/arm64 -f Dockerfile.dependencies -t hyle-dep .
# Build the node image
docker buildx build --platform linux/arm64 -t hyle .

Run Locally with Docker

docker run -v ./db:/hyle/data -e HYLE_RUN_INDEXER=false -p 4321:4321 -p 1234:1234 hyle

🛠️ Note: If you build on MacOS (Apple Silicon), add --platform linux/arm64 to run script. 🛠️ Note: If you encounter permission issues with the /hyle/data volume, add the --privileged flag.

---

📊 Monitoring with Grafana and Prometheus

Starting Services

To start the monitoring stack:

docker compose -f tools/docker-compose.yml up -d

Access Grafana

Grafana is accessible at: http://localhost:3000

Stopping Services

To stop the monitoring stack:

docker compose -f tools/docker-compose.yml down

---

🛠️ Profiling and Debugging

Profiling Build

Run the following command to enable the profiling profile, which is optimised but retains debug symbols:

cargo run --profile profiling

CPU Profiling

• For advanced analysis, we recommend Samply.

Memory Profiling

Hyli includes built-in support for the dhat crate, which uses the Valgrind DHAT viewer for memory profiling.
To enable this feature, add the dhat feature flag. Use it selectively, as it has a runtime performance cost.