NFT metadata and IPFS: why a CID does not guarantee storage

Explainer10 min read

An NFT’s CID identifies content; it does not keep it online. Trace metadata, image links, gateways and pinning to see which claims still need evidence.

Fictional IPFS metadata metaphor: Brokzi follows an image reference from a folder to a skateboard print while checking an empty archival crate. Content identity does not guarantee retained copies.
AI-assisted editorial illustration · Brokzi
On this page

An NFT page loads a picture. Its metadata mentions IPFS. Somewhere nearby, a long content identifier appears. It is tempting to read all three as “this artwork is safely stored forever.” They answer different questions.

NFT metadata on IPFS can use content addressing to identify particular data. A CID does not, by itself, keep that data online, freeze the NFT contract's reference, identify the artist or grant rights to the work. This explainer is for readers trying to understand what a collection's metadata claim actually establishes, without connecting a wallet or testing a live NFT.

Follow the reference, then the image

Start with the distinction in our ERC-721 and ERC-1155 token-ID explainer: a token record and the picture shown beside it are not the same object.

Where the relevant optional metadata extension is implemented, ERC-721 provides tokenURI(tokenId) and ERC-1155 provides uri(id). These return a URI string. They are not promises that the image bytes live inside the token contract. The ERC-721 metadata interface allows its URI to point to a JSON metadata file; the ERC-1155 extension requires a URI pointing to JSON conforming to its metadata schema.

For an NFT using external JSON metadata, the reading chain is:

contract reference → metadata object → image reference → image object

A gateway may help retrieve the objects. Someone still needs to retain and provide their data. Some implementations use other arrangements, including embedded data; this chain is not a claim that every NFT uses an external image.

LayerWhat you are looking atWhat remains a separate question
Contract referenceThe URI returned for that token contextCan that returned reference change?
Metadata objectDescriptive data, potentially including an image fieldWhat does the image reference actually address?
Image objectThe media the metadata refers toWere these bytes verified against the expected content address?
GatewayAn HTTP route used to retrieve or resolve contentWhich validation did the client perform or delegate?
RetentionNodes or services keeping the dataWill the needed data remain stored and reachable?

ERC-1155 adds a detail worth noticing: if a URI contains {id}, compliant clients substitute the token ID as lowercase hexadecimal, without 0x, padded to 64 characters. The standard also specifies substitution in JSON values. It does not require every URI to contain that template. Nor can the uri function be used to prove that a token exists; the specification explicitly warns against that inference.

What an IPFS CID identifies

A content identifier, or CID, describes content-addressed data using information including a codec and a multihash. With appropriate verification, it lets a client check that retrieved data matches the expected address. It does not tell the client where a surviving copy must be stored.

The important correction is that a CID is not generally the ordinary checksum of an entire image file. IPFS can split a file into blocks and represent it through a directed acyclic graph, or DAG. A root CID can address that structure. Hashing the finished image file with a separate checksum tool does not generally reproduce that CID. The official content-addressing documentation explains the distinction.

There are narrower cases: a single raw block's digest can match a hash of that block's file bytes. But the CID also carries format information. “It is always the file's SHA-256” and “it can never contain that digest” are both poor shortcuts.

The reverse shortcut also fails. The same file bytes can produce different CIDs under different chunking, encoding or graph-construction choices. CID version and textual representation can matter too. Two different CID strings are therefore not, by themselves, proof that the underlying artwork changed.

Content verification answers “does this data match this expected address?” It does not answer “did the genuine artist make it?” A correctly addressed copy of an unauthorised image is still correctly addressed data.

Metadata and media need separate checks

Imagine a fictional collection. Its contract points to Metadata A, a JSON object. Inside that object, the image field refers to Picture A. Those names are teaching labels, not real CIDs, URLs or collection entries.

Consider two possible arrangements:

  • The image reference addresses particular IPFS content. There is an additional content-addressed object or path to retrieve and verify. Availability is still a separate concern.
  • The image reference is an ordinary HTTP address whose response can change. Fixing the metadata object's content preserves that address string. It does not automatically freeze whatever image bytes the server later returns.

That second conclusion follows from the separation between a metadata field and its target. It is not a finding about any particular collection or server.

Do not insist that metadata and image must always have two different root CIDs. The IPFS NFT-data guidance also describes directory-based addressing. Different paths under one directory root can identify different resources. Keep the root and path in view rather than discarding the filename and calling everything the same object.

A successful metadata download is evidence of that retrieval. It does not establish that every referenced image is available, independently verified or retained for the future.

A fixed CID does not freeze the contract pointer

Suppose the fictional contract returns a reference to Metadata A today. Even if that particular content address is stable, a separate question remains: could the contract return a reference to Metadata B later?

