agorix
AirdropMarketsCollectionsLeaderboardActivity
Agorix · Decentralized Marketplace
Independent · Resilient · Community-Run

A cross-chain marketplace, run by the community.

Discover, list, and trade across Bitcoin, Ethereum, and Solana on an open, community-run network.

Marketplace
CollectionsMarketsLeaderboardActivity
Network
GovernanceExplorerAirdropDocs
Account
ProfileSettings
Legal
Terms of ServicePrivacy PolicyYour Privacy Choices
agorix.io — Lasting Access
CID: 0xA60R1X · v0.1
AirdropMarketsCollections
D
Protocol Docs
Marketplace OverviewAtomic Buy LocksDatabase ArchitectureProfiles & AuthenticationCollections & RoyaltiesCreator Royalty SystemMedia Cache & OptimizationModeration & ReputationSearch & DiscoveryCollection Rarity AlgorithmsLive Activity & LeaderboardsCollection Preseed Queue
Docs/Marketplace/Media Cache & Optimization
Marketplace

Media Cache & Optimization

Distributed media caching with multi-format optimization (AVIF, WebP, JXL, video), blur placeholders, demand-based tiered storage, distributed processing with node rewards.

#Media Cache & Optimization

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.

#Media Lifecycle

1. Discovery -- When a listing is created, the system extracts the media source URL:

  • BTC ordinals: recursive inscription content, ord indexer metadata
  • EVM NFTs: contract metadata URIs (ERC-721 tokenURI, ERC-1155 uri)
  • Solana: Metaplex metadata accounts

2. Fetching -- Media is downloaded with safeguards:

  • Maximum size: 100 MB (configurable via mediaCacheMaxBytes)
  • Follows HTTP redirects (max 5 hops)
  • Respects cache headers (ETag, Last-Modified)
  • Marks as ERROR if unreachable, TOO_LARGE if oversized

3. Processing -- Content-aware optimization:

  • Images: convert to optimized formats (AVIF, WebP preferred)
  • Video: extract poster frame and preview thumbnails
  • HTML/JSON: parse and extract referenced media (recursive ordinals)
  • Generate blur placeholder data URIs for instant loading

4. Storage -- Distributed across the network:

  • Local filesystem paths (localProcessedPath, localOriginalPath)
  • Foundation gateway URL (foundationUrl) for IPFS or centralized fallback
  • Replicated to other nodes based on demand tier

#Media Entry Schema

Each cached media entry tracks:

FieldPurpose
kindIMAGE, VIDEO, AUDIO, HTML, MODEL, or FILE
statusPENDING, READY, TOO_LARGE, ERROR, MISSING
sourceContentType / processedContentTypeOriginal and optimized MIME types
sourceBytes / processedBytesSize tracking
blurDataUriInline base64 blur placeholder for instant display
transformedWhether processed version differs from original

#Multi-Format Variants

Each media entry can have multiple optimized variants stored in mediaCacheVariants:

Variant KeyPurpose
blurTiny blurred preview (< 1 KB)
thumbMinimal thumbnail for compact UI
smallStandard card/grid media
optimizedWeb-optimized full size
originalUntouched source file
posterVideo cover frame
previewMedium-size preview

Output Formats:

FormatUse Case
AVIFBest compression for images (preferred)
WebPWide browser support fallback
JXL (JPEG XL)Progressive decoding, lossless option
H.265/AV1Next-gen video compression
H.264Legacy video compatibility
gif-webp / gif-avifAnimated GIF replacements

Each (parentCacheId, variantKey, format) combination is unique.

#Distributed Processing

Media optimization is distributed across nodes via a job queue:

  • Enqueue -- mediaOptimizationJobs are created with target variant, format, dimensions, and priority (1-100)
  • Assign -- Nodes claim jobs based on their optimizer tier (BASIC, STANDARD, HIGH)
  • Process -- The assigned node creates the variant and uploads it
  • Reward -- Nodes earn MEDIA_OPTIMIZATION reward claims for completed work

Reward Formula:

text
reward = (sourceBytes / 1 MB) * FORMAT_MULTIPLIER * TIER_BONUS * BASE_REWARD
FactorValues
FORMAT_MULTIPLIERAV1: 10.0, H.265: 5.0, H.264: 3.0, AVIF: 1.5, JXL: 1.2, WebP: 1.0
TIER_BONUSHIGH: 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.

#Demand-Based Tiering

Media access patterns drive storage decisions via mediaDemandScores:

TierCriteriaBehavior
HOTHigh request count, trending upReplicated aggressively, long cache TTL
WARMModerate requests, stable trendStandard replication, moderate cache TTL
COLDLow requests, trending downMinimal 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.

#Recursive Ordinal Handling

Bitcoin ordinals can contain HTML/JSON that references other inscriptions (recursive inscriptions). The system handles this by:

  • Detecting recursive references (isOrdinalRecursiveSource)
  • Resolving dependencies up to ordinalRecursionMaxDepth (default: 8)
  • Limiting to ordinalRecursionMaxDependencies (default: 96)
  • Building merged bundles (maybeBuildOrdinalRecursiveBundle)
  • Inlining static /content/<INSCRIPTION_ID> dependencies as data URIs when cached bytes are local and below ORD_MEDIA_RECURSION_INLINE_MAX_BYTES
  • Brotli-compressing the resulting single-file text bundle during media processing
  • Keeping dynamic /r/* endpoints as cached external references with shorter stale TTL (ordinalDynamicStaleMs)

#Serving

Media is served via /api/media/cache/[cacheId]:

  • Returns the best available variant based on Accept headers
  • Cache-Control headers vary by demand tier (HOT = aggressive caching, COLD = short TTL)
  • Blur placeholders are returned inline for instant perceived loading
PreviousCreator Royalty SystemNext Moderation & Reputation

On this page

  • Media Cache & Optimization
  • Media Lifecycle
  • Media Entry Schema
  • Multi-Format Variants
  • Distributed Processing
  • Demand-Based Tiering
  • Recursive Ordinal Handling
  • Serving