Your First MPC Project

This tutorial builds a small eligibility-score computation. The goal is to model one client value as a share, compute over that share, and reconstruct the derived score explicitly.

This is a small local example. Use the same modeling steps with your own deployment and security validation when moving beyond the tutorial.

Campaign-style Stoffel architecture diagram showing how a StoffelLang program becomes app-prepared inputs, a build contract, and networked MPC runtime execution.

What you will use

The stoffel CLI.
The Rust SDK from crates.io when you run or adapt the Rust wrapper path.
A Share-based StoffelLang program.

Finish Installation before starting.

Create a project

stoffel init eligibility-demo
cd eligibility-demo

Check the generated program first:

stoffel check
stoffel build
stoffel run --program-info

Replace `src/main.stfl`

Use this simple Share-based program:

def normalize_score(raw_score: Share) -> Share:
  var adjusted = raw_score.add_scalar(25)
  return adjusted.mul_scalar(2)

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

The program keeps the input as a Share while it computes, then opens only the final eligibility score as the allowed tutorial output.

Validate and build

stoffel check
stoffel build

Inspect the bytecode if needed:

stoffel compile --disassemble target/debug/eligibility-demo.stflb

If your project name produces a different bytecode file name, list target/debug and use that path.

Run locally with a client input

Run the project through local MPC. This starts several MPC nodes/processes locally on your machine and feeds client slot 0 with the private input value:

cd /path/to/eligibility-demo
stoffel run \
  --client-input 0=42 \
  --parties 5 \
  --threshold 1

The returned value is (42 + 25) * 2, not the raw client input.

Iterate in watch mode

stoffel dev \
  --client-input 0=42 \
  --parties 5 \
  --threshold 1

For scripts, add --once.

Run the same idea from Rust

The Rust SDK is the primary application API for embedding Stoffel programs in Rust apps. Use the bytecode you already built from src/main.stfl instead of embedding a second sample program in Rust. In this example, .execute_local().await? performs local MPC testing by spawning several MPC nodes/processes on your machine:

use stoffel::prelude::*;

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

    println!("Result: {}", result[0]);
    Ok(())
}

Shape the local harness like a participant client

This section is a trusted local development harness. The file handoff and .with_client_input(...) call below expose the fixture plaintext to the local harness process. They prove program behavior; they are not a production privacy architecture and must not be moved into an application backend. For client-owned private input in a deployed app, separate these roles:

application control plane  <->  participant-owned client  ->  separately deployed MPC network
public metadata/config          owns plaintext and submits     coordinator and MPC parties
receipts/authorized aggregate   directly through client IO

The application control plane must not receive the private request field. The participant-owned client obtains public session and client-slot configuration, then connects to the MPC deployment directly. If the participant runtime cannot perform direct client submission, stop at that capability gap or use an explicitly participant-controlled sidecar; do not silently add a plaintext backend gateway. For this tutorial, keep everything on your development machine but split the participant client from the trusted local MPC harness:

src/
├── app.rs                  # ordinary app types and non-private decision logic
├── client.rs               # client/request handling boundary
├── lib.rs                  # shared module exports
├── main.stfl               # private MPC program
└── bin/
    ├── local_mpc.rs        # initializes the Stoffel program and local MPC loop
    └── eligibility_client.rs # command-line client handler

Create src/lib.rs:

pub mod app;
pub mod client;

Create src/app.rs for the ordinary application types:

#[derive(Debug, Clone)]
pub struct EligibilityRequest {
    pub account_id: String,
    pub private_score: i64,
    pub public_region: String,
}

#[derive(Debug, Clone)]
pub struct EligibilityDecision {
    pub account_id: String,
    pub public_region: String,
    pub eligibility_score: i64,
    pub approved: bool,
}

pub fn decision_from_score(
    request: EligibilityRequest,
    eligibility_score: i64,
) -> EligibilityDecision {
    EligibilityDecision {
        account_id: request.account_id,
        public_region: request.public_region,
        eligibility_score,
        approved: eligibility_score >= 100,
    }
}

Create src/bin/local_mpc.rs. This is the trusted local development harness: it loads the bytecode built from src/main.stfl, waits for fixture requests, sees the local fixture plaintext, and runs each score through local MPC. It must not be used as an application backend. Stop it with Ctrl-C when you are done.

use std::{fs, path::Path, time::Duration};

use stoffel::prelude::*;
use tokio::time::sleep;

const WORK_DIR: &str = "target/dev-mpc";
const REQUEST_FILE: &str = "target/dev-mpc/request.txt";
const RESPONSE_FILE: &str = "target/dev-mpc/response.txt";

