TECHNICAL CASE STUDY · Unreleased · Client systems engineering
zig-pulse
Protocol, execution and storage engineering in Zig.
Unreleased R&D · end-to-end sync and packaged distribution remained unverified
FROM THE IMPLEMENTATION
Bound the work before allocating
pub fn bufferBound(
pool_cap: usize,
max_window: usize,
depth: usize,
) error{buffer_overflow}!usize {
const per_peer = std.math.mul(usize, depth, max_window) catch
return error.buffer_overflow;
return std.math.mul(usize, pool_cap, per_peer) catch
return error.buffer_overflow;
}
The scheduler derives its slot capacity from peer count, pipeline depth and window size. Overflow becomes an explicit failure before allocation. Exact source excerpt.
THE ENGINEERING PROBLEM
What needed to work
Design and implement a Zig execution and consensus client whose correctness can be inspected across protocol transitions, storage, peer synchronization and the EVM. The challenge extends beyond decoding blocks: execution, canonicality and recovery must agree on the same history.
Constraints and requirements
- Inherited Ethereum execution history, the PulseChain fork boundary and consensus rules require explicit network and historical context.
- Memory ownership and concurrent downloads need concrete bounds and cleanup behavior.
- This is unreleased development work. Full genesis-to-head validation and sustained head following remain unverified; production readiness is not claimed.
ARCHITECTURE & DESIGN
How the system fits together
- Typed in-process engine
- EVM frame stack + state transition
- LMDB hot state + immutable segments
- Bounded peer scheduler
- Protocol fixtures + tools
Consensus transition modules call a typed in-process execution interface for payload validation and fork choice. The engine connects block transitions, EVM execution, state and commitment calculation.
A single-writer LMDB store supplies MVCC readers for hot data. Compressed immutable segments have read-only memory maps and indexed record lookup.
Peer retrieval feeds a fixed-capacity reordering scheduler. Verified results drain only as a contiguous ascending prefix, preserving commit order across late replies.
Decisions and tradeoffs
Keep the consensus-to-execution interface in process.
Typed requests and result variants make validation outcomes distinct from infrastructure failures without an internal HTTP boundary.
Tradeoff An external consensus driver is outside the supported interface.
Separate mutable hot storage from immutable segments.
Single-writer ownership and MVCC snapshots make mutation and read lifetimes explicit; mapped segments support historical reads.
Tradeoff Borrowed slices must not outlive readers. Segment decompression readers require separate ownership because their shared buffers are not thread-safe.
Derive scheduler capacity from peer count, depth and window size.
Checked multiplication and fixed buffers bound outstanding work; gaps cannot silently become committed progress.
Tradeoff A missing earlier result delays later commits and requires reassignment.
Execute nested EVM calls with an explicit frame stack.
Frame ownership, rollback snapshots and error cleanup remain visible without recursive interpreter calls.
Tradeoff Manual lifetime management needs dedicated failure-path coverage.
PLANNING & EXECUTION
From requirements to working behavior
- Implemented execution, fork-selection, engine, storage and synchronization components with maintained source-level test batteries.
- Built known-answer derivation, reference-EVM differential tooling and spec-corpus runners alongside the implementation.
VALIDATION & RECOVERY
How the behavior is checked
- Engine fixtures exercise real stores, signed transfers, side branches and reorgs.
- Scheduler tests cover gaps, duplicate replies, partial delivery, stalled windows and capacity pressure; storage tests include corruption and allocation failures.
- These are inspected implementation and verification surfaces, not a fresh passing test run or proof of network-wide conformance.
Implementation references
Repository-relative references identify the implementation behind this case study. Selected code excerpts are also available in the portfolio.
- zig-pulse/README.md
- zig-pulse/src/engine/engine.zig
- zig-pulse/src/engine/engine_test.zig
- zig-pulse/src/evm/evm.zig
- zig-pulse/src/storage/store.zig
- zig-pulse/src/storage/segment.zig
- zig-pulse/src/sync/window_scheduler.zig
- zig-pulse/verification/evmdiff/README.md