API reference

audience: developers

A compact reference of the surface the zipnet facade crate exposes. Link-in-book pages cover the “how”; this page is the “what”.

The whole import story

Almost every developer-side agent pulls from exactly one module:

use zipnet::{
    // The universe constant.
    UNIVERSE,

    // The typed facade + handle types.
    Zipnet, Submitter, Receipts, Reader,

    // Deployment fingerprint.
    Config, ShuffleWindow,

    // Datum contract.
    ShuffleDatum, DecodeError,

    // Identifier types and macros.
    UniqueId, NetworkId, Tag, unique_id,

    // Value types.
    Receipt, Outcome, SubmissionId, RoundId,

    // Error model.
    Error, Result,
};

Constants

Deployment fingerprint

pub struct Config { /* opaque, const-constructible */ }

impl Config {
    pub const fn new(name: &'static str) -> Self;
    pub const fn with_window(self, window: ShuffleWindow) -> Self;
    pub const fn with_init(self, init: [u8; 32]) -> Self;

    pub const fn name(&self) -> &'static str;
    pub const fn window(&self) -> &ShuffleWindow;
    pub const fn init(&self) -> &[u8; 32];
}

pub struct ShuffleWindow { /* opaque */ }

impl ShuffleWindow {
    pub const fn interactive() -> Self; // 1s rounds, up to 64
    pub const fn archival()    -> Self; // 30s rounds, up to 1024
    pub const fn custom(
        round_period:     std::time::Duration,
        min_participants: u32,
        max_participants: u32,
        fold_deadline:    std::time::Duration,
        round_deadline:   std::time::Duration,
    ) -> Self;
}

Every field folds into the deployment id — see Quickstart — Pin the deployment in a const.

Datum contract

pub trait ShuffleDatum: Send + Sync + Sized + 'static {
    const TYPE_TAG: UniqueId;
    const WIRE_SIZE: usize;

    fn encode(&self) -> Vec<u8>;
    fn decode(bytes: &[u8]) -> Result<Self, DecodeError>;
}

pub struct DecodeError(pub String);

Every value of D MUST encode to exactly D::WIRE_SIZE bytes. TYPE_TAG and WIRE_SIZE both fold into the deployment identity; schema bumps produce a different id and fail to bond cleanly rather than silently garble.

The typed façade

pub struct Zipnet<D: ShuffleDatum>(/* marker */);

impl<D: ShuffleDatum> Zipnet<D> {
    pub async fn submit  (network: &Arc<Network>, config: &Config) -> Result<Submitter<D>>;
    pub async fn receipts(network: &Arc<Network>, config: &Config) -> Result<Receipts<D>>;
    pub async fn read    (network: &Arc<Network>, config: &Config) -> Result<Reader<D>>;

    pub fn deployment_id(config: &Config) -> UniqueId;
}

Zipnet<D> is a marker — there is no instance to hold. The submit and read constructors open the writer and read-side streams for the deployment described by Config and the datum type D. The receipts constructor is part of the shape but deferred in v1 — see v1 status below. All three reach the same on-wire identity derived from Config + D’s TYPE_TAG/WIRE_SIZE.

deployment_id is a pure function useful for handshake diagnostics — print it on both sides to confirm you and the operator compute the same fingerprint.

Handle types

#[derive(Clone)]
pub struct Submitter<D: ShuffleDatum> { /* opaque */ }

impl<D: ShuffleDatum> Submitter<D> {
    pub async fn send(&self, datum: D) -> Result<SubmissionId>;
}

pub struct Receipts<D: ShuffleDatum> { /* opaque */ }
impl<D: ShuffleDatum> futures::Stream for Receipts<D> {
    type Item = Receipt;
}

pub struct Reader<D: ShuffleDatum> { /* opaque */ }
impl<D: ShuffleDatum> futures::Stream for Reader<D> {
    type Item = D;
}

Submitter<D> is Clone; all clones share one driver task. Drop every clone to tear down the writer. Reader<D> is an independent stream handle; drop it to stop its task.

Receipts (v1 deferred)

Zipnet::<D>::receipts currently returns Error::Protocol("...deferred to v2..."). The Receipts<D> and Receipt / Outcome types stay in the type graph so downstream code can be written against the intended shape — but no handle is ever vended in v1. Applications that need per-submission confirmation poll a Reader<D> and match on byte equality; see Publishing — Confirming delivery via the reader.

The design target for v2 is an ECIES-encrypted per-submission receipt stream; see Roadmap — ECIES-encrypted receipts stream.

Value types

pub struct SubmissionId(pub u64);

pub struct Receipt {
    pub submission_id: SubmissionId,
    pub round:         RoundId,
    pub slot:          usize,
    pub outcome:       Outcome,
}

pub enum Outcome {
    Landed,   // happy path
    Collided, // slot collision; retry next round
    Dropped,  // aggregator never forwarded; retry
}

Receipt and Outcome are the types the v2 receipts stream will yield; in v1 no handle is vended and the types exist only so application code can be compiled forward-compatibly. The SubmissionId is still returned by every send call and can be used by the caller for local correlation.

Errors

pub type Result<T, E = Error> = core::result::Result<T, E>;

#[derive(Debug, thiserror::Error)]
pub enum Error {
    WrongUniverse { expected: NetworkId, actual: NetworkId },
    ConnectTimeout,
    Attestation(String),
    Shutdown,
    Protocol(String),
}

See Troubleshooting for a per-variant diagnostic checklist.

Re-exports from mosaik

Re-exports from zipnet::proto

What you do NOT import

• zipnet::node::* — committee and role internals. Users do not construct CommitteeMachines or run committee Raft groups.
• mosaik::groups::GroupKey — you do not have committee secrets.
• Any raw StreamId / StoreId / GroupId — the SDK derives them from Config + D. Do not try to pin them yourself.

If you find yourself reaching for these, you are probably writing an operator or contributor concern. Revisit What you need from the operator.

Version compatibility

When the operator announces a deployment upgrade, they should publish the zipnet version to use. Users rebuild and redeploy in lockstep.