Built-in Functions - Stoffel Documentation

Stoffel VM registers standard runtime builtins and MPC-focused module-style builtins. In normal application code, prefer StoffelLang method/operator syntax where available; this page names the VM functions those features lower to.

General runtime builtins

The standard library includes object, array/list, closure, local storage, formatting, assertion, and output helpers.

Builtin group	Names
Objects and arrays	`create_object`, `create_array`, `get_field`, `get_or_create_array_field`, `set_field`, `array_length`, `array_push`, `array_concat`, `array_repeat`, `array_equals`
List-style aliases	`append`, `extend`, `copy`, `count`, `index`, `pop`, `remove`, `insert`, `clear`, `reverse`, `sort`, `delete`, `len`, `range`
Closures/upvalues	`create_closure`, `call_closure`, `get_upvalue`, `set_upvalue`
Runtime helpers	`print`, `type`, `to_string`, `slice`, `contains`, `assert`
Local storage	`LocalStorage.store`, `LocalStorage.load`, `LocalStorage.retrieve`, `LocalStorage.delete`, `LocalStorage.exists`

print is variadic: it formats arguments, joins them with spaces, and writes one line through the VM’s configured output sink. In StoffelLang, prefer method syntax where the language exposes it:

def main() -> int64:
  var values: list[int64] = []
  values.append(10)
  values.append(20)
  return values.len()

Share values represent MPC secret shares. The VM exposes these canonical share operations:

Share.from_clear
Share.from_clear_int
Share.from_clear_uint
Share.from_clear_fixed
Share.add
Share.sub
Share.neg
Share.add_scalar
Share.mul_scalar
Share.mul
Share.batch_mul
Share.open
Share.batch_open
Share.send_to_client
Share.interpolate_local
Share.get_type
Share.get_party_id
Share.open_exp
Share.random
Share.random_field
Share.random_int
Share.get_commitment
Share.commitment_count
Share.has_commitments
Share.mul_field
Share.add_field
Share.retag
Share.open_field
Share.open_exp_custom

StoffelLang also supports typed secret values and operators. Prefer this shape in app examples when the scalar type is known:

def compute(a: secret int64, b: secret int64) -> int64:
  var sum: secret int64 = a + b
  var product: secret int64 = sum * 2
  return product.reveal()

Method/function forms remain useful when you want to call a specific builtin directly:

def compute(a: Share, b: Share) -> int64:
  var sum = Share.add(a, b)
  var scaled = sum.mul_scalar(2)
  return scaled.open()

Opening or revealing a share reconstructs a clear value. Do this only at the point where the program intentionally discloses a result.

Batch operations

Use batch operations when a program naturally computes or returns several shares.

def main() -> list[int64]:
  var left = Share.from_clear(40)
  var right = Share.from_clear(2)
  var values: list[Share] = [left, right, left.add(right)]
  return Share.batch_open(values)

Share.batch_mul is the VM builtin for batched share multiplication; use it when the algorithm already has aligned share arrays and should consume MPC multiplication material in batch form.

ClientStore builtins

ClientStore bridges external client input material into a Stoffel program. VM-level client slots are ordinal positions in the configured/sorted client roster, not necessarily raw network client IDs.

Builtin	Purpose
`ClientStore.get_number_clients()`	Total known client slots.
`ClientStore.get_number_input_clients()`	Number of clients with input material.
`ClientStore.get_number_output_clients()`	Number of output-capable client slots.
`ClientStore.take_share(client_slot, input_index)`	Load a default integer share from a client slot.
`ClientStore.take_share_bool(client_slot, input_index)`	Load a one-bit boolean share from a client slot.
`ClientStore.take_share_fixed(client_slot, input_index)`	Load a fixed-point share from a client slot.

Example:

def main() -> int64:
  var client_count = ClientStore.get_number_clients()
  var share: secret int64 = ClientStore.take_share(0, 0)
  return share.reveal() + client_count

CLI local execution:

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

Rust SDK local execution:

use stoffel::prelude::*;

# async fn example() -> stoffel::Result<()> {
let result = Stoffel::load_file("target/debug/hello-mpc.stflb")?
    .parties(5)
    .threshold(1)
    .with_client_input(0, &[42_i64])
    .execute_local()
    .await?;
# Ok(())
# }

Mpc builtins

Mpc exposes runtime metadata, readiness, capabilities, and public randomness helpers.

Mpc.party_id
Mpc.n_parties
Mpc.threshold
Mpc.is_ready
Mpc.instance_id
Mpc.protocol_name
Mpc.curve
Mpc.field
Mpc.has_capability
Mpc.capabilities
Mpc.rand
Mpc.rand_int

Mpc.rand and Mpc.rand_int produce local public randomness. For jointly generated secret-shared randomness, use Share.random or Share.random_int. Capability names include:

multiplication
elliptic-curves
client-input
consensus
open-in-exponent
reservation
client-output
randomness
field-open
preprocessing-persistence

Mpc.has_capability(...) accepts common aliases such as mul, rbc, open-exp, and preproc-store. Example:

def main() -> int64:
  var score: int64 = Mpc.party_id()
  score = score + Mpc.n_parties()
  score = score + Mpc.threshold()

  if Mpc.is_ready():
    score = score + 10

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

  return score

MpcOutput builtins

Use MpcOutput.send_to_client when a program should deliver share outputs to client slots through the coordinator/output path. It accepts a client slot and either a single share or a non-empty homogeneous array/list of shares:

def main() -> int64:
  var client_count = ClientStore.get_number_clients()
  var result: secret int64 = ClientStore.take_share(0, 0) + 5

  if Mpc.has_capability("client-output"):
    MpcOutput.send_to_client(0, [result])

  return client_count

Share.send_to_client(client_slot) is also available for single-share output flows.

Lower-level protocol helper modules

The VM also registers module-style helpers used by advanced protocol and cryptographic examples:

Module	Purpose
`Bytes.*`	Byte-array construction, concatenation, conversion, slicing, and length helpers.
`Crypto.*`	Hashing and signature-related helper functions used by protocol examples.
`Field.*`	Field-oriented helper functions.
`Rbc.*`	Reliable broadcast helpers.
`Avss.*`	AVSS share inspection helpers for commitments and key names. See AVSS.

Treat these as lower-level integration surfaces. Prefer checked examples in crates/stoffel-lang/examples/ before documenting production-facing patterns around them. Current AVSS helper names:

Avss.get_commitment
Avss.get_key_name
Avss.commitment_count
Avss.is_avss_share

​General runtime builtins

​Share builtins

​Batch operations

​ClientStore builtins

​Mpc builtins

​MpcOutput builtins

​Lower-level protocol helper modules

​See also