Skip to main content

​
Stoffel App Getting Started

Scope: AI-agent-agnostic playbook for building applications with the Stoffel framework. This is not a maintainer guide for compiler, VM, protocol, or release engineering work. Dependency assumption: use the public 0.1.0 install snippets from these docs. When developing against a local checkout, make that source-based workflow explicit.

​
Use when

Use this playbook when a developer or coding agent needs the shortest path from an empty directory to a working Stoffel application.

​
Current source of truth

Use the public docs when available, then verify against the 0.1.0 app-facing repo surfaces:
  • README.md
  • crates/stoffel-cli/src/main.rs
  • crates/stoffel-cli/src/project.rs
  • crates/stoffel-lang/examples/README.md
  • crates/stoffel-rust-sdk/README.md
These are source-inspection references for app behavior, not instructions for app developers to edit framework internals.

​
Prerequisites

  • Rust stable and Cargo.
  • The stoffel CLI from the documented 0.1.0 installation path.
  • A local checkout of the stoffel repository for source-based 0.1.0 development.
  • For local MPC execution: a stoffel-run helper binary available through PATH, --runner, STOFFEL_RUN_BIN, or the SDK builder.

​
Install

Preferred public flow after publication: 
cargo install stoffel-cli
stoffel --help
Local checkout flow for source-based 0.1.0 development: 
cd /path/to/stoffel
cargo install --path crates/stoffel-cli
cargo build -p stoffel-vm --bin stoffel-run
stoffel --help

​
Create the first app

stoffel init my-stoffel-app
cd my-stoffel-app
stoffel status --verbose
stoffel check
stoffel build
stoffel run --timeout-secs 180
The default project template includes a Rust wrapper as well as .stfl source. For that wrapper, also run: 
cargo build
cargo run

​
Know the app shape

A new app normally has:
  • Stoffel.toml: app metadata, default source path, output target dir, and local MPC defaults.
  • src/main.stfl: the Stoffel program.
  • target/debug/*.stflb: compiled bytecode after stoffel build.
  • Optional wrapper files (Cargo.toml, src/main.rs, src/stoffel_bindings.rs) when using the default or Rust templates.
Stoffel.toml is a project/build config. It is not the network/off-chain client config passed to stoffel run --network --config.

​
Choose a development path

  • CLI-only path: mostly .stfl source and local smoke tests.
  • Rust SDK path: embedding compilation/execution, creating clients/servers, generating typed client IO bindings, or integrating with a Rust service.
  • Local MPC path: private/secret programs that need real local party execution before network/off-chain work.
  • Network/off-chain path: advanced client/server/coordinator integration after the local smoke passes.

​
Fast examples to inspect

  • Clear language basics: crates/stoffel-lang/examples/local_control_flow, local_collections, local_text_processing.
  • First private input flow: crates/stoffel-lang/examples/mpc_client_private_score.
  • ClientStore gallery with run commands: crates/stoffel-lang/examples/bits/secret/*, matrix/secret/*, polynomials/secret/*, number_theory/secret/*, and the app-level mpc_* algorithm examples.
Many secret examples now include a first-line # run-args: header. Copy those flags when running the example locally.

​
Validation / done criteria

A first-app task is complete only when real output has been collected from: 
stoffel status --verbose
stoffel check
stoffel build
stoffel run --timeout-secs 180
For Rust wrapper apps, also collect output from: 
cargo build
cargo run
For a secret ClientStore example, include its documented # run-args: flags and --expected-output-clients if present.

​
Common pitfalls

  • For 0.1.0 development, prefer the documented source dependency or local path dependency.
  • Do not describe Stoffel VM internals unless they explain public app behavior.
  • Do not claim local MPC works until a real run has completed.
  • Do not treat Stoffel.toml as network/off-chain config.
  • Do not omit --expected-output-clients when running examples that send outputs to clients.

​
Next playbooks