Unified Liquidity Balance API

[lrazovic]

Project Abstract

The Unified Liquidity Balance API is a real‑time balance tracking solution for Polkadot SDK-based chains. It provides a single, unified Server‑Sent Events (SSE) endpoint to monitor user balances across multiple parachains without polling or deep integration with Polkadot‑specific libraries.

Grant level

• Level 1: Up to $10,000, 2 approvals
• Level 2: Up to $30,000, 3 approvals
• Level 3: Unlimited, 5 approvals (for >$100k: Web3 Foundation Council approval)

Application Checklist

• The application template has been copied and aptly renamed (project_name.md).
• I have read the application guidelines.
• Payment details have been provided (Polkadot AssetHub (USDC & DOT) address in the application and bank details via email, if applicable).
• I understand that an agreed upon percentage of each milestone will be paid in vested DOT, to the Polkadot address listed in the application.
• I am aware that, in order to receive a grant, I (and the entity I represent) have to successfully complete a KYC/KYB check.
• The software delivered for this grant will be released under an open-source license specified in the application.
• The initial PR contains only one commit (squash and force-push if needed).
• The grant will only be announced once the first milestone has been accepted (see the announcement guidelines).
• I prefer the discussion of this application to take place in a private Element/Matrix channel. My username is: @_______:matrix.org (change the homeserver if you use a different one)

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[lrazovic]

I have read and hereby sign the Contributor License Agreement.

[keeganquigley]

Thanks for the application @lrazovic could you clarify what you have already built, and what you would build as part of this grant? Since I see the PoC is complete.

[lrazovic]

Thanks for the question, happy to clarify.

The PoC was really about demonstrating the core technical feasibility, showing we could stream basic balance updates via SSE using Cloudflare Workers and Durable Objects. But, as you'd expect with an early prototype, it has its limitations. That's exactly what this grant is for: transforming that basic PoC into a robust, production-ready service.

For instance, the PoC currently handles all connections (both to the chains and to end-users) within a single DO instance. While that works for a demo, it wouldn't scale effectively. A key part of the grant work involves re-architecting this for proper scalability and reliability. Similarly, the PoC currently only streams DOT balances. The grant funding will allow us to significantly expand this, adding support for more assets from various chains and implementing necessary filtering options.

Beyond those specific examples, the grant also covers building out the other essentials for a production service – things like robust error handling, better connection management, thorough testing, and comprehensive documentation – which were naturally outside the scope of simply proving the initial concept.

Hope this helps clarify the scope!

[keeganquigley]

Thanks @lrazovic for your explanation. I will mark the application as ready for review and ping the rest of the committee for comment.

In the meantime, can you clarify which parachains you plan to support out of the box? Is it just these four: Polkadot, Asset Hub, Polimec, Hydration?

[lrazovic]

Correct. Out of the box, we are targeting Polkadot, Polkadot Asset Hub, Polimec, and Hydration. The code is also designed so that supporting other Polkadot SDK-based chains will be quite easy, if needed.

[keeganquigley]

Thanks @lrazovic do you have clients in mind that could immediately use this? Did you hear about a need for this from the community? Just a couple more technical clarifying questions as well:

• If I understand correctly, the API would be read-only?
• How does the system handle potential RPC node failures or unresponsiveness for one or more of the connected parachains?
• Does the API wait for block finality before reporting a balance change?
• Since the PoC is live, what are its current limitations in terms of concurrent SSE connections or number of accounts tracked?

[keeganquigley]

Could you elaborate on a specific scenario where your SSE-based API is distinctly advantageous over using something like SubQuery or Subquid indexer?

[lrazovic]

Indexers are invaluable for historical data, complex filtering, or querying relationships—for instance, "show me all transfers over 100 DOT for this account in the last month". For those needs, an indexer is absolutely the right tool.

ULB, however, offers a distinct advantage when you need a lightweight, low-latency, push-based stream of the current aggregated balance for immediate UI updates. This avoids client-side polling or complex query language integration for this specific real-time need, offering simplicity and directness. This immediate, push-based feedback is particularly crucial in scenarios leveraging Polkadot's interoperability. For example, users often have assets like DOT scattered across various parachains. After an XCM transfer, receiving instant, aggregated balance updates via our SSE stream is vital for keeping the user informed about what's happening.

This directly improves Polkadot's user experience by providing clarity and responsiveness where it matters most.

[lrazovic]

do you have clients in mind that could immediately use this? Did you hear about a need for this from the community?

Yes, definitely. We see a clear and immediate need for this. Especially from teams looking to simplify how dApps and services interact with multi-chain balances. More broadly, we envision this API being valuable for:

• dApp Developers: Anyone building cross-chain applications on Polkadot who needs to display aggregated user balances without wrestling with multiple chain-specific APIs or managing numerous WebSocket connections. This lowers the barrier to entry and reduces end user frictions.
• Wallet Providers: To offer users a unified view of their assets across Polkadot, Asset Hub, and other supported parachains in real-time.
• Analytics Platforms & Dashboards: Projects that monitor on-chain activity need real-time access to balance data across multiple accounts and networks. This API makes that significantly easier and more scalable.

• If I understand correctly, the API would be read-only?

Correct. The API is designed exclusively for read-only access to provide real-time updates on account balances. It aggregates these values from various chains into a single, unified stream. It does not, and will not, handle any transaction submissions or private key management.

• How does the system handle potential RPC node failures or unresponsiveness for one or more of the connected parachains?

The underlying Polkadot-API (PAPI) library we're using has built-in support for connecting to multiple RPC endpoints for a single chain. As highlighted in recent PAPI updates (e.g., point 4 on this PR discussing round-robin/failover), it can perform a round-robin or failover mechanism. For our Unified Liquidity Balance API, this means we can configure multiple RPC URLs per supported chain. If one RPC node becomes unresponsive or fails, PAPI will automatically attempt to connect to the next available one in the list for that chain.

• Does the API wait for block finality before reporting a balance change?

By default, and for the primary use case of tracking balances, our intention is to report changes after block finalization. PAPI makes it straightforward to subscribe to finalized storage changes, which is its default behavior for such queries. This ensures that the balance information streamed is confirmed and not subject to potential reorgs. However, PAPI also allows querying storage from the "best" (unfinalized) block. We could potentially expose an "optimistic" endpoint or a query parameter in the future if there's strong community demand for near-instant updates, with the understanding that such data would be unfinalized. For the core service delivered under this grant, finalized balances will be the standard to ensure accuracy.

• Since the PoC is live, what are its current limitations in terms of concurrent SSE connections or number of accounts tracked?

The primary goal of the PoC was to validate the core technical approach: using Cloudflare Workers with Durable Objects to maintain SSE connections and stream balance updates from Polkadot SDK chains via PAPI. It wasn't specifically stress-tested for maximum concurrent connections or a high volume of tracked accounts, yet. Currently the main architectural limitation that would affect scalability is that a single Durable Object instance manages connections and state. While Cloudflare Workers themselves are highly scalable, this centralized aspect in the PoC would become a bottleneck under heavy load. Benchmarks will be conducted and distributed before the second milestone, and they will be used to have a tangible proof of the performance optimizations part of the second milestone.

[keeganquigley]

Closing per email discussion.