Basic Usage - Stoffel Documentation

This page describes the stoffel CLI. The stoffel binary is a Cargo-like project tool for creating, checking, building, running, and iterating on Stoffel apps. It is the developer-facing entry point for local MPC workflows.

Core workflow

stoffel init hello-mpc
cd hello-mpc
stoffel check
stoffel build
stoffel run

Use stoffel --help to see the installed command set. Current commands are:

init / new: create a project from a template.
check: validate source and MPC configuration without writing bytecode.
compile: compile a project, source directory, or .stfl file to .stflb bytecode, or disassemble existing bytecode.
build: build project bytecode under target/.
run: run a project, .stfl source file, or .stflb bytecode through local or network MPC execution.
dev: watch a project and rerun it on local MPC when files change.
test: run no-argument Stoffel test functions.
status / doctor: show project health and environment status.
clean: remove generated build artifacts.
update / upgrade: check or update the CLI and project dependency files.

Creating projects

# Default Stoffel project
stoffel init my-project

# Supported templates
stoffel init py-app --template python
stoffel init rust-app --template rust
stoffel init foundry-app --template solidity-foundry
stoffel init hardhat-app --template solidity-hardhat

# Template aliases
stoffel init py-app --template py
stoffel init foundry-app --template foundry
stoffel init hardhat-app --template hardhat

# Library-style Stoffel project
stoffel init my-library --lib

# Refresh template files in an existing directory without deleting unrelated files
stoffel init . --force

--lib cannot be combined with --template. Use stoffel init --help for supported template names.

Project structure

The default template currently creates a Rust-backed Stoffel project:

my-project/
├── Cargo.toml
├── README.md
├── Stoffel.toml
└── src/
    ├── main.rs
    ├── main.stfl
    └── stoffel_bindings.rs

Other templates place the Stoffel program under a nested stoffel/ directory and include the host-language scaffold for Python, Rust, Foundry, or Hardhat.

`Stoffel.toml`

Stoffel.toml is the project manifest. The CLI reads package, build, and MPC settings from this file. A minimal shape looks like:

[package]
name = "my-project"
version = "0.1.0"

[build]
source = "src/main.stfl"
target_dir = "target"

[mpc]
backend = "honeybadger"
curve = "bls12-381"
parties = 5
threshold = 1

Use command-line overrides while developing:

stoffel check --backend honeybadger --field bls12-381 --parties 5 --threshold 1
stoffel build --release --parties 5 --threshold 1
stoffel run --parties 5 --threshold 1

Do not pass project Stoffel.toml to stoffel run --config. --config is for an MPC network/off-chain client TOML file; pass the project path as the positional PATH instead.

Checking and compiling

# Validate the current project without writing bytecode
stoffel check

# Validate a source file or directory
stoffel check src/main.stfl
stoffel check src

# Print compiler IR for debugging
stoffel check --print-ir

# Build bytecode under target/
stoffel build
stoffel build --release

# Compile a project, source directory, or single file
stoffel compile
stoffel compile src/main.stfl --output target/debug/main.stflb
stoffel compile src/main.stfl -O3 --output target/release/main.stflb

# Disassemble bytecode
stoffel compile --disassemble target/debug/my-project.stflb

Stoffel bytecode uses the .stflb extension. Optimization flags accepted by compile, build, and source-compiling run include:

stoffel build -O0
stoffel build -O 2
stoffel build --opt-level 3
stoffel build --optimize      # O2 unless --release selects O3
stoffel build --release       # writes under target/release

Running programs

# Run the current project through local MPC
stoffel run

# Run a source file or bytecode file
stoffel run src/main.stfl
stoffel run target/debug/my-project.stflb

# Select an entry function
stoffel run --entry main
stoffel run --function main

# Pass named function inputs
stoffel run --input a=40 --input b=2

# Load named inputs from json/csv/txt
stoffel run --input-file inputs.json

# Print function and instruction metadata before executing
stoffel run --program-info

For programs that use ClientStore.take_share, provide client-provided private inputs by numeric slot:

stoffel run \
  --client-input 0=42 \
  --expected-output-clients 1 \
  --parties 5 \
  --threshold 1

Local MPC is the default unless --network or --config is set. A local run spawns several MPC nodes/processes on your machine using the configured parties and threshold.

Development watch mode

stoffel dev runs a project through local MPC, then watches Stoffel.toml and source files for changes:

stoffel dev \
  --parties 5 \
  --threshold 1

For scripts and CI, run once and exit:

stoffel dev --once

Tune watch latency with --poll-ms:

stoffel dev --poll-ms 250

Testing

stoffel test runs no-argument test functions from a project or test file. By default it searches recursively under tests/.

stoffel test
stoffel test tests/math.stfl
stoffel test --test addition
stoffel test --verbose

Use local MPC execution for tests that need several local MPC nodes instead of the embedded no-network test runner:

stoffel test

Status, clean, and update

# Project health and environment diagnostics
stoffel status
stoffel doctor --verbose

# Remove generated target artifacts
stoffel clean
stoffel clean --dry-run
stoffel clean --all

# Check update actions without mutating files
stoffel update --check

# Reinstall the CLI from a source checkout
stoffel update --self-from-source

Debugging tips

Run stoffel check --print-ir before investigating runtime behavior.
Run stoffel run --program-info to inspect function and instruction metadata.
Use stoffel compile --disassemble <file.stflb> to inspect bytecode.
Use the Rust SDK wrapper when you want application code to compile and run the same Stoffel program.

​Core workflow

​Creating projects

​Project structure

​Stoffel.toml

​Checking and compiling

​Running programs

​Development watch mode

​Testing

​Status, clean, and update

​Debugging tips

​Next steps