26. WebSocket Subscriptions

Kortana provides a native, high-performance WebSocket streaming server running on dedicated TCP Port 8546 (§27.1–§27.3, RFC 6455). The WebSocket subsystem establishes bidirectional, full-duplex persistent connections between client applications and the node daemon, completely replacing inefficient polling loops (eth_getLogs / eth_getBlockByNumber) with real-time push notifications.

The WebSocket architecture enforces robust resource isolation and defensive backpressure management:

• Per-Connection Subscription Registry (SubscriptionRegistry): Subscriptions are strictly scoped to the TCP connection that created them. Subscription identifiers (e.g. 0x9e8a7c2b...) are generated via the operating system's cryptographic random number generator (/dev/urandom / CryptGenRandom). Scoping identifiers to the connection prevents malicious peers from guessing identifiers to unsubscribe other clients or probe active subscription topologies.
• Resource Limits & Bounded Queues: In accordance with §27.3, each active WebSocket connection is permitted a maximum of 10 concurrent active subscriptions (kMaxSubscriptionsPerConnection = 10). Outbound notification frames are buffered in a bounded per-connection queue. If a slow or stalled client fails to consume incoming notifications and the buffer reaches its safety ceiling, the server terminates the connection with WebSocket Close Code 1008 (Policy Violation) rather than silently dropping notifications. This fail-fast design ensures that indexing clients and trading bots never operate with silent data gaps.
• Unified Notification Format: All notifications are serialized into the standard Ethereum notification envelope: {"jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "<id>", "result": <payload>}}.

26.1 newHeads

Subscribing to the newHeads stream creates an ultra-low-latency event pipeline that emits the complete finalized block header JSON object the exact millisecond a block is committed by KSC BFT consensus (~1.5-second intervals).

// Subscription Request
{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"],
  "id": 1
}

// Response (Subscription ID)
{
  "jsonrpc": "2.0",
  "result": "0x4a8f9c1e2b3d4e5f",
  "id": 1
}

// Notification Payload
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x4a8f9c1e2b3d4e5f",
    "result": {
      "number": "0x100000",
      "hash": "0x8f3c2a1b9e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b",
      "parentHash": "0x7e2b1a0f8d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1a0f",
      "stateRoot": "0x3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b",
      "receiptsRoot": "0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
      "miner": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
      "gasUsed": "0x5208",
      "gasLimit": "0x1c9c380",
      "baseFeePerGas": "0x3b9aca00",
      "timestamp": "0x66d3a800"
    }
  }
}

The emitted header includes the block height, canonical block hash, state root, receipt root, gas consumption figures, base fee, and the cryptographic timestamp established by the continuous dPOH hash chain. DeFi applications, arbitrage bots, and bridge relayers rely on newHeads to trigger instantaneous state recalculations without network polling lag.

26.2 logs

The logs subscription provides real-time streaming of smart contract event logs emitted during block execution across both KEVM and KVM execution environments (§27.2). Subscribing clients can supply an optional filter object containing contract addresses and up to four 32-byte indexed topic filters.

// Subscription Request (Filtering for Transfer events on a token)
{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x1111111111111111111111111111111111111111",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ],
  "id": 2
}

// Notification Payload
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x7b6c5d4e3f2a1b0c",
    "result": {
      "address": "0x1111111111111111111111111111111111111111",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c8",
        "0x0000000000000000000000003c44cdddb6a900fa2b585dd299e03d12fa4293bc"
      ],
      "data": "0x0000000000000000000000000000000000000000000000056bc75e2d63100000",
      "blockNumber": "0x100000",
      "transactionHash": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
      "transactionIndex": "0x0",
      "logIndex": "0x0",
      "removed": false
    }
  }
}

The filter matching engine (LogFilter::matches() in rpc/subscription.cpp) executes exact byte matching against emitted event receipts:

• If address is specified, logs must originate from one of the listed contract addresses; empty lists match all emitters.
• Topic arrays support exact matches, wildcards (null entries matching any topic at that position), and OR-arrays (sub-arrays matching any one of the specified hashes).
• If an invalid address or malformed topic hex is provided in the subscription request, the server returns an immediate InvalidArgument error rather than silently ignoring the filter term.

26.3 newPendingTransactions & Native Event Feeds

In addition to finalized blocks and contract logs, the Kortana WebSocket server provides specialized mempool and consensus streaming feeds:

• newPendingTransactions (eth_subscribe("newPendingTransactions")): Streams the 32-byte transaction hash of every valid transaction admitted into the node's local mempool buffer. Maximal Extractable Value (MEV) searchers, market makers, and transaction accelerators consume this stream to observe pending order flow before block inclusion.
• ktn_newEpoch (ktn_subscribe("newEpoch")): Emits notifications at epoch boundary transitions (every 100,000 blocks / ~41.6 hours), broadcasting new active validator set snapshots, staking inflation rates, and governance parameter activations.
• ktn_validatorSetChange (ktn_subscribe("validatorSetChange")): Pushes real-time alerts whenever a validator joins, exits, updates their BLS consensus key, or experiences stake slashing due to equivocation.

// Unsubscribe Request
{
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x4a8f9c1e2b3d4e5f"],
  "id": 3
}

// Unsubscribe Response (Boolean Success)
{
  "jsonrpc": "2.0",
  "result": true,
  "id": 3
}

Unsubscribing via eth_unsubscribe or ktn_unsubscribe immediately releases connection table resources.

---