Stoffel Deployment Runbook

Scope: app/operator playbook for moving a verified Stoffel app from local MPC into a production-shaped network deployment. This is not a maintainer guide for protocol internals. Dependency assumption: use public CLI/SDK surfaces first. If a current SDK wrapper does not start the lower-layer service directly, state the lower-layer handoff instead of pretending local MPC is deployment.

​

Use when

​

Goal

​

Deployment model

1. Build artifacts: .stflb bytecode, generated typed bindings, program manifest, and app release metadata.
2. Application control plane: public metadata, authorization, session lifecycle, client-slot/capability assignment, network discovery, non-sensitive receipts, and explicitly authorized opened aggregates.
3. Participant MPC clients: participant-owned processes that load deployment config and bindings, validate their owner’s plaintext locally, select an assigned client slot, submit directly to the MPC service, and read authorized outputs.
4. MPC service plane: a separately deployed coordinator plus long-running MPC parties/nodes with stable addresses and identity material.

​

Portability and provenance preflight

• app repository URL, commit, and clean/dirty state;
• framework repository URL, commit, and clean/dirty state when a framework checkout is intentionally involved;
• CLI installation source, resolved executable path, and reported version/build identity when available;
• SDK source as a public package version or git URL plus revision; record any intentional path source explicitly;
• committed lockfile path and hash, or the reason a lockfile does not apply;
• bytecode, generated binding, and program/deployment manifest hashes;
• immutable container image digest for every applicable build and runtime image.

​

Deployment inputs to collect

​

Artifact build step

stoffel status --verbose
stoffel check
stoffel build --program-info

cargo check --locked
cargo test --locked

dist/program.stflb
dist/stoffel_bindings.rs or generated bindings in OUT_DIR
release manifest with backend, parties, threshold, client slots, and output slots

​

Local gate before network work

stoffel run --timeout-secs 180 <documented inputs or # run-args>

cargo run --locked --bin <local-smoke-or-demo>

• every ClientStore input slot used by deployment;
• expected output clients;
• backend/topology selection when configurable;
• typed output decoding when generated bindings are used.

​

Network config plan

let deployment = NetworkDeployment::builder([
    "node-0.internal:19200",
    "node-1.internal:19201",
    "node-2.internal:19202",
    "node-3.internal:19203",
    "node-4.internal:19204",
])
.expected_clients(2)
.threshold(1)
.honeybadger()
.consensus_timeout(std::time::Duration::from_secs(60))
.preprocessing(1000, 500)
.build()?;

let paths = deployment.save_toml_files("deploy/network")?;

• party id;
• bind address;
• peer addresses;
• expected parties;
• expected clients;
• threshold;
• backend/curve;
• preprocessing sizes;
• coordinator/off-chain settings when using ClientStore IO.

​

Server/node handoff

• the exact .stflb bytecode;
• the party’s network config;
• coordinator address if using off-chain ClientStore IO;
• node RPC bind address;
• party certificate/key material;
• expected client certificates;
• persistent state location when the backend/workflow stores shares or commitments;
• process supervisor and logs.

let app_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
let runtime = Stoffel::load_file(app_root.join("dist/program.stflb"))?
    .parties(5)
    .threshold(1)
    .honeybadger()
    .build()?;

let servers = runtime.servers_for_deployment(&deployment);
let server0 = servers[0].clone().build()?;

​

Container and host safeguards

• Pin every image by digest and record that digest with the node/client result.
• Record each host-to-container mount. Mount the immutable release bundle read-only where possible, keep state and identity mounts separate, and verify bundle hashes inside every runtime container.
• Never mount a framework checkout, developer target/, or unpublished package cache to make a release work. Such a run is not clean-room tested.
• Distinguish bind addresses from advertised/reachable addresses. 127.0.0.1 and localhost refer to the current network namespace and normally cannot identify a service across host/container boundaries.
• Publish only required ports, and test coordinator, mesh, RPC, and client reachability from the actual source container/host. Record DNS resolution and the address used, not only a host-side health result.

