GRPC Documentation - PeerService

p2p_api.proto

Package p2p_api defines the gRPC service interface for P2P networking operations including peer management, banning, catchup tracking, and reputation management.

AddBanScoreRequest

Represents a request to add a ban score to a peer.

Field	Type	Label	Description
peer_id	string		The peer ID to add ban score to
reason	string		Reason for adding the ban score

AddBanScoreResponse

Represents the response from adding a ban score.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

BanPeerRequest

Represents a request to ban a peer.

Field	Type	Label	Description
addr	string		The address of the peer to ban
until	int64		Unix timestamp indicating when the ban expires

BanPeerResponse

Represents the response from banning a peer.

Field	Type	Label	Description
ok	bool		Indicates whether the ban operation succeeded

ClearBannedResponse

Represents the response from clearing all banned peers.

Field	Type	Label	Description
ok	bool		Indicates whether the clear operation succeeded

ConnectPeerRequest

Represents a request to connect to a peer.

Field	Type	Label	Description
peer_address	string		The peer address in multiaddr format (e.g., /ip4/127.0.0.1/tcp/9005/p2p/12D3KooW...)

ConnectPeerResponse

Represents the response from connecting to a peer.

Field	Type	Label	Description
success	bool		Indicates whether the connection succeeded
error	string		Error message if the connection failed

DisconnectPeerRequest

Represents a request to disconnect from a peer.

Field	Type	Label	Description
peer_id	string		The peer ID to disconnect from

DisconnectPeerResponse

Represents the response from disconnecting from a peer.

Field	Type	Label	Description
success	bool		Indicates whether the disconnection succeeded
error	string		Error message if the disconnection failed

GetPeerRegistryResponse

Represents the response containing comprehensive peer registry data.

Field	Type	Label	Description
peers	PeerRegistryInfo	repeated	List of all peers with full registry metadata

GetPeerRequest

Represents a request to get information about a specific peer.

Field	Type	Label	Description
peer_id	string		The peer ID to query

GetPeerResponse

Represents the response containing information about a specific peer.

Field	Type	Label	Description
peer	PeerRegistryInfo		Peer information (null/empty if peer not found)
found	bool		Indicates whether the peer was found

GetPeersForCatchupRequest

Represents a request to get peers suitable for catchup operations.

This message is currently empty but can be extended with filtering parameters in the future.

GetPeersForCatchupResponse

Represents the response containing peers suitable for catchup.

Field	Type	Label	Description
peers	PeerInfoForCatchup	repeated	List of peers with catchup-relevant information

GetPeersResponse

Represents the response containing all connected peers.

Field	Type	Label	Description
peers	Peer	repeated	List of all connected peers

IsBannedRequest

Represents a request to check if an IP or subnet is banned.

Field	Type	Label	Description
ipOrSubnet	string		The IP address or subnet to check

IsBannedResponse

Represents the response indicating whether an IP or subnet is banned.

Field	Type	Label	Description
isBanned	bool		Indicates whether the IP or subnet is banned

IsPeerMaliciousRequest

Represents a request to check if a peer is considered malicious.

Field	Type	Label	Description
peer_id	string		The peer ID to check

IsPeerMaliciousResponse

Represents the response indicating whether a peer is malicious.

Field	Type	Label	Description
is_malicious	bool		Indicates whether the peer is considered malicious
reason	string		Optional reason why the peer is considered malicious

IsPeerUnhealthyRequest

Represents a request to check if a peer is unhealthy.

Field	Type	Label	Description
peer_id	string		The peer ID to check

IsPeerUnhealthyResponse

Represents the response indicating whether a peer is unhealthy.

Field	Type	Description
is_unhealthy	bool	Indicates whether the peer is considered unhealthy
reason	string	Optional reason why the peer is considered unhealthy
reputation_score	float	Current reputation score of the peer

ListBannedResponse

Represents the response containing all banned addresses.

Field	Type	Label	Description
banned	string	repeated	List of all banned IP addresses or subnets

Peer

Represents detailed information about a connected peer.

Field	Type	Description
id	string	Peer identifier
addr	string	Remote address (host:port)
addrLocal	string	Local address used for this connection
services	string	Services supported by the peer
lastSend	int64	Time of last message sent (seconds since epoch)
lastRecv	int64	Time of last message received (seconds since epoch)
sendSize	int64	Size of send buffer
recvSize	int64	Size of receive buffer
sendMemory	int64	Memory used by send buffer
pauseSend	bool	Whether sending is paused
unpauseSend	bool	Whether sending is unpaused
bytesSent	uint64	Total bytes sent to this peer
bytesReceived	uint64	Total bytes received from this peer
avgRecvBandwidth	int64	Average receive bandwidth
assocId	string	Association identifier
streamPolicy	string	Stream policy used for this connection
inbound	bool	Whether this is an inbound connection
connTime	int64	Connection time (seconds since epoch)
pingTime	int64	Last ping time in microseconds
timeOffset	int64	Time offset from this peer
version	uint32	Protocol version of the peer
subVer	string	User agent string of the peer
startingHeight	uint32	Block height when connection was established
currentHeight	uint32	Current block height of the peer
banscore	int32	Ban score of this peer
whitelisted	bool	Whether this peer is whitelisted
feeFilter	int64	Minimum fee filter for transactions

