Skip to main content
Version: 1.4.0

One certificate flow: 202 while waiting, polygon receipt, batches, monitoring

Version: 1.4.0 Date: 2026-11-05

Goal: The proof zip follows one set of rules in production: a polygon proof comes with its receipt, a requester that can wait is told to call again instead of getting an error, and neo stops tracking what it sent to Hotep.

Solution: The certificate queue is always on. The zip answers 202 when no Bitcoin folder is complete. The requester decides how a missing certificate is handled: an automatic agent publishes it to the Hotep queue, anyone else renders it during the request. Hotep owns retries and idempotency keys, so neo keeps no certificate_jobs collection and no retry sweep.

Features:

  • GET /documents/:id/zip answers 202 { status: "certificates_not_ready" } with Retry-After: 300 when no chainpoint, ots or external folder is complete. It no longer answers 409 or 422 proofs_incomplete
  • Polygon has its receipt in the zip and in the Hotep payload
  • The mode comes from the requester (token agent, then Bcyip-Agent), not from the document
  • Manual renders run in parallel, 180 seconds each
  • Gjallar checks "Neo certificates" (receipt missing) and "Neo manual render load" (more than 4 manual renders or one over 20 s)
  • The watcher batches automatic certificates: one Hotep call at 100 proofs, 2 minutes, or about 3 MB

Implementation Details:

  • Removed: CERTIFICATE_QUEUE_ENABLED, generateZipSystem, certificate_jobs, the sweep, the idempotency key sent by neo, /api/review-copies
  • Required at startup: CERT_S3_*, MONITORING_URL, MONITORING_TOKEN (Gjallar client neo). Optional: NEO_INSTANCE_NAME

Files Modified:

  • src/domains/document/zip.service.ts - Folder rules, requester mode, parallel renders, receipt incidents
  • src/domains/document/document.controller.ts - 202 with Retry-After
  • src/core/certificates/certificate-queue.service.ts - Bucket read and batch publish
  • src/core/hotep/hotep.service.ts, src/core/hotep/manual-render-monitor.service.ts - Batch publish, manual render load
  • src/core/monitoring/monitoring.service.ts, src/core/config/monitoring.config.ts - Gjallar event checks
  • src/core/proof-watcher/proof-watcher.service.ts - Batches, no sweep

Release fragment: feat-certificate-zip-flow