bIP-0001 — Verifier service contract v1
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 · standards-track · card MINT-171 · spec refs R14, R18, R26, §14.4
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 — the library's REASON_* constants plus the error-carried codes, byte-identical.
Freezing means: any change to decision semantics or the reason vocabulary is a major contract version (the ADR-0002 semver policy applied at the contract level); additive, non-semantic surface is minor. The TypeScript and PHP transport-only clients build against the frozen contract.
Why freeze now
ADR-0003 makes this contract the load-bearing artifact of the whole multi-language strategy: 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 library'sPresentationDecisionverbatim; 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.