Quickstart

The balius Cargo plugin provides a set of commands to help you create, build, and test your headless dApps on the Balius framework.

This section provides detailed documentation for each available command:

• init - Initialize a new Balius project
• build - Build your Balius project as a WebAssembly component
• test - Run your Balius project in a local test environment

Getting Started

Before using Balius commands, make sure you have the balius Cargo plugin installed:

cargo install balius

You can run any command with the --help flag to see available options:

cargo balius --help
cargo balius init --help
cargo balius build --help
cargo balius test --help

Command Overview

Init Command

The init command creates a new Balius project with the necessary boilerplate. It sets up your project with the proper dependencies (balius-sdk and other required libraries), file structure, and initial configuration. Simply provide a project name as an argument, and it sets up the required files and directories. The name will be automatically sanitized to be a valid Rust package name.

cargo balius init my-project

Build Command

The build command compiles your Balius project to WebAssembly and converts it to a component format that can be used by the Balius runtime or the baliusd daemon.

Test Command

The test command runs your project in a local test environment with a JSON-RPC server and connections to UTXoRPC services, allowing you to test your dApp locally.

cargo balius test --utxo-url "utxorpc-url" --utxo-api-key "your-api-key"

Required External Tools

Some Balius commands require external tools:

• wasm-tools: Required for the build command to convert WebAssembly files to component format
• Rust wasm32 target: Required for compiling to WebAssembly (rustup target add wasm32-unknown-unknown)

Environment Setup

For the test command, you'll need API keys for the UTXoRPC service. These can be provided either as command-line options or as environment variables (UTXO_URL and UTXO_API_KEY).

Relationship to Other Balius Components

The balius Cargo plugin works alongside other components in the Balius ecosystem:

• It creates projects that use balius-sdk for the core dApp functionality
• It builds WebAssembly components that can be executed by balius-runtime or baliusd
• It provides a testing environment that simulates what baliusd would do in production

While you can manually set up and build Balius projects without the Cargo plugin, using balius simplifies the development workflow significantly.