Skip to main content
Version: 1.4.0

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/zip answers 202 { status: "certificates_not_ready" } with Retry-After: 300 when no chainpoint, ots or external folder is complete, for every requester. It no longer answers 409 or 422 proofs_incomplete
  • required is 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-copies call
  • 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-flow on Hotep) before deploy
  • The certificate_jobs collection 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 builder
  • src/domains/document/document.controller.ts - 202 with Retry-After, Bcyip-Agent passed to the zip
  • src/domains/document/document.module.ts - Monitoring module
  • src/core/certificates/certificate-queue.service.ts - Bucket read and batch publish, no Mongo
  • src/core/certificates/certificate-queue.module.ts - No database
  • src/core/config/certificate-queue.config.ts - Bucket config always validated
  • src/core/hotep/hotep.service.ts - 180 s manual timeout, batch publish, review copy removed
  • src/core/hotep/manual-render-monitor.service.ts - Manual render load
  • src/core/hotep/hotep.module.ts - Render monitor and monitoring module
  • src/core/monitoring/monitoring.service.ts, src/core/monitoring/monitoring.module.ts, src/core/config/monitoring.config.ts - Gjallar event checks, config validated at startup
  • src/core/proof-watcher/proof-watcher.service.ts - Batches, no sweep, no legacy path
  • src/core/proof-watcher/proof-watcher.module.ts - Certificate queue module
  • .env.example, test/e2e-env.ts - Env changes
  • certificate-zip.md, docs/next/certificate-zip-flow.md - Download contract and design reference
  • src/domains/document/zip.service.spec.ts, src/core/hotep/*.spec.ts, src/core/proof-watcher/proof-watcher.service.spec.ts - Tests