Minting

Minting Lifecycle

Overview

Every mint request follows a deterministic lifecycle from submission through to completion. This page describes each stage, the state transitions involved, and what happens during failures.

Mint Request Submission

A mint request begins when a user submits a request through the Minting Wizard or directly via the API (submit_mint_request).

The submission step performs the following atomically:

  1. Preflight validation — verifies the product is mint-ready (active commercial status, all required DPP fields populated).
  2. ERP enforcement — if a production batch is linked, validates it exists, belongs to the brand/product, has READY status, and that the requested quantity does not exceed the batch quantity.
  3. Job creation — creates a mint job in QUEUED status.
  4. Batch creation — creates a corresponding mint batch linked 1:1 to the job.

If any preflight check fails, the request returns a structured list of blocking reasons without creating any records.

Job State Transitions

QUEUED → RESERVED → PROCESSING → COMPLETED
                                → FAILED
StateDescription
QUEUEDJob is waiting to be claimed by a background worker.
RESERVEDA worker has claimed the job and is preparing to process it.
PROCESSINGToken generation is actively in progress. Units are being created in processing cycles.
COMPLETEDAll requested units have been generated successfully.
FAILEDThe job has exhausted retry attempts (max 3) and has been marked as a terminal failure.

Batch Status Transitions

queued → processing → minted
                    → failed

The mint batch status mirrors the job lifecycle. When the job transitions to COMPLETED, the batch transitions to minted and records the final minted_quantity.

Processing Cycles

During the PROCESSING phase:

  • Units are generated in cycles of up to 20,000 units per cycle.
  • Each cycle inserts units with resolver URLs, serial numbers (for serial-mode jobs), and appropriate status.
  • The worker continues processing cycles until the requested quantity is reached or an error occurs.
  • For large jobs (e.g., 1,000,000 units), the background worker automatically continues across multiple invocations until the job is complete.

Failure & Retry Semantics

  • If a processing cycle encounters an error, the error is recorded and the job’s error count is incremented.
  • The job remains eligible for retry until it has accumulated 3 consecutive errors.
  • After 3 failures, the job transitions to FAILED status with the last error message preserved.
  • Partial progress is preserved — units generated before the failure are not rolled back.

Idempotency

Mint requests support client-provided idempotency keys. If a duplicate request is submitted with the same key:

  • The existing job and batch are returned.
  • No new records are created.
  • The response includes is_duplicate: true to indicate the idempotent match.

This makes it safe to retry mint submissions in the event of network failures or timeouts.

Background Continuation

Large jobs are designed to complete without user intervention:

  • The background worker automatically picks up queued and in-progress jobs.
  • Jobs are processed in FIFO order (oldest first).
  • A soft lock mechanism ensures only one worker processes a given job at any time, preventing duplicate unit generation.
  • The system has been tested with multiple overlapping 1,000,000-unit jobs completing concurrently without conflicts.

Token Lifecycle (Post-Mint)

Once units are created, each token follows its own lifecycle:

minted → active → revoked
StateDescription
mintedToken has been created but not yet activated (relevant for first_scan activation mode).
activeToken is live and resolving. For active_at_mint mode, tokens enter this state immediately.
revokedToken has been permanently deactivated.

Activation occurs either at mint time or upon first scan, depending on the activation mode selected during the mint request.