SupernodeService gRPC reference

SupernodeService is a gRPC service exposed by every Lumera SuperNode. It gives you a real-time snapshot of the node’s health. The snapshot covers software version, uptime, CPU and memory load, and connected peers. When you opt in, it also includes detailed DHT diagnostics. You can use this service to build monitoring dashboards, alerting pipelines, or operational tooling without any on-chain queries.

Connection

SuperNodes listen on port 4444 by default. Set supernode.port in config.yml to change it. Port 4444 runs Lumera’s own secure handshake, which checks the peer identity against on-chain state. Plain grpcurl cannot reach it. A plaintext dial opens the socket and then times out resolving the service descriptor. A TLS dial fails to connect. The service does not register gRPC reflection either. To check that a node is alive, call its HTTP gateway on port 8002.

curl http://localhost:8002/api/v1/status

Add ?include_p2p_metrics=true to that request for DHT diagnostics. To call SupernodeService itself, use a client that performs the Lumera handshake, such as the supernode Go SDK. Read the gRPC snippets on this page as message shapes rather than commands you can paste.

Proto definition

service SupernodeService {
  rpc GetStatus(StatusRequest) returns (StatusResponse);
}

GetStatus

Returns a point-in-time status snapshot of the SuperNode. The request lets you toggle expensive P2P diagnostics on or off, so routine polling stays lightweight.

Request message `StatusRequest`

bool

default:"false"

When true, the response includes the full p2p_metrics object containing DHT store/retrieve history, handle counters, ban list, database stats, and disk usage. Set this to false (or omit it) for routine health polling. The peers_count field is always fast and is returned regardless of this flag. Heavier diagnostics are served from a cached last-known-good snapshot.

Response message `StatusResponse`

string

The SuperNode software version string (e.g., "v2.5.2").

uint64

Seconds elapsed since the SuperNode process started.

object

Hardware resource utilisation at the time of the call.

Show resources fields

object

Show cpu fields

double

Current CPU utilisation across all cores, expressed as a percentage (0 to 100).

int32

Number of logical CPU cores available to the process.

object

Show memory fields

double

Total physical memory installed, in GB.

double

Memory currently in use, in GB.

double

Memory available to new allocations, in GB.

double

Memory utilisation as a percentage (0 to 100).

array of objects

Storage volumes monitored by the SuperNode. Currently the array contains one entry. That entry is the filesystem that hosts the configured base directory (--basedir).

Show storage_volumes item fields

string

Filesystem mount path being reported (e.g., "/").

uint64

Total capacity of the volume in bytes.

uint64

Bytes currently consumed on the volume.

uint64

Bytes available for new writes.

double

Volume utilisation as a percentage (0 to 100).

string

Human-readable summary of the node’s hardware profile (e.g., "8 cores / 32GB RAM").

array of strings

The service names this SuperNode is registered to provide. This is typically ["cascade", "sense"] or a subset of it.

object

P2P network connectivity information.

Show network fields

int32

Number of peers currently connected in the P2P network. The whole network object, this field included, is returned only when include_p2p_metrics is true.

array of strings

List of connected peer addresses in "ID@IP:Port" format.

int32

This node’s rank in the top-SuperNodes list as computed by the chain. Returns 0 if the node is not currently in the top list.

string

The publicly-advertised IP address and service port of this SuperNode (e.g., "203.0.113.45:4444").

object

Detailed P2P and DHT diagnostics. Only present when include_p2p_metrics is true.

Show p2p_metrics fields

object

Recent DHT operation history.

Show dht_metrics fields

array of objects

Recent DHT store-operation data points. Each entry includes time_unix (epoch seconds), requests (total node RPCs attempted), successful (successful node RPCs), and success_rate (percentage 0 to 100).

array of objects

Recent batch-retrieval data points. Each entry includes time_unix, keys (keys requested), required, found_local, found_network, and duration_ms.

int64

Number of times a hot-path request was skipped because the target was banned.

int64

Number of times a ban counter was incremented on the hot path.

map<string, HandleCounters>

Per-handler RPC counters. Each HandleCounters value contains total, success, failure, and timeout int64 fields.

map<string, int64>

Connection pool statistics keyed by metric name.

array of objects

Peers currently banned by this node. Each entry contains id, ip, port (uint32), count (ban increment count), created_at_unix, and age_seconds.

object

P2P key-value database stats, containing p2p_db_size_mb (double) and p2p_db_records_count (int64).

object

Disk usage for the P2P data directory, reported as all_mb, used_mb, and free_mb (all double).

Example response

{
  "version": "v2.5.2",
  "uptime_seconds": 86400,
  "resources": {
    "cpu": { "usage_percent": 12.5, "cores": 8 },
    "memory": {
      "total_gb": 64,
      "used_gb": 12.3,
      "available_gb": 51.7,
      "usage_percent": 19.2
    },
    "storage_volumes": [
      {
        "path": "/",
        "total_bytes": 2000398934016,
        "used_bytes": 480374956032,
        "available_bytes": 1520023977984,
        "usage_percent": 24.0
      }
    ],
    "hardware_summary": "8-core CPU, 64GB RAM, 2TB storage"
  },
  "registered_services": ["cascade", "sense"],
  "network": {
    "peers_count": 15,
    "peer_addresses": [
      "12D3KooWExample1@203.0.113.10:4445",
      "12D3KooWExample2@203.0.113.20:4445"
    ]
  },
  "rank": 3,
  "ip_address": "203.0.113.45:4444"
}

Full example with P2P metrics

Set include_p2p_metrics to true to receive DHT diagnostics alongside the standard fields. Over the HTTP gateway the same request looks like this.

curl "http://localhost:8002/api/v1/status?include_p2p_metrics=true"

REST API

RPC

gRPC API

Libraries and tools

SupernodeService gRPC reference

Connection

Proto definition

GetStatus

Request message `StatusRequest`

Response message `StatusResponse`

Example response

Full example with P2P metrics

​Connection

​Proto definition

​GetStatus

​Request message StatusRequest

​Response message StatusResponse

​Example response

​Full example with P2P metrics

Connection

Proto definition

GetStatus

Request message `StatusRequest`

Response message `StatusResponse`

Example response

Full example with P2P metrics