Add sat at index content endpoint (/r/sat/:sat_number/at/:index/content)

[astralarkitekt]

Add recursive endpoint for sat inscription content

This PR adds a new recursive endpoint /r/sat/<SAT_NUMBER>/at/<INDEX>/content that returns the raw content of inscriptions on a specific sat at a given index. This endpoint complements the existing /r/sat/<SAT_NUMBER>/at/<INDEX> endpoint by directly returning the inscription content instead of just the inscription ID.

Features

• New endpoint /r/sat/<SAT_NUMBER>/at/<INDEX>/content
• Supports negative indices (e.g., -1 for most recent inscription)
• Returns appropriate mime-type and content
• Requires --index-sats flag like other sat-based endpoints

Documentation

• Added detailed documentation in docs/src/inscriptions/recursion.md
• Includes example usage with curl
• Follows existing recursive endpoint documentation format

Testing

• Endpoint follows the same pattern as existing recursive endpoints
• Returns proper content-type headers and raw inscription content
• Handles negative indices correctly

Example Usage

curl -s -H "Accept: application/json" \
http://0.0.0.0:80/r/sat/289488340427831/at/-1/content

Use cases

This endpoint is particularly valuable for dynamic on-chain content that evolves over time through reinscriptions. For example:

• On-chain blogs can automatically display their latest posts
• Dynamic NFTs can fetch their most recent state
• Decentralized applications can efficiently access updated content
• Content aggregators can streamline their data fetching
• Games can add special events that auto-update the game

By providing direct access to the latest inscription content on a specific sat, this endpoint reduces the number of API calls needed (from 2 to 1) and simplifies the development of applications that leverage reinscription functionality. This makes it easier to build applications that treat sats as updateable storage locations while maintaining the decentralized nature of ordinal inscriptions.

[gmart7t2]

It looks like your endpoint doesn't handle content proxying or delegation.

Compare your function with the regular content() function:

Wouldn't it be better to look up the inscriptionid and pass it to the content() function rather than adding another function that handles content?

Edit: maybe content proxying isn't needed since we don't proxy the sat endpoint. But delegation is.

[billpan69]

Ty great work!! This will save lots of calls!

[Fl1ntstowned]

Send it ;]

[casey]

Does this only save a single call? I.e., instead of getting the ID with /r/sat/<SAT_NUMBER>/at/<INDEX> and then getting /content/<ID>, you can get the content directly with /r/sat/:sat_number/at/:index/content?

If so, I'm not sure it's worth it. Is there something this enables which isn't possible otherwise?

[astralarkitekt]

Hi Casey, Nice to meet ya! This is about more than saving a single HTTP call—it's about optimizing how we engage with the ecosystem. By reducing the length of calls for content by over 50%, we’re not just trimming the fat. This is a tangible improvement. Here’s an example of what I mean. <https://x.com/boppleton/status/1862340194839437354> Scaling matters. There are 875k bitmaps out there, and parceling their content means *N = transaction_count* child inscriptions being scanned or loaded. Each of these child inscriptions could cascade into additional calls. Considering blocks average ~3k transactions, the difference between 3k and 6k API calls per inscription load adds up quickly. I totally get your hesitation—it’s *just Bitmap,* right? But Bitmap cares. 😉 And if we’re building on-chain, it’s on us to be good citizens of the ecosystem. Respect from the Orange Abyss, 🟧✊ Astral 👷🏗️🟧🌌

…

On Wed, Dec 18, 2024 at 5:39 PM Casey Rodarmor ***@***.***> wrote: Does this only save a single call? I.e., instead of getting the ID with /r/sat/<SAT_NUMBER>/at/<INDEX> and then getting /content/<ID>, you can get the content directly with /r/sat/:sat_number/at/:index/content? If so, I'm not sure it's worth it. Is there something this enables which isn't possible otherwise? — Reply to this email directly, view it on GitHub <#4113 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADLKN5QNZ5I3KTZDC6B2G32GIBTTAVCNFSM6AAAAABSWDGFFCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNJSGQ3DSMBUHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[casey]

Can you provide a concrete example of an inscription which would use this, and of an existing inscription which is slow or sub-optimal because it has to make multiple calls? Bitmap inscriptions are text, so they don't make recursive calls.

[gmart7t2]

I don't think I've ever used the /r/sat//at/ endpoint without immediately parsing the result as JSON and then fetching the returned inscription content. Maybe occasionally I only care about the inscription metadata, but almost every time I want its content.

Those 3 steps are pretty idiomatic, so it makes sense to have the ord server so them in a single call. It turns 2 calls into 1. Win/win for client and server.

[raphjaph]

I see a small problem where this makes configuring the cache more difficult. Right now we tell our CDN to just cache everything under /content indefinetly since it's static content. With this PR we now have to configure additional routes that server content and need to be cached.

[gmart7t2]

@raphjaph just because the route serves content doesn't mean it needs to be cached. A request for "the body of the most recent inscription on sat X" returns content, but different content each time that sat is reinscribed on.

That might be a good reason not to provide this endpoint. It makes correct caching hard if not impossible.

[raphjaph]

LGTM

[casey]

I think this is reasonable. I changed it so it recursively calls Self::content, so delegation should work correctly.