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 when something fails.

Mint request submission

A mint request begins when someone submits it through the Minting Wizard or programmatically through the API.

Submission performs the following atomically:

1

Preflight validation

Confirms the product is mint ready: active commercial status and all required DPP fields populated.

2

ERP enforcement

If a production batch is linked, confirms it exists, belongs to the brand and product, carries READY status, and that the requested quantity fits within the batch quantity.

3

Job creation

Creates a mint job in QUEUED status.
4

Batch creation

Creates a mint batch linked one to one with the job.

If a preflight check fails, the request returns a structured list of blocking reasons and creates no 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 in progress. Units are being created in processing cycles.
COMPLETEDAll requested units have been generated successfully.
FAILEDThe job has exhausted its retry attempts and is a terminal failure.

Batch status transitions

queued → processing → minted
                    → failed

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

Processing cycles

During the PROCESSING phase:

  • Units are generated in high throughput cycles.
  • Each cycle inserts units with resolver URLs, serial numbers for serial mode jobs, and the appropriate status.
  • The worker continues until the requested quantity is reached or an error occurs.
  • Large jobs continue automatically across multiple worker invocations until the job is complete.

Failure and retry semantics

  • If a processing cycle hits an error, the error is recorded and the job’s error count increases.
  • The job stays eligible for retry until it exhausts its allowed attempts.
  • After that, the job moves to FAILED with the last error message preserved.
  • Partial progress is preserved. Units generated before the failure remain in place.

Idempotency

Mint requests support client provided idempotency keys. When a duplicate request arrives with the same key:

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

Idempotency keys make it safe to retry a mint submission after a network failure or timeout, without any risk of issuing a second batch.

Background continuation

Large jobs are designed to complete without user intervention:

  • The background worker picks up queued and in progress jobs.
  • Jobs are processed oldest first.
  • A soft lock ensures only one worker processes a given job at a time, preventing duplicate units.

Token lifecycle

StateDescription
mintedThe token exists and the passport is not yet live, awaiting manual activation by the brand.
activeThe token is live and resolving. Tokens activated at mint enter this state immediately.
revokedThe token has been permanently deactivated.

Activation has two modes chosen on the mint request. Activated at mint makes the passport live the moment it is issued. Manual activation issues the token inactive so the brand can make it live later, for example when the unit is packed, shipped or sold.