Chainsafe Rust Architect

Rust Architect

Use this when designing Rust systems at ChainSafe — Forest-shaped work or any Rust crate/library/binary. Full reference: languages/rust/architect.md.

Key Rust-specific decisions

Workspace layout

ChainSafe Rust projects use Cargo workspaces (Forest is the canonical example):

• Root Cargo.toml declares workspace members.
• Crates split by concern (network, storage, binary, protocol modules).
• A bin/ crate for the executable; a lib/ crate for the consumable API.
• Workspace-level dependency hoisting where possible.

Error model

• thiserror for library crates. Typed errors callers can match via #[derive(thiserror::Error)].
• anyhow for binary crates. Pass-through errors with .context(...) for ergonomics.
• No mixing within a single crate without reason.
• ? for propagation. No match arms on trivial pass-through.

Async runtime

• Pick one. Tokio for most ChainSafe work (Forest included). Don't mix tokio and async-std in the same workspace.
• #[tokio::main] only in the binary crate. Library crates stay runtime-agnostic where possible.
• Bounded concurrency: FuturesUnordered with limits, tokio::sync::Semaphore, buffer_unordered on streams. Unbounded futures-spawn is a leak.
• Send + Sync + 'static bounds — design types so they meet what tokio::spawn requires.
• Bounded Duration: Every potentially blocking external .await boundary (network I/O, database interaction, channel reads across subsystems) must have a strict timeout boundary. Combine bounded concurrency (caps how many) with bounded duration (caps how long) to prevent task pool exhaustion.

Concurrency primitives

• Arc<Mutex<T>> for shared mutable state across tasks. tokio::sync::Mutex when locks span .await; std::sync::Mutex when they don't.
• Channels: mpsc for many-to-one, broadcast for one-to-many, oneshot for single-response.
• No std::thread::spawn in async code. Use tokio::task::spawn or tokio::task::spawn_blocking.

Public API

• pub(crate) is the default. pub is a versioning commitment.
• #[non_exhaustive] on enums and structs that may grow.
• Builder pattern for complex constructors.
• No leaking tokio types in library APIs unless feature-gated.
• API & storage isolation. Keep internal domain types separate from external transport layers. Define serde/wire and database DTOs at the boundary and map them explicitly to domain models; don't hang #[derive(Serialize, Deserialize)] or storage-schema concerns directly on domain types. External edges only — not between internal modules.

Feature-gating and compilation boundaries

• Lean defaults. Keep default = [] as minimal as possible. Heavy dependencies (tracing subscribers, database drivers, serialization codecs, dev utilities) live behind optional cargo features, not in the default build.
• Environment isolation. Abstract environment-specific logic — mocks, test vectors, alternative networking layers — behind descriptive gates like test-utils or mock. Never leak testing dependencies into production builds.
• Conditional compilation. Apply #[cfg(feature = "...")] intentionally on modules and public entry points so that turning a feature off fully removes its artifacts and upstream dependencies from the compilation graph.
• Features are additive. Cargo unifies feature sets across the workspace, so a feature may only add behavior — never remove or swap it. A mock gate that replaces real behavior breaks the moment two crates in one build enable different sets; design gates to layer, not to toggle.

Unsafe

• Every unsafe block needs a // SAFETY: ... comment with the soundness argument.
• Justification beyond "performance."
• miri testing path when possible.
• Minimized — wrap the smallest possible code in unsafe { }.

ADR template for Rust work

• Public surface — pub vs pub(crate) vs private. Justify.
• Error type — thiserror or anyhow. Justify.
• Async commitments — which runtime, where required, how the API is shaped.
• Unsafe — if any, the soundness argument and safety invariants.
• Invariants impacted — deep links into .invariants.

Anti-patterns at design time

• unwrap() in non-test code without // SAFETY: ....
• Box<dyn Error> as a function's return type when you could be specific.
• String everywhere when &str would do.
• Tokio types leaked through public APIs of library crates without feature flags.
• unsafe without a soundness comment.

Forest-specific

Forest carries AI_POLICY.md which sets the security-critical posture for AI-assisted work in a Filecoin client. Architectural decisions on Forest follow that policy — review-time the Rust reviewer skill will enforce.

Related

• Full reference: languages/rust/architect.md
• Sister roles: chainsafe-rust-developer, chainsafe-rust-reviewer
• Framework: invariants/invariants-framework.md
• Workflow: chainsafe-research-plan-implement
• Upstream: Effective Rust · The Rust Book