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/zipanswers202 { status: "certificates_not_ready" }withRetry-After: 300when no chainpoint, ots or external folder is complete. It no longer answers 409 or 422proofs_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 clientneo). Optional:NEO_INSTANCE_NAME
Files Modified:
src/domains/document/zip.service.ts- Folder rules, requester mode, parallel renders, receipt incidentssrc/domains/document/document.controller.ts- 202 withRetry-Aftersrc/core/certificates/certificate-queue.service.ts- Bucket read and batch publishsrc/core/hotep/hotep.service.ts,src/core/hotep/manual-render-monitor.service.ts- Batch publish, manual render loadsrc/core/monitoring/monitoring.service.ts,src/core/config/monitoring.config.ts- Gjallar event checkssrc/core/proof-watcher/proof-watcher.service.ts- Batches, no sweep
Release fragment: feat-certificate-zip-flow