Chaingraph subscriptions

Subscribe to a GraphQL query; receive a push every time the underlying rows change. Runs over WebSocket only.

Wire protocol

Two flavors are accepted:

• graphql-transport-ws — current standard. Frame types: connection_init, connection_ack, subscribe, next, error, complete, ping, pong.
• graphql-ws (legacy) — older Apollo flavor. Frame types: connection_init, connection_ack, start, data, error, complete, stop, ka (keepalive).

Select via the WebSocket Sec-WebSocket-Protocol request header. The gateway translates between the two flavors as needed so upstream Hasura sees only the modern protocol regardless of which one your client speaks.

Opening a connection

wss://solidpeer.io/chaingraph/mainnet/<token>

Send connection_init:

{ "type": "connection_init", "payload": {} }

Expect connection_ack back. Then send a subscribe frame:

{
  "id": "sub-1",
  "type": "subscribe",
  "payload": {
    "query": "subscription { transaction(where:{hash:{_eq:\"<txid>\"}}) { hash inputs { outpoint { transaction_hash } } } }"
  }
}

The first next frame carries the initial snapshot — current matching rows. Subsequent next frames arrive whenever the result set changes.

To stop a single subscription without closing the WS:

{ "id": "sub-1", "type": "complete" }

(stop in the legacy protocol.)

Keepalive

The gateway sends ping (modern) or ka (legacy) every 10 seconds. Most clients respond with pong automatically; if you write a custom client, do the same or some intermediary proxies will close the connection idle.

Cost

• Registration: 300 CC on mainnet, 150 CC on testnets/regtest. Charged once when the subscription is accepted by Hasura.
• Per push: 150 CC on mainnet (75 CC testnets/regtest) per delivered next frame.

Per-push charges accumulate in a per-account batcher and flush to your balance every few seconds — you'll see the resulting CC in your audit log per-push, but the Redis billing is batched for efficiency.

Limits

• max_concurrent_subs per tier caps how many subscriptions one account can hold open across all its WS connections.
• Idle timeout: a WS with no inbound message and no outbound push for 15 minutes is closed by the gateway. Keepalives count as activity.
• Balance: if your account balance drops below the next push's reservation, the gateway closes the affected WS connections with code 4402 insufficient balance.
• Token budget: if a token has its own CC budget cap and pushes exhaust it, that token's WS connections are closed with code 4403 token budget exhausted.

Notes

• Subscriptions are per-connection. Closing the WS drops all active subscriptions on it; the gateway also refunds any reservation held against a never-resolved subscription.
• A subscription targeting a wide table (e.g. transaction with no filter) generates a push for every new tx that matches — high volume on mainnet. Use where: filters to narrow the matching rows.