Metadata

ABX metadata is a field store on the collection contract. Each field has a name, a representation, and a value. A field may hold bytes, point to bytes, or compute them from chain state.

Fields and scope

Fields live at two scopes:

Collection fields apply to the whole project and feed contractURI.
Token fields apply to one token and feed tokenURI.

A token field overrides a collection field with the same name.

A collection image is therefore the fallback image for every token and can mask a computed render. Empty field writes are not allowed. Use featured_image for collection artwork that should not replace token images.

Common token fields are name, description, image, animation_url, external_url, attributes, background_color, and youtube_url. Common collection fields include name, description, banner_image, featured_image, external_link, creator, creator_links, display_notes, and license.

Other field names appear in the token's artifact manifest. The generated keys artifacts and abx_provenance cannot be set as fields.

Resolver routes

Conforming resolvers expose token metadata at /t/{chainId}/{contract}/{tokenId}. Inline or computed field bytes use the stable /t/{chainId}/{contract}/{tokenId}/data/{field} route. Code projects also have /a/{chainId}/{contract}/{tokenId} as their canonical live application view; an animation_url may point to either route when they serve the same document.

Parameters are separate. Read them from the contract rather than tokenURI. See Parameters.

Representations

Representation	Meaning
`inline`	Bytes stored in the field
`inline-gzip`	Gzipped bytes, decoded offchain
`reader`	Bytes read from an onchain storage contract
`reader-gzip`	Gzipped bytes read from an onchain storage contract
`renderer`	Bytes computed by a contract
`ipfs`	An IPFS CID
`arweave`	An Arweave transaction ID
`url`	A URL
`url-template`	A URL with an `{id}` placeholder
`keccak256` / `sha256`	An onchain commitment to bytes stored elsewhere

The representation describes the route. The contract does not fetch a URL, CID, or transaction ID.

For URI fields such as image and animation_url, inline or computed content is embedded in an onchain metadata document. A resolver serves the same content through a URL. A renderer that returns text/uri-list is treated as a locator instead.

Stored image type

Bytes stored in the image field itself (inline, reader, or their gzip forms) carry no media type. Both serving planes label them with the reserved field abx_image_type, and fall back to image/svg+xml when it is unset:

abx set-field 0xYourContract --field abx_image_type --text image/jpeg

The value must be inline and a lowercase image/<subtype> with no parameters. Any other value is ignored and the image is served as SVG. A token value overrides a collection value, so a series of JPEGs can declare the type once with --collection. abx deploy --onchain-image and abx set-field --field image --file write the declaration for you. They refuse formats that browsers don't draw, such as TIFF and PSD.

The declaration applies only to stored bytes. A URL, CID, or hash commitment gets its type from the content it points to, and a renderer field returns its own type. Like the gateway fields, abx_image_type never appears in the metadata document or the artifact list. Lock it with abx lock-field --field abx_image_type when you lock image, or the owner can still change the label.

Renderers before spec v12 ignore abx_image_type and label every stored image as SVG. Existing collections with raster images can move to the current renderer with abx set-renderer, unless the URI configuration is locked.

URI resolution

Each contract chooses one of two paths:

An onchain metadata renderer returns a data:application/json document.
A base URL or per-token URL points to a resolver.

The lookup order is:

Onchain renderer
Per-token URL override
Base URL plus chain, contract, and token ID
Empty string

An onchain renderer can resolve inline, reader, renderer, url, url-template, ipfs, and arweave. Hash commitments and gzipped values need an offchain resolver.

For an in-range token that has not been minted, an offchain resolver returns { "minted": false } instead of full metadata. Its image, data, and live-view routes return 404 until the mint exists. Token IDs outside the project's range also return 404.

Gateways

Store an IPFS CID or Arweave transaction ID as the field value. Keep the HTTP gateway separate so it can change without changing the content address.

abx set-gateway 0xYourContract \
  --ipfs https://your-gateway.example/ipfs/

The collection fields abx_gateway_ipfs and abx_gateway_arweave hold these serving preferences. They do not appear in the public metadata document or artifact list. Public defaults apply when they are unset.

Locks

lock-field freezes one field. lock-uri freezes the URI configuration. Code projects have separate locks for scripts and dependencies. Parameters have their own schema deadlines.

abx lock-field 0xYourContract --field image
abx lock-uri 0xYourContract

A lock freezes the value or address stored by the ABX contract. It cannot freeze:

bytes behind a mutable URL
code behind an upgradeable renderer, reader, or hook
a live dependency registry
an unlocked parameter

Check the whole dependency graph before calling a project immutable. See Owner powers.

Provenance

Served metadata includes abx_provenance. Each entry names the field, its source, and a short note. The resolver also reports a status such as on-chain, verified, mismatch, off-chain, or n/a.

The status is a resolver result. A contract cannot fetch and hash remote bytes.

Example

{
  "name": "Drift #42",
  "image": "https://metadata.example/84532/0xabc/42/image",
  "attributes": [{"trait_type": "Palette", "value": "Ochre"}],
  "abx_provenance": [
    {"field": "image", "source": "reader", "status": "on-chain"}
  ]
}

The resolver URL above may serve bytes that live onchain. Provenance describes where the bytes live; the URL describes how an HTTP client reaches them.

On this page