Skip to main content
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 portable public dependencies by default. A local checkout is a separate, nonportable framework-development workflow and is allowed only when explicitly requested.

​
Use when

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

​
Current source of truth

Use the public docs when available, then verify against the current 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.

​
Mandatory portability contract

Apply these rules before installing dependencies or creating files:
  1. Discover and confirm the project root from the current working directory and repository markers such as Stoffel.toml, Cargo.toml, or .git. Do not invent or require a machine-specific path such as /workspace/....
  2. Resolve Stoffel and related project dependencies from public, reproducible sources in this order: the current crates.io release, then the official GitHub repository pinned to a full immutable commit SHA when the needed change is not published.
  3. Never use a floating branch or require a local path, sibling checkout, or other external filesystem checkout for the default app path.
  4. Use a local Stoffel checkout only when the user explicitly requests framework development. Label that workflow nonportable and keep it separate from the default instructions below.
  5. If no suitable public dependency is available, stop and report the missing dependency and attempted public sources. Do not silently replace it with a local path.
This playbook stays version-agnostic. Obtain concrete versions from the installation docs and record them in the app’s dependency manifest.

​
Prerequisites

  • Rust stable and Cargo.
  • The stoffel CLI from the documented installation path.
  • Crates.io dependencies for Rust SDK work.

​
Install

Install the CLI:

​
Create the first app

The default project template includes a Rust wrapper as well as .stfl source. Run the wrapper too:

​
Know the app shape

A new app normally includes:
  • 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

For client-owned private input in a multi-user or networked application, first complete the trust architecture in Stoffel Full App Golden Path. Each participant-owned client should submit directly to the separately deployed MPC service; the application control plane must not receive or persist plaintext. Then use Stoffel App Network and Off-Chain Integration for the direct client path and runtime capability gate.
  • CLI-only path: mostly .stfl source and trusted 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 workflows that need real local party execution before network/off-chain work; local fixture injection is not production private-data-plane evidence.
  • Network/off-chain path: advanced client/server/coordinator integration after the local smoke passes.

​
Fast examples to inspect

  • At the full immutable official GitHub commit selected by the portability contract, inspect clear language basics under crates/stoffel-lang/examples/local_control_flow, local_collections, and local_text_processing.
  • Inspect the first private input flow at crates/stoffel-lang/examples/mpc_client_private_score in that same official source revision.
  • Inspect the ClientStore gallery under crates/stoffel-lang/examples/bits/secret/*, matrix/secret/*, polynomials/secret/*, number_theory/secret/*, and the app-level mpc_* algorithm examples in that revision.
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:
For Rust wrapper apps, also collect output from:
For a secret ClientStore example, include its documented # run-args: flags and --expected-output-clients if present.

​
Common pitfalls

  • For app development, use the public dependency precedence in the portability contract; do not recommend a local path dependency.
  • Do not confuse browsing examples in an official source revision with requiring that repository as a sibling checkout.
  • 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