Metadata Viewer

What the Metadata Viewer is

The record types the Carrot Network writes to the public registry one at a time — a MassID, a Certificate, a purchase or retirement receipt — each carry a content-addressed provenance document stored on IPFS. The on-chain entry holds the reference, not the provenance payload. It is not empty of data — a Certificate tracks its total, purchased, retired and available amounts on chain, and a receipt records its parties, amounts and certificate allocations — but the chain of custody behind the record is what lives on IPFS. Fungible credit tokens also have their own metadata document, describing the credit rather than an individual unit or purchase. The viewer opens these ERC20 documents too.

The Metadata Viewer (viewer.carrot.eco) is the tool that follows that reference and renders the document behind it. It can read a token's metadata URI from the smart contract or open a document directly, then check it against the schema the record declares — all in the reader's browser.

It answers a narrower question than the Carrot Registry: not "what does this record mean in context" but "what exactly does this record say, and does it agree with the chain". It is not by itself a proof that a record is intact — what it checks is narrower than that, and the difference is spelled out below.

Opening a record

The viewer takes its input from the URL, so any record can be linked to directly. Most readers arrive on a link the platform already generated (see Where these links appear); the URL contract is documented here so a record can also be opened by hand.

By contract address. For an ERC721 record, the canonical form is addressed by the triple of contract address, network, and token identifier:

https://viewer.carrot.eco/?contractAddress=0x<address>&network=polygon&tokenId=<token id>

network takes polygon for the public Polygon mainnet (chain ID 137) and amoy for the Polygon Amoy test network (chain ID 80002). The host is the same for both — the viewer selects the chain from this parameter, and addresses and token identifiers are chain-local, so network has to name the chain the record was written to.

By record type. For the ERC721 record types below, on the mainnet, the viewer can resolve the contract address itself through the on-chain ContractRegistry, so a record type replaces the address:

https://viewer.carrot.eco/?recordType=mass-id&network=polygon&tokenId=<token id>

By IPFS reference. A metadata or provenance document can also be opened directly by its content identifier, without knowing which contract holds it:

https://viewer.carrot.eco/?cid=<cid>

Use this route for a fungible credit document too: paste its CID, ipfs:// URI or gateway URL in IPFS CID, or use the cid URL parameter above. Credits are not options in the recordType selector and do not use an NFT token identifier.

When the document provides a supported on-chain identity, the viewer can also read that contract to check its reference and publication history. A CID alone does not prove a connection to a contract.

The viewer also accepts a document pasted or uploaded from the reader's own machine, which is what makes that round-trip meaningful: it can tell you whether a document you were handed matches the current document the record's own contract and token resolve to.

Where these links appear

Viewer links are generated wherever a record is presented as evidence:

• The Impact Certificate — the PDF issued for a credit purchase — lists that order's public records under Public records, each one a link into the viewer: the order's purchase and retirement receipts. Every purchase is retired when it settles, so the PDF lists both.
• Certificate records carry a viewer link for their own registry entry, alongside the blockchain block explorer link for the same token.

An issued Impact Certificate is a fixed document: the links printed into it are written at issuance and are never rewritten, so each one keeps pointing at the record it was issued for.

What the record pins

Depending on the record type, its format can include these integrity anchors, whether or not a particular tool reads them:

• The schema, pinned three ways — a version-tagged URL, an IPFS reference to that schema, and the SHA-256 hash of the exact schema version the record was written against. Carrot's record schemas are open source at carrot-foundation/schemas.
• An audit hash — a SHA-256 hash recorded at issuance, so a party holding the underlying source data — submitted by Network Integrators — can reconcile it against the published record. A public reader cannot recompute it from the published record alone, because the published document is redacted (see below).
• A reference to the viewer build — see The viewer is verifiable too.

What the viewer checks

The viewer reports structure, on-chain references and publication history separately. A successful check on one does not establish the others:

• Structure — For supported schema versions, validation uses the validators bundled with the viewer. For an earlier major version or a version newer than the build, it can validate against the declared schema document: an embedded historical copy when available, otherwise one fetched over HTTPS or IPFS. This is not limited to the versions bundled at build time. If validation cannot run, the record remains unchecked; a document without a schema declaration is labeled No schema declared. Failure to load a declared schema can prevent the record from opening. A document that fails validation can still be displayed with its structural issues; displaying it does not mean it passed. Structural validation does not guarantee that an older viewer build renders fields introduced later.
• On-chain round-trip — For an ERC721 document, the viewer reads the metadata URI from the contract and token named in the document. With an IPFS reference, it can distinguish the current document, a document previously used by that token, a mismatch, and a history it could not establish. Pasted or uploaded JSON is compared with the current document fetched through that URI; this comparison alone does not establish historical use. This check does not run for a document loaded through the contract form, where the document came from that contract already. ERC20 publication history separately checks the credit contract's current tokenURI() without an NFT token identifier.
• Network — On-chain reads support Polygon and Amoy. They require a supported chain identity; an environment label alone does not establish the chain. An unavailable on-chain check is not proof that the document is wrong.

The viewer does not recompute any of the record's hashes, and it does not verify that the bytes a gateway returned actually hash to the content identifier that was requested. Content addressing makes that check possible — any change to a document produces a different identifier — but it is a check a reader performs, by fetching the identifier through a client that verifies content addressing, or by re-pinning it and comparing.

Provenance documents are public, so personal and commercially sensitive attributes are withheld or masked before publication: an attribute marked private is left out of the published document entirely, and one kept public but flagged sensitive is published in masked form, with the full value preserved for auditors. What the viewer renders is the published record — the chain of custody as it was cleared for publication. Visibility is set per event as well as per attribute, so an event marked private is absent from the document entirely; what you are reading is not necessarily the full operational history an auditor sees.

Publication history and revisions

Publication history reads both legacy and revised TokenURIUpdated events for ERC721 records and ERC20 credits. Where the event provides them, version details show the predecessor URI, the operator and the declared reason, alongside the transaction and a block timestamp when available. The operator is the address recorded by the contract, not a list of individual multisig signers.

An older document stays open as that version; the viewer can offer a link to the current one. History coverage is reported separately. In particular, a credit's initial metadata URI is not announced by a URI event at initialization, so its history may be incomplete even when the current update and its predecessor are found. Failed or limited log reads also leave gaps; they do not establish that an update never happened.

A document may contain a revision declaration with previous_uri, a reason and field changes. Its comparison: verified or comparison: unavailable value is the publisher's declaration. When the predecessor is retrievable, the viewer compares the documents independently and shows before/after values, contradictions and changes not covered by the declaration. That comparison does not prove the truth of the recorded reason. If the predecessor cannot be read, no comparison is available; the viewer does not invent old values or infer missing operations.

The viewer is verifiable too

A verification tool that only its author can vouch for moves the trust problem rather than solving it. A provenance document can embed an IPFS reference to the viewer build itself, pinning the tool by content address alongside the document. When that reference is present, a reader can run the referenced build instead of the copy served at viewer.carrot.eco. Not every document includes this pin; fungible credit metadata may omit it.

Where it fits

Three surfaces present the same underlying facts at different depths:

The Registry is where a reader starts from a question about impact. The Metadata Viewer is where a reader ends up when the question becomes whether a specific record holds up on its own.

Learn about the Carrot Registry · Learn about registry record creation