Glossary

Recursive Inscription

A recursive inscription is a Bitcoin Ordinal that references and composes data from other inscriptions, enabling on-chain composable media.

Key Takeaways

  • A recursive inscription is an inscription that references the content of other inscriptions on Bitcoin, pulling their data at render time to build complex applications from small, composable pieces.
  • Recursive inscriptions dramatically reduce block space usage by eliminating data duplication: shared libraries, images, and code are inscribed once and reused by thousands of other inscriptions.
  • By chaining references across multiple inscriptions, creators can circumvent the ~4MB single-block size limit and assemble arbitrarily complex on-chain applications: 3D art, games, and interactive websites running entirely on Bitcoin.

What Is a Recursive Inscription?

A recursive inscription is a Bitcoin Ordinal inscription that contains code referencing other inscription IDs instead of embedding all its data directly. When the inscription is rendered, the ord indexer resolves those references and serves the referenced content, allowing the inscription to compose media, logic, and assets from multiple on-chain sources.

Think of it like a web page that loads external scripts and images via URL paths. A recursive inscription does the same thing, except every resource it references lives permanently on the Bitcoin blockchain. The inscription itself might be under 1KB, but it can render a full 3D scene by pulling in a JavaScript library from one inscription, texture data from another, and model geometry from a third.

Recursive inscriptions were introduced in ord v0.6.2, released on June 15, 2023. The feature was proposed and merged by Casey Rodarmor (the creator of the Ordinals protocol) via PR #2167, which modified the Content-Security-Policy headers on inscription iframes to whitelist requests to /content/ paths.

How It Works

Every inscription on Bitcoin is assigned a unique inscription ID in the format <TXID>i<INDEX>, where TXID is the reveal transaction ID and INDEX is the inscription's position within that transaction. The content of any inscription can be accessed at the path /content/<INSCRIPTION_ID>.

Recursive inscriptions work by including references to these content paths in their HTML, JavaScript, or SVG code. When the ord indexer serves the inscription, it resolves these references and returns the referenced inscription's raw content.

Basic Reference Patterns

A recursive inscription can reference other inscriptions using standard HTML and JavaScript patterns:

<!-- Load a JavaScript library inscribed on Bitcoin -->
<script src="/content/13a5c8e41dfc...i0"></script>

<!-- Display an image from another inscription -->
<img src="/content/abc123def456...i0" />

<!-- Fetch inscription data programmatically -->
<script>
  fetch("/content/789xyz...")
    .then(r => r.json())
    .then(data => render(data));
</script>

Each reference is a relative URL path. The ord server intercepts these requests and serves the corresponding inscription's content, regardless of which block it was inscribed in.

Recursive Endpoints

Beyond referencing other inscriptions' content, recursive inscriptions can also access on-chain data through dedicated /r/ endpoints provided by the ord indexer:

  • /r/blockheight and /r/blocktime: current block height and timestamp
  • /r/blockhash/<HEIGHT>: block hash at a given height
  • /r/children/<INSCRIPTION_ID>: paginated list of child inscriptions (max 100 per page)
  • /r/inscription/<INSCRIPTION_ID>: metadata about a specific inscription
  • /r/sat/<SAT_NUMBER>: inscriptions on a given satoshi

Inscriptions can use the keyword self in place of an inscription ID to reference their own data. The Ordinals documentation guarantees backwards compatibility for these endpoints: existing fields will not be renamed or change types, though new fields may be added.

Rendering Flow

When a user views a recursive inscription, the process follows these steps:

  1. The ord indexer serves the inscription's content inside a sandboxed iframe with modified CSP headers
  2. The browser encounters references to /content/ or /r/ paths in the inscription's HTML or JavaScript
  3. The ord server intercepts these requests and serves the referenced inscription data
  4. The inscription's code assembles the referenced data into its final rendered output

This is purely a rendering-layer mechanism. The references are not enforced at the Bitcoin consensus level. The raw data of every referenced inscription exists immutably on-chain, but composing them into a coherent output depends on the ord indexer resolving the paths correctly.

Use Cases

Shared Code Libraries

