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 are registry records too, but they carry no provenance document of their own and the viewer does not open them.

The Metadata Viewer (viewer.carrot.eco) is the tool that follows that reference and renders the document behind it. It reads the token's metadata URI from the smart contract, fetches the document, and checks 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. The canonical form. A record 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. 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 provenance document can also be opened directly by its content identifier, without knowing which contract holds it:

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

This still reads the chain: the record names its own contract and token, and the round-trip check below re-reads that contract to confirm the document matches. What the identifier saves you is having to know the address.

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 is the one 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 purchase receipt, and the retirement receipt when the order was retired in the same transaction. An order retired later, in a standalone transaction, produces its retirement receipt after the PDF was issued.
• 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

The record's integrity anchors are part of its format and exist whether or not any 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

Three checks run, and each reports its own status. They are narrower than the anchors above, and the difference matters if you are relying on them:

• Structure — The document is validated against the copy of the schema pinned into the viewer build, matched by the schema URL the record declares. When a record declares a version the build does not carry, the viewer reports not structurally checked instead of validating, and fields introduced after that build was pinned are not rendered.
• On-chain round-trip — When a document is opened by its IPFS reference, or pasted or uploaded, the viewer re-reads the metadata URI from the contract and token the record itself names, and requires it to resolve to the same document: verified, or mismatch. This is the strongest thing the viewer does. It does not run when a record is opened by contract address, because there the document came from that contract to begin with.
• Network — The network embedded in the record must be one of the two supported chains, or the record is rejected outright.

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.

The viewer is verifiable too

A verification tool that only its author can vouch for moves the trust problem rather than solving it. Every Carrot provenance record embeds an IPFS reference to the viewer build itself, so the tool that reads the record is pinned by content address, exactly like the document it reads. A reader who does not want to trust the copy served at viewer.carrot.eco can run the referenced build instead.

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