Circles V2 Subgraph + Path Explorer to visualize and understand trust-based flows on Circles Network
Circles is a unique experiment aiming to redefine how we think about money. The Circles network is based on a web of trust, where value flows from user to user through personal trust connections.
Traditional block explorers only show the direct events of a single transaction. However, in Circles, a transfer from user A to user B can involve hundreds or even thousands of individual transfers across the trust graph. This makes standard explorers insufficient for understanding what's really happening.
To address this, the project set out to build a custom subgraph that not only indexes raw event data but also performs deeper processing—capturing complete transfer paths, the number of hops, user balances, and more. This enables fast and rich analytics.
The second part of the project was a frontend tool that connects to this enhanced subgraph, allowing users to explore and visualize the Circles network in a meaningful way. It also integrates with the MCP subgraph, enabling an on-demand agent to run smart queries on the Circles Hub smart contract—providing real-time answers and insights into the network.
To make this actionable, we wrote custom logic in AssemblyScript that reconstructs complete transfer paths:
It listens for StreamCompleted events.
It gathers all related TransferSingle and TransferBatch events in that transaction.
We build a flow network and decompose it into individual paths using a custom findAllPaths function.
These paths are stored as entities like TransferPath and TransferHop for later querying.
This gives us rich data like number of hops, trust intermediaries, and flow amounts—impossible to get with standard block explorers.
We structured the app around:
Reusable components (src/components)
Data-fetching hooks (src/hooks)
Apollo GraphQL client (src/services)
GraphQL queries to interact with the subgraph
A user can search by address or transaction hash, and the UI presents reconstructed paths, hop details, and flow visualization in a clean and intuitive interface.
-Backend Bridge: Natural Language Interface To add intelligent querying, we introduced an MCP bridge (Node.js/Express backend) that connects the frontend to the subgraph via OpenAI.
How it works:
Users ask a natural-language question in the chat UI.
The backend sends the message to the OpenAI API.
The model returns a GraphQL query.
The MCP client executes this query against the subgraph.
The result is formatted and returned to the frontend.
This enables on-the-fly queries about addresses, balances, trust links, and even custom transfer logic—without needing to understand GraphQL.
Data Indexing: The Graph Protocol (subgraph, AssemblyScript)
Visualization: React, TypeScript, Vite, Tailwind, ECharts
AI Integration: OpenAI API + custom query-to-GraphQL bridge
Backend: Node.js, Express, WebSocket for real-time responses
Submodule Handling: Circles V2 Hub is a Git submodule, allowing independent development of the indexing logic.