Summary

I am requesting a 1000 DOT Big Tipper treasury tip for completed work on Acuity Index, the configurable event indexer for Substrate-based chains in this repository:

• https://github.com/acuity-network/acuity-index

This proposal is specifically for substantial work delivered after the earlier funded phases of the project.

The project is also fully documented here:

• https://acuity-network.github.io/acuity-index/

This is not a speculative concept: the code is public in this repository, the documentation is published, the project includes synthetic runtime/integration tooling for end-to-end validation, and Acuity Index has already been used as part of the Kusama Forum Tech Preview application stack.

Background

Acuity Index was originally called Hybrid. As documented in this repository’s book, the project previously received support from:

• two Web3 Foundation grants (1, 2)
• a Kusama Treasury referendum (referendum)

The work from that previous funding phase was implemented in the earlier repositories:

• https://github.com/acuity-network/acuity-index-substrate
• https://github.com/acuity-network/acuity-index-polkadot

This treasury proposal is not for that earlier work. It is for the subsequent work that has already been completed in the current combined repository.

Scope of this tip request

This request covers completed work in the current acuity-index repository, including:

• config-driven indexing architecture
• generic event decoding without generated chain-specific Rust event types
• resumable local persistence and span tracking
• the dapp-facing WebSocket API for queries and subscriptions
• finalized event proof support
• hot reload, operational hardening, and recovery improvements
• synthetic runtime testing, deterministic seeding, benchmarking, and published documentation

This request does not cover:

• work previously funded through the earlier Hybrid / Acuity Index grants
• work delivered in the earlier repositories:
  • https://github.com/acuity-network/acuity-index-substrate
  • https://github.com/acuity-network/acuity-index-polkadot

The purpose of this tip request is to recognize substantial additional work delivered after those earlier funded phases.

What Acuity Index is

Acuity Index is a config-driven event indexer for Substrate-based blockchains that is specifically designed to expose a dapp-facing WebSocket API for direct application integration.

That is the project's primary distinction from many other indexers in the ecosystem. Rather than being designed mainly as an internal analytics pipeline, a bespoke backend component, or an operator-only data service, Acuity Index is built to expose indexed blockchain events through a public WebSocket API that applications can integrate with directly.

It connects to a node over WebSocket RPC, decodes runtime events without requiring chain-specific generated Rust types, stores queryable indexed references locally, and exposes the indexed data through its own WebSocket API.

Its purpose is to make on-chain event data practical for dapps to query, paginate, subscribe to, and verify.

Work completed in this repository

The completed work in this repo includes a major maturation of the project from earlier prototypes into a much more complete, configurable, and operator-friendly indexing service.

Area	Delivered in the current repository
Configuration	TOML index specs, explicit chain identity and mappings, generated starter specs
Indexing	Generic event decoding, resumable local persistence, span tracking, reindex support
API	JSON-RPC 2.0 WebSocket API, event queries, subscriptions, pagination, metadata lookup
Verification	Finalized event proof support
Operations	Hot reload, runtime option reloads, startup validation, chain safety checks
Reliability	RPC reconnects, exponential backoff, preserved sessions, defensive persistence handling
Performance	Concurrent backfill/live catch-up, queue-based flow, benchmarked throughput
Security	Bounded queues, backpressure handling, caps and limits, deployment guidance
Validation	Synthetic runtime, deterministic seeding, integration testing, published documentation

More detail on the completed work is outlined below.

1. Config-driven indexing architecture

Acuity Index now uses explicit TOML index specifications to define chain-specific indexing behavior.

Completed work includes:

• explicit chain identity and indexing rules in TOML
• declared scalar and composite query keys
• explicit pallet and event mappings
• generated starter specs from live metadata
• separation between index-spec configuration and deployment/runtime options

Example index-spec.toml:

# Machine-readable name for this chain config.
name = "acuity-runtime"
# Chain identity hash; change this only when targeting a different chain.
genesis_hash = "c5605452b91e2b3e2da0a77596fae2448c52b794aea675738f52f31e2cdf49f4"
# Default node endpoint used with this index spec.
default_url = "ws://[::1]:9944"
# Block heights where a new index spec revision starts; must begin with 0.
# Example: [0, 1250000, 2485000]
# Adding a new boundary in past history causes the indexer to keep earlier data
# and re-index from the earliest affected boundary onward.
spec_change_blocks = [0]
# Whether to index event variant names for variant-based queries.
index_variant = false

# Declare all query keys here. Event params may only reference names declared
# in this section. Scalar keys map one event field to one typed query key.
# Composite keys combine multiple fields into one query key.
# Supported scalar kinds: bytes32, u32, u64, u128, string, bool.
# Example scalar key: item_id = "bytes32"
# Example composite key: item_revision = { fields = ["bytes32", "u32"] }
[keys]
account_id = "bytes32"
item_id = "bytes32"
item_revision = { fields = ["bytes32", "u32"] }

