Overview

This document specifies the Networking gRPC service for inspecting and managing peer connectivity in Seed’s daemon. It exposes read-only discovery (peer info, listings) and an explicit connect RPC to attempt direct links to peers via supplied multiaddrs.

Goals

Provide a simple API to inspect known peers (ids, addresses, connection state, metadata).

Support paginated listings of peers for diagnostics and UIs.

Allow clients to explicitly attempt connections when background discovery is insufficient.

Non‑Goals

Implementing the DHT, relay, or NAT traversal protocols themselves (delegated to libp2p stack).

Peer authentication/session negotiation beyond exposing resulting state.

Bulk mutation of peer stores (add/remove) beyond Connect attempt.

Protocol Definition


syntax = "proto3";

package com.seed.networking.v1alpha;

import "google/protobuf/timestamp.proto";

option go_package = "seed/backend/genproto/networking/v1alpha;networking";

// Networking API service of the Seed daemon.
service Networking {
  // Lookup details about a known peer.
  rpc GetPeerInfo(GetPeerInfoRequest) returns (PeerInfo);

  // List peers by status.
  rpc ListPeers(ListPeersRequest) returns (ListPeersResponse);

  // Establishes a direct connection with a given peer explicitly.
  rpc Connect(ConnectRequest) returns (ConnectResponse);
}

// Request to get peer's addresses.
message GetPeerInfoRequest {
  // Required. CID-encoded Peer ID (a.k.a. Device ID).
  string device_id = 1;
}

// Request to get peer's addresses.
message ListPeersRequest {
  // Optional. Number of results per page. Default is defined by the server.
  int32 page_size = 1;

  // Optional. Value from next_page_token obtains from a previous response.
  string page_token = 2;
}

// Various details about a list of peers.
message ListPeersResponse {
  // List of known Hyper Media peers.
  repeated PeerInfo peers = 1;

  // Token for the next page if there're more results.
  string next_page_token = 2;
}

// Request for connecting to a peer explicitly.
message ConnectRequest {
  // A list of multiaddrs for the same peer ID to attempt p2p connection.
  // For example `/ip4/10.0.0.1/tcp/55000/p2p/QmDeadBeef`.
  repeated string addrs = 1;
}

// Response for conneting to a peer.
message ConnectResponse {}

// Various details about a known peer.
message PeerInfo {
  // Libp2p peer ID.
  string id = 1;

  // Account ID that this peer is bound to.
  string account_id = 2;

  // List of known multiaddrs of the request peer.
  repeated string addrs = 3;

  // Connection status of our node with a remote peer.
  ConnectionStatus connection_status = 4;

  // Whether this peer was a direct connection or someone else shared it with us.
  bool is_direct = 5;

  // When we first inserted that peer in the database.
  google.protobuf.Timestamp created_at = 6;

  // When the peer updated its addresses for the last time.
  google.protobuf.Timestamp updated_at = 7;

  // Seed protocol version the peer talks.
  string protocol = 9;
}

// Indicates connection status of our node with a remote peer.
// Mimics libp2p connectedness.
enum ConnectionStatus {
  // NotConnected means no connection to peer, and no extra information (default).
  NOT_CONNECTED = 0;

  // Connected means has an open, live connection to peer.
  CONNECTED = 1;

  // CanConnect means recently connected to peer, terminated gracefully.
  CAN_CONNECT = 2;

  // CannotConnect means recently attempted connecting but failed to connect.
  // (should signal "made effort, failed").
  CANNOT_CONNECT = 3;

  // Limited means we have a transient connection to the peer, but aren't fully connected.
	LIMITED = 4;
}