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

# API Reference

> Current Rust SDK API surface for compiling, loading, executing, and configuring Stoffel programs.

Import the SDK through the `stoffel` crate name:

```rust theme={null}
use stoffel::prelude::*;
```

The Cargo package is `stoffel-rust-sdk`, but the library crate is `stoffel`.

## Program entry points

```rust theme={null}
// Compile source text. Useful for small tests.
Stoffel::compile(source)?

// Compile a source file. Useful for tooling.
Stoffel::compile_file("src/main.stfl")?

// Load compiled bytecode bytes.
Stoffel::load(&bytecode)?

// Load compiled bytecode from disk. Preferred for app wrappers after `stoffel build`.
Stoffel::load_file("target/debug/hello-mpc.stflb")?

// Load an executable runtime directly from bytes, a PathBuf, or a Program.
Stoffel::load_program(std::path::PathBuf::from("target/debug/hello-mpc.stflb"))?
```

For app integrations, prefer `stoffel build` followed by `Stoffel::load_file(...)` so Rust code executes the same `.stflb` artifact that the CLI checked and built.

## Builder configuration

```rust theme={null}
Stoffel::load_file("target/debug/hello-mpc.stflb")?
    .parties(5)
    .threshold(1)
    .instance_id(1)
    .backend(MpcBackend::HoneyBadger)
    .build()?;
```

Common settings:

| Method                                                   | Purpose                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `.parties(n)`                                            | Number of MPC parties/nodes for local or network execution.                     |
| `.threshold(t)`                                          | Fault/security threshold. Current local/network config validates `n >= 4t + 1`. |
| `.instance_id(id)`                                       | Computation instance identifier.                                                |
| `.backend(MpcBackend::HoneyBadger)`                      | Select HoneyBadgerMPC, the default field-arithmetic backend.                    |
| `.backend(MpcBackend::Avss { curve })`                   | Select AVSS for group/scalar workflows and threshold-cryptography examples.     |
| `.curve(Curve::Secp256k1)`                               | Shortcut for selecting AVSS with a specific curve.                              |
| `.compiler_options(options)`                             | Adjust compilation when compiling source.                                       |
| `.network_config(config)` / `.network_config_file(path)` | Configure network client execution.                                             |

Supported AVSS curves include `Curve::Bls12_381`, `Curve::Bn254`, `Curve::Curve25519`, `Curve::Ed25519`, `Curve::Secp256k1`, and `Curve::Secp256r1`. See [MPC Protocols](../mpc-protocols/overview) for backend selection guidance.

## Inputs

Named function inputs:

```rust theme={null}
.with_inputs(&[("a", 40_i64), ("b", 2_i64)])
.with_input("a", 40_i64)
.with_input_file("inputs.json")?
```

ClientStore inputs:

```rust theme={null}
.with_client_input(0, &[42_i64])
.with_client_input_file("client-inputs.json")?
```

`with_client_input(0, &[42_i64])` supplies values read by StoffelLang calls such as `ClientStore.take_share(0, 0)`.

## Execution

Clear execution is synchronous and skips MPC. Use it for fast logic checks:

```rust theme={null}
let result = Stoffel::compile("def main(a: int64, b: int64) -> int64:\n  return a + b")?
    .with_inputs(&[("a", 40_i64), ("b", 2_i64)])
    .execute_clear()?;
```

Local MPC execution is async and runs a local MPC test network on your machine:

```rust theme={null}
# 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(())
# }
```

Named-function local MPC execution:

```rust theme={null}
# async fn example() -> stoffel::Result<()> {
let result = Stoffel::load_file("target/debug/hello-mpc.stflb")?
    .parties(5)
    .threshold(1)
    .with_inputs(&[("a", 40_i64), ("b", 2_i64)])
    .execute_local_function("add_private_values")
    .await?;
# Ok(())
# }
```

## Runtime and bytecode helpers

```rust theme={null}
let runtime = Stoffel::compile_file("src/main.stfl")?
    .parties(5)
    .threshold(1)
    .build()?;

runtime.save_bytecode("target/debug/hello-mpc.stflb")?;
let bytecode = runtime.to_bytecode()?;
let summary = runtime.bytecode_summary()?;
let program = runtime.program();
```

## Program metadata

A loaded runtime exposes program metadata used by generated bindings and debugging tools:

```rust theme={null}
let runtime = Stoffel::load_file("target/debug/hello-mpc.stflb")?.build()?;
let program = runtime.program();

println!("functions={}", program.function_count());
if let Some(client) = program.client(0) {
    println!("client slot {} inputs={}", client.client_slot(), client.input_count());
}
```

## Network configuration

The SDK can generate network configuration files for deployments where MPC nodes run separately from input/output clients:

```rust theme={null}
let deployment = NetworkDeployment::builder([
    "127.0.0.1:19200",
    "127.0.0.1:19201",
    "127.0.0.1:19202",
    "127.0.0.1:19203",
    "127.0.0.1:19204",
])
.expected_clients(1)
.threshold(1)
.backend(MpcBackend::HoneyBadger)
.preprocessing(1000, 500)
.build()?;

let paths = deployment.save_toml_files("./network-configs")?;
let config = NetworkConfig::from_toml_file(&paths[0])?;
let server = StoffelServer::builder(0).network_deployment(&deployment).build()?;
let client = StoffelClient::builder().network_config(&config).build()?;
```

For most application developers, start with CLI builds and `.execute_local().await?` before using network configuration directly.

Use `MpcBackend::Avss { curve: Curve::Bls12_381 }` for AVSS network/client experiments that use the current SDK off-chain client I/O path. Other AVSS curves are selectable for bytecode/runtime paths and curve-aware StoffelLang examples; validate the client/network path before relying on a specific curve.

## Errors and observability

```rust theme={null}
let tracing = TracingConfig::builder()
    .service_name("stoffel-app")
    .ansi(false)
    .build();

let error = Error::Preprocessing("not enough triples".to_owned());
println!("category={} recoverable={}", error.category(), error.is_recoverable());
println!("tracing={:?}", tracing.summary());
```

## See also

* [Rust SDK Overview](./overview)
* [Examples](./examples)
* [CLI Overview](../cli/overview)
* [MPC Protocols](../mpc-protocols/overview)