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.
| Protocol | Spec repo path | # vectors |
|---|---|---|
| OC Attest | oc- (opens in a new tab) | 29 (tv01–tv29) |
| OC Lock | oc- (opens in a new tab) | 4 (v01–v04), plus device- |
| OC Stamp | oc- (opens in a new tab) | 9 (v01–v09) |
| OC Vote | oc- (opens in a new tab) | 18 (v01–v18) |
| OC Agent | oc- (opens in a new tab) | 66 (v01–v66) |
| OC Pledge | oc- (opens in a new tab) | 58 (v01–v58) |
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:
| Category | Count | What they pin |
|---|---|---|
canonical_ | 7 | Byte-exact canonical-message output for a given input set |
identities_ | 3 | Identity-list sort order and escape rules |
attestation_ | 2 | sha256( matches |
score_ | 4 | Scoring formula output (tv10–tv13) |
reject | 4 | MUST-reject cases — malformed identifiers, wrong header, etc. |
bip322_ | 3 | Real BIP-322 signatures against fixed addresses |
bond_ | 6 | The 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:
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:
- Write the vector JSON in
oc-<verb>-protocol/test-vectors/<id>.jsonfollowing the existing shape for that spec. OC Attest additionally has agenerate.mjshelper for vectors that are derivable from a reference calculation. - Update the spec's
test-vectors/index.json(orREADME.mdlisting) so tooling can discover the new file. - Run the matching reference core's test suite locally against the new vector.
For OC Attest, re-vendor
conformance/vectors/intooc-packages/sdk/src/__tests__/vectors/andsdk-py/tests/vectors/first; the other cores read the spec repo directly. - 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
- Canonical message — what the bytes look like
- SDKs at a glance — the per-protocol cores that run these vectors