circles_subgraph

Circles V2 Subgraph + Path Explorer to visualize and understand trust-based flows on Circles Network

circles_subgraph

Created At

ETHGlobal Cannes

Winner of

The Graph - Best Use of The Graph Token API, Subgraphs, Substreams, or AI MCPs 2nd place

Project Description

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.

How it's Made

  • Subgraph: Indexing + Path Reconstruction We built a custom subgraph using The Graph Protocol to go beyond just tracking basic transfer events. The smart contracts emit complex events like StreamCompleted, which can represent 100s or 1000s of low-level token movements.

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.

  • Frontend: Circles Path Explorer The frontend is a React + TypeScript app built with Vite and styled using Tailwind CSS. It’s fully responsive and uses ECharts for rendering Sankey diagrams to visualize token flow between users.

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.

  • Architecture + Tools Used Smart Contract Data: Circles V2 contracts on Gnosis Chain

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.

  • Notable Hacks One particularly hacky (and powerful) aspect is how we reconstruct transfer paths from event logs using a flow-network decomposition. This isn't native to The Graph or Circles—it’s custom logic that acts almost like a mini pathfinding algorithm embedded inside the subgraph.
background image mobile

Join the mailing list

Get the latest news and updates