feat-certificate-zip-flow
✨ New Features
[One certificate flow: 202 while waiting, polygon receipt, batches, Gjallar]
Goal: The proof zip must follow one set of rules in production (docs/next/certificate-zip-flow.md): 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, for every requester. It no longer answers 409 or 422proofs_incompleterequiredis checked on the final folders: confirmed but incomplete is 202- Polygon has its receipt (
<denomination>.proof.json) 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
- A confirmed proof without its receipt opens an error case on the Gjallar check "Neo certificates"
- Manual renders are counted per instance; more than 4 at once or one over 20 s opens a warning on "Neo manual render load"
- The watcher batches automatic certificates: one Hotep call at 100 proofs, 2 minutes, or about 3 MB
Implementation Details:
- Removed:
CERTIFICATE_QUEUE_ENABLED, the legacy render path (generateZipSystem),certificate_jobs, the five-minute sweep,attempts, the idempotency key sent by neo, and the/api/review-copiescall CERT_S3_*is now required at startup- New env, required at startup:
MONITORING_URL(Gjallar origin),MONITORING_TOKEN(token of the Gjallar client "neo", which both checks are linked to). Optional:NEO_INSTANCE_NAME - Needs Hotep with the batch publish route (
feat/certificate-flowon Hotep) before deploy - The
certificate_jobscollection is no longer read and can be dropped
Files Modified:
src/domains/document/zip.service.ts- Folder rules, requester mode, parallel renders, receipt incidents, watcher job buildersrc/domains/document/document.controller.ts- 202 withRetry-After,Bcyip-Agentpassed to the zipsrc/domains/document/document.module.ts- Monitoring modulesrc/core/certificates/certificate-queue.service.ts- Bucket read and batch publish, no Mongosrc/core/certificates/certificate-queue.module.ts- No databasesrc/core/config/certificate-queue.config.ts- Bucket config always validatedsrc/core/hotep/hotep.service.ts- 180 s manual timeout, batch publish, review copy removedsrc/core/hotep/manual-render-monitor.service.ts- Manual render loadsrc/core/hotep/hotep.module.ts- Render monitor and monitoring modulesrc/core/monitoring/monitoring.service.ts,src/core/monitoring/monitoring.module.ts,src/core/config/monitoring.config.ts- Gjallar event checks, config validated at startupsrc/core/proof-watcher/proof-watcher.service.ts- Batches, no sweep, no legacy pathsrc/core/proof-watcher/proof-watcher.module.ts- Certificate queue module.env.example,test/e2e-env.ts- Env changescertificate-zip.md,docs/next/certificate-zip-flow.md- Download contract and design referencesrc/domains/document/zip.service.spec.ts,src/core/hotep/*.spec.ts,src/core/proof-watcher/proof-watcher.service.spec.ts- Tests