Rust

This document provides the recommended structure and content for the Rust SDK section of the DeRec documentation.

It is designed to guide Rust developers through installing, understanding, and integrating the DeRec protocol using the official derec-library crate.

---

Rust SDK Overview

The DeRec Rust SDK is the canonical surface of the protocol — every other binding (.NET, TypeScript/Node, TypeScript/Web) wraps this crate over an FFI or WASM boundary. Rust applications can depend on the crate directly.

The SDK allows applications to:

• Distribute Secret shares across trusted Helpers using a threshold secret-sharing scheme

• Verify Helpers still hold shares

• Recover the Secret from a threshold of Helpers

• Optionally extend the Owner identity across multiple devices via the replica feature, with automatic Secret synchronization between them

The crate is published on crates.io:

derec-library

It exposes DeRecProtocol — a stateful orchestrator that drives every flow on top of application-supplied storage and transport — plus stateless primitives::* helpers for callers that want to drive the wire format directly.

---

Installation

Add the crate to your Cargo.toml:

[dependencies]
derec-library = "0.0.1-alpha.7"

The crate is pre-1.0. Breaking changes between alpha versions are expected — pin an exact version and treat upgrades as a deliberate review step.

The crate compiles for both native targets and wasm32-*. Native consumers depend on it directly; the WASM and FFI surfaces are internal feature flags used by the language bindings shipped from this repository.

---

Quick Start

Implement the four store traits, a transport callback, and drive the orchestrator. The example below is the minimum scaffold; the four flow chapters show how each protocol round-trip flows through process(...).

use derec_library::protocol::{
    DeRecEvent, DeRecFlow, DeRecProtocolBuilder,
};
use derec_library::protocol::types::{Target, UserSecret};

// 1. Application-supplied persistence + transport. The crate ships no
//    default implementations — your app owns storage and network I/O.
let channels = MyChannelStore::new();      // impls DeRecChannelStore
let shares = MyShareStore::new();          // impls DeRecShareStore
let secrets = MySecretStore::new();        // impls DeRecSecretStore
let user_secrets = MyUserSecretStore::new(); // impls DeRecUserSecretStore
let transport = MyTransport::new();        // impls DeRecTransport

// 2. Build the orchestrator. One DeRecProtocol instance manages one Secret.
let mut protocol = DeRecProtocolBuilder::new(0xC0FFEE_u64) // secret_id
    .with_channel_store(channels)
    .with_share_store(shares)
    .with_secret_store(secrets)
    .with_user_secret_store(user_secrets)
    .with_transport(transport)
    .with_own_transport("https://owner.example.com")
    .with_threshold(3)
    .build()?;

// 3. Drive an inbound envelope through the orchestrator. The library
//    returns every DeRecEvent it produced while handling the envelope.
let envelope: Vec<u8> = receive_from_transport().await;
let events: Vec<DeRecEvent> = protocol.process(&envelope).await?;

for event in events {
    match event {
        DeRecEvent::PairingCompleted { channel_id, kind, .. } => {
            println!("paired channel {channel_id:?} as {kind:?}");
        }
        DeRecEvent::ActionRequired { action, .. } => {
            // App consents; library resumes the flow and emits its own events.
            let _follow_up = protocol.accept(action).await?;
        }
        DeRecEvent::ShareStored { channel_id, version, .. } => {
            println!("stored share v{version} for {channel_id:?}");
        }
        DeRecEvent::SecretRecovered { secret } => {
            use_recovered_bytes(&secret);
        }
        _ => {}
    }
}
# Ok::<(), derec_library::Error>(())

DeRecProtocolBuilder is a typestate builder — the call to .build() is only reachable once every required slot (with_channel_store, with_share_store, with_secret_store, with_user_secret_store, with_transport, with_own_transport) has been filled. Missing slots surface as a compile-time error, not a runtime panic.

---

Protocol Flows

The crate exposes every DeRec flow through a single protocol.start(DeRecFlow::*) entry point plus the inbound process / accept loop. The four chapters below cover the core integration areas; the full flow catalog (Discovery, Unpair, UpdateChannelInfo) lives in Protocol Specification / Flows.

Flow	Purpose
Pairing	Establish secure communication between two participants — Owner ↔ Helper, or Replica pairings
Share Distribution	Split the Secret and distribute shares to Helpers; sync the full Secret to every paired Replica
Verification	Verify Helpers still hold shares
Recovery	Recover shares and reconstruct the Secret

Each flow follows the same shape: the initiator calls start(DeRecFlow::X { .. }); the library produces outbound envelopes through your DeRecTransport; the responder feeds inbound envelopes to process and consents to any DeRecEvent::ActionRequired via accept.

---

Message Model

The crate operates on serialized protocol envelopes rather than exposing protobuf types directly on the public API.

• Inbound and outbound envelopes are plain Vec<u8> / &[u8] byte buffers on both sides of the orchestrator

• These bytes represent:

  • A serialized DeRecMessage envelope, or

  • A plain serialized ContactMessage (the out-of-band bootstrap, see Pairing)

• For encrypted protocol exchanges, the DeRecMessage envelope contains an encrypted inner protobuf message — the library performs the encryption, decryption, and framing for you

This design ensures:

• Transport-agnostic usage (HTTP, WebSocket, mailbox relay, etc.)

• Language-agnostic interoperability with the .NET, TypeScript, and other SDKs

• Clear separation between protocol and transport layers

Applications are responsible for:

• Delivering outbound envelopes — the library passes them to DeRecTransport::send(endpoint, message) — to the counterparty

• Receiving inbound envelopes and passing them back through DeRecProtocol::process(...)

---

Error Handling

The public surface returns Result<T, derec_library::Error>. The Error enum is #[non_exhaustive] and aggregates the per-flow error types behind structured variants:

use derec_library::Error;
use derec_library::primitives::pairing::PairingError;

match protocol.process(&envelope).await {
    Ok(events) => handle(events),
    Err(process_err) => match &process_err.source {
        Error::Pairing(PairingError::PrePairHashMismatch) => {
            // HashedKeys binding hash failed — the contact bytes were tampered.
        }
        Error::RoleMismatch { channel_id, expected, actual } => {
            // A flow was started against a channel where this node holds the
            // wrong role (e.g. Helper trying to initiate ProtectSecret).
            eprintln!("channel {channel_id:?}: expected {expected:?}, got {actual:?}");
        }
        Error::ReplicaIdNotConfigured => {
            // A replica-mode flow was attempted without `.with_replica_id(..)`.
        }
        other => eprintln!("DeRec error: {other}"),
    },
}

process returns ProcessError, which carries the offending channel_id (if any) alongside the inner Error. start and accept return the inner Error directly. The same variants carry the same meaning across every language binding — see Error Handling for the cross-binding catalog.

---

API Reference

Full Rustdoc lives at docs.rs/derec-library. The source of truth for every method, trait, and event documented in this section is the published crate.

Recommended documentation structure:

• README.md

• pairing.md

• share-distribution.md

• verification.md

• recovery.md

---

SDK Architecture

Unlike the .NET binding (which wraps a C ABI) or the TypeScript bindings (which wrap WASM), Rust consumers depend on the canonical crate directly. There is no FFI layer between the application and the protocol logic — every other binding is a thin translation over the same core.