Minimal integration example

The Quickstart shows what a DeRecProtocol instance looks like in isolation. This page shows the lifecycle: two in-process actors pair, cross-confirm their fingerprints, and run one ProtectSecret round end-to-end. Every println! corresponds to an event you would surface to your application.

This example covers the Owner ↔ Helper case only — enough to see the start / process / accept triangle in action. The pattern below is a stripped-down version of the canonical fixture at bindings/rust/src/protocol.rs — once you've understood this page, that file is where you go next for the fuller worked example (multi-helper sharing rounds, verification, recovery, replica-mode pairings and Secret sync, UpdateChannelInfo, unpairing).

What we are building

Two actors live in the same process:

• Alice — Owner. Creates a contact, accepts Bob's pairing request, eventually publishes a secret via DeRecFlow::ProtectSecret.

• Bob — Helper. Scans Alice's contact, drives DeRecFlow::Pairing, accepts the inbound share when it arrives.

The "transport" is an Arc<Mutex<VecDeque<_>>> per peer: each peer's send enqueues (endpoint, bytes); a driver loop drains the queues and feeds bytes into the destination peer's protocol.process(...). In a real deployment this would be HTTPS, WebSockets, or a message bus — the library doesn't care.

Project setup

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

The store traits (in-memory)

Four tiny HashMap-backed stores. Every method returns Box::pin(std::future::ready(...)) — sync work, async-shaped signature.

use std::collections::HashMap;
use derec_library::protocol::{
    ChannelStoreFuture, DeRecChannelStore, DeRecSecretStore, DeRecShareStore,
    DeRecUserSecretStore, MissingPolicy, SecretKind, SecretStoreFuture, SecretValue,
    Share, ShareStoreFuture,
};
use derec_library::protocol::types::{Channel, UserSecrets};
use derec_library::types::ChannelId;

#[derive(Default)]
struct ChannelStore { data: HashMap<(u64, u64), Channel> }

impl DeRecChannelStore for ChannelStore {
    fn load(&self, sid: u64, cid: ChannelId) -> ChannelStoreFuture<'_, Option<Channel>> {
        Box::pin(std::future::ready(Ok(self.data.get(&(sid, cid.0)).cloned())))
    }
    fn save(&mut self, sid: u64, ch: Channel) -> ChannelStoreFuture<'_, ()> {
        self.data.insert((sid, ch.id.0), ch);
        Box::pin(std::future::ready(Ok(())))
    }
    fn remove(&mut self, sid: u64, cid: ChannelId) -> ChannelStoreFuture<'_, bool> {
        Box::pin(std::future::ready(Ok(self.data.remove(&(sid, cid.0)).is_some())))
    }
    fn channels(&self, sid: u64) -> ChannelStoreFuture<'_, Vec<Channel>> {
        let out = self.data.iter()
            .filter(|((s, _), _)| *s == sid)
            .map(|(_, c)| c.clone())
            .collect();
        Box::pin(std::future::ready(Ok(out)))
    }
    fn link_channel(&mut self, _: u64, _: ChannelId, _: ChannelId) -> ChannelStoreFuture<'_, ()> {
        Box::pin(std::future::ready(Ok(())))
    }
    fn linked_channels(&self, _: u64, cid: ChannelId) -> ChannelStoreFuture<'_, Vec<ChannelId>> {
        Box::pin(std::future::ready(Ok(vec![cid])))
    }
}

ShareStore, SecretStore, and UserSecretStore follow the same shape — see bindings/rust/src/protocol.rs for the full code (~70 lines per trait).

Why so terse? The store traits are the application's responsibility, not the library's. The terser the better — they only need to persist values verbatim and return them by key.

The transport

A per-peer outbox the test driver drains and routes by URI.

use std::sync::{Arc, Mutex};
use std::collections::VecDeque;
use derec_library::protocol::{DeRecTransport, TransportFuture};
use derec_proto::TransportProtocol;

#[derive(Clone, Default)]
struct Transport {
    outbox: Arc<Mutex<VecDeque<(TransportProtocol, Vec<u8>)>>>,
}

impl Transport {
    fn drain(&self) -> Vec<(TransportProtocol, Vec<u8>)> {
        self.outbox.lock().unwrap().drain(..).collect()
    }
}

