Decision record — the verifier service contract
The freeze of the verifier-service OpenAPI contract at v1: three operations, a closed reason-code vocabulary, and the invariants the freeze locks in for every client in every language.
What is being frozen
Status: Accepted (2026-07-21) — contract v1 frozen at 1.0.0 · depends on the specification’s presentation rules, decision records, paid-verification permission and single-core rule
The OpenAPI document verifier-service.v1.yaml at contract version 1.0.0: three operations (getBuildInfo, createChallenge, validatePresentation), their schemas, and the closed ReasonCode vocabulary — byte-identical to the reason codes the embedded SDK emits.
Freezing means: any change to decision semantics or the reason vocabulary is a major contract version (the SDK’s semver policy, applied at the contract level); additive, non-semantic surface is minor. Transport-only clients, in every language, build against the frozen contract.
Why freeze now
The multi-language strategy makes this contract the load-bearing artifact of the whole approach: it is the boundary that guarantees no client ever carries cryptography or policy. The nine acceptance conditions, the 10-second constant and the retention schema sit behind the contract and are deliberately unexpressible in it: no lifetime parameter, no skip flags, no per-request height-lag override.
A contract test enforces route-for-route and code-for-code agreement between the YAML and the running service, so the frozen document is checked against reality on every CI run.
Invariants the freeze locks in
- One decision path:
validatePresentationresponses are the embedded SDK’s decision verbatim; HTTP 400 exists only where no session identity can exist — nothing parseable means no retention record. - Closed reason vocabulary shared with the conformance vectors; any change is major and flows to every language at once.
- Challenge identity (verifier id, exact origin, request key) is deployment configuration bound to on-chain registrations — never caller input.
build-infoexposes exactly the release pins — enough for a client to verify what it talks to, never secrets.
Post-freeze changelog
| Version | Date | Change |
|---|---|---|
1.0.0 | 2026-07-21 | Contract frozen (this record). |
1.1.0 | 2026-07-21 | Additive minor: BuildInfo gains required conformance_suite_version. No decision-semantics or reason-code change. |
The freeze is what lets every client — in any language — treat the service surface as a stable fact: the conformance suite, the reason-code page and the service-mode guide in these docs all build on it.