#[tokio::main]
async fn main() -> stoffel::Result<()> {
    fs::create_dir_all(WORK_DIR)?;
    let runtime = Stoffel::load_file("target/debug/eligibility-demo.stflb")?
        .parties(5)
        .threshold(1)
        .build()?;

    println!("Local MPC process ready. Waiting for requests in {REQUEST_FILE}.");

    let mut last_request = String::new();
    loop {
        if Path::new(REQUEST_FILE).exists() {
            let request = fs::read_to_string(REQUEST_FILE)?;
            if request != last_request {
                last_request = request.clone();
                let private_score: i64 = request.trim().parse().map_err(|error| {
                    Error::InvalidInput(format!("invalid private score: {error}"))
                })?;

                let result = runtime
                    .clone()
                    .with_client_input(0, &[private_score])
                    .execute_local()
                    .await?;

                let eligibility_score = result[0]
                    .as_i64()
                    .ok_or_else(|| Error::InvalidInput("expected int64 eligibility score".into()))?;

                fs::write(RESPONSE_FILE, eligibility_score.to_string())?;
                println!("Handled private score for client slot 0.");
            }
        }

        sleep(Duration::from_millis(250)).await;
    }
}

Create src/client.rs. This file represents participant-owned client code: it accepts its owner’s request, sends the private score to the trusted local MPC harness, then combines the returned score with ordinary client-side fields. Do not expose EligibilityRequest.private_score as an application-service request schema.

use std::{fs, path::Path, thread, time::Duration};

use stoffel::prelude::*;

use crate::app::{decision_from_score, EligibilityDecision, EligibilityRequest};

const WORK_DIR: &str = "target/dev-mpc";
const REQUEST_FILE: &str = "target/dev-mpc/request.txt";
const RESPONSE_FILE: &str = "target/dev-mpc/response.txt";

pub fn handle_eligibility_request(
    request: EligibilityRequest,
) -> stoffel::Result<EligibilityDecision> {
    fs::create_dir_all(WORK_DIR)?;
    if Path::new(RESPONSE_FILE).exists() {
        fs::remove_file(RESPONSE_FILE)?;
    }

    fs::write(REQUEST_FILE, request.private_score.to_string())?;

    let eligibility_score = loop {
        if Path::new(RESPONSE_FILE).exists() {
            let raw = fs::read_to_string(RESPONSE_FILE)?;
            break raw.trim().parse::<i64>().map_err(|error| {
                Error::InvalidInput(format!("invalid eligibility score: {error}"))
            })?;
        }
        thread::sleep(Duration::from_millis(250));
    };

    Ok(decision_from_score(request, eligibility_score))
}

Create src/bin/eligibility_client.rs as a command-line entry point for the client-handling code:

use eligibility_demo::app::EligibilityRequest;
use eligibility_demo::client::handle_eligibility_request;

fn main() -> stoffel::Result<()> {
    let mut args = std::env::args().skip(1);
    let account_id = args.next().unwrap_or_else(|| "acct_123".to_owned());
    let private_score = args
        .next()
        .as_deref()
        .unwrap_or("42")
        .parse::<i64>()
        .map_err(|error| stoffel::Error::InvalidInput(format!("invalid score: {error}")))?;
    let public_region = args.next().unwrap_or_else(|| "ca".to_owned());

    let decision = handle_eligibility_request(EligibilityRequest {
        account_id,
        private_score,
        public_region,
    })?;

    println!("{decision:?}");
    Ok(())
}

Run the local MPC owner in one terminal:

cargo run --bin local_mpc

Then run the client handler from another terminal:

cargo run --bin eligibility_client -- acct_123 42 ca

The important local separation is that participant client handling lives in its own module and the Stoffel program owns the private computation. In this tutorial, main.rs starts local MPC nodes and sees fixture plaintext on the same development machine. In a deployed setup, the participant-owned client would load pinned bindings and public deployment config, then submit directly to the separately deployed network. A separate application control plane may manage public metadata, session lifecycle, non-sensitive receipts, and authorized opened aggregates, but it must remain outside the plaintext path.

Want to deploy MPC apps instead of running local development networks? Sign up for Stoffel updates to hear when we launch the platform for deploying MPC apps.

Design notes

Identify which input is secret-shared, which policy logic is public, and which computed result should be reconstructed.
Keep sensitive values as Share values while computing.
Use open() only for outputs you intentionally reveal.
For client-directed share outputs beyond this tutorial, prefer MpcOutput.send_to_client or Share.send_to_client.
Use stoffel check --print-ir, stoffel run --program-info, and bytecode disassembly when debugging.

Introduction

Getting Started

Tutorials

The Stoffel CLI

MPC Backends

Deployment

StoffelLang

Stoffel VM

Architecture

What you will use

Create a project

Replace `src/main.stfl`

Validate and build

Run locally with a client input

Iterate in watch mode

Run the same idea from Rust

Shape the local harness like a participant client

Design notes

Next steps

​What you will use

​Create a project

​Replace src/main.stfl

​Validate and build

​Run locally with a client input

​Iterate in watch mode

​Run the same idea from Rust

​Shape the local harness like a participant client

​Design notes

​Next steps

What you will use

Create a project

Replace `src/main.stfl`

Validate and build

Run locally with a client input

Iterate in watch mode

Run the same idea from Rust

Shape the local harness like a participant client

Design notes

Next steps