Skip to content
TxPipe Docs

Cargo Plugin

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:

Terminal window
cargo install balius

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

Terminal window
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.

Terminal window
cargo balius init <project-name>

Arguments

  • project-name - The name for your new Balius project
    • The name will be automatically sanitized to be a valid Rust package name
    • Special characters will be removed or replaced with hyphens
    • If the sanitized name is different from your input, you’ll be informed of the change

Examples

Create a new project
Terminal window
cargo balius init my awesome dapp
# Result: Package name will be: my-awesome-dapp
Create a project with a complex name
Terminal window
cargo balius init My.Cool_Project!
# Result: Package name will be: my-cool_project

Project Structure

After running the init command, your project will have the following structure:

my-awesome-dapp/
├── Cargo.toml          # Project manifest with appropriate dependencies
└── src/
    └── lib.rs          # Main library file with boilerplate code

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.

Terminal window
cargo balius build

Process

The build command performs the following steps:

  1. Executes cargo build with the wasm32-unknown-unknown target
  2. Converts the generated .wasm file into a WebAssembly component using wasm-tools

What It Does

This command:

  1. Compiles your project to WebAssembly targeting wasm32-unknown-unknown
  2. Locates the built .wasm file in your target directory
  3. Uses wasm-tools to convert it into a component WebAssembly file with the name format {package_name}-c.wasm

Requirements

  • WebAssembly target support in your Rust toolchain (install with rustup target add wasm32-unknown-unknown)
  • The wasm-tools command-line utility must be installed in your path

Build Outputs

After running the build command, you’ll find:

  • A standard WebAssembly file at ./target/wasm32-unknown-unknown/debug/{package_name}.wasm
  • A component WebAssembly file at ./{package_name}-c.wasm in your project root directory

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.

Terminal window
cargo balius test [OPTIONS]

Options

  • --config, -c <CONFIG> - Path to a custom configuration file (JSON format) (can also be set via WASM_CONFIG_PATH environment variable)
  • --port, -p <PORT> - Port to use for the JSON-RPC server (default: 3000, can also be set via PORT environment variable)
  • --utxo-url <UTXO_URL> - UTXoRPC endpoint URL (required, can also be set via UTXO_URL environment variable)
  • --utxo-api-key <UTXO_API_KEY> - UTXoRPC API key (required, can also be set via UTXO_API_KEY environment variable)

What It Does

The test command:

  1. Sets up a local Balius runtime environment with the specified configuration
  2. Starts a JSON-RPC server on the specified port
  3. Connects to the specified UTXoRPC service for both ledger and chainsync functionalities
  4. Loads and registers your project’s WebAssembly component
  5. Runs the project locally, allowing you to interact with it

Requirements

First, build your project with cargo balius build. This will create a WebAssembly component that the test command will load.

Environment Variables

All options can also be provided via environment variables:

  • WASM_CONFIG_PATH - Path to a custom configuration file
  • PORT - Port for the JSON-RPC server
  • UTXO_URL - URL for the UTXoRPC service
  • UTXO_API_KEY - API key for the UTXoRPC service

Examples

Run with default settings
Terminal window
cargo balius test --utxo-url "https://preview.utxorpc-v0.demeter.run" --utxo-api-key "your-api-key"
Run with custom port and configuration
Terminal window
cargo balius test --port 8080 --config ./my-config.json --utxo-url "https://preview.utxorpc-v0.demeter.run" --utxo-api-key "your-api-key"
Run with environment variables
Terminal window
export UTXO_URL="https://preview.utxorpc-v0.demeter.run"
export UTXO_API_KEY="your-api-key"
cargo balius test

Custom Configuration

You can provide a custom JSON configuration file with the --config option. This will be passed to your worker when it’s registered with the runtime.

Testing Process

During testing, your project will be running with:

  • A local LevelDB database (stored in baliusd.db)
  • Connection to the specified UTXoRPC service for both ledger and chainsync functionality
  • A JSON-RPC server for interacting with your dApp

To stop the test, press Ctrl+C. The local database file will be automatically cleaned up.

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.