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.

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;
}