Quickstart

This page is a five-minute primer for developers who have already read the Overview and want to see what wiring up the DeRec library looks like in code.

What you are actually integrating

The derec-library crate gives you an orchestrator — DeRecProtocol — that drives every protocol flow (pairing, sharing, verification, discovery, recovery, unpairing, update-channel-info) on top of storage and transport callbacks you supply. You implement four small storage traits and one transport callback; the library handles wire framing, encryption, replay protection, per-flow state, and — when the application uses the replica feature — automatic Secret synchronization across every device under the same Owner identity. Your application reacts to typed events.

The library also exposes a lower altitude — the primitives layer — but the orchestrator is the recommended default. See Primitives and Orchestrator for when you would reach for the lower tier.

Five moving pieces

1. DeRecProtocolBuilder — typestate builder that returns a configured DeRecProtocol once every required slot is filled. Setters can be called in any order; build() is only callable once the type system is satisfied.

2. The four store traits — DeRecChannelStore, DeRecShareStore, DeRecSecretStore, and DeRecUserSecretStore. Application-supplied storage. All four are async-shaped (they return type-erased Futures) so they fit any executor — sync backends just return Box::pin(std::future::ready(...)).

3. The DeRecTransport trait — a single async send(endpoint, bytes) callback the library calls whenever it needs to deliver bytes to a peer. You implement it over whatever transport you use (HTTP, WebSocket, message bus, in-memory queue for tests).

4. The event loop — when bytes arrive on your transport, call protocol.process(&envelope_bytes).await. You get back a Vec<DeRecEvent> describing what happened (PairingCompleted, ShareStored, SecretRecovered, ActionRequired { action }, etc.). React accordingly, and accept or reject any ActionRequired to complete the round-trip.

5. DeRecFlow for outbound actions — initiate any protocol flow with protocol.start(DeRecFlow::Pairing { ... }), protocol.start(DeRecFlow::ProtectSecret { ... }), protocol.start(DeRecFlow::RecoverSecret { ... }), and so on. The orchestrator queues the outbound envelopes through your DeRecTransport.

The store and transport traits are async by design — even sync backends return a Future. This is how the same library targets native async runtimes (Tokio), FFI hosts (.NET), and WASM (Node.js / Web) without forking the API surface.

Wiring it up

The example below shows the smallest meaningful DeRecProtocol instantiation: no-op stores (just enough to satisfy the type bounds), an in-memory transport, and a single process() call against a junk envelope to demonstrate the event-loop shape. Real stores live in bindings/rust/src/protocol.rs — see Minimal integration example for the runnable end-to-end version.

[dependencies]
derec-library = "0.0.1-alpha.7"
tokio = { version = "1", features = ["macros", "rt"] }

use derec_library::protocol::{DeRecProtocolBuilder, DeRecEvent};
// Bring the no-op store and transport types into scope. In a real app these
// would be your in-memory / SQLite / Postgres / HTTP implementations.
mod stores; // ChannelStore, ShareStore, SecretStore, UserSecretStore
mod net;    // Transport

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let secret_id: u64 = 0xDE_2EC;

    let mut protocol = DeRecProtocolBuilder::new(secret_id)
        .with_channel_store(stores::ChannelStore::default())
        .with_share_store(stores::ShareStore::default())
        .with_secret_store(stores::SecretStore::default())
        .with_user_secret_store(stores::UserSecretStore::default())
        .with_transport(net::Transport::default())
        .with_own_transport("https://owner.example.com/derec")
        .with_threshold(3)
        .build()
        .expect("builder.build() should succeed");

    // Feed an inbound envelope through the orchestrator. In a real app this
    // would be whatever bytes your transport just delivered.
    let inbound_envelope_bytes: &[u8] = b"...";
    match protocol.process(inbound_envelope_bytes).await {
        Ok(events) => {
            for event in events {
                match event {
                    DeRecEvent::PairingCompleted { channel_id, .. } => {
                        println!("paired on channel {channel_id:?}");
                    }
                    DeRecEvent::ActionRequired { action, .. } => {
                        // Application policy decides — auto-accept here.
                        let _ = protocol.accept(action).await;
                    }
                    _ => {}
                }
            }
        }
        Err(err) => eprintln!("process failed: {err}"),
    }
}

That's the loop. Every flow — pairing, sharing, verification, recovery — drives through this same start / process / accept triangle.

Where to next

• Dev environment setup — toolchain, dependency, local build.

• Repository Map — where each piece lives in lib-derec.

• Choose your integration path — orchestrator vs primitives, language, role.

• Minimal integration example — runnable two-actor pairing + protect-secret round.

• Concepts / Replicas — how the Owner identity extends across multiple devices, and what changes at the integration level when replicas are in play.

• Rust SDK reference — flow-by-flow API documentation.