Certificate ZIP (Hotep)
Overview
GET /api/v2/documents/:id/zip streams a ZIP archive containing blockchain proof certificates and receipt files (.json, .ots, etc.). Neo fetches MongoDB + stored objects and projects a raw field mask to Hotep; Hotep owns all certificate layout logic.
The zip answers 202 { status: "certificates_not_ready" } with Retry-After: 300 when no Bitcoin folder (chainpoint, ots or external) is complete, for every requester. Polygon alone is never enough. A document without any proof still answers 422 No proofs available.
The mode comes from the requester (token agent, then the Bcyip-Agent header), not from the document:
- Automatic agent (
agent_codes.automatic, e.g. Tower): a missing certificate is published to the Hotep queue and the zip answers 202 until it is stored. - Anyone else (Box, web): missing certificates are rendered during the request, in parallel, 180 s each.
Every folder holds the certificate and its receipt. Polygon has its receipt (<denomination>.proof.json) in the zip and in the Hotep payload. HOTEP_MODE=test reads dev/, HOTEP_MODE=live reads prd/ in the certificate bucket.
Request
GET /api/v2/documents/:id/zip?exclude=file&required=chainpoint,ots&only=polygon
Authorization: Bearer <token>
| Query param | Values | Effect |
|---|---|---|
exclude | file | Omit the source document binary from the ZIP |
required | comma-separated proof types | Checked on the final folders: confirmed but incomplete is 202 |
only | comma-separated proof types | Restrict archive to these types only |
Responses: 200 application/zip stream, 202 with Retry-After: 300 while certificates are not ready.
Supported proof types: chainpoint, ots, polygon, external. External proof PDFs are served from Swift storage directly (no Hotep call).
Architecture
The proof watcher (PROOF_WATCHER_ENABLED=true) listens to confirmed proofs and pre-publishes the certificates of automatic documents in batches: one Hotep call at 100 proofs, 2 minutes after the first one, or before the body passes about 3 MB. A batch lost in a restart is published again by the next zip request of the agent.
Monitoring
Neo reports to two Gjallar event checks, both linked to the Gjallar client neo. One token (MONITORING_TOKEN) covers both; the body names the check.
| Check | Opens when | Case id |
|---|---|---|
| Neo certificates | A confirmed proof has no receipt (payload, error) | Proof id |
| Neo manual render load | More than 4 manual renders at once, or one over 20 s (render, warning, 15 min delay) | NEO_INSTANCE_NAME, defaults to the hostname |
Configuration
| Env var | Required | Description |
|---|---|---|
HOTEP_URL | Yes | Hotep service base URL |
HOTEP_SERVICE_TOKEN | Yes | Bearer token for Hotep |
HOTEP_MODE | Yes | test (specimen watermark, dev/) or live (prd/) |
CERT_S3_ENDPOINT, CERT_S3_REGION, CERT_S3_BUCKET, CERT_S3_ACCESS_KEY_ID, CERT_S3_SECRET_ACCESS_KEY | Yes | Certificate bucket, read-only for neo (GetObject on its prefix) |
MONITORING_URL | Yes | Gjallar origin, without /api/checks |
MONITORING_TOKEN | Yes | Gjallar client neo token |
NEO_INSTANCE_NAME | No | Instance name in the load case |
PROOF_WATCHER_ENABLED | No | true to pre-publish certificates |
Neo refuses to start when a required value is missing.
Swift storage
Two credential sets (legacy parity):
| Set | Env prefix | Used for |
|---|---|---|
| Files | OVH_USERNAME, OVH_PASSWORD, OVH_FILES_CONTAINER, … | Source document binary |
| Proofs | OVH_PROOFS_*, OVH_PROOFS_CONTAINER_* | Receipt blobs per proof type |
Keystone v3 auth with in-memory token cache (swift-auth.service.ts).
Technical decisions
- Neo as dumb pipe:
projectPayload()picks Mongo fields; Hotep resolves owner type, coauthors, represented client,ownerShare - Streaming ZIP:
archiverpipes to HTTP response — no full archive buffered in memory - Hotep owns retries: idempotency key
<proofId>:<payload hash>:<UTC hour>and retries live in the Hotep queue. Neo keeps nocertificate_jobscollection and no sweep - Least privilege on the bucket: Hotep can only
PutObject, neo can onlyGetObject. WithoutListBucket, a missing certificate answers 403 and is logged as a warning, then handled as missing
Key files
src/domains/document/zip.service.ts— Folder rules, requester mode, parallel renders, receipt incidents, watcher job buildersrc/domains/document/document.controller.ts—GET :id/zip, 202 withRetry-Aftersrc/core/certificates/certificate-queue.service.ts— Bucket read and batch publishsrc/core/hotep/hotep.service.ts—POST /api/generate, batch publishsrc/core/hotep/manual-render-monitor.service.ts— Manual render loadsrc/core/monitoring/monitoring.service.ts— Gjallar event checkssrc/core/proof-watcher/proof-watcher.service.ts— Batches on confirmationsrc/core/hotep/hotep.types.ts—HotepPayloadprojection typessrc/core/storage/storage.service.ts— Swift HTTP downloadscertificate-zip.md,docs/next/certificate-zip-flow.md(neo-backend repo) — Download contract and design reference
Known issues
- OTS proofs can stay pending for a long time on dev; chainpoint alone completes the Bitcoin folder
Next steps
- Drop the unused
certificate_jobscollection