chainsafe-zig-architect

# Zig Architect Use this when designing Zig modules at ChainSafe — lodestar-z-shaped work (consensus libraries consumed by Lodestar across a C ABI) or any Zig library. Full reference: [`languages/zig/architect.md`](../../languages/zig/architect.md). ## When Zig (and when not) Zig earns its place where the realistic alternative is C: small, performance-critical, memory-controlled libraries consumed across an FFI boundary — hashing, SSZ encode/decode, Merkleization. It is **not** the default for services or tooling (those are TypeScript/Go/Rust/Solidity/Python). Introducing Zig outside that niche is an org-level decision — raise it with the curator and capture the rationale in an ADR first. ## Key Zig-specific decisions ### Project layout - `build.zig` + `build.zig.zon` at the root; `build.zig.zon` pins dependencies and `minimum_zig_version`. - Public modules declared in `build.zig` via `b.addModule` — the module list *is* the public surface (lodestar-z exposes `ssz`, `hashing`, `persistent_merkle_tree`, `consensus_types`). - `src/` (root.zig / main.zig), `test/`, `bench/`, `bindings/`. Files are structs; one primary type per file. ### Allocator strategy (the central decision) - **Inject, never capture.** Every allocating function/type takes an `std.mem.Allocator`; none reaches for a global. This is what makes code testable, leak-checkable, and FFI-usable. - **Match the allocator to the lifetime** — arena for operation-scoped bulk frees, fixed-buffer for bounded hot paths, leak-detecting GPA in tests/debug. - **Ownership is explicit** across returns and the C ABI. Pair every acquire with `defer` / `errdefer`. ### Error model - Explicit error sets at public boundaries so callers `switch` exhaustively; inference (`!T`) for internal helpers. - `try` to propagate, `errdefer` to unwind partial construction. - `catch unreachable` only where success is a proven invariant — never on fallible I/O (UB in unsafe builds). ### Build mode and safety posture - **ReleaseSafe is the default** for anything where a wrong answer matters (all of lodestar-z). Runtime safety stays on. - **ReleaseFast only on measured hot paths**, with `@setRuntimeSafety(false)` scoped tightly and justified. Overflow and bounds checks become UB there — never assume them for correctness. ### Comptime over macros Generics are functions returning `type` (`fn UintType(comptime bits: u16) type`). Keep comptime surfaces small and documented; comptime that could be runtime costs compile time and readability. ### The C ABI is a contract Bindings cross a C ABI (`export fn`, `callconv(.C)`, `extern` layout). Treat the exported surface as a versioned public API with explicit cross-boundary memory ownership — breaking it breaks a downstream client in another language. ### Pre-1.0 reality Zig is pre-1.0; pin `minimum_zig_version` and the CI compiler, wrap heavily-used std APIs, and budget for migration on upgrades. ## ADR shape for Zig modules Allocator ownership · error set · build-mode/safety posture · comptime surface · exported C ABI + memory ownership · Zig version floor · invariants impacted (`.invariants`). ## Anti-patterns at design time - A hidden/global allocator. - ReleaseFast for correctness-critical code without a measured, scoped justification. - Comptime where runtime would do. - Leaking allocator ownership across the C ABI without a documented contract. - `catch unreachable` on fallible operations. ## Related - Full reference: [`languages/zig/architect.md`](../../languages/zig/architect.md) - Sister roles: `chainsafe-zig-developer`, `chainsafe-zig-reviewer` - Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md) - Workflow: `chainsafe-research-plan-implement` - Upstream: [Zig Language Reference](https://ziglang.org/documentation/master/), [Learn Zig](https://ziglang.org/learn/)