Skip to content
refcellPublic

About

some zig components

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

zigware

Zig Platform Dependencies Status License

zigware is the Commonware Library rewritten from scratch in Zig: codec, cryptography, a deterministic runtime, storage, authenticated p2p, broadcast, and BFT consensus, with zero dependencies.

It is a ground-up port of the public commonware monorepo and keeps its layout: every crate there is a package here with the same name and the same dependency graph, and wire formats are byte-identical so the two can interoperate.

Validators reshare a threshold BLS12-381 key at every epoch boundary while a fifth joins with state sync

dkg follows commonware's flow: dkg setup writes configs for five peers with a committee of four, the epoch-zero players run bootstrap to complete a one-shot DKG and write the genesis, then four validators run Simplex over marshal and a QMDB-backed stateful application. At every epoch boundary the committee reshares its threshold key on chain: each pane shows dealings and acks arriving, dealer logs observed on chain, completed reshare ceremony ... success=true, and the orchestrator entering the next epoch with the new key. After the first reshare, the bottom pane starts a fifth validator with --state-sync: its first block is a peer's floor rather than genesis, and it enters the current epoch and reshares in step with the rest (video). etc/scripts/record-demo.sh dkg records it again.

Three commonware and three zigware validators run one dkg network through reshares

The same network runs with both implementations at once. One commonware-dkg setup writes the configs, commonware's players 0 and 1 and zigware's players 2 and 3 complete the epoch-zero DKG together, and all six genesis files come out identical. Then commonware's validators 0, 1 and 4 and zigware's validators 2 and 3 run Simplex, marshal, and the stateful application together, and zigware's validator 5 joins with --state-sync. Every pane shows the same digest at each height through every epoch's reshare (video). etc/scripts/interop.sh runs this check, and etc/scripts/record-demo.sh interop-dkg records it again.

Two commonware Rust validators and two zigware validators finalize the same blocks

zigware and commonware run one network together. Here commonware's Rust log validators 0 and 1 and zigware's validators 2 and 3 form one Simplex committee: each implementation proposes about half the views, and all four finalize every view with the same digest. A zigware validator that is stopped and restarted on its storage rejoins and finalizes later views with the same digests (video). etc/scripts/interop.sh runs this check, after a chat session between the two implementations, and etc/scripts/record-demo.sh interop-log records it again.

Two consensus networks finalize each other's certificates through a shared indexer

bridge runs two independent networks of four validators, each with a threshold BLS12-381 key dealt by bridge-dealer, plus an indexer they share. Each network runs Simplex and proposes either random data or the other network's latest finalization, which its validators verify against the other network's public identity before voting. The top pane is the indexer storing blocks and finalizations from both networks; the bottom panes are one validator from each network, where block=Bridge(..) marks a proposal carrying the other network's finalization (video). etc/scripts/record-demo.sh bridge records it again.

The other examples have their own READMEs and recordings: chat, an encrypted group chat over authenticated p2p, including a session with commonware's Rust chat; log, four Simplex validators over TCP; flood, p2p load; and estimator, simulated consensus latency across AWS regions.

Warning

zigware is pre-alpha and being ported now. Do not use it in production.

Packages

Each package's README gives its upstream stability, its modules, how to test, bench, and fuzz it, and every recorded difference from commonware.

Package What it does Status
codec Serialize structured data ported
cryptography Keys, signatures, hashes, BLS12-381 threshold crypto porting
curve25519 Curve25519 arithmetic, Ed25519 signing and batch verification, X25519 ported
math Fields, polynomials, NTT porting
runtime Async tasks with a deterministic scheduler or io_uring porting
storage Journals, archives, MMRs, authenticated databases porting
utils Shared functionality across primitives ported
parallel Parallel folds with pluggable strategies ported
actor Coordinate concurrent components ported
stream Encrypted messages over any transport ported
p2p Communicate with authenticated peers porting
broadcast Disseminate data over a wide-area network ported
resolver Resolve data by a fixed-length key ported
collector Collect responses to committable requests ported
coding Erasure-code data for recovery from fragments ported
clearing Settle actions at scale porting
consensus Order messages in a Byzantine environment (simplex, aggregation, marshal) porting
glue Default constructions spanning several primitives porting
deployer Deploy infrastructure across cloud providers porting

Support packages: formatting, conformance, invariants, simd, allocator, bench. docs/ARCHITECTURE.md maps every commonware crate to its package and lists the dependency order.

Performance

Twelve of commonware's criterion benchmarks, run against the zigware benchmark of the same name and parameters on the same machine (docs/BENCHMARKS.md has the setup, the commands, and the caveats). Below 1× means zigware is faster.

bench zigware / commonware
codec::lazy::get (100k shared) 0.17×
journal::append_sync (fixed) / fixed_append (10k) / fixed_replay (100k) 0.11× / 0.23× / 0.76×
buffer_paged::append (4 KiB) 0.43×
bls12381::aggregate_verify_same_message (1000 keys) / single verify 0.98× / 0.79×
sha256::hash_message (4 KiB / 1 MiB) 1.11× / 1.12×
ed25519::signature_verification / batch_verify_same_message (100 keys) 0.55× / 0.52×
qmdb::apply_batch (16384 updates) 2.43×

End to end, four local flood peers over authenticated p2p at 262144 msg/s each: zigware receives 673–772k msg/s per peer at 23–80 ms mean latency, commonware 212–266k at 194–294 ms. Below saturation both hit the rate cap, and zigware's latency is lower at every rate (details).

These were measured on a busy desktop with storage on tmpfs, so ratios near 1 are noise and the storage numbers measure code, not the disk. ed25519 single verify uses an AVX-512 IFMA backend where the CPU has one; batch verify uses IFMA, then AVX2 (0.76×), then a scalar path. The BLS rows wait on a quiet re-run, and the qmdb gap is being worked on.

Design

  • Zero dependencies. Only the Zig standard library: no C libraries, no vendored code, build.zig.zon has an empty .dependencies. BLS12-381, ed25519, secp256r1, the hashes, Reed-Solomon, the runtime, and the storage engines are all implemented here.
  • Same wire formats. Encodings, storage layouts, and network messages match commonware's byte for byte, checked against commonware's own test vectors and conformance hashes.
  • Deterministic simulation testing. All time, randomness, tasks, network, and storage go through the runtime. The deterministic runtime runs real protocol code on a simulated network with fault injection, and any run replays exactly from its seed.
  • TigerStyle. Assertions on every precondition, postcondition, and invariant; every loop, queue, and mailbox bounded; no recursion; functions ≤ 70 lines. See docs/TIGER_STYLE.md.
  • Fuzzed. Every decoder, parser, and state machine has a coverage-guided fuzz target and a seeded fuzz run that executes with the normal test suite.
  • Production runtime. Production I/O runs on std.Io.Threaded; on Linux, blob and socket I/O can move onto an io_uring ring (Config.io_uring).

Installation

git clone https://github.com/refcell/zigware && cd zigware
just release

just release needs just and curl. It uses Zig 0.17.1 from PATH, or downloads it into .cache/zig, and writes optimized binaries to zig-out/bin. zigware has no other build dependency. There are no tagged releases; build from main.

Use a package from your own build.zig through the zigware module, or one package by name (b.dependency("zigware", .{}).module("codec")).

Contributing

just lists every development recipe. zig build test runs every package's tests and zig build test-<package> runs one. Contributor rules are in AGENTS.md; the port's work split is in docs/lanes and docs/ROADMAP.md.

License

MIT. zigware is a port of the Commonware Library, which is dual-licensed under MIT and Apache 2.0.

About

some zig components

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages