Substreams Data Service

Design repo for bringing Substreams onto The Graph Network as a first-class “data service”, using a pair of sidecars (consumer + provider) and a gRPC control-plane that coordinates session lifecycle, metering, and GraphTally/TAP payment state.

This repository is currently spec-first: it contains the Phase 1 draft spec and a protobuf draft for the sidecar-to-sidecar protocol. Implementation code is not yet present.

What’s in here (today)

• phase1-sidecar-spec.md — Phase 1 (Q1 2026) technical spec and end-to-end flow.
• sidecar.proto — Draft gRPC service + messages for Consumer Sidecar ↔ Provider Sidecar coordination.
• consumer/ — Placeholder for the consumer sidecar implementation.
• provider/ — Placeholder for the provider sidecar implementation.

Protocol snapshot (Phase 1)

• Data plane: the Substreams CLI connects to a provider Substreams endpoint for streaming data.
• Control plane: the consumer sidecar connects to the provider sidecar via SidecarControl:
  • OpenSession bootstraps a streaming session and returns an ephemeral Substreams credential.
  • ControlStream is a long-lived bidirectional stream for usage reporting, RAV requests/updates, funding status, and session close.
  • Heartbeat is a lightweight liveness check.
• Payments: coordinated via GraphTally / TAP concepts (rolling Receipt Aggregate Vouchers / RAVs), with the intent that the consumer sidecar holds the signer and produces signed updates when the provider requests them.

Notes / known gaps

• The spec text references a future proto location under proto/graphops/substreams/sidecar/v1/…, but the current draft lives at repo root as sidecar.proto.
• consumer/ and provider/ are currently empty scaffolding directories.

License

Apache-2.0 — see LICENSE.