Minting

Minting Architecture

Overview

The tieback minting system is designed for enterprise-scale Digital Product Passport issuance. It separates concerns between a synchronous control plane (user-facing API) and an asynchronous execution plane (background processing), enabling reliable generation of up to 1,000,000 tokens per request.

High-Level Flow

User / API Client
       │
       ▼
 ┌─────────────┐
 │  Mint Gateway │  ← submit_mint_request (synchronous)
 │  (Control)    │     Preflight validation, job + batch creation
 └──────┬────────┘
        │
        ▼
 ┌─────────────┐
 │  Job Queue   │  ← QUEUED status, FIFO ordering
 └──────┬────────┘
        │
        ▼
 ┌──────────────────┐
 │  Background Worker │  ← Claims jobs, processes in cycles
 │  (Execution)       │     20,000 units per cycle
 └──────┬─────────────┘
        │
        ▼
 ┌─────────────┐
 │  Mint Units  │  ← Tokens with resolver URLs
 └──────┬────────┘
        │
        ▼
 ┌──────────────────┐
 │  Export Generator  │  ← CSV manifests (10,000 per pack)
 └──────┬─────────────┘
        │
        ▼
 ┌─────────────┐
 │  Signed URL  │  ← Client-side download (5-min TTL)
 └──────────────┘

Control Plane vs Execution Plane

Control Plane

The control plane handles user-facing operations:

  • Mint Gateway — submit_mint_request performs atomic preflight validation and creates the job/batch pair. Returns immediately with a job ID.
  • Read APIs — list_mint_batches, list_mint_units, list_mint_events, get_mint_batch_by_id, and get_mint_kpis provide paginated read access to minting data.
  • Export APIs — list_payload_packs lists generated export artifacts.

All control plane operations require authenticated sessions with appropriate role permissions (admin or owner).

Execution Plane

The execution plane handles asynchronous token generation:

  • Job Claiming — the background worker claims queued jobs using a locking mechanism that prevents multiple workers from processing the same job simultaneously.
  • Chunk Processing — units are generated in cycles of up to 20,000, with each cycle inserting tokens, resolver URLs, and serial numbers atomically.
  • Continuation — for jobs exceeding a single processing window, the worker automatically continues in subsequent invocations until the job reaches COMPLETED status.
  • Failure Isolation — errors in one processing cycle do not affect previously generated units. The retry mechanism (max 3 attempts) provides resilience against transient failures.

Idempotency

The mint gateway supports client-provided idempotency keys. When a duplicate key is detected, the system returns the existing job without creating new records. This enables safe retries across network boundaries.

Concurrency Model

The system supports multiple concurrent mint jobs:

  • Each job is independently claimed and processed.
  • A soft-lock mechanism ensures exclusive access during processing.
  • No duplicate tokens or serial numbers are generated, even under concurrent load.
  • The system has been validated with multiple overlapping 1,000,000-unit jobs completing without conflicts.

Resolver Plane (Separate)

The resolver infrastructure is architecturally separated from the minting control plane:

  • Resolver URLs are written at token creation time and are immediately scannable.
  • The resolver handles scan resolution, token activation (for first_scan mode), and telemetry capture.
  • Resolver endpoints operate independently and do not share authentication with the minting control plane.
  • Bot detection prevents automated scanning from triggering false telemetry.

This separation ensures that high-volume minting operations do not impact scan resolution performance, and vice versa.

Storage & Exports

Export artifacts (CSV manifests) are stored in private cloud storage with row-level security enforcement:

  • Only users with brand-level access can generate and download exports.
  • Downloads use short-lived signed URLs (5-minute TTL).
  • Large batches produce multiple sequential packs (up to 10,000 units per pack).
  • Export generation is resumable — interrupted exports can be continued without regenerating completed packs.