Stoffel Local MPC Dev Loop

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: app dependencies come from current public crates.io releases by default. Use a full pinned revision of the official GitHub repository only as fallback; reserve local paths for explicit nonportable framework development.

Use when

Use this playbook when an app needs local MPC smoke testing, ClientStore input runs, hot reload, or SDK local coordinator-backed execution.

Goal

Give developers a repeatable local loop for testing private/MPC apps before any real network deployment. Local MPC is a verification gate, not the production topology.

Current source of truth

crates/stoffel-cli/src/main.rs
crates/stoffel-rust-sdk/README.md
crates/stoffel-rust-sdk/src/runtime.rs
crates/stoffel-lang/examples/README.md
crates/stoffel-lang/examples/**/*.stfl

CLI local run

stoffel run --timeout-secs 180
stoffel run path/to/main.stfl --timeout-secs 180
stoffel run target/debug/app.stflb --program-info --timeout-secs 180

Local mode is the default unless --network or --config is set.

Hot reload

stoffel dev --once --timeout-secs 180
stoffel dev --poll-ms 500 --timeout-secs 180

Use --once for CI/smoke checks and default watch mode during interactive development.

Input paths

Named function args:

stoffel run --input a=40 --input b=2

.with_inputs(&[("a", 40_i64), ("b", 2_i64)])

ClientStore values:

stoffel run --client-input 0=40 --client-input 0=2 --expected-output-clients 1

.with_client_input(0, &[40_i64, 2_i64])
.expected_output_clients(1)

The CLI also supports --input-file and --client-input-file for .json, .csv, and .txt inputs. See Stoffel CLI App Workflow.

Use example `run-args` headers

Many secret examples include the exact local flags in the first source line:

# run-args: --client-input 0=50 --client-input 0=20 --client-input 0=40 --client-input 0=10 --client-input 0=30 --expected-output-clients 1

Run by appending those flags:

stoffel run crates/stoffel-lang/examples/mpc_top_k/main.stfl \
  --client-input 0=50 --client-input 0=20 --client-input 0=40 \
  --client-input 0=10 --client-input 0=30 \
  --expected-output-clients 1 \
  --timeout-secs 180

For repeated client slots, order matters: --client-input 0=50 --client-input 0=20 maps to ClientStore.take_share(0, 0) then ClientStore.take_share(0, 1).

SDK local run

For a Rust app, use the version from the current SDK installation docs and commit Cargo.lock:

[dependencies]
stoffel = { package = "stoffel-rust-sdk", version = "<current-docs-version>" }

If a needed change is not released, use git = "https://github.com/Stoffel-Labs/stoffel.git" with rev = "<full-40-character-commit-sha>". Do not substitute branch = "main". A path = "../stoffel/crates/stoffel-rust-sdk" dependency is nonportable and is valid only when deliberately testing framework source.

let result = runtime
    .local_network()
    .entry("main")
    .timeout(std::time::Duration::from_secs(180))
    .run()
    .await?;

Builder shortcut:

let source = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
    .join("src/main.stfl");
let result = Stoffel::compile_file(source)?
    .parties(5)
    .threshold(1)
    .with_client_input(0, &[42_i64])
    .expected_output_clients(1)
    .execute_local()
    .await?;

Recommended local loop

Resolve the app root from an explicit argument, manifest, or the script’s own location; do not assume the caller’s CWD.
Run stoffel status --verbose "$APP_ROOT".
Run stoffel check "$APP_ROOT" to catch syntax/config/type errors.
Run stoffel build "$APP_ROOT" --program-info to inspect bytecode and client IO metadata.
Run stoffel run "$APP_ROOT" --timeout-secs 180 with named inputs or documented # run-args: flags.
If using Rust, run cargo check --locked and cargo run --locked with an explicit --manifest-path against the same bytecode/source.
Inspect cargo metadata --locked and prove the app in a clean external checkout.
Record the exact command/output in the app handoff.
Only then move to network/off-chain config with Stoffel Deployment Runbook.

For a repository script, derive a stable root from the script path:

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
APP_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
APP_MANIFEST="$APP_ROOT/Cargo.toml"
STOFFEL_ROOT="$APP_ROOT"
if [ ! -f "$STOFFEL_ROOT/Stoffel.toml" ] && [ -f "$APP_ROOT/stoffel/Stoffel.toml" ]; then
  STOFFEL_ROOT="$APP_ROOT/stoffel"
fi
test -f "$STOFFEL_ROOT/Stoffel.toml"

stoffel check "$STOFFEL_ROOT"
cargo check --locked --manifest-path "$APP_MANIFEST"
cargo metadata --locked --format-version 1 --manifest-path "$APP_MANIFEST" \
  > "$APP_ROOT/cargo-metadata.json"

The Stoffel package in metadata must have a registry+... source or a pinned official git+...#<full-sha> source. source: null exposes a local path/workspace dependency.

Validation / done criteria

For app local-MPC work:

stoffel status --verbose "$STOFFEL_ROOT"
stoffel check "$STOFFEL_ROOT"
stoffel build "$STOFFEL_ROOT" --program-info
stoffel run "$STOFFEL_ROOT" --timeout-secs 180 <inputs or documented run-args>
cargo check --locked --manifest-path "$APP_ROOT/Cargo.toml"

Commit Cargo.lock, then clone the app into a temporary directory outside the framework checkout (with no sibling ../stoffel) and rerun the locked check and local smoke. A pass inside the framework repository alone is insufficient portability proof. For framework example validation:

FRAMEWORK_ROOT="/absolute/path/to/stoffel"
"$FRAMEWORK_ROOT/crates/stoffel-lang/examples/validate_examples.sh"
STOFFEL_PROGRAM_NAME=mpc_runtime_info.stflb \
  "$FRAMEWORK_ROOT/crates/stoffel-lang/examples/validate_examples.sh" --host-mpc

Common pitfalls

Compile-only success is not a local MPC smoke test.
A local MPC pass backed by an adjacent path dependency is not a portable app proof.
Do not let cargo run update the graph implicitly; commit the lockfile and use --locked.
Do not encode framework checkout locations or assume commands start at the repository root.
Local MPC success is not production deployment; it only proves the program and app boundary work on the local test network.
Increase --timeout-secs before assuming protocol failure.
Avoid port/process collisions by serializing tests that spawn local party meshes.
Keep ClientStore inputs separate from named function inputs.
Do not omit --expected-output-clients for examples/programs that send client outputs.
AVSS support is backend/curve/input dependent; verify the current SDK boundary.

Overview

App Development Skills

Use when

Goal

Current source of truth

CLI local run

Hot reload

Input paths

Use example `run-args` headers

SDK local run

Recommended local loop

Validation / done criteria

Common pitfalls

​Use when

​Goal

​Current source of truth

​CLI local run

​Hot reload

​Input paths

​Use example run-args headers

​SDK local run

​Recommended local loop

​Validation / done criteria

​Common pitfalls

Use when

Goal

Current source of truth

CLI local run

Hot reload

Input paths

Use example `run-args` headers

SDK local run

Recommended local loop

Validation / done criteria

Common pitfalls