impl DeRecTransport for Transport {
    fn send(&self, endpoint: &TransportProtocol, bytes: Vec<u8>) -> TransportFuture<'_> {
        let outbox = self.outbox.clone();
        let entry = (endpoint.clone(), bytes);
        Box::pin(async move {
            outbox.lock().unwrap().push_back(entry);
            Ok(())
        })
    }
}

Wiring a Peer

Bundles a DeRecProtocol instance with the transport handle so the driver can route bytes by URI.

use derec_library::protocol::DeRecProtocolBuilder;

struct Peer {
    label: &'static str,
    uri: String,
    protocol: derec_library::protocol::DeRecProtocol<
        ChannelStore, ShareStore, SecretStore, UserSecretStore, Transport,
    >,
    transport: Transport,
}

impl Peer {
    fn new(label: &'static str, uri: &str, secret_id: u64) -> Self {
        let transport = Transport::default();
        let protocol = DeRecProtocolBuilder::new(secret_id)
            .with_channel_store(ChannelStore::default())
            .with_share_store(ShareStore::default())
            .with_secret_store(SecretStore::default())
            .with_user_secret_store(UserSecretStore::default())
            .with_transport(transport.clone())
            .with_own_transport(uri)
            .with_threshold(2)
            .build()
            .expect("builder.build()");
        Self { label, uri: uri.to_owned(), protocol, transport }
    }
}

The event loop

deliver feeds bytes into a peer's process() and auto-accepts every ActionRequired. pump drains one peer's outbox into the other's process() until the network is quiescent — that's all the "transport" we need for an in-process demo.

use derec_library::protocol::DeRecEvent;

async fn deliver(peer: &mut Peer, bytes: &[u8]) -> Vec<DeRecEvent> {
    let mut events = peer.protocol.process(bytes).await
        .unwrap_or_else(|e| panic!("[{}] process: {e}", peer.label));
    let mut i = 0;
    while i < events.len() {
        let action = match std::mem::replace(&mut events[i], DeRecEvent::NoOp) {
            DeRecEvent::ActionRequired { action, .. } => Some(action),
            other => { events[i] = other; None }
        };
        if let Some(action) = action {
            let mut more = peer.protocol.accept(action).await
                .unwrap_or_else(|e| panic!("[{}] accept: {e}", peer.label));
            events.append(&mut more);
        }
        i += 1;
    }
    events
}

async fn pump(from: &mut Peer, to: &mut Peer) -> Vec<DeRecEvent> {
    let mut all = Vec::new();
    let mut pending: VecDeque<(String, Vec<u8>)> = from.transport.drain()
        .into_iter().map(|(tp, b)| (tp.uri, b)).collect();
    while let Some((uri, bytes)) = pending.pop_front() {
        let target = if uri == to.uri { &mut *to } else { &mut *from };
        let mut evs = deliver(target, &bytes).await;
        for (tp, reply) in target.transport.drain() {
            pending.push_back((tp.uri, reply));
        }
        all.append(&mut evs);
    }
    all
}

The full handshake + protect round