​

Participant-client integration

let app_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
let runtime = Stoffel::load_file(app_root.join("dist/program.stflb"))?
    .parties(5)
    .threshold(1)
    .honeybadger()
    .build()?;

let offchain = runtime
    .offchain_client_config(0)?
    .coordinator("coordinator.example.com", 31415)
    .timestamp(deployment_timestamp)
    .node_rpc_addresses([
        "node-0.example.com:40000",
        "node-1.example.com:40001",
        "node-2.example.com:40002",
        "node-3.example.com:40003",
        "node-4.example.com:40004",
    ])
    .identity_files("client-0.crt", "client-0.key")
    .build()?;

let client = runtime
    .client_for_deployment(&deployment)
    .offchain_io(offchain)
    .client_id(0)
    .connect()
    .await?;

let outputs = client
    .run_typed::<Client0Inputs, Client0Outputs>(Client0Inputs { input_0: 42 })
    .await?;

​

Operational checklist

• Bytecode and bindings come from the same build.
• All nodes run the same bytecode hash and compatible configs.
• The coordinator address is reachable from every node and client.
• Node mesh ports and node RPC ports are reachable according to the topology.
• Party and client identity files are present, readable by the process, and not committed.
• Client slots and output slots match the generated manifest.
• Preprocessing capacity covers the expected workload shape.
• Application-service schemas, persistence, logs, traces, caches, queues, analytics, crash reports, and receipts contain no participant plaintext.
• A plaintext-canary test confirms the application control plane is outside the private-input path.
• Participant clients submit directly to the MPC service using verified runtime support.
• Logs redact identity material, tokens, certificates, shares, and private client values.
• Restart behavior is documented for the control plane, participant clients, coordinator, and nodes.
• Rollback means reverting bytecode, bindings, config, and app client code together.
• Repository, CLI, SDK, lockfile, artifact, and image provenance is recorded for each labeled execution context.
• The external clean-checkout/public dependency consumer proof passed.
• Every deployment host/container verified the unchanged release bundle hashes before startup.
• The real service processes started and an actual SDK client traversed the intended coordinator/node service path and decoded the authorized typed output.

​

Verification commands

stoffel check
stoffel build --program-info
cargo check --locked
cargo test --locked
cargo run --locked --bin build-program
cargo run --locked --bin validate-network-config
cargo run --locked --bin client-smoke -- --client-slot 0

curl -f http://<service>/health

​

CI/release gates

​

Failure report shape

• bytecode hash;
• branch/commit;
• party id or client slot;
• command run;
• redacted config path;
• first failing log line;
• whether local MPC passed;
• whether typed bindings matched;
• whether the failure is build, config validation, network reachability, identity, coordinator, protocol, or output decoding;
• labeled execution context and working directory;
• exact command, exit status, first actionable error, and unabridged log location;
• app/framework repository URLs, commits, and dirty state;
• CLI source, SDK source, lockfile hash, bundle member hashes, and applicable image digest;
• mount map and bind/advertised addresses when containers are involved;
• every skipped check and why it was skipped.

​

Common pitfalls

• Calling local MPC deployment because it returned the right answer on one machine.
• Treating the application backend, participant client, CLI, and browser as one client/app role.
• Accepting participant plaintext in control-plane APIs, persistence, queues, logs, or generic payload blobs.
• Using .with_client_input(...) or .execute_local() in a production application-service path.
• Replacing unsupported direct browser/client submission with an unapproved plaintext gateway.
• Letting each node compile source independently instead of distributing pinned bytecode.
• Running clients against bindings generated from stale bytecode.
• Forgetting node RPC addresses when using off-chain ClientStore IO.
• Committing client or party keys.
• Treating backend/curve changes as config-only changes without rebuilding and revalidating artifacts.
• Hiding a missing production server wrapper behind local SDK examples.

​

Next playbooks

• Stoffel Full App Golden Path
• Stoffel App Network and Off-Chain Integration
• Stoffel Rust App SDK
• Stoffel App Troubleshooting