# Network Statistics

The `/ws/stats` endpoint streams a comprehensive snapshot of MultiversX network state every 250ms. It is a read-only, push-only stream — no subscribe action required. Connect and data arrives immediately.

***

## Connection

```javascript
const ws = new WebSocket('wss://relayer.xoxno.com/ws/stats');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type === 'networkStats'
  console.log(msg);
};
```

This endpoint operates independently of the main `/ws` endpoint. Connect to both simultaneously when your application needs subscription-based topics alongside the network stats stream.

***

## Message Schema

```json
{
  "type": "networkStats",
  "schemaVersion": "1.1.0",
  "sequence": 1,
  "ts": 1738800000000,
  "data": {
    "network": {
      "currentTps": 2500,
      "avgTps10s": 2400,
      "avgTps30s": 2350,
      "connectedPeers": 450,
      "activeValidators": 32,
      "wsLagMs": 25
    },
    "blocks": {
      "latestShard": {
        "shardId": 0,
        "nonce": 54321,
        "round": 12345,
        "epoch": 678,
        "txCount": 5000,
        "executedTxCount": 4950,
        "timestampMs": 1738800000000,
        "leaderSignatureHex": "0x...",
        "accumulatedFees": "1234567890000000000",
        "developerFees": "123456789000000000"
      },
      "latestMeta": {
        "nonce": 54321,
        "round": 12345,
        "epoch": 678,
        "txCount": 15000,
        "executedTxCount": 14850,
        "timestampMs": 1738800000000
      },
      "blockTimeMsP50ByShard": {
        "0": 6250,
        "1": 6200,
        "2": 6300
      },
      "nonceGapEvents1m": 0,
      "duplicateNonceEvents1m": 0
    },
    "mempool": {
      "estimatedQueue": 500,
      "ingressTps": 3000,
      "inclusionTps": 2500,
      "pressure": 0.167
    },
    "validators": {
      "onlineByShard": {
        "0": 11,
        "1": 11,
        "2": 10,
        "meta": 0
      },
      "totalOnline": 32,
      "heartbeatRatePerSec": 0.53
    },
    "health": {
      "p2pDedupRatio1m": 0.02,
      "streamSubscribers": 45,
      "dataCompleteness": 0.95
    }
  }
}
```

***

## Field Descriptions

### Top-Level Envelope

