graphops/subgraph-radio

Gossip about Subgraphs with other Graph Protocol Indexers

Subgraph Radio

Introduction

This is a Graphcast Radio focused on sending messages about particular Subgraphs on a P2P network. The available message types are Public Proof of Indexing (PoI) messages from an indexer, or a version intent message from a subgraph owner.

Reaching Public PoI consensus and ensuring data availability during subgraph upgrades is critical to the indexing service. Both messages should find value from indexers, subgraph owners, and ultimately data consumers.

Documentation | Packages | Chat

Public PoI message

The key requirement for an Indexer to earn indexing rewards is to submit a valid Proof of Indexing (POI) promptly. The importance of valid POIs causes many Indexers to alert each other on subgraph health in community discussions. To alleviate the Indexer workload, this Radio utilized Graphcast SDK to exchange and aggregate POI along with a list of Indexer on-chain identities that can be used to trace reputations. With the pubsub pattern, the Indexer can get notified as soon as other indexers (with majority of stake) publish a POI different from the local POI.

Upgrade Intent message

When developers publish a new version (subgraph deployment) to their subgraph, data service instability may occur while their API queries the pre-existing version. Indexers may require some time to sync a subgraph to the chainhead after they have stopped syncing the previous deployment. To decrease the upgrade friction, developers can send a message before publishing the subgraph on current deployment hash's Graphcast channel, which includes the subgraph id, corresponding new deployment hash, and the represented graph account that must be validated to be the subgraph's owner.

Indexers running the subgraph radio and listening to that channel will in turn receive the message. Given valid configurations to notification, indexer management server, and auto_upgrade_coverage coverage level, the radio will send a notification to the indexer and/or an offchain request to their indexer management server that should automatically presync the deployment on graph node.

Note that it is still at the subgraph developers' discretion to await for the indexers to sync upto chainhead, in which point they can publish the staged version without disrupting API usage.

Subgraph APIs

Depending on your intended network, please pick the correct configurations and replace [api-key] with a valid api key for the decentralized network services.

Protocol Network	Graphcast Network	Registry Subgraph Endpoint	Network Subgraph Endpoint
Arbitrum-One	mainnet	https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/5tHgjCNF4XxAzp9ja8dU3j9JrqU7zctXj6DnxWpwAzc6	https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/DZz4kDTdmzWLWsV373w2bSmoar3umKKH9y82SUKr5qmp
Arbitrum-Sepolia	testnet	https://gateway-arbitrum.network.thegraph.com/api/{api-key}/subgraphs/id/9bnkkKmSqX3FpoxnBVNFcQfmdSJt2Zc8PrsY1ek64jPr	https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV
Ethereum Mainnet	mainnet	https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/rcKzonu5NGbKcxCDZoQWmcckRKJw8rnmMNJDV8UeDzJ	https://gateway-arbitrum.network.thegraph.com/api/{api-key}/subgraphs/id/GgwLf9BTFBJi6Z5iYHssMAGEE4w5dR3Jox2dMLrBxnCT

🧪 Testing

To run unit tests for the Radio. We recommend using nextest as your test runner. Once you have it installed you can run the tests using the following commands:

cargo nextest run

Contributing

We welcome and appreciate your contributions! Please see the Contributor Guide, Code Of Conduct and Security Notes for this repository.