Peer Scoring

Peer scoring is a local operational defense layer. It affects sync, gossip, and payload-backfill transport decisions for this node only.

It is not consensus logic. It does not remove validators, change validator voting power, rewrite finalized blocks, or change protocol state. Future Raft, OpenBFT, or CometBFT integrations must keep this boundary: consensus membership and validator suspension are protocol/governance decisions, not local reputation decisions.

Statuses

• healthy: normal transport participation.
• degraded: peer remains usable, but recent behavior was poor.
• quarantined: peer transport is disabled locally until operator recovery.
• banned: stronger manual operator block; unban/reset is required before use.

Quarantine and ban disable the corresponding trusted peer transport locally.

Default Policy

Initial score is 100.

Positive events:

• sync_success: +1
• gossip_success: +1
• payload_backfill_success: +1
• raft_message_success: +1

Negative events:

• timeout: -5
• http_error: -5
• sync_failure: -10
• payload_backfill_failure: -10
• malformed_head_response: -20
• malformed_block_response: -25
• gossip_auth_failure: -25
• gossip_invalid_transaction: -20
• raft_message_timeout: -5
• raft_message_http_error: -5
• raft_message_auth_failure: -25
• merkle_root_mismatch: -40
• block_hash_mismatch: -50
• state_root_mismatch: -50
• finalized_conflict: -100

Thresholds:

• score >= 70: healthy
• score >= 40: degraded
• score < 40: quarantined

finalized_conflict immediately quarantines and the conflict layer may also enter incident mode. Manual ban always sets status to banned.

Storage

Local tables:

• peer_scores: current score and status per trusted peer.
• peer_score_events: append-only local event history.

These tables are local operational metadata and are not consensus state.

APIs

Peer scoring, peer configuration, conflicts, and incidents are operator APIs. They use the same node-operator bearer-token guard as /node/observability/*: send Authorization: Bearer <NOOS_OPERATOR_TOKEN>. Outside production, when NOOS_OPERATOR_TOKEN is not set, the built-in development token is dev-operator-token.

Protected operator APIs:

• GET /peers
• POST /peers
• POST /peers/:peerId/disable
• GET /peers/scores
• GET /peers/:peerId/score
• GET /peers/:peerId/score/events
• POST /peers/:peerId/quarantine
• POST /peers/:peerId/unquarantine
• POST /peers/:peerId/ban
• POST /peers/:peerId/unban
• POST /peers/:peerId/score/reset
• GET /chain/conflicts
• GET /chain/incidents/active
• POST /chain/incidents/:id/resolve

GET /peers includes score and scoreStatus when peer scoring rows exist.

Transport Effects

Sync manager skips disabled trusted peers and peers whose local score status is quarantined or banned. For the remaining eligible peers, it prefers healthy higher-scoring peers before degraded lower-scoring peers. It still attempts each eligible peer in order during a run: this preserves payload recovery when the best block-sync peer is valid for blocks but does not have ciphertext bytes for a bucket this node is allowed to store.

Payload backfill skips quarantined/banned peers unless explicitly forced by an operator path. Gossip does not send outbound transactions to quarantined/banned peers, and inbound gossip from those peers is rejected by node-auth checks.

Raft HTTP transport records local scoring events for successful messages, timeouts, HTTP errors, and auth failures when the configured Raft peer is linked to a trusted_peers id. These scores are operational transport defense only: they do not remove validators, change voting power, or alter committed Raft log entries. Raft/OpenBFT/CometBFT membership changes remain future consensus or governance logic.

Validator Governance Boundary

Validator status and voting power are consensus state controlled by validator governance transactions. A local peer ban or quarantine can stop this node from using a peer for transport, but it does not suspend, retire, or remove the validator from governance state.

Not Implemented

• shared peer reputation
• validator slashing
• peer-score-driven validator suspension/removal
• peer-score-driven voting-power changes
• peer scoring as consensus evidence
• automatic disaster recovery