How it works, and how to check.

Your metadata is a folder

A series is one IPFS folder — the folder is the series. Its content hash becomes its on-chain identity, so nothing is assigned, nothing is sequential, and nothing can collide.

• Metadata is never right the first time. Update the folder in place while the run is still settling; patch mode reads back the currently pinned folder so you retype nothing, matching attributes by name rather than by position.
• If your new content hashes to the CID already on chain, the run exits as a no-op: zero uploads, zero transactions, zero gas.
• Freeze it when it stops moving, and the freeze is permanent — a later update fails before it can touch anything. Metadata, royalties, and the contract URI each freeze separately, on their own schedule.
• Freezing a ten-thousand-token series does not die on gas. Event emission is streamed across transactions behind a cursor, so series size is not a design constraint.
• Token ids are yours to choose. Sparse and vanity ids are first-class — the pipeline validates a set, not a range.

The object claims itself

The claim is a signature, not a key handover — and that distinction is the whole security model. The private key lives on the physical object, inside the QR code under the tamper sticker.

• The holder scans. The key is decoded in their browser and never leaves the device — not to a server, not to us.
• It signs a message naming the holder’s own wallet. Their wallet then sends the transaction and pays the gas.
• The contract recovers the signer, looks up which token that address was registered to, transfers it, and marks it activated — permanently.
• A stolen signature is worthless. It only ever authorises a transfer to the wallet named inside the signed message.
• The scanner reads the token’s status live, so a holder sees “already activated” or “not registered” before being asked to sign anything.

Dead QR codes never ship

For a physical product, a batch of dead QR codes is an unrecoverable failure — the objects are already in boxes. So the pipeline treats the QR payload as something to be proven, not trusted. You supply the holder files; it refuses to take a single value in them on faith.

• Every declared address is re-derived from its private key rather than believed.
• Every secret — the exact string that will be printed on the physical object — is decoded and checked to reconstruct the same key that gets registered on-chain. A well-formed-but-wrong secret would otherwise ship a dead QR.
• The encoding alphabet is a shared constant between the pipeline and the scanner, so a code the scanner would reject cannot pass registration.
• Your holder set must exactly match your metadata token-id set, and you are told both what is missing and what is extra.
• All of it runs in a dry run, in full, before anything is uploaded or written.

Every value says where it came from

The public token page is not a product page with a blockchain badge. It is a verification surface, built so that it cannot quietly lie. Every value on it is tagged with its source — read from the chain, or read from IPFS — and carries the evidence for that tag.

• The tag is not a badge someone remembered to add. The source is locked into each field’s type, so a function that produces metadata physically cannot return a chain-tagged value.
• There is no third source. Even the site’s own configuration — the brand name, the domain — is tagged as metadata. The site’s opinion of itself is treated as a claim, not as evidence. There is no “trust us” tier.
• Every chain read on the page is pinned to a single block, and a runtime check proves no field drifted to a different one. The page is a consistent snapshot, not a smear of reads across time.
• The gateway is never trusted. Metadata is fetched as raw IPLD blocks and hash-verified against its CID, with the fetcher resolving directory paths itself. Gateways are raced, not depended on: one that lies is dropped, one that stalls is outrun.
• Contradictions are shown, not smoothed. If the metadata declares a serial number that disagrees with the on-chain one, both rows render side by side, differently tagged. The disagreement is the feature.
• The page is assembled from chain reads and CID-verified IPFS blocks. There is no company database anywhere in that path.

Rehearse the run, then run it

One command runs the entire onboarding of a physical batch: render, validate, upload, verify, create the series, register the holders, mint, verify again, and hand you a receipt. Every safety property exists because the alternative is a pallet of ruined product.

• The dry run is not a linter — it simulates. It performs real chain reads, checks your wallet holds the roles it needs, estimates worst-case gas against your actual balance, cryptographically validates every QR code, computes the exact CIDs the real run would produce, and simulates the transactions against the live chain. Then it exits without a single side effect.
• Resume treats the chain as the authority, not a journal. Crash, Ctrl-C, dropped RPC, dead laptop: re-run the identical command and it re-derives every skip-or-do decision from live chain reads. No double-mint, no double-register.
• Edit the source folder mid-flight and it refuses to resume — you cannot accidentally resume into a different CID than the one you started registering.
• CIDs are computed locally and verified three separate times: against what the pinning provider returns, against two independent gateways, and again from the bytes a gateway actually serves after the chain write.
• Because a token id binds to its series forever, an id that already belongs to someone else’s series would otherwise leave you with tokens resolving to someone else’s metadata. The pipeline detects this before doing anything and aborts, listing every offending id.
• Nothing is trusted, including receipts. Every transaction is simulated before it is sent, waits for confirmations, and is then independently re-read from chain state.
• Mainnet is opt-in: it refuses to run without an explicit confirmation flag.

Your deployment, your keys, no backend

You get your own contracts — not a slot in a shared registry. Your own token contract, your own activation contract, deployed with one command and recorded as a versioned artifact the apps build against.

• Five separate roles, so the key that mints is not the key that can upgrade.
• Admin authority is transferable and revocable. Hand it to a multisig, hand it to a timelock, or renounce it and make the implementation permanent. That is your ratchet to choose, not ours.
• Trust is deliberately asymmetric. The token contract is upgradeable, because a metadata schema evolves. The activation contract is not — it holds custody, so its code is fixed at deployment and cannot be changed by anyone, including you. Custody logic does not get a back door.
• ERC-1155 with royalties capped at 10%, full supply tracking, burnable, and a pauser role that halts transfers and mints without touching anything else.
• No servers. No database, no API tier, no backend to breach and no backend to keep paying for. The read path is the chain and IPFS.
• Safe by default in the field: the app hard-fails if it is served from a domain other than the configured one, so a cloned phishing site gets a 404 rather than a working scanner. The network badge is always visible and turns red on an unknown chain. A single environment variable puts either app into maintenance mode with your message, no deploy required.

Putting a physical run on-chain?

Each issuer gets their own contracts and holds their own keys. Tell us what you are minting and we will tell you plainly whether this fits.