| Field           | Type   | Description                                                                          |
| --------------- | ------ | ------------------------------------------------------------------------------------ |
| `type`          | string | Always `"networkStats"`                                                              |
| `schemaVersion` | string | Semantic version of the message schema. See [Schema Versioning](#schema-versioning). |
| `sequence`      | number | Monotonically increasing counter per connection. Use to detect missed messages.      |
| `ts`            | number | Server timestamp in milliseconds (Unix epoch) when the snapshot was assembled        |
| `data`          | object | Network state payload                                                                |

### data.network

| Field              | Type   | Description                                                                                |
| ------------------ | ------ | ------------------------------------------------------------------------------------------ |
| `currentTps`       | number | Transactions per second executed in the most recent block across all shards                |
| `avgTps10s`        | number | Rolling average TPS over the last 10 seconds                                               |
| `avgTps30s`        | number | Rolling average TPS over the last 30 seconds                                               |
| `connectedPeers`   | number | Total P2P peers connected to the relayer node                                              |
| `activeValidators` | number | Number of validators actively participating in consensus                                   |
| `wsLagMs`          | number | Internal propagation latency from block observation to WebSocket delivery, in milliseconds |

### data.blocks.latestShard

The most recent finalized shard block observed by the relayer.

| Field                | Type   | Description                                                    |
| -------------------- | ------ | -------------------------------------------------------------- |
| `shardId`            | number | Shard identifier of the block                                  |
| `nonce`              | number | Block nonce (height)                                           |
| `round`              | number | Consensus round number                                         |
| `epoch`              | number | Epoch number                                                   |
| `txCount`            | number | Total transactions included in the block                       |
| `executedTxCount`    | number | Transactions successfully executed (excludes failed/invalid)   |
| `timestampMs`        | number | Block timestamp in milliseconds                                |
| `leaderSignatureHex` | string | Hex-encoded signature of the block proposer                    |
| `accumulatedFees`    | string | Total transaction fees collected in atomic EGLD units          |
| `developerFees`      | string | Developer fee portion of accumulated fees in atomic EGLD units |

### data.blocks.latestMeta

The most recent finalized metachain block. Fields are the same as `latestShard` but without `leaderSignatureHex`, `accumulatedFees`, and `developerFees`.

### data.blocks (additional)

| Field                    | Type   | Description                                                                                                                   |
| ------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `blockTimeMsP50ByShard`  | object | Median block time in milliseconds for each shard over the last 60 seconds. Keys are `"0"`, `"1"`, `"2"`.                      |
| `nonceGapEvents1m`       | number | Number of times a shard block nonce was skipped (missed block) in the last minute. Non-zero values indicate validator issues. |
| `duplicateNonceEvents1m` | number | Number of duplicate block nonce events in the last minute. Indicates a fork or consensus anomaly.                             |

### data.mempool

| Field            | Type   | Description                                                                                                                                           |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `estimatedQueue` | number | Estimated number of transactions currently waiting for inclusion across all shards                                                                    |
| `ingressTps`     | number | Rate at which new transactions are arriving at the relayer (transactions per second)                                                                  |
| `inclusionTps`   | number | Rate at which transactions are being included in blocks (transactions per second)                                                                     |
| `pressure`       | number | Ratio of queue growth to inclusion rate: `(ingressTps - inclusionTps) / ingressTps`. Values approaching `1.0` indicate the network is falling behind. |

### data.validators

| Field                 | Type   | Description                                                                |
| --------------------- | ------ | -------------------------------------------------------------------------- |
| `onlineByShard`       | object | Count of online validators per shard. Keys: `"0"`, `"1"`, `"2"`, `"meta"`. |
| `totalOnline`         | number | Sum of all online validators across shards                                 |
| `heartbeatRatePerSec` | number | Average rate of validator heartbeat messages received per second           |

### data.health

| Field               | Type   | Description                                                                                                                                    |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `p2pDedupRatio1m`   | number | Fraction of P2P gossip messages that were duplicates in the last minute. High values indicate gossip amplification or topology issues.         |
| `streamSubscribers` | number | Current number of clients connected to the `/ws/stats` stream                                                                                  |
| `dataCompleteness`  | number | Fraction of expected data fields populated in this snapshot (0.0–1.0). Values below `1.0` indicate partial data due to a slow upstream source. |

***

## Schema Versioning

The `schemaVersion` field uses semantic versioning (`MAJOR.MINOR.PATCH`):

* **MAJOR** increments on breaking changes (field removals, type changes, structural reorganization).
* **MINOR** increments when new fields are added in a backward-compatible way.
* **PATCH** increments for documentation or metadata corrections.

Check `schemaVersion` on connection and log a warning if the major version exceeds what your client expects. New minor-version fields appear as `null` or are absent on older relayer deployments.

{% hint style="info" %}
The current schema version is `1.1.0`. Check `schemaVersion` in your client and alert when it changes to avoid silent breakage.
{% endhint %}

***

## Example: Network Dashboard

```javascript
class NetworkDashboard {
  constructor() {
    this.latest = null;
    this.sequence = 0;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket('wss://relayer.xoxno.com/ws/stats');

    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.type !== 'networkStats') return;

      // Detect missed messages
      if (this.sequence > 0 && msg.sequence !== this.sequence + 1) {
        console.warn(`Sequence gap: expected ${this.sequence + 1}, got ${msg.sequence}`);
      }
      this.sequence = msg.sequence;
      this.latest = msg;
      this.render(msg);
    };

    this.ws.onclose = () => {
      console.log('Stats stream closed, reconnecting in 2s');
      setTimeout(() => this.connect(), 2000);
    };
  }

  render(msg) {
    const { network, blocks, mempool, validators, health } = msg.data;

    console.log('--- Network Stats ---');
    console.log(`TPS: ${network.currentTps} (10s avg: ${network.avgTps10s})`);
    console.log(`Peers: ${network.connectedPeers} | Validators: ${validators.totalOnline}`);
    console.log(`Mempool queue: ${mempool.estimatedQueue} | Pressure: ${(mempool.pressure * 100).toFixed(1)}%`);
    console.log(`Latest shard block: #${blocks.latestShard.nonce} (shard ${blocks.latestShard.shardId})`);
    console.log(`Data completeness: ${(health.dataCompleteness * 100).toFixed(0)}%`);
    console.log(`WS lag: ${network.wsLagMs}ms`);
  }

  isHealthy() {
    if (!this.latest) return false;
    const { health, blocks } = this.latest.data;
    return (
      health.dataCompleteness >= 0.95 &&
      blocks.nonceGapEvents1m === 0 &&
      blocks.duplicateNonceEvents1m === 0
    );
  }

  getMempoolPressure() {
    return this.latest?.data.mempool.pressure ?? 0;
  }
}

const dashboard = new NetworkDashboard();
```

***

## Use Cases

* **Real-time dashboards** — Display TPS, validator count, block times, and mempool depth.
* **Mempool monitoring** — Track `mempool.pressure` to detect backlog buildup and delay non-urgent transactions.
* **Validator health alerting** — Alert when `nonceGapEvents1m > 0` or `duplicateNonceEvents1m > 0`.
* **Transaction timing** — Submit transactions when `mempool.pressure` is low for faster inclusion.
* **Relayer health monitoring** — Use `health.dataCompleteness` and `health.p2pDedupRatio1m` to verify data feed quality.
* **Block time SLAs** — Use `blockTimeMsP50ByShard` to confirm shards are producing blocks within expected intervals.

***

## Related Pages

* [Gas Statistics](https://docs.xoxno.com/developers/relayer-api/gas-stats) — Per-shard gas price and PPU
* [Account Subscriptions](https://docs.xoxno.com/developers/relayer-api/account-subscriptions) — Address-level balance and nonce updates
* [Error Reference](https://docs.xoxno.com/developers/relayer-api/error-reference) — WebSocket error codes