hylix 0.2.0

Build, test & deploy verifiable apps on Hyli
Documentation

Hylix

Build, test & deploy verifiable apps on Hyli.

Hyli is the easiest way to build vApps. Powered by Risc0 & SP1. Designed for developers.

🚀 Why Hylix?

Hylix is a developer toolbox and CLI (hy) to build vApps on Hyli, the new proof-powered L1 to build the next generation of apps onchain.

Who is this for?

Developers who are building vApps on the Hyli blockchain and have prior knowledge of Rust and CLI usage.

Main benefits

  • ✅ Zero-config project scaffolding
  • 🚀 Built-in SP1 and Risc0 support (with Noir and more soon)
  • 🧪 End-to-end testing made simple
  • 🧱 Easy local node setup with explorer
  • 🔐 No proving infra needed

🧪 Trying this out

We’re just getting started. If you're testing Hylix early:

🚀 Getting started

Install the CLI:

cargo install hylix

Then run:

hy new my-vapp
cd my-vapp
hy build
hy devnet
hy test

🧰 CLI reference

Cheatsheet

Command Action
hy new [PROJECT] Create a project using the scaffold.
hy build Build contracts.
hy test Run E2E tests.
hy run Start backend.
hy devnet Start local node.

hy new [PROJECT]

Generate a new project:

hy new my-vapp
  • You will be asked to choose SP1 or Risc0 for your backend
  • Clone the default vApp scaffold
  • More proving schemes
  • Validate & setup your local dev environment (Rust, risc0, sp1 toolchains...)

A Hylix vApp project is made of three main components:

  • 📜 contracts/: ZK program written in Rust (using SP1 or Risc0 SDK)
  • 🧠 server/: Your vApp’s backend, runs locally with hy run
    • By default includes:
      • 📝 Register contract at startup
      • ✅ Proof auto-generation
      • 📇 Contract-specific indexing
      • 🧩 Optional custom logic & APIs
  • 🎨 front/: Frontend interface powered by Bun and Vite (optional)

Each part is optional: you can build CLI-only vApps, headless backends, or full dApps.

Read more: Scaffold repo | Quickstart in docs.

hy build

Build the project:

hy build

Then, clean the project build artifacts:

hy clean

hy devnet

Command Alias Description
up u Start the local devnet
down d Stop the local devnet
status ps Check the status of the local devnet
restart r Restart the local devnet
bake b Create and fund test accounts
fork f Fork a running network
env Print environment variables for sourcing in bash
help Print this message or the help of the given subcommand(s)

Launch a local devnet with:

  • Node
  • Oranj token contract & Auto-Provers
  • Wallet app & Auto-Provers
  • Indexer
  • Explorer
  • Pre-funded test accounts

See Configuration section for customization.

hy devnet up
# And to stop all services
hy devnet down

Check status of devnet

hy devnet ps
# Or
hy devnet status

Export devnet env vars:

source <(hy devnet env)

Soon

Want to fork a running network ?

hy devnet fork [ENDPOINT]

hy test

Run your vApp’s end-to-end tests in a fully orchestrated local Hyli environment.

hy test

Read more on executing unit & E2E tests.

Key Features

  • ✅ Contract unit tests
  • 🧪 Full E2E workflows (from proving to verification)
  • ⚙️ Full integration with cargo test or custom test runners

What hy test does (under the hood)

  1. Starts hy devnet if not already running
  2. Compiles your project (hy build)
  3. Runs your application backend hy run
  4. Runs tests defined in tests/ using cargo test
  5. Shuts down the devnet & backend after completion (unless --keep-alive is set)

Example

hy test

Want to keep the devnet alive after tests?

hy test --keep-alive

hy run

Start your backend service locally or on testnet. The app backend registers your contract, runs a local auto-prover, and launches core modules like the contract indexer. You can customize the backend in the server/ folder.

hy run

By default, hy run operates in local dev mode.

Options

  • --testnet: Register and interact with contracts on the public Hyli testnet.
  • --watch: Automatically rebuild and re-register on file changes (coming soon)

What hy run does (under the hood)

  • ✅ Registers your vApp contract on-chain
  • 🔁 Starts a local auto-prover (generates and posts proofs when needed)
  • 📇 Launches a contract indexer to track state transitions
  • 🛠️ Wires everything together for a ready-to-use dev backend

Configuration

Hylix stores its configuration in ~/.config/hylix/config.toml (Linux). You can customize various aspects of the CLI behavior:

Custom Docker Images

You can specify custom Docker images for different services in your devnet configuration:

[devnet]
# Custom Docker images for each service
custom_node_image = "ghcr.io/hyli-org/hyli:0.14.0-rc1"
custom_wallet_server_image = "ghcr.io/hyli-org/wallet/wallet-server:main"
custom_wallet_ui_image = "ghcr.io/hyli-org/wallet/wallet-ui:main"

# Or use completely custom images:
# custom_node_image = "my-registry.com/my-hyli-node:v1.0.0"
# custom_wallet_server_image = "my-registry.com/my-wallet-server:latest"
# custom_wallet_ui_image = "my-registry.com/my-wallet-ui:dev"

This allows you to:

  • Use specific versions of services
  • Test with custom-built images
  • Use images from private registries
  • Override default images for development/testing

🧠 Hylix components

Hylix builds on top of:

  • SP1/Risc0 zkVM for fast, verifiable compute
  • Rust for native speed and tooling compatibility
  • Bun, vite, vue3 & tailwind for frontend application

🛤️ Roadmap

  • Noir + Cairo support
  • Tool auto-upgrade
  • Plugins for custom commands
  • Test proc-macro for isolated E2E testing
  • Upload to a prover network (hy upload): upload your compiled ELF to a prover network without setting up lovcal proving infrastructure
  • Testnet mode (hy run --testnet) to start a backend and deploy the contract on a prover network

🔗 Links