ERC-721's metadata rationale explicitly permits a mutable URI. ERC-1155 includes rules for URI changes and events, with an important exception for dynamic or programmatic changes that cannot be expressed through an event. These standards describe interfaces; they do not certify the freeze policy of a deployed collection.

One returned value is an observation of a reference in a particular state. It is not proof that no administrator, program logic or upgrade mechanism can ever change it. Our proxy and upgradeability explainer covers why an implementation's change authority needs its own investigation. No such investigation was performed here.

IPFS also supports mutable naming layers:

  • IPNS uses signed records to associate a stable name with a content path that can be updated. An IPNS name can itself have a CID representation; its namespace and meaning differ from an immutable /ipfs/ content address.
  • DNSLink uses editable DNS TXT records to map a domain name to an IPFS or IPNS path. A familiar domain name can keep working while that mapping changes.

The official IPNS documentation and DNSLink documentation describe these mechanisms. A stable-looking link is not sufficient evidence of a fixed underlying target. An IPNS signature establishes the relevant signing-key relationship, not the signer's real-world identity or an eternal storage commitment.

A gateway delivers data; the client decides how to verify it

An IPFS gateway exposes IPFS content over HTTP. Its hostname identifies a service used for access; it is not the content identifier. A particular gateway can be unavailable even when another route to the data exists. Conversely, switching gateway addresses does not create a missing copy of the data.

The HTTP gateway reference distinguishes two modes. By default, a gateway can assemble a file and return it like an ordinary HTTP server. The client then trusts the gateway to have validated the underlying content-addressed data correctly.

Clients capable of checking content themselves can request verifiable responses, including raw blocks or Content Addressed Archives (CARs). CAR responses can include the blocks needed to verify path resolution. Signed IPNS records are another supported response type. The point is verification actually performed, not merely a different button or file extension.

Seeing a picture or an HTTP success response does not establish that the viewer independently verified its CID. It would also be wrong to say that gateway retrieval can never be verified. Ask what the client checked, what the gateway checked, and which expected address or naming record anchored that check.

This article did not retrieve an NFT, validate a CAR, resolve an IPNS name or test a gateway's output.

Pinning is retention, not a lifetime guarantee

IPFS content addressing does not oblige a node to keep every file it has encountered. Cached data can be removed through garbage collection. Pinning protects selected data from that collection within the pinning node's retention scope.

That is useful. It is not a promise that the machine will stay online, its storage will survive, a service will keep operating or every reader will always reach it. The IPFS persistence documentation explicitly warns that third-party pinning services can cease operating. A storage arrangement needs its own evidence about what is retained, by whom and under which continuing conditions.

Keep the objects separate here too. A metadata object being accessible or pinned does not, by itself, demonstrate that every arbitrary URI mentioned inside it has been retained. This article does not test a specific pinning implementation or claim how it handles external references.

The CID answers the identity question. Retention and reachable providers answer different availability questions. One cannot substitute for the others.

A read-only checklist for an NFT metadata claim

You do not need to sign a message or connect a wallet to understand these distinctions. Before accepting “on IPFS” as a complete explanation, record the unanswered questions:

  1. Reference: what kind of URI does the collection claim to use, and what evidence supports its change or freeze policy?
  2. Metadata: which object or root-and-path is identified? Has its content been verified, or only displayed?
  3. Media: does the metadata address particular image content, or a target that may change? Was that separate target checked?
  4. Transport: is the link a gateway route, an immutable content path or a mutable naming path? Who performed validation?
  5. Retention: which data is being kept, who is keeping it, and what evidence supports continued availability?

Leave an unanswered field as unknown. Do not turn “the image opened” into “the collection is immutable” or “the work is licensed to me.” This article does not assess copyright, a collection's terms, creator identity, investment merit or a particular storage provider.

For NFT metadata and IPFS, the useful next step is to identify the missing layer of evidence. A CID can help verify content identity. It does not do the work of a contract review, a retention arrangement or a rights assessment.

Sources and scope

Official documentation checked on 20 November 2026. ERC-721 and ERC-1155 are Final standards created on 24 January 2018 and 17 June 2018 respectively; those are standards dates, not new release dates. The IPFS pages are living documentation, captured on the check date without an asserted software release or semantic version.

This is a documentation-based explanation. No deployed NFT, contract call, wallet connection, signature, transaction, media upload, pinning-service account or real content-address verification was performed. The fictional object labels and illustration explain the distinctions, not a tested collection. The NFT-data guide includes legacy js-ipfs examples marked end-of-life; those examples are not used as current instructions here.

See something wrong? Brokzi logs material changes. Prepare a correction note.

About the byline

Brokzi Editorial

The accountable byline for Brokzi’s explainers, definitions, news notes, and corrections.

Editorial responsibility →