commonware-conformance

Automatically assert the stability of encoding and mechanisms over time.

Status

Stability varies by primitive. See README for details.

lib.rs:

Automatically assert the stability of encoding and mechanisms over time.

This crate provides a unified infrastructure for verifying that implementations maintain backward compatibility by comparing output against known-good hash values stored in TOML files.

The Conformance Trait

The core abstraction is the Conformance trait, which represents types that can produce deterministic bytes from a seed.

This enables conformance testing across different domains, for example:

• Codec: Verify wire format stability
• Storage: Verify on-disk format stability
• Network: Verify message ordering consistency

Storage Format

Test vectors are stored in a TOML file with a single hash per type:

["Vec<u8>"]
n_cases = 100
hash = "abc123..."

["Vec<u16>"]
n_cases = 100
hash = "def456..."

The hash is computed by generating n_cases commitments (using seeds 0..n_cases), and hashing all the bytes together.

Regeneration Mode

When cfg(generate_conformance_tests) is set, tests regenerate their expected hashes in the TOML file. Use this to intentionally update the format:

RUSTFLAGS="--cfg generate_conformance_tests" cargo test