Skip to content

Feature: Inscription enumeration index #793

@eynhaender

Description

@eynhaender

Feature: Inscription enumeration index

Background

GET /v1/inscription/{txhash}/{vin} already parses and serves inscription content directly from the witness data stored in libbitcoin-database.
No additional index is needed for single-item lookup by known txid. -> libbitcoin/libbitcoin-server#754

What is missing is the ability to enumerate inscriptions: list them by number, paginate, and navigate prev/next. This requires a new table in
libbitcoin-database.

Required index

A single new table in libbitcoin-database:

inscription_number (u32) → (txid (hash_digest), vin (uint32_t))

This is sufficient to:

  • Serve GET /v1/inscriptions?page=N (paginated list)
  • Serve GET /v1/inscription/{number} (lookup by ordinal number)
  • Provide prev/next links in responses

Content bytes, content-type, and size are resolved on demand via the existing endpoint — no denormalization needed.

How the index is built

A forward scan over all confirmed blocks in height order, reusing the existing parse_inscription() logic introduced with the inscription
endpoint. For each block, for each transaction, for each input: if the witness tapscript contains an inscription envelope, emit one record.
Inscription numbers are assigned in encounter order (non-coinbase transactions first, matching ord's assignment order).

The scan runs at node startup if the table is absent, then incrementally as new blocks are confirmed. Reorgs must revert records back to the fork point, consistent with how libbitcoin-database handles other tables.

What is explicitly out of scope

  • Satoshi-level tracking (which sat carries which inscription)
  • Transfer history / current satpoint after sends
  • Parent/child hierarchy
  • Rune balances
  • Unconfirmed / mempool inscriptions

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions