> ## 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.

# Syntax and Examples

> Current StoffelLang syntax for functions, variables, control flow, lists, Share values, and ClientStore inputs.

StoffelLang uses Python-like indentation, `def` functions, `var` bindings, static types, lists, and explicit MPC share APIs. Programs compile to `.stflb` bytecode and are run through the `stoffel` CLI or Rust SDK.

## Comments

```stoffel theme={null}
# Single-line comment
def main() -> int64:
  var value = 42  # inline comment
  return value
```

## Functions and entry point

Functions use `def`. The default entry point is a function named `main`:

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

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

Select another entry point with the CLI when needed:

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

## Variables and primitive types

Use `var` for local bindings. Type annotations are optional when inference is clear.

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

  discard message
  discard ready
  return count
```

Common types:

* signed integers: `int8`, `int16`, `int32`, `int64`
* unsigned integers: `uint8`, `uint16`, `uint32`, `uint64`
* `bool`
* `string`
* `Share` and typed secret values such as `secret int64`
* `list[T]`
* `None` for no-value returns

## 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()
```

## Share and `secret` values

`Share` values represent private MPC values. You can also use the `secret` keyword in type annotations, such as `secret int64`, `secret bool`, or `secret fix64`, to declare typed share values. Keep sensitive values as shares while computing, then reveal, open, or send only the output you intend to disclose.

`secret` is valid inside type annotations for parameters, returns, locals, list elements, and object fields. It is not a declaration modifier: use `var x: secret int64 = ...`, not `secret var x = ...`.

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

def main() -> int64:
  var private_score: secret int64 = ClientStore.take_share(0, 0)
  var eligibility = normalize_score(private_score)
  return eligibility.reveal()
```

For arithmetic, use normal operators when they fit the value shape:

```stoffel theme={null}
def compute(a: secret int64, b: secret int64) -> int64:
  var total = a + b
  var delta = a - b
  var product = total * delta
  var ratio = product / 2
  return ratio.reveal()
```

The same operator style works for secret booleans and fixed-point values where the operation is supported:

```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
```

You can still call share operations as methods or functions when you want a specific builtin:

```stoffel theme={null}
def compute(a: Share, b: Share) -> int64:
  var sum = Share.add(a, b)
  var scaled = sum.mul_scalar(2)
  return scaled.open()
```

## ClientStore inputs

`ClientStore` reads external client input slots during local or network MPC execution.

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

Run locally with a client-slot input:

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

With the Rust SDK, pass the same slot input using `.with_client_input(0, &[42_i64])`.

## Runtime metadata

```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
```

## Runnable examples for this page

Use the [runnable examples guide](./examples) for a guided path through the examples. For the syntax on this page, these examples are the most direct references:

* [`local_control_flow`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/local_control_flow) for functions, loops, ranges, branching, and arithmetic.
* [`local_collections`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/local_collections) and [`local_nested_generics`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/local_nested_generics) for lists and nested generic list shapes.
* [`mpc_share_arithmetic`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/mpc_share_arithmetic) and [`mpc_boolean_circuit`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/mpc_boolean_circuit) for share arithmetic and `secret bool` values.
* [`mpc_client_private_score`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/mpc_client_private_score) and [`mpc_client_federated_average`](https://github.com/Stoffel-Labs/stoffel/tree/main/crates/stoffel-lang/examples/mpc_client_federated_average) for `ClientStore` input slots and client-output patterns.

## Build and run

```bash theme={null}
stoffel check
stoffel build
stoffel run --client-input 0=42 --parties 5 --threshold 1
stoffel compile --disassemble target/debug/<project>.stflb
```

## See also

* [StoffelLang Overview](./overview)
* [Runnable Examples](./examples)
* [Compilation](./compilation)
* [Built-in Functions](../stoffel-vm/builtins)