> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stoffelmpc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StoffelLang Overview

> The current Stoffel language for clear local logic and MPC-aware computations compiled to Stoffel VM bytecode.

StoffelLang is the application language compiled by the `stoffellang` crate in the `stoffel` repository. It uses Python-like indentation, `def` functions, `var` bindings, static type annotations, lists, objects, closures, and explicit MPC share APIs.

Prefer examples from [`crates/stoffel-lang/examples/`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples), the generated project template, and the Rust SDK examples over older syntax outside the documented `def`/`var`/`.stflb` workflow. Use the [runnable examples guide](./examples) to choose examples by task.

## Design goals

* Familiar Python-style control flow and indentation.
* Static types with inference for local development ergonomics, including `secret T` annotations for share-typed private values.
* Direct compilation to portable `.stflb` Stoffel VM bytecode.
* Explicit share-oriented MPC APIs such as `Share.*`, `ClientStore.*`, `Mpc.*`, and `MpcOutput.*`, plus operator syntax for share arithmetic.
* Host integration through the CLI and Rust SDK.

## A minimal program

```stoffel theme={null}
def add(a: int64, b: int64) -> int64:
  return a + b

def main() -> int64:
  return add(40, 2)
```

Compile and run it from a project or as a source file:

```bash theme={null}
stoffel check src/main.stfl
stoffel build
stoffel run --entry main
```

## Variables and types

Use `var` for local bindings. Type annotations are optional when the compiler can infer the type.

```stoffel theme={null}
def main() -> int64:
  var count: int64 = 42
  var message = "hello"
  var ready = true
  discard message
  discard ready
  return count
```

Current primitive and runtime-facing types include:

* signed integers: `int8`, `int16`, `int32`, `int64`
* unsigned integers: `uint8`, `uint16`, `uint32`, `uint64`
* `bool`
* `string`
* `None` / no-value returns
* `Share` and `secret T` types such as `secret int64` for MPC secret shares
* `list[T]`
* object and closure values used by the VM runtime

The `secret` keyword is part of type annotations. Use it on parameters, return types, local variables, list elements, and object fields when a value is represented as an MPC share:

```stoffel theme={null}
def weighted_score(raw: secret int64, weight: int64) -> secret int64:
  var scaled: secret int64 = raw * weight
  return scaled + 10
```

Do not put `secret` before `def` or `var`; write `var score: secret int64 = ...`, not `secret var score = ...`.

## Functions

```stoffel theme={null}
def multiply(a: int64, b: int64) -> int64:
  return a * b

def log_message(message: string) -> None:
  print(message)
```

The CLI and SDK default to executing `main`, but most commands can select another entry function:

```bash theme={null}
stoffel run --entry multiply --input a=6 --input b=7
```

## Control flow

```stoffel theme={null}
def fibonacci(n: int64) -> int64:
  if n <= 1:
    return n

  var previous: int64 = 0
  var current: int64 = 1
  var index: int64 = 2

  while index <= n:
    var next: int64 = previous + current
    previous = current
    current = next
    index = index + 1

  return current
```

Ranges and list iteration are supported:

```stoffel theme={null}
def checksum(limit: int64) -> int64:
  var total: int64 = 0

  for value in 1..limit:
    total += value

  return total
```

## Lists

```stoffel theme={null}
def main() -> int64:
  var scores: list[int64] = []
  scores.append(72)
  scores.append(41)
  scores.append(93)

  scores[1] = scores[1] + 10

  var total: int64 = 0
  for score in scores:
    total += score

  return total + scores.len()
```

## MPC share APIs

StoffelLang models MPC values explicitly as share values. You can write those values with the generic `Share` type or with typed secret annotations such as `secret int64`, `secret bool`, or `secret fix64`. Use `ClientStore` to read client-provided shares, regular operators such as `+`, `-`, `*`, and `/` for arithmetic when they fit the value shape, and `reveal()`, `Share.open(...)`, or `MpcOutput.send_to_client` where your program intentionally reconstructs or delivers a result.

```stoffel theme={null}
def add_private_values(a: secret int64, b: secret int64) -> int64:
  var sum = a + b
  return sum.reveal()
```

Method-style calls are also available when you want to call a specific share builtin directly:

```stoffel theme={null}
def normalize(raw_score: secret int64) -> secret int64:
  var adjusted = raw_score.add_scalar(25)
  return adjusted * 2
```

Boolean and fixed-point secret values use the same type-annotation pattern:

```stoffel theme={null}
def gate(a: secret bool, b: secret bool) -> secret bool:
  var not_a: secret bool = 1 - a
  return not_a * b

def half(value: secret fix64) -> secret fix64:
  return value / 2.0
```

## ClientStore inputs

`ClientStore` exposes local or network client input slots to the program:

```stoffel theme={null}
def main() -> int64:
  var client_count = ClientStore.get_number_clients()
  var share = ClientStore.take_share(0, 0)
  var opened: int64 = share.open()
  return opened + client_count
```

When running locally through the CLI, provide client-slot inputs with `--client-input`:

```bash theme={null}
stoffel run --client-input 0=42 --parties 5 --threshold 1
```

With the Rust SDK, use `.with_client_input(0, &[42_i64])`.

## Runtime metadata

MPC programs can query runtime metadata and capabilities:

```stoffel theme={null}
def main() -> int64:
  var score: int64 = Mpc.party_id()
  score = score + Mpc.n_parties()
  score = score + Mpc.threshold()

  if Mpc.has_capability("multiplication"):
    score = score + 100

  discard Mpc.protocol_name()
  discard Mpc.curve()
  discard Mpc.field()
  discard Mpc.instance_id()
  return score
```

## Compilation outputs

The current bytecode extension is `.stflb`:

```bash theme={null}
stoffel compile src/main.stfl --output target/debug/main.stflb
stoffel compile --disassemble target/debug/main.stflb
```

`stoffel build` writes project bytecode under `target/debug` or `target/release` depending on the selected profile.

## Examples in the repository

Runnable examples live under [`crates/stoffel-lang/examples/`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples). Start with the [examples guide](./examples) when you want source-level patterns for clear StoffelLang, client-provided private inputs, share arithmetic, reusable MPC building blocks, or larger private workflows.

## Next steps

* [Syntax and Examples](./syntax)
* [Runnable Examples](./examples)
* [Compilation](./compilation)
* [Built-in Functions](../stoffel-vm/builtins)
* [Rust SDK Examples](../rust-sdk/examples)