# Example pallet config showing scalar, multi, and composite keys.
# [[pallets]]
# name = "MyPallet"
# events = [
#   { name = "MyEvent", params = [
#     { field = "who", key = "account_id" },
#     { field = "item_id", key = "item_id" },
#     { field = "related_ids", key = "item_id", multi = true },
#     { fields = ["item_id", "revision_id"], key = "item_revision" },
#   ] },
# ]

[[pallets]]
name = "Content"
events = [
  { name = "PublishItem", params = [
    { field = "item_id", key = "item_id" },
    { field = "owner", key = "account_id" },
    { field = "parents", key = "item_id", multi = true },
  ] },
  { name = "PublishRevision", params = [
    { field = "item_id", key = "item_id" },
    { fields = ["item_id", "revision_id"], key = "item_revision" },
    { field = "owner", key = "account_id" },
    { field = "links", key = "item_id", multi = true },
    { field = "mentions", key = "account_id", multi = true },
  ] },
  { name = "RetractItem", params = [
    { field = "item_id", key = "item_id" },
    { field = "owner", key = "account_id" },
  ] },
  { name = "SetNotRevisionable", params = [
    { field = "item_id", key = "item_id" },
    { field = "owner", key = "account_id" },
  ] },
  { name = "SetNotRetractable", params = [
    { field = "item_id", key = "item_id" },
    { field = "owner", key = "account_id" },
  ] },
]

This makes the indexer significantly more reusable across Substrate chains and reduces the need for chain-specific code changes.

2. Generic event decoding without generated chain types

A major completed capability is the ability to decode and index runtime events generically rather than depending on chain-specific generated Rust event types.

This improves portability and lowers maintenance overhead when targeting different Substrate runtimes.

3. Queryable local event index with resumable span tracking

The current repository implements robust local persistence and indexing behavior, including:

• indexed event references stored in an embedded database
• persisted block-span tracking
• resume-safe indexing after interruption
• reindex support across spec revisions using spec_change_blocks
• chain identity protection using the stored genesis hash

This turns the project into a practical long-running indexing service rather than only an experimental implementation.

4. Public WebSocket API for direct dapp queries and subscriptions

A key distinguishing feature of Acuity Index is its dapp-facing WebSocket API for direct application integration.

This repository delivers a public JSON-RPC 2.0 WebSocket API for:

• index status
• event metadata lookup
• event queries
• event subscriptions
• unsubscribe flows

The API supports:

• paginated event queries
• live subscriptions for matching keys
• structured error responses
• stable query key formats

This is one of the core user-facing outputs of the project, and it is central to what makes Acuity Index different from many ecosystem indexers: it is intended to be application-facing infrastructure, not just backend infrastructure.

5. Support for finalized proofs

A significant completed feature is support for returning finalized event proofs for queried events.

The indexer can return proof material for finalized events so that clients can verify that the returned event is included in finalized chain data rather than trusting the indexer's response alone. In other words, the API can return not just the event reference, but also the supporting proof data needed for independent verification against finalized chain state.

This matters because it makes the service more trust-minimized than a conventional indexer API: applications can use the index for fast querying while still retaining a path to cryptographic verification for finalized results.

This is a strong differentiator for trust-minimized event indexing and is directly aligned with the needs of the Polkadot ecosystem.

6. Hot reload and operator-focused improvements

The current repo includes substantial operational work, including:

• hot reload of accepted index-spec changes
• hot-reloadable runtime options
• restart of indexing without dropping the public service
• improved startup validation
• better database path handling
• improved chain safety checks

This makes the software much more practical for real operators to run and maintain.

7. Reliability and recovery improvements

Completed reliability work includes:

• recoverable upstream RPC reconnect loops
• exponential backoff recovery
• preservation of WebSocket sessions across reconnects
• preservation of span state on errors
• improved handling of syncing / warp-synced nodes
• more defensive handling of malformed persisted records
• reduction of panic paths in favor of structured failures

These are important production-readiness improvements and represent substantial engineering work beyond the original concept.

8. Throughput and scalability improvements

This repo also includes major implementation work to improve performance, including:

• concurrent backfill and live head catch-up
• queue-based indexing flow
• better handling of out-of-order completed work
• blocking-pool event decode work
• widened event indexing support
• benchmarking workflows for end-to-end indexing performance

With these improvements, Acuity Index can populate the index from a full node at around 45,000 events/second on an AMD Ryzen 7 6800HS Creator Edition (16) @ 4.79 GHz.