JavaScript libraries like p5.js, Three.js, and React have been inscribed as public goods on Bitcoin. Any future inscription can reference these libraries instead of re-inscribing them. The OCM Dimensions collection (300 pieces of 3D generative art) referenced inscribed copies of p5.js and Three.js, keeping each individual artwork under 1KB while rendering fully interactive 3D scenes.

This creates a growing ecosystem of reusable on-chain components. Compression libraries like fflate and pako, rendering frameworks, and utility code are inscribed once and available to every future creator.

Composable PFP Collections

Profile picture (PFP) collections benefit enormously from recursive inscriptions. The BRC-69 standard defines a pattern where trait layers (backgrounds, bodies, accessories) are inscribed individually, and each NFT in the collection is a small code inscription that references and composes the relevant traits. A 10,000-piece collection might inscribe 200 trait layers plus 10,000 tiny composition scripts, rather than 10,000 full images. Projects like Pizza Ninjas (1,500 PFPs with dynamic SVG loading) and Cirque Le Noir (9,999 PFPs) use this approach, achieving up to 90% cost reduction compared to inscribing each image individually.

On-Chain Games and Interactive Media

Games can be built entirely on Bitcoin by inscribing game logic, assets, and rendering code as separate inscriptions. A game inscription references its sprite sheets, sound effects, and engine code from other inscriptions, assembling a playable application at render time. This approach has been used to create arcade-style games sharded across multiple inscriptions.

Exceeding the 4MB Limit

A single inscription is constrained by Bitcoin's ~4MB block size limit. Recursive inscriptions circumvent this by splitting data across multiple inscriptions in separate blocks and reassembling them at render time. Bitcoin Magazine demonstrated this by combining 20 separate inscriptions recursively to render a full magazine cover at high resolution.

Why It Matters

Recursive inscriptions transformed Bitcoin's inscription ecosystem from a collection of isolated data blobs into a composable data layer. Before recursion, every inscription was self-contained. If 1,000 artworks needed the same JavaScript library, that library was inscribed 1,000 times, wasting block space and inflating costs.

With recursion, the paradigm shifted toward write-once, reference-many. Shared resources are treated as public infrastructure, and new inscriptions become lightweight pointers that compose existing on-chain data into novel outputs. This mirrors how the web works: pages link to CDN-hosted libraries rather than embedding them inline.

For projects building on Bitcoin's data layer, recursive inscriptions make ambitious applications feasible. Layer 2 protocols like Spark focus on scaling Bitcoin's payment capabilities, while recursive inscriptions expand what can be stored and composed on the base layer itself.

Risks and Considerations

Indexer Dependency

Recursive inscriptions rely on the ord indexer to resolve /content/ references at render time. The underlying data is permanently stored on Bitcoin's base layer, but assembling referenced inscriptions into a coherent output requires a functioning indexer. If the ord software changes how it resolves paths, or if a user accesses inscriptions through an incompatible viewer, recursive inscriptions may not render correctly.

Block Space Debate

Inscriptions in general remain controversial within the Bitcoin community. Critics argue that storing non-financial data on Bitcoin competes with monetary transactions for block space, drives up fee rates, and increases blockchain size, making it more expensive to run full nodes. Supporters counter that block space is permissionless, miners earn legitimate fee revenue that strengthens long-term network security, and recursive inscriptions specifically reduce bloat by encouraging data reuse.

Reference Fragility

A recursive inscription is only as useful as the inscriptions it references. If a referenced inscription contains a bug or was inscribed with incorrect data, every inscription that depends on it inherits the problem. Unlike traditional web development where a library can be updated at its URL, inscriptions are immutable. A broken dependency is permanently broken.

Browser and Rendering Inconsistencies

Because recursive inscriptions run inside sandboxed iframes with specific CSP headers, rendering behavior can vary across browsers and platforms. Early implementations encountered issues with Safari and iOS browsers handling CSP headers differently. Creators must test across environments to ensure their recursive inscriptions render consistently.

No Consensus Enforcement

The Ordinals protocol and its recursive endpoints are a convention layered on top of Bitcoin, not a consensus rule. Bitcoin Core nodes do not validate or enforce inscription references. The OP_RETURN debate and proposals like BIP-110 (which sought to filter inscription data) highlight the tension between Bitcoin's monetary use case and its emerging role as a general-purpose data layer.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.