Recursive Inscriptions: Creating a Collection from Shared Layers

5 min readJun 17, 2023

With over 12 million inscriptions in only a few months, ordinals have brought a lot of excitement and innovation back to Bitcoin. The latest craze to hit the ordinals space is the concept of “Recursive Inscriptions”. This new feature allows one inscription to link to another, opening a whole new realm of composability on Bitcoin.

How does it work?

There has actually not been any change to the ord binary or protocol to enable this feature. It is simply an update to the main Ordinals block explorer to allow any links to other inscriptions using the following format: /content/<INSCRIPTION_ID>

For security, any external link requests are still blocked by default in the sandboxed iframes that display inscriptions, with the exception of these /content/ links. The explorer was also updated to allow for Javascript and CSS file types.

With this new update, inscriptions can become very powerful and inherit elements from previous inscriptions. For example, someone could inscribe popular Javascript and CSS libraries for anyone to use, allowing rich HTML files to be inscribed directly on Bitcoin and even link to each other.

Other explorers in the space have to follow suit and make the same updates that ordinals.com did to enable the /content/ links. The community has responded very well to the change, and almost all current explorers now support recursive inscriptions.

Creating an Ordinals Collection

At OrdinalsBot, we have inscribed many collections for projects in the space since launch. Due to the expensive nature of Bitcoin blockspace, a consistent pain point for almost all projects was the need to optimize their artwork to the smallest file size possible.

In many cases, this meant reducing the resolution to well under 1000px and applying heavy optimization that really impacted the final quality of the art.

The composable nature of recursive inscriptions can offer an alternative way of creating collections without having to compromise image quality.

You simply inscribe each trait in the collection in its original format (lossless optimization is still recommended), and then you can use recursion to generate HTML files that pull in these traits and rebuild the artwork.

The end result is a collection of HTML files that “look” exactly like the final image in every way at only a fraction of the file size, in most cases under 1kb.

Let’s set up an example

Below you will see we have 4 traits that make up the final image, each one is its own layer. They are still in their full 2500x2500px resolution and have been converted to WebP with lossless optimization applied.

If we were to merge these layers into a single image and apply optimization, the final 2500px file would still be around 230 kb, which becomes very expensive to inscribe, especially for a collection of 5000 images, which at that size would cost well over $1 million to inscribe them all.

To do this using the recursion method, we can create an HTML inscription that simply “layers” these traits. The first approach we came up with for this was to literally just use multiple <img> elements stacked on top of each other.

The issue here is that the layers load at different times, and when you right-click to save the image, you only save the top layer. Not great, so what can we do?

Canvas to the rescue!

The HTML <canvas> element is used to draw graphics on the fly via JavaScript. This is perfect for our use case, as we can also reach for recursion to share any JS logic we need throughout the collection.

Here is the final HTML for the recursion inscription:

<html>
   <body style="margin: 0;padding: 0">
      <script src="/content/b52f97a91555acce06f7cc1b42455a2b785be3a5cd3f4351b5358d1591690e2ei0"></script>
      <canvas id="canvas" style="width: 100%; height: auto;" width="2500" height="2500"></canvas>
      <script>
        draw(document.getElementById('canvas'), [ 
          "/content/e8ef7b28630fed165dad3acda08db5f089dfcf1bd005086abbf4c078958ccfb4i0",
          "/content/87f9c8d7b99734816346cbe942ca6709e64a49278026b1e1345bf751468ae267i0",
          "/content/0f27fcbaf43f17a39320af2d0cfc85fc4293d300f5bf932c1eb96b942f7a022ci0",
          "/content/cb692d0b3c306ee0d129b0903106571b6e98c17d5c75e266c0207d103b042be5i0"]
        );
      </script>
   </body>
</html>

As you can see, with only a few lines of code, we can pull in all the necessary elements we need and output what looks like an exact replica of the final digital artwork.

In the example above, the javascript logic has also been extracted to an inscription, saving yet more space on the final HTML. The script has one draw function that accepts a canvas element and an array of inscription links. It will load all image layers first and then draw the canvas, this is great as it makes sure the user only sees the full image, rather than traits loading in one at a time.

The end result is a flattened image inside a canvas element. The beauty here is that it acts like a normal image, can be resized like an image, and you can even right click and save!

Check it out: https://ordinals.com/inscription/3ab3d8dcd31cc8db0f0feaf2373c444697aae275a108ba72615c93de5ebcc4f8i0

The final HTML file is only 621 bytes! If you view the content of the inscription, it is still the full size of the linked traits, 2500x2500px. You can now generate a large number of these HTML files based on the collection metadata by simply mapping the attributes/traits in JSON to the linked trait inscription IDs.

It’s a really exciting time to be building on Bitcoin, and this new dimension that recursive ordinals bring to the space is sure to see yet another explosion of innovation and creativity!

Stay in touch…

Join the OrdinalsBot Discord here: https://discord.ordinalsbot.com
Follow us here: https://twitter.com/ordinalsbot
Inscribe something here: https://ordinalsbot.com
Launch your collection here: https://ordinalsbot.com/launchpad