Skip to content
On this page

Conformance vectors

Every sibling protocol ships normative test vectors in its oc-*-protocol repo. The reference implementations (TypeScript + Python) run those vectors on every CI push: the OC Attest SDKs vendor a copy, and the other cores read the spec repo's test-vectors/ directly. Any drift between the spec and the implementations is a CI failure.

This page describes the pattern. Per-protocol vector details live in the protocol's own repo.

Why conformance vectorsLink to this section

The attestation ID is a content hash of the canonical message. Two implementations that agree on the inputs but disagree on the canonical bytes produce different IDs — which breaks Nostr discovery, verifier trust, and every downstream protocol that references an attestation.

Conformance vectors pin the bytes. Each vector is a triple (inputs, expected_bytes, expected_id). A passing run proves the implementation produces the same bytes and the same hash as the spec.

Vector set per protocolLink to this section

Every spec repo ships its vectors under test-vectors/ (the family standard). OC Attest, the progenitor spec, additionally mirrors them under conformance/vectors/ for backward compatibility — both directories contain the same files.

The OC Attest SDKs vendor conformance/vectors/ verbatim (sdk/src/__tests__/vectors/ and sdk-py/tests/vectors/). Each other reference core (@orangecheck/<verb>-core) checks out its spec repo in CI and reads test-vectors/ from it (OC_<VERB>_VECTORS_DIR, or a sibling checkout locally), so it keeps no copy. Every vector runs on each CI push.

Vector categories (OC Attest example)Link to this section

The 29 OC Attest vectors are organized by test category:

CategoryCountWhat they pin
canonical_message7Byte-exact canonical-message output for a given input set
identities_format3Identity-list sort order and escape rules
attestation_id2sha256(canonical_bytes) matches
score_v04Scoring formula output (tv10–tv13)
reject4MUST-reject cases — malformed identifiers, wrong header, etc.
bip322_signature3Real BIP-322 signatures against fixed addresses
bond_*6The bond extension: message, signature (2), nullifier, floors, extension

The categories exist so a developer debugging a specific failure can skim to the relevant block rather than re-reading all 29.

How the CI gate worksLink to this section

Each reference SDK has a test:conformance target (or a dedicated test file) that loads the vector JSON and asserts every expected output. A typical flow:

Shell
cd oc-packages/sdk      && yarn test   # TS passes all 29 vectors
cd oc-packages/sdk-py   && pytest      # Python passes all 29 vectors

If either fails, the PR is blocked. If both pass, byte-identity between the two implementations is proven (modulo floating-point edge cases in score_v0, which are handled with a tolerance of 0.01).

Cross-impl drift is prevented by a third CI job in oc-packages: after both suites pass, a diff job fetches oc-attest-protocol's conformance/vectors/ on main and compares it against what's vendored in each SDK. If the vendored copy is out of date, CI fails and the SDK must re-vendor.

Adding a vectorLink to this section

For any sibling protocol, the flow is the same:

  1. Write the vector JSON in oc-<verb>-protocol/test-vectors/<id>.json following the existing shape for that spec. OC Attest additionally has a generate.mjs helper for vectors that are derivable from a reference calculation.
  2. Update the spec's test-vectors/index.json (or README.md listing) so tooling can discover the new file.
  3. Run the matching reference core's test suite locally against the new vector. For OC Attest, re-vendor conformance/vectors/ into oc-packages/sdk/src/__tests__/vectors/ and sdk-py/tests/vectors/ first; the other cores read the spec repo directly.
  4. The new vector must pass before the spec PR merges; for OC Attest, the SDK PR that re-vendors the vectors is paired with the spec PR.

Specs that add a new MUST-reject case should include a vector in the spec's reject category so the behavior is pinned.

See alsoLink to this section