open-standards/smart-byte/conformance/README.md

Smart Byte Conformance Vectors

This directory contains the conformance test-vector pack for the Smart Byte substrate specification. Any third-party implementation, in any language, can consume these vectors to self-certify against the canonical wire format without trusting the reference implementation.

The vectors are the social contract. The spec text in ../spec/ says what the substrate is; the vectors here say what the substrate's wire format looks like, byte for byte, on the inputs the spec text describes. An implementation that passes the vectors is canonical. An implementation that fails the vectors is not.

The vectors are licensed CC-BY-4.0, consistent with the spec directory. They contain no $ref pointers, no external URLs, and no runtime dependencies.

What is in the pack

Each spec version has its own subdirectory (v1/, v2/, ...). Today only v1/ exists; it corresponds to the spec text in ../spec/treatise_v1_parts_I_II_III_combined.md.

A pack for a given version contains five JSON files plus regeneration.md:

File	Tests
canonicalisation_vectors.json	CBOR canonical-encoding rules (§8 wire format)
said_vectors.json	SAID computation: BLAKE3-256 over canonical CBOR (§8.2)
signature_vectors.json	Ed25519 sign + verify over SAIDs (§8.3, §8.4)
lockstep_vectors.json	BFT supermajority commit logic (§9, §13)
gossip_vectors.json	Gossip propagation, conflict detection, ordering (§17)

regeneration.md documents how to regenerate the vectors from the Rust reference implementation (smart-byte-rs, landing alongside spec v1.0).

How to consume the vectors

Each JSON file is a top-level array of vector objects. Vector objects share the common shape:

{
  "name": "short-stable-identifier",
  "description": "human-readable description of what is being tested",
  ...test-specific fields...
}

The conventional flow for an implementation under test (IUT):

1. Load the JSON file for the relevant spec version.
2. For each vector, run the IUT against the input (or equivalent field) and compare its output to the expected_* field.
3. A vector passes if the IUT's output is byte-for-byte equal to the expected_* field (or, for negative vectors, the IUT rejects the input with the documented error class).
4. The IUT is canonical for a spec version iff every vector in that version's pack passes.

There is no scoring, no "mostly conforms" status, and no waiver process. A vector pack is a hard gate.

Versioning rule

Vectors are versioned per spec version, not per implementation, not per calendar release of the conformance pack.

• v1/ corresponds to spec v1. Once spec v1 is frozen, v1/ is append-only in scope (additional vectors may be added that test the same canonical wire format) and never modifies existing vectors' expected_* outputs.
• v2/ will appear when (and only when) the spec moves to a new version that introduces an incompatible wire-format change. The compatibility matrix lives in VERSIONS.md.
• A bug in a vector pack (e.g. an expected_* field that disagrees with the spec) is fixed by superseding the vector with a new one whose name carries a suffix (-fixed, -corrected); the original is retained with a "superseded_by" field so historical IUTs that pinned to the old vector can detect the supersession.

CI gate

../../.github/workflows/conformance.yml is the repository-level CI gate. Every PR that touches smart-byte/spec/ or smart-byte/conformance/ must pass the gate. The gate validates:

• Every JSON file in v*/ parses as valid JSON.
• Every spec change is accompanied by a vector-pack update (a PR that modifies smart-byte/spec/ without modifying smart-byte/conformance/ is rejected at the gate).

The gate's purpose is procedural: a spec change without a vector change is either a clarifying edit (which should declare itself by also touching the vector pack's regeneration.md to record the editorial reason) or a silent wire-format change (which is prohibited). Either way, both directories move together.

What the pack does not cover

The pack is the wire-format gate. It does not cover:

• Application-layer cargo schemas. Cargo is opaque to the substrate; what a USD-byte or a joule-byte or a sensor-reading-byte means is a layer-2 protocol concern. Layer-2 protocols ship their own vectors.
• Performance. The pack tests correctness, not throughput, latency, or energy cost. Performance is documented in the reference implementation's benchmarks.
• Operational concerns. Cluster topology choice, key custody, hardware procurement, regulatory compliance for specific cargo types — all out of scope for the substrate's conformance pack.

License

The vector pack is licensed CC-BY-4.0. See ../../LICENSE for the repository-level license terms.