For developers
The reference implementation, its two local HTTP services, the API contracts and the identifiers an independent implementation must match.
Source code
The source repository for the Python reference implementation is not public yet. The documents, API contracts and identifiers on this page are enough to start an independent, compatible implementation.
With a copy of the source, it needs Python 3.12 or 3.13. Install it from the repository root:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
python -m pip checkStart the read-only inclusion verifier on your own machine, then query it from another terminal:
openaiis-verify-http --host 127.0.0.1 --port 8081
curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/capabilities
The package installs three commands: openaiis-verify-http (the verifier above),
openaiis-registry-http (the owner-operated registry) and openaiis-demo.
Runtime dependencies are pinned: cryptography for Ed25519 and cbor2
for CBOR.
The registry service binds to 127.0.0.1 and needs a durable database, a checkpoint
database, a registry origin, issuer policy, a checkpoint signing key and an operator token.
Keep its configuration files owner-only (0600) and never publish signing keys or
operator credentials.
HTTP API
Both services describe themselves in OpenAPI 3.1. They are local reference services; an endpoint existing does not mean a public service is running.
Registry registry-openapi.json
| Method | Path | What it does |
|---|---|---|
GET | /health | Process liveness |
GET | /v1/capabilities | Complete local registry capability manifest |
POST | /v1/verify/inclusion | Verify signed inclusion against caller pinned keys |
POST | /v1/claims | Submit externally signed typed claim against operator provisioned pins |
POST | /v1/checkpoints | Sign and durably store Merkle checkpoint with operator authorization |
GET | /v1/claims/{digest} | Retrieve a persisted canonical signed claim, but not typed payload |
GET | /v1/claims/{digest}/receipt | Proof of inclusion against a stored signed checkpoint |
GET | /v1/checkpoints/latest | Latest signed checkpoint; does not assert Bitcoin confirmation |
GET | /v1/checkpoints/{size} | Retrieve a particular immutable checkpoint |
GET | /v1/proofs/consistency | Consistency path between two published checkpoint tree sizes |
GET | /v1/registry/status | Durable append-only registry current status |
GET | /v1/claim-types | List all supported typed claim profiles |
POST | /v1/verify/record | Verify canonical record signature against caller-provided pinned key |
POST | /v1/verify/typed | Verify typed payload and issuer signature against caller-provided pinned key |
POST /v1/claims takes exactly record_base64, payload_base64
and issuer_id; the claim must already be signed by its issuer.
POST /v1/checkpoints requires the operator's bearer token. Public read and verify
routes never get signing authority.
Read-only verifier verifier-openapi.json
| Method | Path |
|---|---|
GET | /health |
GET | /v1/capabilities |
POST | /v1/verify/inclusion |
A verification response reports cryptographic validity against the keys you supply.
CRYPTOGRAPHIC_INCLUSION_VERIFIED is an inclusion result, not an operational ALLOW, and a
checkpoint marked SIGNED is not a Bitcoin confirmation.
Wire identifiers
Exact strings from Protocol V5.0 Appendix A. \0 means one zero byte. A verifier must
reject a record presented under the wrong profile or domain.
| Object | Identifier |
|---|---|
| Signed universal record | openaiis-universal-registry-v1 |
| Record signing domain (ASCII + NUL) | OPENAIIS/UNIVERSAL-REGISTRATION/v1\0 |
| Inclusion receipt | openaiis-universal-inclusion-v1 |
| Registry log kind | registry_record |
| Core 17-type catalogue | openaiis-universal-type-lock-v1 |
| Extension type catalogue | openaiis-universal-type-extensions-v2 |
| Identity consent-intent domain (ASCII + NUL) | OPENAIIS/IDENTITY-CONSENT/v1\0 |
| Private artifact registration profile | openaiis-artifact_registration-private-v1 |
| Private artifact commitment domain (ASCII + NUL) | OPENAIIS/PRIVATE-ARTIFACT-COMMITMENT/v1\0 |
| Authenticated lifecycle index | openaiis-lifecycle-index-v1 |
| Lifecycle-index proof | openaiis-lifecycle-index-proof-v1 |
| Universal Bitcoin proof bundle | openaiis-universal-bitcoin-bundle-v1 |
Building a compatible verifier
Start with Protocol V5.0 §17, which lists the eleven requirements a conforming verifier must apply, and Appendix B, the 23 invariants it must preserve. Given the same evidence, trust roots, profiles and policy, independent verifiers must reach the same result and reasons.
The documents are licensed under CC BY 4.0, so you may reuse and adapt the specification with attribution. Independent compatible implementations are welcome. See Licensing and name for what the licences do and do not cover.