Skip to main content

nautilus_blockchain/rpc/
core.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use std::{
17    collections::{HashMap, HashSet},
18    fmt::Debug,
19    sync::Arc,
20};
21
22use alloy::primitives::Address;
23use nautilus_core::{
24    hex,
25    string::secret::{REDACTED, SecretString},
26};
27use nautilus_live::SocketControl;
28#[cfg(feature = "hypersync")]
29use nautilus_model::defi::DexType;
30use nautilus_model::defi::{
31    Block, Chain, PoolIdentifier,
32    rpc::{RpcLog, RpcNodeWssResponse},
33};
34use nautilus_network::{
35    RECONNECTED,
36    http::create_standard_nautilus_headers,
37    websocket::{TransportBackend, WebSocketClient, WebSocketConfig, channel_message_handler},
38};
39use tokio_tungstenite::tungstenite::Message;
40
41#[cfg(feature = "hypersync")]
42use crate::exchanges::get_dex_extended;
43use crate::rpc::{
44    error::BlockchainRpcClientError,
45    log::{extract_address, extract_log_index, extract_transaction_hash},
46    types::{BlockchainMessage, RpcEventType},
47    utils::{
48        extract_rpc_subscription_id, is_subscription_confirmation_response, is_subscription_event,
49        is_unsubscribe_confirmation_response,
50    },
51};
52
53/// Core implementation of a blockchain RPC client that serves as the base for all chain-specific clients.
54///
55/// It provides a shared implementation of common blockchain RPC functionality, handling:
56/// - WebSocket connection management with blockchain RPC node.
57/// - Subscription lifecycle (creation, tracking, and termination).
58/// - Message serialization and deserialization of RPC messages.
59/// - Event type mapping and dispatching.
60/// - Automatic subscription re-establishment on reconnection.
61pub struct CoreBlockchainRpcClient {
62    /// The blockchain network type this client connects to.
63    chain: Chain,
64    /// WebSocket secure URL for the blockchain node's RPC endpoint.
65    wss_rpc_url: String,
66    /// Auto-incrementing counter for generating unique RPC request IDs.
67    request_id: u64,
68    /// Tracks in-flight subscription requests by request ID with event type and connection epoch.
69    pending_subscription_request: HashMap<u64, (RpcEventType, u64)>,
70    /// Request ids pruned by reconnect whose confirmations arrive too late to act on.
71    dead_subscription_requests: HashSet<u64>,
72    /// Maps active subscription IDs to their corresponding event types for message
73    /// deserialization.
74    subscription_event_types: HashMap<String, RpcEventType>,
75    /// The active WebSocket client connection.
76    wss_client: Option<Arc<WebSocketClient>>,
77    /// Channel receiver for consuming WebSocket messages.
78    wss_consumer_rx: Option<tokio::sync::mpsc::UnboundedReceiver<Message>>,
79    /// Tracks desired subscriptions that need to be re-established on reconnection.
80    subscriptions: Arc<tokio::sync::RwLock<HashMap<RpcEventType, RpcSubscription>>>,
81    /// WebSocket transport backend (defaults to `Sockudo`).
82    transport_backend: TransportBackend,
83    /// Optional proxy URL for the WebSocket connection.
84    proxy_url: Option<SecretString>,
85    socket_control: Option<SocketControl>,
86}
87
88impl Debug for CoreBlockchainRpcClient {
89    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
90        f.debug_struct(stringify!(CoreBlockchainRpcClient))
91            .field("chain", &self.chain)
92            .field("wss_rpc_url", &REDACTED)
93            .field("request_id", &self.request_id)
94            .field(
95                "pending_subscription_request",
96                &self.pending_subscription_request,
97            )
98            .field(
99                "dead_subscription_requests",
100                &self.dead_subscription_requests,
101            )
102            .field("subscription_event_types", &self.subscription_event_types)
103            .field(
104                "wss_client",
105                &self.wss_client.as_ref().map(|_| "<WebSocketClient>"),
106            )
107            .field(
108                "wss_consumer_rx",
109                &self.wss_consumer_rx.as_ref().map(|_| "<Receiver>"),
110            )
111            .field("confirmed_subscriptions", &"<RwLock<HashMap>>")
112            .finish()
113    }
114}
115
116#[derive(Debug, Clone)]
117struct RpcSubscription {
118    name: String,
119    filter: Option<serde_json::Value>,
120}
121
122impl RpcSubscription {
123    fn new(name: &str) -> Self {
124        Self {
125            name: name.to_string(),
126            filter: None,
127        }
128    }
129
130    fn pool_logs(addresses: &[Address], event_signature: &str) -> Self {
131        let mut addresses: Vec<String> = addresses
132            .iter()
133            .map(|address| format!("{address:?}"))
134            .collect();
135        addresses.sort();
136
137        Self {
138            name: "logs".to_string(),
139            filter: Some(serde_json::json!({
140                "address": addresses,
141                "topics": [event_signature],
142            })),
143        }
144    }
145
146    fn params(&self) -> Vec<serde_json::Value> {
147        let mut params = vec![serde_json::json!(self.name)];
148        if let Some(filter) = &self.filter {
149            params.push(filter.clone());
150        }
151        params
152    }
153}
154
155impl CoreBlockchainRpcClient {
156    #[must_use]
157    pub fn new(chain: Chain, wss_rpc_url: String, proxy_url: Option<String>) -> Self {
158        Self {
159            chain,
160            wss_rpc_url,
161            request_id: 1,
162            wss_client: None,
163            pending_subscription_request: HashMap::new(),
164            dead_subscription_requests: HashSet::new(),
165            subscription_event_types: HashMap::new(),
166            wss_consumer_rx: None,
167            subscriptions: Arc::new(tokio::sync::RwLock::new(HashMap::new())),
168            transport_backend: TransportBackend::default(),
169            proxy_url: proxy_url.map(SecretString::from),
170            socket_control: None,
171        }
172    }
173
174    /// Sets the transport backend for the next [`Self::connect`].
175    #[must_use]
176    pub fn with_transport_backend(mut self, backend: TransportBackend) -> Self {
177        self.transport_backend = backend;
178        self
179    }
180
181    /// Updates the transport backend in place.
182    pub fn set_transport_backend(&mut self, backend: TransportBackend) {
183        self.transport_backend = backend;
184    }
185
186    /// Configures socket state reporting and reconnect control.
187    pub fn set_socket_control(&mut self, control: SocketControl) {
188        self.socket_control = Some(control);
189    }
190
191    /// Establishes a WebSocket connection to the blockchain node and sets up the message channel.
192    ///
193    /// Configures automatic reconnection with exponential backoff and subscription re-establishment.
194    /// Reconnection is handled via the `RECONNECTED` message in the message stream.
195    ///
196    /// # Errors
197    ///
198    /// Returns an error if the WebSocket connection fails.
199    pub async fn connect(&mut self) -> anyhow::Result<()> {
200        let (handler, rx) = channel_message_handler();
201
202        // Most blockchain RPC nodes require a heartbeat to keep the connection alive
203        let heartbeat_interval = 30;
204        let headers = create_standard_nautilus_headers();
205
206        let config = WebSocketConfig {
207            url: self.wss_rpc_url.clone(),
208            headers,
209            heartbeat_interval_secs: Some(heartbeat_interval),
210            heartbeat_payload: None,
211            connect_timeout_ms: Some(10_000),
212            reconnect_delay_initial_ms: Some(1_000),
213            reconnect_delay_max_ms: Some(30_000),
214            reconnect_backoff_factor: Some(2.0),
215            reconnect_jitter_ms: Some(1_000),
216            reconnect_max_attempts: None,
217            heartbeat_timeout_secs: None,
218            idle_timeout_ms: None,
219            writer_capacity: None,
220            backend: self.transport_backend,
221            proxy_url: self
222                .proxy_url
223                .as_ref()
224                .map(|value| value.expose_secret().to_owned()),
225            max_message_size_bytes: None,
226            max_frame_size_bytes: None,
227        };
228
229        let client = WebSocketClient::builder()
230            .config(config)
231            .message_handler(handler)
232            .maybe_state_sink(self.socket_control.as_ref().map(SocketControl::sink))
233            .connect()
234            .await?;
235        let reconnect_handle = client.reconnect_handle();
236        if let Some(control) = &self.socket_control {
237            control.register(move || reconnect_handle.request_reconnect());
238        }
239
240        self.wss_client = Some(Arc::new(client));
241        self.wss_consumer_rx = Some(rx);
242
243        Ok(())
244    }
245
246    /// Registers a subscription for the specified event type.
247    async fn subscribe_events(
248        &mut self,
249        event_type: RpcEventType,
250        subscription: RpcSubscription,
251    ) -> Result<(), BlockchainRpcClientError> {
252        if self.subscriptions.read().await.contains_key(&event_type) {
253            return Ok(());
254        }
255
256        self.send_subscription_request(event_type, subscription)
257            .await
258    }
259
260    async fn replace_subscription(
261        &mut self,
262        event_type: RpcEventType,
263        subscription: RpcSubscription,
264    ) -> Result<(), BlockchainRpcClientError> {
265        self.unsubscribe_event_type(event_type).await?;
266        self.send_subscription_request(event_type, subscription)
267            .await
268    }
269
270    async fn send_subscription_request(
271        &mut self,
272        event_type: RpcEventType,
273        subscription: RpcSubscription,
274    ) -> Result<(), BlockchainRpcClientError> {
275        if let Some(client) = &self.wss_client {
276            log::debug!(
277                "Subscribing to '{}' on chain '{}'",
278                subscription.name,
279                self.chain.name
280            );
281            let msg = serde_json::json!({
282                "method": "eth_subscribe",
283                "id": self.request_id,
284                "jsonrpc": "2.0",
285                "params": subscription.params()
286            });
287            let request_id = self.request_id;
288            let connection_epoch = client.connection_epoch();
289            self.request_id += 1;
290
291            // Track desired first so a cancelled send is still retried by recovery
292            self.subscriptions
293                .write()
294                .await
295                .insert(event_type, subscription);
296
297            // Yield before recording: the send below must not suspend before queueing
298            tokio::task::yield_now().await;
299
300            // Record before sending: a cancelled send still wrote its frame
301            self.pending_subscription_request
302                .insert(request_id, (event_type, connection_epoch));
303
304            if let Err(e) = client
305                .send_text_on_connection(msg.to_string(), None, connection_epoch)
306                .await
307            {
308                log::error!("Error sending subscribe message: {e:?}");
309                self.pending_subscription_request.remove(&request_id);
310            }
311
312            Ok(())
313        } else {
314            Err(BlockchainRpcClientError::ClientError(String::from(
315                "Client not connected",
316            )))
317        }
318    }
319
320    /// Re-establishes all confirmed subscriptions after reconnection.
321    async fn resubscribe_all(&mut self) {
322        // Prior connection is dead so its server ids stay stale
323        self.subscription_event_types.clear();
324
325        // Stale requests must not block their resend
326        if let Some(client) = &self.wss_client {
327            let connection_epoch = client.connection_epoch();
328            let dead: Vec<u64> = self
329                .pending_subscription_request
330                .iter()
331                .filter(|(_, (_, pending_epoch))| *pending_epoch != connection_epoch)
332                .map(|(request_id, _)| *request_id)
333                .collect();
334            self.dead_subscription_requests.extend(dead);
335            self.pending_subscription_request
336                .retain(|_, (_, pending_epoch)| *pending_epoch == connection_epoch);
337        } else {
338            self.pending_subscription_request.clear();
339        }
340
341        self.ensure_subscribed().await;
342    }
343
344    /// Sends every desired subscription lacking a live id or fresh request.
345    ///
346    /// Runs after reconnect recovery and at the start of every receive so a
347    /// cancelled restore still converges on the next call.
348    async fn ensure_subscribed(&mut self) {
349        let (is_active, connection_epoch) = match &self.wss_client {
350            Some(client) => (client.is_active(), client.connection_epoch()),
351            None => return,
352        };
353
354        if !is_active {
355            return;
356        }
357
358        let missing = self.missing_subscriptions(connection_epoch).await;
359
360        if !missing.is_empty() {
361            log::info!(
362                "Re-establishing {} subscription(s) for chain '{}'",
363                missing.len(),
364                self.chain.name
365            );
366        }
367
368        for (event_type, subscription) in missing {
369            let active = self
370                .wss_client
371                .as_ref()
372                .is_some_and(|client| client.is_active());
373
374            if !active {
375                break;
376            }
377
378            if self
379                .send_subscription_request(event_type, subscription)
380                .await
381                .is_err()
382            {
383                break;
384            }
385        }
386    }
387
388    /// Desired subscriptions with neither a live id nor a fresh request on this connection.
389    async fn missing_subscriptions(
390        &self,
391        connection_epoch: u64,
392    ) -> Vec<(RpcEventType, RpcSubscription)> {
393        let subscriptions = self.subscriptions.read().await;
394
395        subscriptions
396            .iter()
397            .filter(|(event_type, _)| {
398                let live = self
399                    .subscription_event_types
400                    .values()
401                    .any(|live_type| live_type == *event_type);
402                let fresh = self.pending_subscription_request.values().any(
403                    |(pending_type, pending_epoch)| {
404                        pending_type == *event_type && *pending_epoch == connection_epoch
405                    },
406                );
407
408                !live && !fresh
409            })
410            .map(|(event_type, subscription)| (*event_type, subscription.clone()))
411            .collect()
412    }
413
414    /// Terminates a subscription with the blockchain node using the provided subscription ID.
415    async fn unsubscribe_events(
416        &self,
417        subscription_id: String,
418    ) -> Result<(), BlockchainRpcClientError> {
419        if let Some(client) = &self.wss_client {
420            log::debug!(
421                "Unsubscribing from '{}' on chain {}",
422                subscription_id,
423                self.chain.name
424            );
425            let msg = serde_json::json!({
426                "method": "eth_unsubscribe",
427                "id": 1,
428                "jsonrpc": "2.0",
429                "params": [subscription_id]
430            });
431
432            // Yield first so pre-queue suspension cannot drop this untracked send
433            tokio::task::yield_now().await;
434
435            if let Err(e) = client
436                .send_text_on_connection(msg.to_string(), None, client.connection_epoch())
437                .await
438            {
439                log::error!("Error sending unsubscribe message: {e:?}");
440            }
441            Ok(())
442        } else {
443            Err(BlockchainRpcClientError::ClientError(String::from(
444                "Client not connected",
445            )))
446        }
447    }
448
449    async fn unsubscribe_event_type(
450        &mut self,
451        event_type: RpcEventType,
452    ) -> Result<(), BlockchainRpcClientError> {
453        let subscription_ids_to_remove: Vec<String> = self
454            .subscription_event_types
455            .iter()
456            .filter(|(_, active_event_type)| **active_event_type == event_type)
457            .map(|(id, _)| id.clone())
458            .collect();
459
460        for id in subscription_ids_to_remove {
461            self.unsubscribe_events(id.clone()).await?;
462            self.subscription_event_types.remove(&id);
463        }
464
465        // Forget only current-connection requests outright: older ones died with
466        // their connection, so record them instead of cleaning up the new session.
467        let current_epoch = self
468            .wss_client
469            .as_ref()
470            .map(|client| client.connection_epoch());
471        let dead_requests = &mut self.dead_subscription_requests;
472        self.pending_subscription_request.retain(
473            |request_id, (pending_event_type, pending_epoch)| {
474                if *pending_event_type != event_type {
475                    return true;
476                }
477
478                if current_epoch.is_some_and(|current| *pending_epoch != current) {
479                    dead_requests.insert(*request_id);
480                }
481
482                false
483            },
484        );
485
486        self.subscriptions.write().await.remove(&event_type);
487
488        Ok(())
489    }
490
491    /// Routes a subscribe confirmation to its pending request, replacement, or cleanup.
492    ///
493    /// Confirmations for reconnect-pruned requests are ignored because their server
494    /// subscription died with the old connection, and a result colliding with a live
495    /// id is never unsubscribed; anything else unknown is unsubscribed so the node
496    /// holds no orphan subscription.
497    async fn handle_subscription_confirmation(
498        &mut self,
499        json: &serde_json::Value,
500    ) -> Result<(), BlockchainRpcClientError> {
501        let subscription_request_id = json
502            .get("id")
503            .and_then(serde_json::Value::as_u64)
504            .ok_or_else(|| {
505                BlockchainRpcClientError::InternalRpcClientError(
506                    "Missing subscription request id".to_string(),
507                )
508            })?;
509
510        let result = json
511            .get("result")
512            .and_then(serde_json::Value::as_str)
513            .ok_or_else(|| {
514                BlockchainRpcClientError::InternalRpcClientError(
515                    "Missing subscription id".to_string(),
516                )
517            })?;
518
519        let Some((event_type, _)) = self
520            .pending_subscription_request
521            .remove(&subscription_request_id)
522        else {
523            // Requests pruned by reconnect died with their connection,
524            // their server subscription is already gone
525            if self
526                .dead_subscription_requests
527                .remove(&subscription_request_id)
528            {
529                log::debug!(
530                    "Ignoring confirmation for request '{subscription_request_id}' pruned by reconnect on chain '{}'",
531                    self.chain.name
532                );
533                return Ok(());
534            }
535
536            // Never unsubscribe an id that is live: under
537            // connection-local id reuse the stale result can collide
538            // with the replacement subscription.
539            if self.subscription_event_types.contains_key(result) {
540                log::debug!(
541                    "Skipping unsubscribe for stale confirmation colliding with live id '{result}' on chain '{}'",
542                    self.chain.name
543                );
544                return Ok(());
545            }
546
547            log::debug!(
548                "Unsubscribing from stale subscription confirmation '{result}' on chain '{}'",
549                self.chain.name
550            );
551            self.unsubscribe_events(result.to_string()).await?;
552            return Ok(());
553        };
554
555        if self.subscriptions.read().await.contains_key(&event_type) {
556            self.subscription_event_types
557                .insert(result.to_string(), event_type);
558        } else {
559            self.unsubscribe_events(result.to_string()).await?;
560        }
561
562        Ok(())
563    }
564
565    /// Waits for and returns the next available message from the WebSocket channel.
566    pub async fn wait_on_rpc_channel(&mut self) -> Option<Message> {
567        self.wss_consumer_rx.as_mut()?.recv().await
568    }
569
570    /// Retrieves, parses, and returns the next blockchain RPC message as a structured `BlockchainRpcMessage` type.
571    ///
572    /// Handles subscription confirmations, events, and reconnection signals automatically.
573    ///
574    /// # Errors
575    ///
576    /// Returns an error if the RPC channel encounters an error or if deserialization of the message fails.
577    pub async fn next_rpc_message(
578        &mut self,
579    ) -> Result<BlockchainMessage, BlockchainRpcClientError> {
580        // Repair any restore a cancelled call left behind
581        self.ensure_subscribed().await;
582
583        while let Some(msg) = self.wait_on_rpc_channel().await {
584            match msg {
585                Message::Text(text) => {
586                    if text == RECONNECTED {
587                        log::info!("Detected reconnection for chain '{}'", self.chain.name);
588
589                        self.resubscribe_all().await;
590                        continue;
591                    }
592
593                    match serde_json::from_str::<serde_json::Value>(&text) {
594                        Ok(json) => {
595                            if is_unsubscribe_confirmation_response(&json) {
596                                log::debug!(
597                                    "Received unsubscribe confirmation on chain '{}'",
598                                    self.chain.name
599                                );
600                                continue;
601                            } else if is_subscription_confirmation_response(&json) {
602                                self.handle_subscription_confirmation(&json).await?;
603                                continue;
604                            } else if is_subscription_event(&json) {
605                                let subscription_id = match extract_rpc_subscription_id(&json) {
606                                    Some(id) => id,
607                                    None => {
608                                        return Err(BlockchainRpcClientError::InternalRpcClientError(
609                                        "Error parsing subscription id from valid rpc response"
610                                            .to_string(),
611                                    ));
612                                    }
613                                };
614
615                                if let Some(event_type) =
616                                    self.subscription_event_types.get(subscription_id).copied()
617                                {
618                                    match event_type {
619                                        RpcEventType::NewBlock => {
620                                            return match serde_json::from_value::<
621                                                RpcNodeWssResponse<Block>,
622                                            >(
623                                                json
624                                            ) {
625                                                Ok(block_response) => {
626                                                    let mut block = block_response.params.result;
627                                                    block.set_chain(self.chain.name);
628                                                    Ok(BlockchainMessage::Block(block))
629                                                }
630                                                Err(e) => Err(
631                                                    BlockchainRpcClientError::MessageParsingError(
632                                                        format!(
633                                                            "Error parsing rpc response to block with error {e}"
634                                                        ),
635                                                    ),
636                                                ),
637                                            };
638                                        }
639                                        RpcEventType::PoolSwap(_)
640                                        | RpcEventType::PoolMint(_)
641                                        | RpcEventType::PoolBurn(_)
642                                        | RpcEventType::PoolCollect(_)
643                                        | RpcEventType::PoolFlash(_)
644                                        | RpcEventType::PoolFeeProtocolUpdate(_)
645                                        | RpcEventType::PoolFeeProtocolCollect(_) => {
646                                            let log = Self::parse_rpc_log_response(json)?;
647
648                                            return self.blockchain_message_from_pool_log(
649                                                event_type, &log,
650                                            );
651                                        }
652                                    }
653                                }
654                                return Err(BlockchainRpcClientError::InternalRpcClientError(
655                                    format!(
656                                        "Event type not found for defined subscription id {subscription_id}"
657                                    ),
658                                ));
659                            }
660                            return Err(BlockchainRpcClientError::UnsupportedRpcResponseType(
661                                json.to_string(),
662                            ));
663                        }
664                        Err(e) => {
665                            return Err(BlockchainRpcClientError::MessageParsingError(
666                                e.to_string(),
667                            ));
668                        }
669                    }
670                }
671                Message::Pong(_) => {}
672                _ => {
673                    return Err(BlockchainRpcClientError::UnsupportedRpcResponseType(
674                        msg.to_string(),
675                    ));
676                }
677            }
678        }
679
680        Err(BlockchainRpcClientError::NoMessageReceived)
681    }
682
683    fn parse_rpc_log_response(json: serde_json::Value) -> Result<RpcLog, BlockchainRpcClientError> {
684        serde_json::from_value::<RpcNodeWssResponse<RpcLog>>(json)
685            .map(|response| response.params.result)
686            .map_err(|e| {
687                BlockchainRpcClientError::MessageParsingError(format!(
688                    "Error parsing rpc response to log with error {e}"
689                ))
690            })
691    }
692
693    #[cfg(feature = "hypersync")]
694    fn blockchain_message_from_pool_log(
695        &self,
696        event_type: RpcEventType,
697        log: &RpcLog,
698    ) -> Result<BlockchainMessage, BlockchainRpcClientError> {
699        if log.removed {
700            return Self::blockchain_message_from_removed_pool_log(log)
701                .map_err(|e| BlockchainRpcClientError::MessageParsingError(e.to_string()));
702        }
703
704        let dex = Self::pool_event_dex(event_type)?;
705        let dex_extended = get_dex_extended(self.chain.name, &dex).ok_or_else(|| {
706            BlockchainRpcClientError::InternalRpcClientError(format!(
707                "DEX {dex} is not registered for chain {}",
708                self.chain.name
709            ))
710        })?;
711
712        match event_type {
713            RpcEventType::PoolSwap(_) => dex_extended
714                .parse_swap_event_rpc(log)
715                .map(BlockchainMessage::SwapEvent),
716            RpcEventType::PoolMint(_) => dex_extended
717                .parse_mint_event_rpc(log)
718                .map(BlockchainMessage::MintEvent),
719            RpcEventType::PoolBurn(_) => dex_extended
720                .parse_burn_event_rpc(log)
721                .map(BlockchainMessage::BurnEvent),
722            RpcEventType::PoolCollect(_) => dex_extended
723                .parse_collect_event_rpc(log)
724                .map(BlockchainMessage::CollectEvent),
725            RpcEventType::PoolFlash(_) => dex_extended
726                .parse_flash_event_rpc(log)
727                .map(BlockchainMessage::FlashEvent),
728            RpcEventType::PoolFeeProtocolUpdate(_) => dex_extended
729                .parse_fee_protocol_update_event_rpc(log)
730                .map(BlockchainMessage::FeeProtocolUpdateEvent),
731            RpcEventType::PoolFeeProtocolCollect(_) => dex_extended
732                .parse_fee_protocol_collect_event_rpc(log)
733                .map(BlockchainMessage::FeeProtocolCollectEvent),
734            RpcEventType::NewBlock => Err(anyhow::anyhow!(
735                "NewBlock event type cannot parse pool logs"
736            )),
737        }
738        .map_err(|e| BlockchainRpcClientError::MessageParsingError(e.to_string()))
739    }
740
741    #[cfg(not(feature = "hypersync"))]
742    fn blockchain_message_from_pool_log(
743        &self,
744        event_type: RpcEventType,
745        log: &RpcLog,
746    ) -> Result<BlockchainMessage, BlockchainRpcClientError> {
747        if log.removed {
748            return Self::blockchain_message_from_removed_pool_log(log)
749                .map_err(|e| BlockchainRpcClientError::MessageParsingError(e.to_string()));
750        }
751
752        Err(BlockchainRpcClientError::UnsupportedRpcResponseType(
753            format!("RPC pool log parsing for {event_type:?} requires the hypersync feature"),
754        ))
755    }
756
757    fn blockchain_message_from_removed_pool_log(log: &RpcLog) -> anyhow::Result<BlockchainMessage> {
758        let pool_identifier = PoolIdentifier::from_address(extract_address(log)?);
759        let transaction_hash = extract_transaction_hash(log)?;
760        let _transaction_hash_bytes =
761            hex::decode_array::<32>(transaction_hash.trim_start_matches("0x").as_bytes())?;
762        let log_index = extract_log_index(log)?;
763
764        Ok(BlockchainMessage::PoolLogRemoved {
765            pool_identifier,
766            transaction_hash,
767            log_index,
768        })
769    }
770
771    #[cfg(feature = "hypersync")]
772    fn pool_event_dex(event_type: RpcEventType) -> Result<DexType, BlockchainRpcClientError> {
773        match event_type {
774            RpcEventType::PoolSwap(dex)
775            | RpcEventType::PoolMint(dex)
776            | RpcEventType::PoolBurn(dex)
777            | RpcEventType::PoolCollect(dex)
778            | RpcEventType::PoolFlash(dex)
779            | RpcEventType::PoolFeeProtocolUpdate(dex)
780            | RpcEventType::PoolFeeProtocolCollect(dex) => Ok(dex),
781            RpcEventType::NewBlock => Err(BlockchainRpcClientError::InternalRpcClientError(
782                "NewBlock event type has no DEX".to_string(),
783            )),
784        }
785    }
786
787    /// Subscribes to real-time block updates from the blockchain node.
788    ///
789    /// # Errors
790    ///
791    /// Returns an error if the subscription request fails or if the client is not connected.
792    pub async fn subscribe_blocks(&mut self) -> Result<(), BlockchainRpcClientError> {
793        self.subscribe_events(RpcEventType::NewBlock, RpcSubscription::new("newHeads"))
794            .await
795    }
796
797    /// Subscribes to real-time pool logs for one event type.
798    ///
799    /// # Errors
800    ///
801    /// Returns an error if the subscription request fails or if the client is not connected.
802    pub async fn subscribe_pool_events(
803        &mut self,
804        event_type: RpcEventType,
805        addresses: &[Address],
806        event_signature: String,
807    ) -> Result<(), BlockchainRpcClientError> {
808        if matches!(event_type, RpcEventType::NewBlock) {
809            return Err(BlockchainRpcClientError::InvalidParameters(
810                "NewBlock is not a pool event subscription".to_string(),
811            ));
812        }
813
814        if addresses.is_empty() {
815            return self.unsubscribe_event_type(event_type).await;
816        }
817
818        self.replace_subscription(
819            event_type,
820            RpcSubscription::pool_logs(addresses, &event_signature),
821        )
822        .await
823    }
824
825    /// Cancels the subscription to real-time block updates.
826    ///
827    /// # Errors
828    ///
829    /// Returns an error if the unsubscription request fails or if the client is not connected.
830    pub async fn unsubscribe_blocks(&mut self) -> Result<(), BlockchainRpcClientError> {
831        self.unsubscribe_event_type(RpcEventType::NewBlock).await
832    }
833}
834
835#[cfg(test)]
836mod tests {
837    use alloy::primitives::address;
838    use nautilus_model::defi::{Blockchain, Chain, DexType};
839    use rstest::rstest;
840
841    use super::*;
842
843    #[rstest]
844    fn debug_redacts_websocket_rpc_url() {
845        const USERINFO_SECRET: &str = "core-wss-userinfo-secret";
846        const PATH_SECRET: &str = "core-wss-path-secret";
847        const QUERY_SECRET: &str = "core-wss-query-secret";
848        let wss_rpc_url = format!(
849            "wss://rpc-user:{USERINFO_SECRET}@rpc.example.com/{PATH_SECRET}?api_key={QUERY_SECRET}"
850        );
851        let client = CoreBlockchainRpcClient::new(
852            Chain::from_chain_id(1)
853                .expect("Ethereum chain should exist")
854                .clone(),
855            wss_rpc_url.clone(),
856            None,
857        );
858
859        let debug = format!("{client:?}");
860
861        assert!(debug.contains("wss_rpc_url: \"<redacted>\""));
862        assert!(!debug.contains(USERINFO_SECRET));
863        assert!(!debug.contains(PATH_SECRET));
864        assert!(!debug.contains(QUERY_SECRET));
865        assert!(!debug.contains(&wss_rpc_url));
866    }
867
868    #[rstest]
869    fn pool_logs_subscription_params_use_logs_filter_with_sorted_addresses() {
870        let event_signature =
871            "0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67".to_string();
872        let subscription = RpcSubscription::pool_logs(
873            &[
874                address!("2222222222222222222222222222222222222222"),
875                address!("1111111111111111111111111111111111111111"),
876            ],
877            &event_signature,
878        );
879
880        let params = subscription.params();
881        let filter = &params[1];
882
883        assert_eq!(params[0], serde_json::json!("logs"));
884        assert_eq!(
885            filter["address"],
886            serde_json::json!([
887                "0x1111111111111111111111111111111111111111",
888                "0x2222222222222222222222222222222222222222",
889            ])
890        );
891        assert_eq!(filter["topics"], serde_json::json!([event_signature]));
892    }
893
894    #[cfg(feature = "hypersync")]
895    #[rstest]
896    fn pool_event_dex_rejects_block_event_type() {
897        assert!(CoreBlockchainRpcClient::pool_event_dex(RpcEventType::NewBlock).is_err());
898        assert_eq!(
899            CoreBlockchainRpcClient::pool_event_dex(RpcEventType::PoolSwap(DexType::UniswapV3))
900                .unwrap(),
901            DexType::UniswapV3
902        );
903    }
904
905    #[rstest]
906    fn removed_pool_log_returns_removal_message() {
907        let client = CoreBlockchainRpcClient::new(
908            Chain::from_chain_id(1)
909                .expect("Ethereum chain should exist")
910                .clone(),
911            "ws://127.0.0.1:9".to_string(),
912            None,
913        );
914        let log = removed_pool_log();
915
916        let message = client
917            .blockchain_message_from_pool_log(RpcEventType::PoolSwap(DexType::UniswapV3), &log)
918            .expect("removed logs should not fail conversion");
919
920        let BlockchainMessage::PoolLogRemoved {
921            pool_identifier,
922            transaction_hash,
923            log_index,
924        } = message
925        else {
926            panic!("expected pool log removal message");
927        };
928
929        assert_eq!(
930            pool_identifier,
931            PoolIdentifier::from_address(address!("1111111111111111111111111111111111111111"))
932        );
933        assert_eq!(
934            transaction_hash,
935            "0x24058dde7caf5b8b70041de8b27731f20f927365f210247c3e720e947b9098e7"
936        );
937        assert_eq!(log_index, 42);
938    }
939
940    #[rstest]
941    #[case("address", "Invalid contract address length: expected 20 bytes, was 0")]
942    #[case("missing_transaction_hash", "Missing transaction hash")]
943    #[case("malformed_transaction_hash", "invalid hex character: 0x7a")]
944    #[case("empty_transaction_hash", "expected 64 hex characters, was 0")]
945    #[case("short_transaction_hash", "expected 64 hex characters, was 62")]
946    #[case("log_index", "Missing log index")]
947    #[case(
948        "malformed_log_index",
949        "Invalid hex u32: invalid digit found in string"
950    )]
951    fn removed_pool_log_rejects_invalid_identity(
952        #[case] invalid_field: &str,
953        #[case] expected_message: &str,
954    ) {
955        let client = CoreBlockchainRpcClient::new(
956            Chain::from_chain_id(1)
957                .expect("Ethereum chain should exist")
958                .clone(),
959            "ws://127.0.0.1:9".to_string(),
960            None,
961        );
962        let mut log = removed_pool_log();
963        match invalid_field {
964            "address" => log.address = "0x".to_string(),
965            "missing_transaction_hash" => log.transaction_hash = None,
966            "malformed_transaction_hash" => log.transaction_hash = Some("z".repeat(64)),
967            "empty_transaction_hash" => log.transaction_hash = Some(String::new()),
968            "short_transaction_hash" => {
969                log.transaction_hash = Some(format!("0x{}", "a".repeat(62)));
970            }
971            "log_index" => log.log_index = None,
972            "malformed_log_index" => log.log_index = Some("0xzz".to_string()),
973            _ => unreachable!(),
974        }
975
976        let error = client
977            .blockchain_message_from_pool_log(RpcEventType::PoolSwap(DexType::UniswapV3), &log)
978            .expect_err("invalid removal identity should fail conversion");
979
980        let BlockchainRpcClientError::MessageParsingError(message) = error else {
981            panic!("expected message parsing error");
982        };
983
984        assert_eq!(message, expected_message);
985    }
986
987    fn removed_pool_log() -> RpcLog {
988        RpcLog {
989            removed: true,
990            log_index: Some("0x2a".to_string()),
991            transaction_index: Some("0x0".to_string()),
992            transaction_hash: Some(
993                "0x24058dde7caf5b8b70041de8b27731f20f927365f210247c3e720e947b9098e7".to_string(),
994            ),
995            block_hash: Some("0x1".to_string()),
996            block_number: Some("0x1".to_string()),
997            address: "0x1111111111111111111111111111111111111111".to_string(),
998            data: "0x".to_string(),
999            topics: vec![],
1000        }
1001    }
1002
1003    #[tokio::test]
1004    async fn next_rpc_message_returns_removed_pool_log() {
1005        let mut client = CoreBlockchainRpcClient::new(
1006            Chain::from_chain_id(1)
1007                .expect("Ethereum chain should exist")
1008                .clone(),
1009            "ws://127.0.0.1:9".to_string(),
1010            None,
1011        );
1012        client.subscription_event_types.insert(
1013            "0xpool".to_string(),
1014            RpcEventType::PoolSwap(DexType::UniswapV3),
1015        );
1016        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
1017        client.wss_consumer_rx = Some(rx);
1018        tx.send(Message::Text(
1019            serde_json::json!({
1020                "jsonrpc": "2.0",
1021                "method": "eth_subscription",
1022                "params": {
1023                    "subscription": "0xpool",
1024                    "result": {
1025                        "removed": true,
1026                        "logIndex": "0x2a",
1027                        "transactionIndex": "0x0",
1028                        "transactionHash": "0x24058dde7caf5b8b70041de8b27731f20f927365f210247c3e720e947b9098e7",
1029                        "blockHash": "0x1",
1030                        "blockNumber": "0x1",
1031                        "address": "0x1111111111111111111111111111111111111111",
1032                        "data": "0x",
1033                        "topics": []
1034                    }
1035                }
1036            })
1037            .to_string()
1038            .into(),
1039        ))
1040        .expect("removed pool log should enqueue");
1041        drop(tx);
1042
1043        let message = client
1044            .next_rpc_message()
1045            .await
1046            .expect("removed pool log should parse");
1047
1048        let BlockchainMessage::PoolLogRemoved {
1049            pool_identifier,
1050            transaction_hash,
1051            log_index,
1052        } = message
1053        else {
1054            panic!("expected pool log removal message");
1055        };
1056
1057        assert_eq!(
1058            pool_identifier,
1059            PoolIdentifier::from_address(address!("1111111111111111111111111111111111111111"))
1060        );
1061        assert_eq!(
1062            transaction_hash,
1063            "0x24058dde7caf5b8b70041de8b27731f20f927365f210247c3e720e947b9098e7"
1064        );
1065        assert_eq!(log_index, 42);
1066    }
1067
1068    #[tokio::test]
1069    async fn next_rpc_message_skips_unsubscribe_confirmation() {
1070        let mut client = CoreBlockchainRpcClient::new(
1071            Chain::from_chain_id(1)
1072                .expect("Ethereum chain should exist")
1073                .clone(),
1074            "ws://127.0.0.1:9".to_string(),
1075            None,
1076        );
1077        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
1078        client.wss_consumer_rx = Some(rx);
1079        tx.send(Message::Text(
1080            serde_json::json!({"jsonrpc": "2.0", "id": 1, "result": true})
1081                .to_string()
1082                .into(),
1083        ))
1084        .expect("unsubscribe ack should enqueue");
1085        drop(tx);
1086
1087        let error = client
1088            .next_rpc_message()
1089            .await
1090            .expect_err("unsubscribe ack should be skipped");
1091
1092        assert!(matches!(error, BlockchainRpcClientError::NoMessageReceived));
1093    }
1094
1095    #[tokio::test]
1096    async fn next_rpc_message_sets_client_chain_on_new_block() {
1097        let mut client = CoreBlockchainRpcClient::new(
1098            Chain::from_chain_id(8453)
1099                .expect("Base chain should exist")
1100                .clone(),
1101            "ws://127.0.0.1:9".to_string(),
1102            None,
1103        );
1104        client
1105            .subscription_event_types
1106            .insert("0xblocks".to_string(), RpcEventType::NewBlock);
1107        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
1108        client.wss_consumer_rx = Some(rx);
1109        tx.send(Message::Text(
1110            serde_json::json!({
1111                "jsonrpc": "2.0",
1112                "method": "eth_subscription",
1113                "params": {
1114                    "subscription": "0xblocks",
1115                    "result": {
1116                        "hash": "0xabc",
1117                        "number": "0x10",
1118                        "parentHash": "0xdef",
1119                        "miner": "0x0000000000000000000000000000000000000001",
1120                        "gasLimit": "0x1c9c380",
1121                        "gasUsed": "0x5208",
1122                        "timestamp": "0x6553f100"
1123                    }
1124                }
1125            })
1126            .to_string()
1127            .into(),
1128        ))
1129        .expect("block notification should enqueue");
1130
1131        let message = client
1132            .next_rpc_message()
1133            .await
1134            .expect("block notification should parse");
1135
1136        let BlockchainMessage::Block(block) = message else {
1137            panic!("expected block message");
1138        };
1139
1140        assert_eq!(block.chain(), Blockchain::Base);
1141        assert_eq!(block.number, 16);
1142        assert_eq!(block.hash, "0xabc");
1143    }
1144
1145    #[tokio::test]
1146    async fn stale_confirmation_matching_live_id_skips_unsubscribe() {
1147        let mut client = CoreBlockchainRpcClient::new(
1148            Chain::from_chain_id(1)
1149                .expect("Ethereum chain should exist")
1150                .clone(),
1151            "ws://127.0.0.1:9".to_string(),
1152            None,
1153        );
1154        client
1155            .subscription_event_types
1156            .insert("0x1".to_string(), RpcEventType::NewBlock);
1157        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
1158        client.wss_consumer_rx = Some(rx);
1159        tx.send(Message::Text(
1160            serde_json::json!({"jsonrpc": "2.0", "id": 999, "result": "0x1"})
1161                .to_string()
1162                .into(),
1163        ))
1164        .expect("stale confirmation should enqueue");
1165        drop(tx);
1166
1167        // Without a connection an unsubscribe attempt fails, so reaching the
1168        // drained channel proves the live id was left alone
1169        let error = client
1170            .next_rpc_message()
1171            .await
1172            .expect_err("live id collision should skip unsubscribe");
1173
1174        assert!(matches!(error, BlockchainRpcClientError::NoMessageReceived));
1175    }
1176
1177    #[tokio::test]
1178    async fn stale_confirmation_for_unknown_id_attempts_unsubscribe() {
1179        let mut client = CoreBlockchainRpcClient::new(
1180            Chain::from_chain_id(1)
1181                .expect("Ethereum chain should exist")
1182                .clone(),
1183            "ws://127.0.0.1:9".to_string(),
1184            None,
1185        );
1186        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
1187        client.wss_consumer_rx = Some(rx);
1188        tx.send(Message::Text(
1189            serde_json::json!({"jsonrpc": "2.0", "id": 998, "result": "0xdead"})
1190                .to_string()
1191                .into(),
1192        ))
1193        .expect("stale confirmation should enqueue");
1194        drop(tx);
1195
1196        let error = client
1197            .next_rpc_message()
1198            .await
1199            .expect_err("unknown id should attempt unsubscribe");
1200
1201        let BlockchainRpcClientError::ClientError(message) = error else {
1202            panic!("expected client error from unsubscribe attempt");
1203        };
1204
1205        assert_eq!(message, "Client not connected");
1206    }
1207}