PeerInfoForCatchup

Represents peer information relevant for catchup operations.

Field	Type	Description
id	string	Peer identifier
height	uint32	Current block height of the peer
block_hash	string	Hash of the peer's current block
data_hub_url	string	URL of the peer's data hub service
catchup_reputation_score	double	Reputation score for catchup operations
catchup_attempts	int64	Number of catchup attempts with this peer
catchup_successes	int64	Number of successful catchup operations
catchup_failures	int64	Number of failed catchup operations

PeerRegistryInfo

Represents comprehensive peer information with all registry metadata.

Field	Type	Description
id	string	Peer identifier
height	uint32	Current block height of the peer
block_hash	string	Hash of the peer's current block
data_hub_url	string	URL of the peer's data hub service
ban_score	int32	Ban score of this peer
is_banned	bool	Whether the peer is currently banned
is_connected	bool	Whether the peer is currently connected
connected_at	int64	Connection time (Unix timestamp)
bytes_received	uint64	Total bytes received from this peer
last_block_time	int64	Time of last block received (Unix timestamp)
last_message_time	int64	Time of last message received (Unix timestamp)
interaction_attempts	int64	Number of interaction attempts
interaction_successes	int64	Number of successful interactions
interaction_failures	int64	Number of failed interactions
last_interaction_attempt	int64	Time of last interaction attempt (Unix timestamp)
last_interaction_success	int64	Time of last successful interaction (Unix timestamp)
last_interaction_failure	int64	Time of last failed interaction (Unix timestamp)
reputation_score	double	Overall reputation score
malicious_count	int64	Number of times peer was flagged as malicious
avg_response_time_ms	int64	Average response time in milliseconds
storage	string	Storage type used by the peer
client_name	string	Human-readable name of the client software
last_catchup_error	string	Last error message from catchup attempt
last_catchup_error_time	int64	Time of last catchup error (Unix timestamp)

RecordBytesDownloadedRequest

Represents a request to record bytes downloaded from a peer via HTTP.

Field	Type	Label	Description
peer_id	string		Peer ID that provided the data
bytes_downloaded	uint64		Number of bytes downloaded

RecordBytesDownloadedResponse

Represents the response from recording bytes downloaded.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

RecordCatchupAttemptRequest

Represents a request to record a catchup attempt with a peer.

Field	Type	Label	Description
peer_id	string		Peer ID for the catchup attempt

RecordCatchupAttemptResponse

Represents the response from recording a catchup attempt.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

RecordCatchupFailureRequest

Represents a request to record a failed catchup attempt.

Field	Type	Label	Description
peer_id	string		Peer ID for the failed catchup

RecordCatchupFailureResponse

Represents the response from recording a catchup failure.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

RecordCatchupMaliciousRequest

Represents a request to record a malicious catchup attempt.

Field	Type	Label	Description
peer_id	string		Peer ID flagged as malicious

RecordCatchupMaliciousResponse

Represents the response from recording a malicious catchup.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

RecordCatchupSuccessRequest

Represents a request to record a successful catchup.

Field	Type	Label	Description
peer_id	string		Peer ID for the successful catchup
duration_ms	int64		Duration of the catchup in milliseconds

RecordCatchupSuccessResponse

Represents the response from recording a catchup success.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

ReportValidBlockRequest

Represents a request to report reception of a valid block from a peer.

Field	Type	Label	Description
peer_id	string		Peer ID that provided the block
block_hash	string		Hash of the valid block

ReportValidBlockResponse

Represents the response from reporting a valid block.

Field	Type	Label	Description
success	bool		Indicates whether the report was successful
message	string		Optional message about the result

ReportValidSubtreeRequest

Represents a request to report reception of a valid subtree from a peer.

Field	Type	Label	Description
peer_id	string		Peer ID that provided the subtree
subtree_hash	string		Hash of the valid subtree

ReportValidSubtreeResponse

Represents the response from reporting a valid subtree.

Field	Type	Label	Description
success	bool		Indicates whether the report was successful
message	string		Optional message about the result

ResetReputationRequest

Represents a request to reset reputation scores for peers.

