Repository Map

A tour of the lib-derec monorepo. Use this when you are looking for a particular trait, flow, or worked example and want to know which directory owns it.

Layout

Path	What it is
library/	The Rust library crate itself (derec-library). library/src/lib.rs re-exports the public surface and defines generate_replica_id().
library/src/primitives/	Stateless produce / extract / process helpers per flow — pairing, sharing, verification, discovery, recovery, unpairing. Used directly when you want a stateless integration. primitives::pairing::fingerprint derives the fingerprint string from a shared key.
library/src/protocol/	The DeRecProtocol orchestrator plus DeRecProtocolBuilder, the five store traits and the DeRecTransport trait (traits.rs), the DeRecEvent / DeRecFlow / PendingAction types (events/), the transport adapters SendOne / SequentialFailover / SingleEndpointTransport (transport_adapters.rs), the fingerprint confirmation gate get_fingerprint / verify_fingerprint (fingerprint.rs), and tick() (sweeps.rs).
library/src/transport/	The library-level TransportProtocol endpoint type, its structural validation (the four schemes https, http, grpcs, grpc), and TransportPolicy — the plaintext and one-endpoint-per-protocol rules.
library/src/derec_message/	Outer DeRecMessage envelope parsing and building, plus the trace_id helpers read_trace_id / apply_trace_id used to match a reply to its request.
library/src/protocol_version.rs	The DeRec wire protocol version (CURRENT, currently 0.0) stamped on every outbound envelope. Distinct from the package version.
library/src/interop/ffi/	The C ABI surface used by the .NET, Go, and React Native bindings. Internal — not exposed via the crate's Rust API.
library/src/interop/wasm/	The wasm-bindgen surface used by the TypeScript bindings (Node.js and Web). Also internal.
protobufs/	The derec-proto crate. protobufs/protobufs/ holds the protobuf wire messages — single source of truth for the wire format; every binding generates its types from here. protobufs/grpc/derectransport.proto is the optional gRPC transport service (rpc Send(DeRecMessage) returns (google.protobuf.Empty)). The recoverable secret's gzip-JSON encoding is specified separately, in the library's protocol::types::secret module.
cryptography/	The cryptographic primitives the library composes (derec-cryptography): pairing (ML-KEM-1024 + ECIES handshake), channel (AES-256-GCM), vss (verifiable secret sharing: AES-256-GCM encryption, Shamir split of the key, SHA-256 Merkle commitments), replica (the fingerprint derivation, SHA-256(shared_key) rendered as 16 digits), and random (every nonce, seed and id drawn straight from the OS generator). The confirmation gate that uses the fingerprint lives in library/src/protocol/fingerprint.rs.
smoke-tests/rust/	A complete in-process Rust example that pairs an Owner with Helpers and Replicas, protects a Secret (fanning out shares to Helpers and the full Secret to the replica group), verifies, recovers, restores, unpairs, and runs ReplicaDiscovery — all driven through the orchestrator. The best starting point for understanding DeRecProtocol and how the replica feature fits into a full integration.
smoke-tests/grpc/	A transport reference rather than a binding test: three nodes on loopback pair, share and verify over real gRPC using derectransport.proto. Copy it when your transport is gRPC.
smoke-tests/sqlite/, smoke-tests/postgres/	Reference persistence implementations of all five store traits, DeRecStateStore included. Good templates for building your own.
smoke-tests/nodejs/, smoke-tests/web/, smoke-tests/dotnet/, smoke-tests/go/, smoke-tests/react-native/	Smoke-test consumers of the respective language SDKs. They exercise the same flows as smoke-tests/rust/ through the WASM / FFI bridges. The web one builds the browser package and runs its suites in headless Chromium (Playwright). The React Native one is a runnable app rather than a CLI — it drives the scenarios on a simulator or device and reports a single sentinel line the harness greps out of the device log.
packages/dotnet/, packages/nodejs/, packages/web/, packages/go/, packages/react-native/	Packaging configuration for the published language SDKs (NuGet, npm, Go module). Mostly not source code — build manifests, README files, and bundler config. packages/react-native/ is the exception: it carries the binding's own TypeScript (src/) and C++/JSI (cpp/, ios/, android/) sources. packages/go/ carries the Go wrapper (protocol/, derec/, derecpb/).
scripts/	Release and packaging tooling: get-version.sh reads the single version from library/Cargo.toml and every package is stamped from it; prepare-* build each SDK package; sync-schema.sh and the test-*-schema-* scripts build and check the .proto bundle each package ships.

Start with smoke-tests/rust/. It is the recommended entry point for understanding the orchestrator and the store traits — it shows a complete working integration in a single process: in-memory stores, an in-process transport, and every flow driven end-to-end. The deliver / pump_many driver pattern in smoke-tests/rust/src/protocol.rs is what the Minimal integration example is built from.

Schema distribution

Every SDK ships the protobuf schema alongside its generated types, so you can generate your own code (a gRPC transport, a non-Rust tool) from exactly the schema your SDK version speaks. In Rust it is the derec-proto crate's descriptor feature; the other packages carry the flat .proto files plus a compiled descriptor set. See Schema distribution.

Source-of-truth ordering

If two places appear to disagree, this is the priority order:

1. protobufs/ — wire format.

2. library/src/ — Rust API and protocol semantics.

3. smoke-tests/rust/ — runnable confirmation of how the API is meant to be wired.

4. packages/{nodejs,web,dotnet,go,react-native}/ — language-specific surface; mirrors Rust by construction.

When in doubt, run the smoke tests (see Dev environment setup) — they cover every flow and fail loudly when the Rust source and the bindings drift.