Feat/nmv3 agents subscription

[jstuczyn]

NR-759

Nym node chain watcher and network monitors agents bypass

Summary

This PR introduces real-time blockchain monitoring for network monitor agent authorizations and implements replay protection bypass for authorized network monitor (NM) agents. This allows NM agents to perform node stress testing, while maintaining security for regular traffic.

Key Changes

1. Real-Time Blockchain Subscription for Network Monitor Agents

• New Module: nym-node/src/node/nyxd_watcher/network_monitor_agents.rs

  • Implements MsgModule trait to watch for Network Monitors smart contract messages
  • Automatically updates authorized NM agent list when AuthoriseNetworkMonitor, RevokeNetworkMonitor, or RevokeAllNetworkMonitors messages are executed on-chain

• Integration: Websocket subscription to nyx blockchain using the enhanced nyxd-scraper framework

  • Real-time updates without polling overhead
  • Survives transient network failures with automatic reconnection

2. Replay Protection Bypass for Authorized Network Monitors

• Implementation Location: nym-node/src/node/mixnet/handler.rs
  • Checks if replayed packet originates from an authorized NM agent IP
  • Allows NM agents to bypass replay detection while enforcing it for all other traffic
  • Maintains per-connection authorization check via is_from_authorised_network_monitor_agent()

3. Enhanced Prometheus Metrics

• New/Fixed Metrics:
  • ingress_replayed_packet() - Now properly tracked when replay detection triggers
  • ingress_network_monitor_packet() - Counts packets from authorized NM agents

Technical Details

Packet Journey for Replay Protection

handle_received_nym_packet()
  ↓
handle_received_packet_with_replay_detection()
  ↓
try_partially_unwrap_packet() [derive secrets, check MAC]
  ↓
batch_check_and_set() [bloomfilter replay detection]
  ↓
handle_post_replay_detection_packets()
  ↓
if replayed && !is_from_authorised_network_monitor_agent():
    → drop packet + increment metrics
else:
    → finalise_unwrapping() + forward packet

Authorization Flow

Contract ExecuteMsg::AuthoriseNetworkMonitor { address: IpAddr }
  ↓
Blockchain transaction committed
  ↓
NetworkMonitorAgentsModule receives message via MsgModule
  ↓
DeclaredNetworkMonitors.add_known(address)
  ↓
ArcSwap updates live filter (lock-free)
  ↓
ConnectionHandler checks is_from_authorised_network_monitor_agent()

Testing Considerations

• Network monitor agents can now intentionally send replayed packets for testing
• Operators can monitor NM activity via new Prometheus metrics
• Real-time authorization updates without node restarts

Breaking Changes

None - fully backward compatible with existing configurations.

Security Implications

• Authorization is on-chain and requires execute privileges
• Only specific IP addresses can bypass replay protection
• All bypass activity is logged and metrics-tracked
• Operators should monitor ingress_network_monitor_packet metric for unexpected activity

Related Issues

• Depends on: Network Monitors smart contract deployment (Feat/nmv3 agents contract #6555)

---

This change is 

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nym-explorer-v2	Ready	Preview, Comment	Apr 23, 2026 0:20am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs-nextra	Ignored	Preview	Apr 23, 2026 0:20am
nym-node-status	Ignored	Preview	Apr 23, 2026 0:20am

[simonwicky]

That's not a compare and swap, if by any chance two threads arrive at the same time, the first update will be lost

[jstuczyn]

which is not a problem because there is only ever one thread performing writes to the list of known addresses. the arcswap exists here for the purposes of lock-free reads and eventual consistency

[simonwicky]

Can we then update the comment about it being thread-safe?

[simonwicky]

If the pending addresses are already resolve, we might want to clear them no?

[simonwicky]

This might not be enough, IP addresses can be spoofed

[simonwicky]

Actually not, as the update is not a compare and swap. Badly timed updates will overwrite each other. See comment in network_filter.rs

[jstuczyn]

as I mentioned there's only a single writer thread, so it's fine. the module wasn't designed with multiple writers in mind