☰

neofs-sdk-zig

neofs-sdk-zig

Zig implementation of the NeoFS SDK, aligned with neofs-sdk-go and built on the pinned neofs-api protocol submodule.

Documentation lives in docs/ — start with Getting started, then follow the topic guides below.

Documentation

Guide Topic
Overview Index of all guides
Getting started Requirements, clone, first zig build test
Adding as a dependency build.zig.zon, OpenSSL, module import
Client Dial, RPCs, sessions, status handling
Authentication WIF keys, signers, request signing
Containers Create, list, ACL, attributes
Objects Put/get, streaming, search, delete
Placement policy QL syntax, presets, wire encoding
Netmap Policy parser, placement engine, HRW
Pool Multi-node dial and session cache
Examples Runnable programs (zig build run -Dexample=…)
Testing Unit tests, vectors, NeoFS AIO integration

Project layout

  • docs/ — user guides (see docs/README.md)
  • neofs-api/ — protocol definitions submodule (pinned to v2.23.0)
  • src/proto/gen/ — generated Zig protocol stubs (committed)
  • src/internal/proto/ + src/proto/*/encoding.zig — stable wire helpers
  • src/hrw/ — port of nspcc-dev/hrw/v2
  • src/tzhash/ — port-compatible TZ checksum API with reference vectors

Core modules

  • client — high-level request API for NeoFS services
  • pool — multi-node selection and session cache
  • object, container, session, session/v2, eacl, bearer
  • netmap — placement policy parser and HRW-backed node selection
  • crypto, user, checksum, accounting, version

Development

Requirements:

  • Zig 0.15.x (see minimum_zig_version in build.zig.zon)
  • bash
  • protoc (only needed if regenerating stubs)

Commands:

zig build test
zig build gen-proto
zig build vectors
zig build integration

Test tiers

Step Command Scope
Unit zig build test SDK modules, request signing, gRPC encode paths (mock transport), status mapping, WalletConnect crypto/pairing helpers
Vectors zig build vectors Cross-language HRW, tzhash, netmap JSON, and protobuf round-trip binaries
Integration zig build integration Dockerized NeoFS AIO: dial smoke test plus full container/object lifecycle (test/integration/lifecycle.zig, requires NEOFS_AIO=1)

zig build test is the default CI gate and must pass without network access.

Examples

Run with zig build run -Dexample=<name>. See docs/examples.md for the full catalog and environment variables.

zig build run -Dexample=client_dial
zig build run -Dexample=placement_policy              # no network
zig build run -Dexample=container_object_lifecycle   # needs NEOFS_WIF
Install 
zig f -S zub.sh/neofs-sdk-zig
Repository
License
NOASSERTION
Category

Not categorized yet.

Author
merl111
merl111
Dependencies

No explicit dependencies.

On this page