Image serving
This page explains the code behind the image endpoints. The public behaviour is on the Image options and Image priority pages.
The pipeline
Section titled “The pipeline”The routes live in packages/server/src/server/image/. index.ts registers them in this order, from the most specific to the least:
/direct/:imageHash/fallback/:order/:chainId/:address/:order/:chainId/:address/:chainId/:address/:chainId(the network image)/(the batch lookup)
Query options:
?as=webpconverts the output format. Thesharpresize pipeline does it.?only=vectorfilters the source type. The filter works on the extension, before selection. It applies to the token routes, the network route (/:chainId) and the batch lookup. With?only=vectorthe answer is an SVG source or a 404, never a raster image. A network keeps one icon, so the network route answers 404 when that icon is not a vector.- A path extension such as
.webpon the address does the same as?as=webp.
handlers.ts holds the routes and the format checks. resize.ts holds the resize pipeline and the variant cache. rate-limit.ts holds the limiter for new variants. attribution.ts decides the licence headers. headers.ts names shared headers such as x-resolved-chain.
Choosing an image
Section titled “Choosing an image”The choice comes from one rule, listEntryPreferenceSql() in db/index.ts. In order, it prefers:
- The image tier. A stored usable image comes first. A usable image on a link-only host such as DeBank comes next (the host set is
LINK_ONLY_HOSTS). No image comes last. - Provider ranking, as
ranking / 1000. - Format.
- Version, newest first.
- The default flag.
- The list key.
There is one rule for the by-address image (applyOrder), for the chain lists and for search. A logoURI therefore names the image that /image/:chainId/:address serves.
applyOrder adds one term right after the usable image: a current list version beats a superseded one. The lists read current versions only, so without that term, a higher-ranked provider’s superseded entry would win the image route while the list named a current entry. The two routes would then serve different images for one token. It is a ranking term, not a filter. A token that only a superseded version still carries keeps its image.
RANKING_SPACING = 1000 in sync-order.ts groups sub-lists under their providers. That is why the rule compares ranking / 1000.
Reading the bytes
Section titled “Reading the bytes”See Image store internals. The short version: never select image.content directly. Use withImageBytes or loadImageBytes, and keep res.contentType(ext).send(buffer) so the ETag and 304 answers stay identical.
Resizing and variants
Section titled “Resizing and variants”wandhare limited to 1 to 2048 (MAX_DIM).- A vector image with a
viewBoxand no format change is served as it is. - A link-only host’s terms forbid a copy as much as a derivative, and a resize or a format change is a derivative. For such an image the resize code returns false, and the caller redirects to the source address. Fetching the bytes only to convert them would be exactly what storage already refuses to do.
- After resizing, the code stores the variant in
image_variantonly if the rate limiter allows it. The response is sent either way. - A daily job (
pruneVariants) removes variants with fewer than 3 accesses in 24 hours, and then resets the access counts.
Provenance headers
Section titled “Provenance headers”attribution.ts is the single place that decides which source produced a served image and what attribution that source needs. sendImage and sendVariant both use it, so they cannot disagree.
- The licence belongs to the list, not to the provider. One provider can publish many lists under different terms. A list that only points at someone else’s image cannot grant a licence to it.
- The effective licence of one entry’s image is decided once, at collection time, by
effectiveEntryLicense. It uses the list’s own licence and theownArtworklocation recorded on each registry entry. - A source with no verified licence is marked
unknown. It is never guessed, because a guessed licence is worse than none. - Every registry entry was filled in by opening the named source’s own licence file and copying its real copyright line.
ATTRIBUTION_HEADER_NAMESis the exact set of headers the cross-origin configuration must expose.
Caching headers
Section titled “Caching headers”resize.ts builds cache-control:
- Content-addressed responses (
/image/direct/...) getpublic, max-age=31536000, immutable. - Other responses get
public, max-age=<cache seconds>, stale-while-revalidate=<seven days>, stale-if-error=<seven days>.
See Caching.