IPFS, Metadata, and Immutable Quantum Provenance
IPFS, Metadata, and Immutable Quantum Provenance
An NFT without proper metadata is just a number on a blockchain. The metadata is what gives it meaning — the name, the image, the attributes, and in our case, a cryptographic certificate proving the art was generated by a real quantum computer. Here is how we structured all of it on IPFS for the Quantum Genesis collection.
1. What Is IPFS and Why It Matters for NFTs
Content Addressing vs Location Addressing
Traditional web URLs are location-based: they tell you where something is (https://example.com/image.png). If the server goes down or the file is moved, the link breaks. Your NFT's image disappears.
IPFS uses content addressing: the address is derived from the content itself. A file's CID (Content Identifier) is a cryptographic hash of its contents. If even one byte changes, the CID changes. This gives you two guarantees:
- Immutability: The CID
bafybei...will always point to the exact same file. Nobody can swap the image. - Verifiability: Anyone can hash the file and confirm it matches the CID. No trust required.
Pinning Services
IPFS is a distributed network, but content only stays available if at least one node is hosting it. Pinning services like Pinata guarantee your files stay available by keeping them pinned to dedicated infrastructure. We used Pinata for all Quantum Genesis assets.
Why this matters: When someone buys Quantum Genesis #42 on OpenSea, the metadata URL resolves through IPFS to the exact same JSON file we uploaded. It cannot be tampered with. The quantum provenance certificate inside that JSON is permanent and verifiable.
2. Our IPFS Structure
We organized the collection into three IPFS directories, each uploaded as a folder to get a single CID per category:
| Folder | Contents | CID |
|---|---|---|
| Art (SVG) | 100 SVG files (1.svg – 100.svg) | bafybeiacqj5gi5p75tpp2ph7f3ovub4bffqpfuboyuhpmuffhzxxm76roq |
| Art (PNG) | 100 PNG files (1.png – 100.png) | bafybeifges7tei5x7drj37f34yhzqofwlz2icbo7z67isg6g446k65yw3a |
| Metadata | 100 JSON files (1.json – 100.json) | bafybeif7z767txkebwz7iqlgkvikvhxciuxt2kxenmjad4bbzx4rfioyc4 |
The relationship between them:
metadata/1.json
└─ "image": "ipfs://bafybeifges7tei5x7drj37f34yhzqofwlz2icbo7z67isg6g446k65yw3a/1.png"
└─ "animation_url": "ipfs://bafybeiacqj5gi5p75tpp2ph7f3ovub4bffqpfuboyuhpmuffhzxxm76roq/1.svg"
Smart Contract baseURI:
└─ "ipfs://bafybeif7z767txkebwz7iqlgkvikvhxciuxt2kxenmjad4bbzx4rfioyc4/metadata/"
└─ tokenURI(1) → baseURI + "1.json"
Each metadata JSON references the PNG as the primary image (better compatibility) and the SVG as the animation_url (which OpenSea renders as the interactive/animated version).
Quantum Genesis #1 — generated from measurements on a real quantum processor
3. ERC-721 Metadata Standard Deep Dive
The ERC-721 metadata standard defines a JSON schema that marketplaces like OpenSea parse to display your NFT. Here is the complete metadata for Quantum Genesis #1:
{
"name": "Quantum Genesis #1",
"description": "Generative art born from real quantum computer measurements. Each piece encodes authentic quantum entropy into visual form, creating patterns that are physically impossible to replicate classically. Part of the Quantum Genesis collection — 100 unique artworks with cryptographic proof of quantum origin.",
"image": "ipfs://bafybeifges7tei5x7drj37f34yhzqofwlz2icbo7z67isg6g446k65yw3a/1.png",
"external_url": "https://opensea.io/collection/quantum-genesis",
"animation_url": "ipfs://bafybeiacqj5gi5p75tpp2ph7f3ovub4bffqpfuboyuhpmuffhzxxm76roq/1.svg",
"attributes": [
{ "trait_type": "Entropy Level", "value": "High" },
{ "trait_type": "Entropy Score", "value": 78, "display_type": "number", "max_value": 100 },
{ "trait_type": "Qubit Configuration", "value": "GHZ-3" },
{ "trait_type": "Quantum Phase", "value": "Superposition" },
{ "trait_type": "Color Harmony", "value": "Complementary" },
{ "trait_type": "Complexity Score", "value": 65, "display_type": "number", "max_value": 100 },
{ "trait_type": "Quantum Seed", "value": "a7c3f1..." },
{ "trait_type": "Processor", "value": "Origin Quantum WK_C180" },
{ "trait_type": "Generation", "value": 1, "display_type": "number" }
],
"properties": {
"quantum_certificate": {
"certificate_id": "QG-001-CERT",
"quantum_seed": "a7c3f1e8b2d94a6c...",
"source": "quantum_real",
"processor": "Origin Quantum WK_C180",
"circuit": "ghz_3qubit_hadamard_cnot",
"timestamp_utc": "2026-03-18T14:22:31Z",
"integrity_hash": "sha256:e3b0c44298fc1c14...",
"verification": "This artwork was generated using measurements from a real quantum processor. The quantum_seed is derived from actual quantum state measurements and can be independently verified against the processor's execution logs."
}
}
}Field by Field
- name: The display name. OpenSea shows this prominently.
- description: Appears below the image on OpenSea. We explain the quantum origin here.
- image: The primary image URL using the
ipfs://protocol. OpenSea and other platforms resolve this through their IPFS gateways. We use PNG for maximum compatibility. - external_url: Links back to the collection page.
- animation_url: Points to the SVG. OpenSea renders this in an iframe, preserving vector quality and any CSS animations in the SVG.
- attributes[]: An array of trait objects. OpenSea parses these into filterable properties on the collection page.
- properties{}: A freeform object for extended data. We use it for the quantum authenticity certificate.
4. Attributes Design
Each Quantum Genesis NFT has nine attributes. Here is what they mean and how they are derived:
Entropy Level and Entropy Score
These measure the randomness quality of the quantum measurements. The score (0–100) is calculated from the probability distribution of measurement outcomes. A perfectly uniform distribution scores 100; a completely biased one scores 0. The level is a human-readable bucketing: Low (0–33), Medium (34–66), High (67–100).
Qubit Configuration
The quantum circuit topology used to generate the seed. Examples:
- GHZ-3: Greenberger-Horne-Zeilinger state with 3 qubits (maximally entangled)
- Steane-7: Inspired by the 7-qubit Steane error correction code
- Surface-5: Based on surface code patterns with 5 qubits
Quantum Phase
The dominant quantum phenomenon in the circuit: Superposition, Entangled, Interfering, Decoherent, or Tunneling. This is determined by the circuit structure and gate composition.
Color Harmony
The palette algorithm applied to convert quantum data into colors: Complementary, Analogous, Triadic, Split-Complementary, or Quantum Chromatic. The quantum measurements determine which harmony is selected.
Complexity Score
A 0–100 score measuring the visual density and intricacy of the generated artwork. More complex quantum states tend to produce more intricate visual patterns.
Quantum Seed
A truncated hexadecimal string derived from the actual quantum measurements. This is the provenance link — it connects the on-chain token to the specific quantum execution that generated it.
Processor
The quantum computer that generated the measurements. In our collection:
- NFTs #1–#18: Origin Quantum WK_C180 (180-qubit superconducting processor, Hefei, China)
- NFTs #19–#100: IBM Quantum ibm_fez (156-qubit Eagle processor)
Generation
A numeric field indicating the minting batch. Generation 1 for early mints, Generation 2 for batch mints.
Quantum Genesis #42 — generated on IBM Quantum's ibm_fez (156 qubits)
5. Quantum Authenticity Certificates
The most distinctive feature of our metadata is the quantum_certificate object embedded in each token's properties. This is our proof of quantum origin.
{
"certificate_id": "QG-001-CERT",
"quantum_seed": "a7c3f1e8b2d94a6c8e1f7b3d5a2c9e4f6d8b0a7c3f1e8b2d94a6c8e1f7b3d",
"source": "quantum_real",
"processor": "Origin Quantum WK_C180",
"circuit": "ghz_3qubit_hadamard_cnot",
"timestamp_utc": "2026-03-18T14:22:31Z",
"integrity_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"verification": "This artwork was generated using measurements from a real quantum processor. The quantum_seed is derived from actual quantum state measurements and can be independently verified against the processor's execution logs."
}How It Proves Quantum Origin
- certificate_id: Unique identifier for each certificate, following the pattern
QG-{token_number}-CERT. - quantum_seed: The full hex string from quantum measurements. This is the SHA-256 hash of the raw measurement bitstrings. You can verify it: take the same circuit, run it on the same processor, and the statistical distribution should match (though individual measurements will differ — that is the nature of quantum mechanics).
- source: Always
"quantum_real"for this collection, meaning actual quantum hardware, not a simulator. - processor: The specific machine. Origin Quantum's WK_C180 and IBM's ibm_fez are both well-documented, publicly accessible quantum computers.
- circuit: The quantum circuit description.
ghz_3qubit_hadamard_cnotmeans a 3-qubit GHZ state created with Hadamard and CNOT gates. - timestamp_utc: When the quantum job ran. This can be cross-referenced with the processor's job queue.
- integrity_hash: A SHA-256 hash that ties the certificate fields together. If any field is altered, the hash will not match.
Why this matters: Classical random number generators can produce superficially similar art. But they cannot produce a valid certificate that traces back to a real quantum processor execution at a specific timestamp. The certificate is the unforgeable link between the art and quantum mechanics.
6. Upload Process: Pinata API
We uploaded all assets using Pinata's v2 API through our upload_to_ipfs.py script. Here is the core approach:
# upload_to_ipfs.py (conceptual excerpt)
import requests
import os
from pathlib import Path
PINATA_JWT = os.environ["PINATA_JWT"]
PINATA_API = "https://api.pinata.cloud"
def upload_folder(folder_path, folder_name):
"""Upload an entire folder to Pinata, get back a single CID."""
files = []
for file_path in sorted(Path(folder_path).iterdir()):
files.append((
"file",
(f"{folder_name}/{file_path.name}", open(file_path, "rb"))
))
response = requests.post(
f"{PINATA_API}/pinning/pinFileToIPFS",
files=files,
headers={"Authorization": f"Bearer {PINATA_JWT}"},
data={
"pinataMetadata": '{"name": "' + folder_name + '"}',
"pinataOptions": '{"cidVersion": 1}'
}
)
cid = response.json()["IpfsHash"]
print(f"Uploaded {folder_name}: ipfs://{cid}")
return cid
# Upload in order
art_svg_cid = upload_folder("nft-output/art-svg", "quantum-genesis-svg")
art_png_cid = upload_folder("nft-output/art-png", "quantum-genesis-png")
# Generate metadata JSONs (referencing the art CIDs)
generate_metadata(art_svg_cid, art_png_cid)
# Upload metadata
metadata_cid = upload_folder("nft-output/metadata", "quantum-genesis-metadata")
The order matters: art is uploaded first so we have the CIDs to embed in the metadata JSONs. Then metadata is uploaded. Finally, the metadata CID is set as the contract's baseURI.
All files are accessible through our Pinata gateway at maroon-bright-perch-405.mypinata.cloud and through any public IPFS gateway.
7. How baseURI Connects Contract to Metadata
The ERC-721 standard defines a tokenURI(uint256 tokenId) function that returns the metadata URL for a given token. Our implementation concatenates the base URI with the token ID:
function tokenURI(uint256 tokenId) public view returns (string memory) {
if (!_exists(tokenId)) revert TokenDoesNotExist();
return string(abi.encodePacked(_baseTokenURI, toString(tokenId), ".json"));
}With our baseURI set to:
ipfs://bafybeif7z767txkebwz7iqlgkvikvhxciuxt2kxenmjad4bbzx4rfioyc4/metadata/The resolution chain works like this:
tokenURI(1)
→ "ipfs://bafybeif7z767txkebwz7iqlgkvikvhxciuxt2kxenmjad4bbzx4rfioyc4/metadata/1.json"
→ OpenSea fetches this JSON via IPFS gateway
→ JSON contains "image": "ipfs://bafybei.../1.png"
→ OpenSea fetches and displays the image
→ JSON contains "animation_url": "ipfs://bafybei.../1.svg"
→ OpenSea renders SVG in iframe
→ JSON contains "attributes" and "properties.quantum_certificate"
→ OpenSea displays traits and properties
Every link in this chain is content-addressed. The contract points to a specific metadata CID. The metadata points to specific image CIDs. Nothing can be changed without breaking the chain. This is the immutability guarantee that makes IPFS ideal for NFT storage.
The permanence equation: On-chain contract (immutable) + IPFS content addressing (tamper-evident) + Pinata pinning (availability) + quantum certificates (provenance) = NFTs whose origin and content are permanently verifiable.
Wrapping Up
The metadata layer is where an NFT collection goes from "tokens on a blockchain" to "verifiable digital art with provenance." For Quantum Genesis, every piece of metadata is structured to answer the question: how can someone verify that this art actually came from a quantum computer?
The answer is in the data: quantum seeds that trace to real processor executions, integrity hashes that bind the certificate together, and IPFS content addressing that ensures nothing can be silently altered after upload.
Combined with the on-chain smart contract we built in Post 7, we have a complete system: quantum measurements become art, art becomes IPFS-pinned files, files become metadata, and metadata becomes permanently linked to tokens on the Polygon blockchain.
Desenvolvo sistemas que usam hardware quântico real (IBM Quantum, Origin Quantum) para gerar arte e NFTs com proveniência verificável on-chain. Escrevo sobre computação quântica aplicada, criptografia, Web3 e arte generativa — tudo com código que roda em processadores quânticos de verdade.
Comentários
Postar um comentário