Compilation - Stoffel Documentation

StoffelLang source files (.stfl) compile to portable Stoffel bytecode files (.stflb). The current compiler lives in crates/stoffel-lang; the primary user-facing entry points are the stoffel CLI and Rust SDK.

Pipeline

The compiler validates .stfl source, lowers it to VM function metadata and instructions, then writes the .stflb artifact that the CLI, SDK, and VM can load.

Validate without writing bytecode

stoffel check
stoffel check src/main.stfl
stoffel check src
stoffel check --print-ir

check reads project defaults from Stoffel.toml unless you pass a source path. MPC settings can be overridden:

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

Build a project

stoffel build
stoffel build --release
stoffel build --print-ir

build writes bytecode under target/debug or target/release.

Compile a source file

stoffel compile src/main.stfl --output target/debug/main.stflb
stoffel compile src/main.stfl -O3 --output target/release/main.stflb

When compiling one selected source file, use --output to choose the bytecode path.

Optimization flags

stoffel compile src/main.stfl -O0 --output target/debug/main.stflb
stoffel compile src/main.stfl -O 2 --output target/debug/main.stflb
stoffel compile src/main.stfl --opt-level 3 --output target/release/main.stflb
stoffel build --optimize
stoffel build --release

--optimize uses O2 unless --release selects O3. --release writes under target/release and uses O3 unless --opt-level is set.

Disassemble bytecode

stoffel compile --disassemble target/debug/main.stflb

Use disassembly to confirm generated functions, instructions, and metadata before debugging runtime behavior.

Run after compiling

stoffel run target/debug/main.stflb --entry main
stoffel run src/main.stfl --input a=40 --input b=2
stoffel run --program-info

For local MPC runs, use the CLI local MPC path and provide any required client-slot inputs:

stoffel run --client-input 0=42 --parties 5 --threshold 1

Validate repository examples

The repository examples are runnable programs under crates/stoffel-lang/examples/. From the Stoffel repository root, compile the examples and run local-only examples through the VM with:

cd crates/stoffel-lang
./examples/validate_examples.sh

Compiled bytecode is written to examples/dist/. Use the runnable examples guide to choose examples by task.

Common errors

`secret` placement

Use secret inside type annotations for share values:

def compute(x: secret int64) -> secret int64:
  var doubled: secret int64 = x * 2
  return doubled

Do not use secret as a declaration modifier before def or var. The accepted form is var x: secret int64 = ..., not secret var x = ....

Secret control flow

Do not branch on secret values. Reveal/open only the output you intend to disclose, or keep values as Share / secret T and send them to a client output path.

​Pipeline

​Validate without writing bytecode

​Build a project

​Compile a source file

​Optimization flags

​Disassemble bytecode

​Run after compiling

​Validate repository examples

​Common errors

​secret placement

​Secret control flow

​See also