gen_subscribe

Opens a subscription to a stream of GenLayer consensus events over the node's inbound WebSocket endpoint. Notifications are pushed as they occur, removing the need to poll gen_getTransactionStatus.

Method: gen_subscribe

Transport: WebSocket only. This method is not available over HTTP — an HTTP POST cannot receive push notifications. See the WebSocket endpoint section for the URL.

Parameters:

• stream (string, required): The event stream to subscribe to. One of transactions, leadership, epochs, newHeads.

Returns: A subscription id (UUID v4 string) used to correlate notifications and to cancel via gen_unsubscribe

Streams:

Notification Fields:

Example Request:

{
  "jsonrpc": "2.0",
  "method": "gen_subscribe",
  "params": [
    "transactions"
  ],
  "id": 1
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": "b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33",
  "id": 1
}

Example Notification:

{
  "jsonrpc": "2.0",
  "method": "gen_subscription",
  "params": {
    "subscription": "b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33",
    "result": {
      "kind": "TransactionAccepted",
      "event": {
        "txId": "0x9c1f3a7b8d2e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e",
        "raw": {
          "address": "0x1234567890abcdef1234567890abcdef12345678",
          "blockNumber": "0x151ec5",
          "transactionHash": "0x4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c"
        }
      }
    }
  }
}

Notes:

• The subscription id is a UUID v4 generated by this node; it is never an upstream chain subscription id
• Streams are coarse by design: one subscription covers a whole lifecycle, so following a transaction end to end costs one subscription rather than one per event kind
• The kind values are the consensus contracts' ABI event names, which are stable across node releases. They are deliberately not the node's internal topic names
• Every payload is derived from on-chain logs and contains no node-private data. The node's own GenVM sync position is not exposed here; use gen_syncing
• newHeads is served for convenience and duplicates eth_subscribe("newHeads"), which is fed from the same upstream. Latency-sensitive clients should prefer eth_subscribe
• Notifications are live only — there is no historical replay or backfill. Reconcile any gap with gen_getLogs
• Server-side filtering (for example by txId) is not supported; subscribe to the stream and filter client-side
• Subscribing to an unknown stream returns error code -32602 with the list of supported streams
• Exceeding max_subs_per_conn returns error code -32000 ("subscription limit reached")
• This method belongs to the genlayer endpoint group; disabling that group disables it on the WebSocket transport too
• Standard clients can consume this with their generic subscription API, since notifications use the conventional gen_subscription envelope. In go-ethereum: client.Subscribe(ctx, "gen", ch, "transactions")

wscat Example:

wscat -c ws://localhost:9151/ws
> {"jsonrpc":"2.0","method":"gen_subscribe","params":["transactions"],"id":1}
< {"jsonrpc":"2.0","result":"b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33","id":1}
< {"jsonrpc":"2.0","method":"gen_subscription","params":{"subscription":"b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33","result":{"kind":"NewTransaction","event":{"txId":"0x9c1f..."}}}}