Distributed media caching with multi-format optimization (AVIF, WebP, JXL, video), blur placeholders, demand-based tiered storage, distributed processing with node rewards.
Every listed asset needs media (images, video, 3D models). The media system fetches, processes, optimizes, and distributes media across the network with automatic format conversion and demand-based tiering.
1. Discovery -- When a listing is created, the system extracts the media source URL:
ord indexer metadatatokenURI, ERC-1155 uri)2. Fetching -- Media is downloaded with safeguards:
mediaCacheMaxBytes)3. Processing -- Content-aware optimization:
4. Storage -- Distributed across the network:
localProcessedPath, localOriginalPath)foundationUrl) for IPFS or centralized fallbackEach cached media entry tracks:
| Field | Purpose |
|---|---|
kind | IMAGE, VIDEO, AUDIO, HTML, MODEL, or FILE |
status | PENDING, READY, TOO_LARGE, ERROR, MISSING |
sourceContentType / processedContentType | Original and optimized MIME types |
sourceBytes / processedBytes | Size tracking |
blurDataUri | Inline base64 blur placeholder for instant display |
transformed | Whether processed version differs from original |
Each media entry can have multiple optimized variants stored in mediaCacheVariants:
| Variant Key | Purpose |
|---|---|
blur | Tiny blurred preview (< 1 KB) |
thumb | Minimal thumbnail for compact UI |
small | Standard card/grid media |
optimized | Web-optimized full size |
original | Untouched source file |
poster | Video cover frame |
preview | Medium-size preview |
Output Formats:
| Format | Use Case |
|---|---|
| AVIF | Best compression for images (preferred) |
| WebP | Wide browser support fallback |
| JXL (JPEG XL) | Progressive decoding, lossless option |
| H.265/AV1 | Next-gen video compression |
| H.264 | Legacy video compatibility |
| gif-webp / gif-avif | Animated GIF replacements |
Each (parentCacheId, variantKey, format) combination is unique.
Media optimization is distributed across nodes via a job queue:
mediaOptimizationJobs are created with target variant, format, dimensions, and priority (1-100)MEDIA_OPTIMIZATION reward claims for completed workReward Formula:
reward = (sourceBytes / 1 MB) * FORMAT_MULTIPLIER * TIER_BONUS * BASE_REWARD| Factor | Values |
|---|---|
| FORMAT_MULTIPLIER | AV1: 10.0, H.265: 5.0, H.264: 3.0, AVIF: 1.5, JXL: 1.2, WebP: 1.0 |
| TIER_BONUS | HIGH: 1.0, STANDARD: 0.8, BASIC: 0.5, NONE: 0.25 |
Computationally expensive formats (AV1, H.265) pay higher rewards to incentivize nodes to invest in processing hardware.
Media access patterns drive storage decisions via mediaDemandScores:
| Tier | Criteria | Behavior |
|---|---|---|
| HOT | High request count, trending up | Replicated aggressively, long cache TTL |
| WARM | Moderate requests, stable trend | Standard replication, moderate cache TTL |
| COLD | Low requests, trending down | Minimal replication, short cache TTL |
Scores are updated on every access. The trendScore (-1.0 to 1.0) tracks whether demand is rising or falling. The rebalancer periodically promotes/demotes entries between tiers.
Bitcoin ordinals can contain HTML/JSON that references other inscriptions (recursive inscriptions). The system handles this by:
isOrdinalRecursiveSource)ordinalRecursionMaxDepth (default: 8)ordinalRecursionMaxDependencies (default: 96)maybeBuildOrdinalRecursiveBundle)/content/<INSCRIPTION_ID> dependencies as data URIs when cached bytes are local and below ORD_MEDIA_RECURSION_INLINE_MAX_BYTES/r/* endpoints as cached external references with shorter stale TTL (ordinalDynamicStaleMs)Media is served via /api/media/cache/[cacheId]: