Labcoat

From Rust source to decoded trace.

Labcoat is the Rust-native CLI for building, testing, and operating Alkanes smart contracts with a complete local Bitcoin devnet.

Early-stage software for local Alkanes development. Interfaces may change before 1.0; mainnet deployment controls are not production-ready.

Labcoat gives contract developers one command system for the local workflow:

• scaffold Rust Alkanes contract projects;
• build deployable WebAssembly;
• run contracts in a native test harness;
• start and control a complete Bitcoin regtest stack;
• manage project wallets;
• deploy, call, simulate, and trace Alkanes contracts;
• automate every command with JSON envelopes or MCP.

The supported public interface is the labcoat CLI.

Website · Documentation · Agent index · Security policy

Release channel note: the stable cli-v0.1.0 release uses labcoat contract new, labcoat compile, and raw-Wasm deployment. The current main branch and these examples use labcoat new, labcoat build, and package-name deployment. Run labcoat docs --llm for the reference bundled with your installed version.

Install

macOS and Linux binaries are published for arm64 and x86_64. Windows CLI support is not available yet.

curl -fsSL https://labcoat.sh/install | sh

Inspect the installer before running it if required by your security policy:

curl -fsSL https://labcoat.sh/install -o /tmp/install-labcoat.sh
less /tmp/install-labcoat.sh
sh /tmp/install-labcoat.sh 0.1.0

The installer requires sha256sum or shasum, verifies the release checksum automatically, and writes the binary to ${LABCOAT_INSTALL_DIR:-$HOME/.local/bin}. Install a specific version with:

curl -fsSL https://labcoat.sh/install \
  | sh -s -- 0.1.0

Contract compilation requires an LLVM Clang with a WebAssembly backend.

brew install llvm       # macOS
sudo apt install clang wasi-libc  # Debian/Ubuntu

Check the complete environment with:

labcoat doctor

See the installation guide for upgrades, rollback, uninstall, artifact attestation verification, supported platforms, and runtime limitations.

Quick start

Create a project and run its Rust integration test:

labcoat init hello-alkane
cd hello-alkane
labcoat test

Every new project includes a fixed Counter starter. Add another minimal contract from anywhere inside the project with:

labcoat new token

Start the local devnet and initialize the project wallet:

labcoat up
labcoat status
labcoat wallet init
labcoat wallet addresses

Fund the displayed address, mine a block, and inspect its UTXOs:

labcoat fund <address>
labcoat mine 1
labcoat wallet utxos

Build the Counter without deploying, or deploy it directly by package name:

labcoat build counter
labcoat deploy counter --dry-run
labcoat deploy counter
labcoat abi fetch counter
labcoat abi verify counter

Interact with the deployed contract:

labcoat simulate counter 2
labcoat call counter 1
labcoat trace <txid> --wait

Stop the devnet when finished:

labcoat down

Projects and configuration

labcoat init creates:

contracts/          Cargo contract packages
tests/              Native integration tests using labcoat-test
Cargo.toml          Host-side test package and workspace manifest
Cargo.lock          Reproducible dependency lock (created on first build)
labcoat.toml        Public project configuration
AGENTS.md           Agent instructions
SKILL.md            Agent workflow

Settings resolve in this order:

CLI flags → LABCOAT_* environment variables → labcoat.toml → defaults

labcoat.toml supports network, rpc_url, wallet_file, and fee_rate. Mnemonics and passphrases are rejected from the file; use LABCOAT_MNEMONIC, mnemonic stdin, and LABCOAT_WALLET_PASSPHRASE.

Deployments are recorded by network in labcoat.lock. Commit this file when deployments are part of the project state.

Each contract is an ordinary Cargo package under contracts/, so normal crates.io, git, path dependencies, modules, and shared workspace crates work. The first build creates Cargo.lock; commit it and avoid bare cargo update. Host tests use isolated in-memory contract storage that persists across calls on the same ContractHarness.

When multiple contracts need common Rust code, add a Cargo library under crates/<name>/ and add "crates/<name>" to the root workspace members. New projects omit both the directory and its workspace glob until shared code is needed.

Add another minimal contract package and matching host test without copying files:

labcoat new token

CLI map

Area	Commands
Project	init, new, doctor, docs
Test and build	test, build
Devnet	up, down, status, mine, fund, logs, reset, snapshot, restore, binaries
Wallet	wallet init, wallet addresses, wallet utxos
Contracts	deploy, call, simulate, trace, abi, lock
Automation	mcp serve, global --json

Run labcoat --help, labcoat <command> --help, or labcoat docs --llm for the full command reference.

Automation

Every command accepts --json and emits a stable labcoat/v1/* envelope. Errors include a typed code, human-readable message, and recovery hint.

labcoat status --json
labcoat deploy counter --dry-run --json
labcoat mcp serve

Support and stability

Labcoat supports macOS and Linux on arm64 and x86_64. Windows, hosted operation, durable production state, and production mainnet controls are not supported. Public web documentation tracks the current main branch; use labcoat docs --llm for installed-version command truth.

Read SECURITY.md before using local wallets or exposing runtime services. See CONTRIBUTING.md for development setup, generated-file rules, validation, and release boundaries.

Develop Labcoat

The CLI and its runtime are a Rust workspace pinned to Rust 1.86.0.

cargo fmt --all -- --check
cargo check --workspace --locked
cargo test --workspace --locked
cargo clippy --workspace --locked -- -D warnings
cargo build --release -p labcoat-cli
export PATH="$PWD/target/release:$PATH"

Core layout:

crates/isomer-core/   headless devnet orchestration engine
crates/labcoat-core/  contract, wallet, deployment, and trace operations
crates/labcoat-cli/   labcoat command-line interface and MCP server
crates/labcoat-test/  native WebAssembly contract test harness

See TOOLCHAIN.md for pinned upstream revisions and build requirements, docs/MIGRATING.md for migration from the retired TypeScript package, and docs/RELEASING.md for the CLI release process.