Field	Type	Label	Description
peer_id	string		Peer ID to reset (empty string means reset all peers)

ResetReputationResponse

Represents the response from resetting reputation scores.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded
peers_reset	int32		Number of peers whose reputation was reset

UnbanPeerRequest

Represents a request to unban a peer.

Field	Type	Label	Description
addr	string		The address of the peer to unban

UnbanPeerResponse

Represents the response from unbanning a peer.

Field	Type	Label	Description
ok	bool		Indicates whether the unban operation succeeded

UpdateCatchupErrorRequest

Represents a request to update the catchup error message for a peer.

Field	Type	Label	Description
peer_id	string		Peer ID to update
error_msg	string		Error message to record

UpdateCatchupErrorResponse

Represents the response from updating a catchup error.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

UpdateCatchupReputationRequest

Represents a request to update the catchup reputation score for a peer.

Field	Type	Label	Description
peer_id	string		Peer ID to update
score	double		Reputation score between 0-100

UpdateCatchupReputationResponse

Represents the response from updating catchup reputation.

Field	Type	Label	Description
ok	bool		Indicates whether the operation succeeded

PeerService

Service provides methods for P2P peer management, including connection handling, ban management, catchup tracking, and reputation management.

Method Name	Request Type	Response Type	Description
GetPeers	.google.protobuf.Empty	GetPeersResponse	Retrieves a list of all connected peers with their detailed information.
BanPeer	BanPeerRequest	BanPeerResponse	Bans a peer by address until the specified time.
UnbanPeer	UnbanPeerRequest	UnbanPeerResponse	Removes a ban for a peer address.
IsBanned	IsBannedRequest	IsBannedResponse	Checks if an IP address or subnet is currently banned.
ListBanned	.google.protobuf.Empty	ListBannedResponse	Lists all currently banned addresses.
ClearBanned	.google.protobuf.Empty	ClearBannedResponse	Clears all banned addresses.
AddBanScore	AddBanScoreRequest	AddBanScoreResponse	Adds a ban score to a peer. Peers with high ban scores may be automatically banned.
ConnectPeer	ConnectPeerRequest	ConnectPeerResponse	Initiates a connection to a peer using multiaddr format.
DisconnectPeer	DisconnectPeerRequest	DisconnectPeerResponse	Disconnects from a peer by peer ID.
RecordCatchupAttempt	RecordCatchupAttemptRequest	RecordCatchupAttemptResponse	Records an attempt to perform catchup with a peer. Used for reputation tracking.
RecordCatchupSuccess	RecordCatchupSuccessRequest	RecordCatchupSuccessResponse	Records a successful catchup operation including duration. Improves peer reputation.
RecordCatchupFailure	RecordCatchupFailureRequest	RecordCatchupFailureResponse	Records a failed catchup operation. Negatively affects peer reputation.
RecordCatchupMalicious	RecordCatchupMaliciousRequest	RecordCatchupMaliciousResponse	Records a malicious catchup attempt by a peer. Severely damages peer reputation.
UpdateCatchupReputation	UpdateCatchupReputationRequest	UpdateCatchupReputationResponse	Updates the catchup reputation score for a peer (0-100).
UpdateCatchupError	UpdateCatchupErrorRequest	UpdateCatchupErrorResponse	Records an error message from a catchup attempt for debugging.
ResetReputation	ResetReputationRequest	ResetReputationResponse	Resets reputation scores for a peer or all peers.
GetPeersForCatchup	GetPeersForCatchupRequest	GetPeersForCatchupResponse	Retrieves peers that are suitable for catchup operations with their reputation scores.
ReportValidSubtree	ReportValidSubtreeRequest	ReportValidSubtreeResponse	Reports reception of a valid subtree from a peer. Improves peer reputation.
ReportValidBlock	ReportValidBlockRequest	ReportValidBlockResponse	Reports reception of a valid block from a peer. Improves peer reputation.
IsPeerMalicious	IsPeerMaliciousRequest	IsPeerMaliciousResponse	Checks if a peer is flagged as malicious and returns the reason if so.
IsPeerUnhealthy	IsPeerUnhealthyRequest	IsPeerUnhealthyResponse	Checks if a peer is considered unhealthy based on reputation score and interaction history.
GetPeerRegistry	.google.protobuf.Empty	GetPeerRegistryResponse	Retrieves comprehensive information about all peers with full registry metadata.
RecordBytesDownloaded	RecordBytesDownloadedRequest	RecordBytesDownloadedResponse	Records bytes downloaded via HTTP from a peer for bandwidth tracking.
GetPeer	GetPeerRequest	GetPeerResponse	Retrieves comprehensive information about a single peer by peer ID.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)