These changes are important for practical deployment on active networks.

9. Security hardening and operational limits

A significant amount of completed work has gone into reducing operational risk for public-facing use, including:

• bounded subscription queues
• backpressure handling
• WebSocket message/frame size limits
• configurable connection and subscription caps
• idle timeouts and heartbeats
• safer handling of upstream outages
• separation of metrics exposure
• clearer deployment and security guidance

This is necessary work for any infrastructure intended for external consumers.

10. Synthetic runtime, integration testing, and benchmarking

The current repository includes a substantial testing and validation effort:

• an in-repo synthetic Polkadot runtime
• deterministic seeding tools
• end-to-end integration testing workflows
• benchmarking tools for synthetic indexing scenarios
• fully published project documentation via mdBook at https://acuity-network.github.io/acuity-index/

This kind of tooling is very valuable for long-term maintainability and future ecosystem adoption.

Why this work matters for Polkadot

Acuity Index addresses an important gap for dapps and ecosystem services built on Substrate and Polkadot technology.

Its most important distinguishing characteristic is that it provides a dapp-facing query API designed for direct application integration. That matters because many indexing approaches in the ecosystem ultimately still require each team to run or depend on a custom backend layer between the application and indexed chain data. Acuity Index is intended to reduce that gap by providing a reusable query service for event data.

Writing data to events is often much cheaper and more natural than storing everything in chain state, but dapps still need a practical way to search historic events and subscribe to new ones.

Without tooling like this, teams are often pushed toward:

• expensive repeated log scanning
• dependence on centralized RPC or indexing providers
• custom one-off indexing backends
• storing more data on-chain than should be necessary

Acuity Index helps provide a reusable, configurable foundation for event indexing that is better aligned with open infrastructure and the needs of Substrate-based applications, especially for teams that want dapps to consume indexed event data directly rather than through another closed intermediary layer.

A concrete example of this approach is the Kusama Forum Tech Preview, where Acuity Index is part of the application stack for a decentralized forum dapp:

• Video: https://www.youtube.com/watch?v=zorO0wG8HXw
• Forum post: https://forum.polkadot.network/t/kusama-forum-tech-preview/17689

The video and forum post demonstrate the intended role of Acuity Index in the ecosystem: not just as an internal indexing tool, but as infrastructure that can effectively power real dapp user experiences.

Users and use cases

Acuity Index is useful for teams building applications and services that need to search historic events, subscribe to new events, and expose that data in a reusable application-facing way.

Relevant use cases include:

• forums and social applications
• governance dashboards and referendum tooling
• notifications and alerting systems
• explorers and analytics tools focused on event-centric workflows
• applications that write important domain data to events rather than long-lived chain storage
• operator-managed infrastructure that wants to provide a reusable event query layer for multiple applications

Why a tip is appropriate

This proposal is for work already completed and publicly visible in the repository.

A tip is appropriate because this request is not asking the Treasury to underwrite speculative future work. It asks the Treasury to recognize completed, publicly auditable infrastructure work that is already implemented, documented, and reusable by the ecosystem. This repository represents substantial post-grant maturation beyond the earlier funded phases, and a tip is therefore a fitting mechanism to acknowledge delivered value rather than proposed milestones.

The repo demonstrates that delivered value through:

• architectural consolidation of the project
• a configurable production-oriented indexing system
• a dapp-facing WebSocket API designed for direct application queries
• proof support
• reliability and security hardening
• synthetic testing and benchmarking infrastructure
• fully published project documentation at https://acuity-network.github.io/acuity-index/

A tip is therefore an appropriate mechanism to recognize completed ecosystem infrastructure work that benefits Polkadot developers and operators.

Amount requested

1000 DOT

This amount is intended as a moderate Treasury recognition of substantial completed infrastructure work, not as a full retroactive valuation of all engineering time invested in the project. The repo reflects significant post-grant delivery across architecture, indexing, API design, proofs, reliability, security hardening, testing, and documentation. In that context, 1000 DOT is proposed as a proportionate Big Tipper request for meaningful delivered ecosystem value.

Closing

This proposal asks the Polkadot Treasury to recognize the completed work delivered in this repository as a meaningful continuation of the previously funded Acuity Index / Hybrid effort.

The earlier funding supported the work delivered in the earlier Acuity Index repositories:

• https://github.com/acuity-network/acuity-index-substrate
• https://github.com/acuity-network/acuity-index-polkadot

This request is for the substantial additional work delivered in the current repository:

• https://github.com/acuity-network/acuity-index

I believe this represents real delivered value for the Polkadot ecosystem and is suitable for a Big Tipper treasury proposal for 1000 DOT.