use derec_library::protocol::types::UserSecret;
use derec_library::protocol::DeRecFlow;
use derec_proto::{ContactMode, SenderKind};

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

    let mut alice = Peer::new("alice", "https://alice.example/derec", secret_id);
    let mut bob   = Peer::new("bob",   "https://bob.example/derec",   secret_id);

    // ── 1. Alice creates a contact ────────────────────────────────
    // The ContactMessage is transferred out of band (QR code, SMS, etc.).
    // In-process: Bob receives the value directly.
    let contact = alice.protocol
        .create_contact(Some(channel_id), ContactMode::InlineKeys)
        .await
        .expect("alice.create_contact");
    println!("[alice] contact created for channel {channel_id:?}");

    // ── 2. Bob starts pairing from the scanned contact ────────────
    bob.protocol.start(DeRecFlow::Pairing {
        kind: SenderKind::Helper,
        contact,
        peer_communication_info: HashMap::from([("name".into(), "bob".into())]),
    })
    .await
    .expect("bob start(Pairing)");

    // ── 3. Pump bytes both ways until both sides emit PairingCompleted ──
    let evs1 = pump(&mut bob, &mut alice).await; // PairRequest → Bob to Alice
    let evs2 = pump(&mut alice, &mut bob).await; // PairResponse → Alice to Bob
    let paired = evs1.iter().chain(evs2.iter())
        .filter(|e| matches!(e, DeRecEvent::PairingCompleted { .. }))
        .count();
    assert!(paired >= 2, "expected PairingCompleted on both sides, got {paired}");
    println!("[both]  PairingCompleted on channel {channel_id:?}");

    // ── 4. Fingerprint cross-confirmation ─────────────────────────
    // Both sides derive the same fingerprint from the shared key.
    // In production each side displays its fingerprint to the user, who
    // reads off the peer's and confirms they match.
    let alice_fp = alice.protocol.get_fingerprint(channel_id).await.unwrap();
    let bob_fp   = bob.protocol.get_fingerprint(channel_id).await.unwrap();
    assert_eq!(alice_fp, bob_fp);
    let _ = alice.protocol.verify_fingerprint(channel_id, &bob_fp).await.unwrap();
    let _ = bob.protocol.verify_fingerprint(channel_id, &alice_fp).await.unwrap();
    println!("[both]  fingerprint cross-confirmed: {alice_fp}");

    // ── 5. Alice protects a secret ────────────────────────────────
    // With only one Helper paired, the configured threshold (2) is NOT
    // met — see the hint below.
    alice.protocol.start(DeRecFlow::ProtectSecret {
        secrets: vec![UserSecret {
            id: vec![0x01],
            name: "demo-credential".into(),
            data: b"super-secret-bytes".to_vec(),
        }],
        description: Some("first publish".into()),
    })
    .await
    .expect("alice start(ProtectSecret)");

    // ── 6. Drive the round ────────────────────────────────────────
    let publish_events = pump(&mut alice, &mut bob).await;
    let ack_events     = pump(&mut bob, &mut alice).await;
    for e in publish_events.iter().chain(ack_events.iter()) {
        match e {
            DeRecEvent::ShareStored { channel_id, version, .. } => {
                println!("[bob]   ShareStored channel={channel_id:?} v={version}");
            }
            DeRecEvent::ShareConfirmed { channel_id, version } => {
                println!("[alice] ShareConfirmed channel={channel_id:?} v={version}");
            }
            DeRecEvent::SharingComplete { version, confirmed_count, threshold_met, .. } => {
                println!(
                    "[alice] SharingComplete v={version} confirmed={confirmed_count} \
                     threshold_met={threshold_met}"
                );
            }
            _ => {}
        }
    }
}

What you should see

[alice] contact created for channel ChannelId(1)
[both]  PairingCompleted on channel ChannelId(1)
[both]  fingerprint cross-confirmed: 1234-5678-9012-3456
[bob]   ShareStored channel=ChannelId(1) v=1
[alice] ShareConfirmed channel=ChannelId(1) v=1
[alice] SharingComplete v=1 confirmed=1 threshold_met=false

threshold_met=false is expected with a single Helper and the default threshold of 2. The library still fires ShareStored / ShareConfirmed so you can observe per-peer progress, but SharingComplete.threshold_met tells you whether the round met the quorum the Owner needs for recovery. Pair a second Helper (or lower the threshold to 1 via with_threshold(1)) to see threshold_met=true. Setting the threshold below 2 collapses the secret-sharing guarantee — the orchestrator rejects it at build() time with Error::InvalidInput.

What this leaves out

The example above covers pairing through one publish round. The canonical fixture at bindings/rust/src/protocol.rs extends it with:

• multi-helper sharing with the threshold actually met;

• a DeRecFlow::VerifyShares round and ShareVerified events;

• DeRecFlow::Discovery followed by DeRecFlow::RecoverSecret and the SecretRecovered event;

• replica-mode pairings, ReplicaSecretReceived, and ReplicaSecretAcked;

• DeRecFlow::Unpair with both UnpairAck::Required and UnpairAck::NotRequired;

• DeRecFlow::UpdateChannelInfo with mid-flow endpoint changeover.

Read it as the next step. Every flow follows the same start / process / accept triangle this example demonstrates.