Skip to main content
Version: 1.5.0

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 paramValuesEffect
excludefileOmit the source document binary from the ZIP
requiredcomma-separated proof typesChecked on the final folders: confirmed but incomplete is 202
onlycomma-separated proof typesRestrict 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.

CheckOpens whenCase id
Neo certificatesA confirmed proof has no receipt (payload, error)Proof id
Neo manual render loadMore 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 varRequiredDescription
HOTEP_URLYesHotep service base URL
HOTEP_SERVICE_TOKENYesBearer token for Hotep
HOTEP_MODEYestest (specimen watermark, dev/) or live (prd/)
CERT_S3_ENDPOINT, CERT_S3_REGION, CERT_S3_BUCKET, CERT_S3_ACCESS_KEY_ID, CERT_S3_SECRET_ACCESS_KEYYesCertificate bucket, read-only for neo (GetObject on its prefix)
MONITORING_URLYesGjallar origin, without /api/checks
MONITORING_TOKENYesGjallar client neo token
NEO_INSTANCE_NAMENoInstance name in the load case
PROOF_WATCHER_ENABLEDNotrue to pre-publish certificates

Neo refuses to start when a required value is missing.

Swift storage​

Two credential sets (legacy parity):

SetEnv prefixUsed for
FilesOVH_USERNAME, OVH_PASSWORD, OVH_FILES_CONTAINER, …Source document binary
ProofsOVH_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: archiver pipes 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 no certificate_jobs collection and no sweep
  • Least privilege on the bucket: Hotep can only PutObject, neo can only GetObject. Without ListBucket, 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 builder
  • src/domains/document/document.controller.ts — GET :id/zip, 202 with Retry-After
  • src/core/certificates/certificate-queue.service.ts — Bucket read and batch publish
  • src/core/hotep/hotep.service.ts — POST /api/generate, batch publish
  • src/core/hotep/manual-render-monitor.service.ts — Manual render load
  • src/core/monitoring/monitoring.service.ts — Gjallar event checks
  • src/core/proof-watcher/proof-watcher.service.ts — Batches on confirmation
  • src/core/hotep/hotep.types.ts — HotepPayload projection types
  • src/core/storage/storage.service.ts — Swift HTTP downloads
  • certificate-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_jobs collection