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

Development source and architecture presentation for the unreleased zig-pulse client
Development source & architecture view · actual code · no running-node claim.

FROM THE IMPLEMENTATION

Bound the work before allocating

Zig · SELECTED SOURCE
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;
}
zig-pulse/src/sync/window_scheduler.zig

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

  1. Typed in-process engine
  2. EVM frame stack + state transition
  3. LMDB hot state + immutable segments
  4. Bounded peer scheduler
  5. 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

  1. Implemented execution, fork-selection, engine, storage and synchronization components with maintained source-level test batteries.
  2. 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