use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;
use futures::{SinkExt, StreamExt};
use serde::Deserialize;
use serde_json::Value;
use starknet::core::types::{
AddressFilter, ConfirmedBlockId, EmittedEventWithFinality, Felt, L2TransactionFinalityStatus,
L2TransactionStatus, SubscriptionId, Transaction,
requests::{
SubscribeEventsRequest, SubscribeNewHeadsRequest, SubscribeNewTransactionsRequest,
UnsubscribeRequest,
},
};
use tokio::sync::mpsc;
use tokio_tungstenite::tungstenite::Message;
use tracing::{debug, error, info, warn};
use crate::app::actions::{Action, Source};
use crate::app::state::SourceStatus;
use crate::data::DataSource;
use crate::data::types::{AddressTxSummary, SnEvent};
use crate::utils::felt_to_u64;
const MAX_RECONNECT_DELAY: Duration = Duration::from_secs(30);
const INITIAL_RECONNECT_DELAY: Duration = Duration::from_secs(1);
const MAX_CONSECUTIVE_FAILURES: u32 = 5;
const SUBSCRIBE_TIMEOUT: Duration = Duration::from_secs(10);
const RESUME_OVERLAP_BLOCKS: u64 = 5;
const MAX_RESUME_BLOCKS: u64 = 1000;
#[derive(Debug, Clone)]
enum SubscriptionKind {
NewHeads,
Events {
address: Felt,
},
Transactions {
address: Felt,
},
Transfers {
address: Felt,
},
}
#[derive(Debug)]
pub enum WsCommand {
SubscribeEvents { address: Felt },
SubscribeTransactions { address: Felt },
SubscribeTransfers { address: Felt },
UnsubscribeAddress { address: Felt },
}
pub struct WsSubscriptionManager {
cmd_tx: mpsc::UnboundedSender<WsCommand>,
}
impl WsSubscriptionManager {
pub fn subscribe_events(&self, address: Felt) {
let _ = self.cmd_tx.send(WsCommand::SubscribeEvents { address });
}
pub fn subscribe_transactions(&self, address: Felt) {
let _ = self
.cmd_tx
.send(WsCommand::SubscribeTransactions { address });
}
pub fn subscribe_address(&self, address: Felt) {
let _ = self.cmd_tx.send(WsCommand::SubscribeEvents { address });
let _ = self
.cmd_tx
.send(WsCommand::SubscribeTransactions { address });
let _ = self.cmd_tx.send(WsCommand::SubscribeTransfers { address });
}
pub fn unsubscribe_address(&self, address: Felt) {
let _ = self.cmd_tx.send(WsCommand::UnsubscribeAddress { address });
}
}
#[derive(Default)]
struct Resume {
addresses: Vec<Felt>,
last_head: Option<u64>,
}
impl Resume {
fn add(&mut self, address: Felt) {
if !self.addresses.contains(&address) {
self.addresses.push(address);
}
}
fn remove(&mut self, address: Felt) {
self.addresses.retain(|a| *a != address);
}
fn replay_from(&self, tip: Option<u64>) -> Option<u64> {
let from = self.last_head?.saturating_sub(RESUME_OVERLAP_BLOCKS);
Some(match tip {
Some(tip) => from.max(tip.saturating_sub(MAX_RESUME_BLOCKS)),
None => from,
})
}
}
pub fn spawn_ws_subscriber(
ws_url: String,
data_source: Arc<dyn DataSource>,
response_tx: mpsc::UnboundedSender<Action>,
head_block: Arc<super::HeadTracker>,
) -> (tokio::task::JoinHandle<()>, WsSubscriptionManager) {
let (cmd_tx, cmd_rx) = mpsc::unbounded_channel::<WsCommand>();
let manager = WsSubscriptionManager { cmd_tx };
let (block_tx, block_rx) = mpsc::unbounded_channel::<Value>();
tokio::spawn(fetch_new_blocks(
block_rx,
Arc::clone(&data_source),
response_tx.clone(),
));
let handle = tokio::spawn(async move {
let mut delay = INITIAL_RECONNECT_DELAY;
let mut consecutive_failures: u32 = 0;
let mut cmd_rx = cmd_rx;
let mut resume = Resume::default();
loop {
info!(url = %ws_url, "Connecting to WebSocket");
let _ = response_tx.send(ws_source_update(SourceStatus::Configured));
match connect_and_run(
&ws_url,
&data_source,
&response_tx,
&mut cmd_rx,
&mut resume,
&head_block,
&block_tx,
)
.await
{
Ok(true) => {
info!("WsSubscriptionManager dropped, stopping WS task");
return;
}
Ok(false) => {
info!("WebSocket stream ended cleanly");
delay = INITIAL_RECONNECT_DELAY;
consecutive_failures = 0;
}
Err(e) => {
consecutive_failures += 1;
error!(error = %e, attempt = consecutive_failures, "WebSocket connection failed");
let _ = response_tx
.send(ws_source_update(SourceStatus::ConnectError(e.to_string())));
if consecutive_failures >= MAX_CONSECUTIVE_FAILURES {
error!(
"WebSocket gave up after {consecutive_failures} consecutive failures"
);
return;
}
}
}
warn!(
delay_secs = delay.as_secs(),
"Reconnecting WebSocket after delay"
);
tokio::time::sleep(delay).await;
delay = (delay * 2).min(MAX_RECONNECT_DELAY);
}
});
(handle, manager)
}
fn ws_source_update(status: SourceStatus) -> Action {
Action::SourceUpdate {
source: Source::Ws,
status,
}
}
struct ConnectionState {
subscriptions: HashMap<String, SubscriptionKind>,
address_subs: HashMap<Felt, Vec<String>>,
pending: HashMap<u64, SubscriptionKind>,
fallbacks: HashMap<u64, SubscribeEventsRequest>,
last_head: Option<u64>,
next_id: u64,
}
impl ConnectionState {
fn new() -> Self {
Self {
subscriptions: HashMap::new(),
address_subs: HashMap::new(),
pending: HashMap::new(),
fallbacks: HashMap::new(),
last_head: None,
next_id: 2, }
}
fn next_id(&mut self) -> u64 {
let id = self.next_id;
self.next_id += 1;
id
}
fn confirm_subscribe(&mut self, request_id: u64, sub_id: String) {
if let Some(kind) = self.pending.remove(&request_id) {
if let Some(addr) = kind_address(&kind) {
self.address_subs
.entry(addr)
.or_default()
.push(sub_id.clone());
}
self.subscriptions.insert(sub_id, kind);
}
}
fn remove_address(&mut self, address: Felt) -> Vec<String> {
self.address_subs
.remove(&address)
.unwrap_or_default()
.into_iter()
.inspect(|id| {
self.subscriptions.remove(id);
})
.collect()
}
fn subscription_kind(&self, sub_id: &str) -> Option<&SubscriptionKind> {
self.subscriptions.get(sub_id)
}
}
fn kind_address(kind: &SubscriptionKind) -> Option<Felt> {
match kind {
SubscriptionKind::Events { address }
| SubscriptionKind::Transactions { address }
| SubscriptionKind::Transfers { address } => Some(*address),
SubscriptionKind::NewHeads => None,
}
}
#[derive(Debug, Deserialize)]
struct RawMessage {
#[allow(dead_code)]
jsonrpc: Option<String>,
id: Option<Value>,
method: Option<String>,
params: Option<RawParams>,
result: Option<Value>,
error: Option<JsonRpcError>,
}
#[derive(Debug, Deserialize)]
struct RawParams {
#[serde(alias = "subscription", alias = "subscription_id")]
subscription_id: Value,
result: Value,
}
#[derive(Debug, Deserialize)]
struct JsonRpcError {
#[allow(dead_code)]
code: i64,
message: String,
}
async fn connect_and_run(
ws_url: &str,
data_source: &Arc<dyn DataSource>,
response_tx: &mpsc::UnboundedSender<Action>,
cmd_rx: &mut mpsc::UnboundedReceiver<WsCommand>,
resume: &mut Resume,
head_block: &Arc<super::HeadTracker>,
block_tx: &mpsc::UnboundedSender<Value>,
) -> Result<bool, Box<dyn std::error::Error + Send + Sync>> {
let (ws_stream, _) = tokio_tungstenite::connect_async(ws_url).await?;
let (mut write, mut read) = ws_stream.split();
let mut state = ConnectionState::new();
let heads_msg = build_subscribe_msg(
1,
"starknet_subscribeNewHeads",
serde_json::to_value(SubscribeNewHeadsRequest { block_id: None })?,
);
write.send(Message::Text(heads_msg.into())).await?;
state.pending.insert(1, SubscriptionKind::NewHeads);
debug!("Sent starknet_subscribeNewHeads");
let (tip, age) = head_block.read();
let from_block = resume.replay_from((tip > 0 && age < 300).then_some(tip));
if !resume.addresses.is_empty() {
info!(
?from_block,
addresses = resume.addresses.len(),
"Re-subscribing address streams"
);
}
for &address in &resume.addresses {
for cmd in [
WsCommand::SubscribeEvents { address },
WsCommand::SubscribeTransactions { address },
WsCommand::SubscribeTransfers { address },
] {
send_subscribe_cmd(&mut write, &mut state, &cmd, from_block).await?;
}
}
let _ = response_tx.send(ws_source_update(SourceStatus::Live));
loop {
tokio::select! {
msg = read.next() => {
match msg {
Some(Ok(Message::Text(text))) => {
handle_message(&text, &mut write, &mut state, data_source, response_tx, head_block, block_tx).await;
if state.last_head > resume.last_head {
resume.last_head = state.last_head;
}
}
Some(Ok(Message::Ping(data))) => {
let _ = write.send(Message::Pong(data)).await;
}
Some(Ok(Message::Close(_))) => {
info!("WebSocket server sent close frame");
break;
}
Some(Ok(_)) => {} Some(Err(e)) => {
return Err(format!("WS read error: {e}").into());
}
None => {
info!("WebSocket stream closed");
break;
}
}
}
cmd = cmd_rx.recv() => {
match cmd {
Some(WsCommand::UnsubscribeAddress { address }) => {
resume.remove(address);
let ids = state.remove_address(address);
for sub_id in ids {
let req_id = state.next_id();
let msg = build_subscribe_msg(
req_id,
"starknet_unsubscribe",
serde_json::to_value(UnsubscribeRequest {
subscription_id: SubscriptionId(sub_id.clone()),
})?,
);
if write.send(Message::Text(msg.into())).await.is_err() {
break;
}
debug!(sub_id, "Sent unsubscribe");
}
}
Some(cmd) => {
if let Some(address) = command_address(&cmd) {
resume.add(address);
}
if let Err(e) = send_subscribe_cmd(&mut write, &mut state, &cmd, None).await {
warn!(error = %e, "Failed to send subscribe command");
}
}
None => return Ok(true),
}
}
}
}
Ok(false)
}
fn command_address(cmd: &WsCommand) -> Option<Felt> {
match cmd {
WsCommand::SubscribeEvents { address }
| WsCommand::SubscribeTransactions { address }
| WsCommand::SubscribeTransfers { address } => Some(*address),
WsCommand::UnsubscribeAddress { .. } => None,
}
}
fn build_subscribe_msg(id: u64, method: &str, params: Value) -> String {
serde_json::json!({
"jsonrpc": "2.0",
"id": id,
"method": method,
"params": params,
})
.to_string()
}
async fn send_subscribe_cmd(
write: &mut (impl SinkExt<Message, Error = tokio_tungstenite::tungstenite::Error> + Unpin),
state: &mut ConnectionState,
cmd: &WsCommand,
from_block: Option<u64>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
let block_id = from_block.map(ConfirmedBlockId::Number);
match cmd {
WsCommand::SubscribeEvents { address } => {
let req = SubscribeEventsRequest {
from_address: Some(AddressFilter::Single(*address)),
keys: None,
block_id,
finality_status: Some(L2TransactionFinalityStatus::AcceptedOnL2),
};
send_events_subscription(
write,
state,
SubscriptionKind::Events { address: *address },
req,
)
.await?;
debug!(address = %format!("{:#x}", address), ?from_block, "Sent starknet_subscribeEvents");
}
WsCommand::SubscribeTransactions { address } => {
let id = state.next_id();
let req = SubscribeNewTransactionsRequest {
sender_address: Some(vec![*address]),
finality_status: Some(vec![L2TransactionStatus::AcceptedOnL2]),
tags: None,
};
let msg = build_subscribe_msg(
id,
"starknet_subscribeNewTransactions",
serde_json::to_value(req)?,
);
write.send(Message::Text(msg.into())).await?;
state
.pending
.insert(id, SubscriptionKind::Transactions { address: *address });
debug!(address = %format!("{:#x}", address), "Sent starknet_subscribeNewTransactions");
}
WsCommand::SubscribeTransfers { address } => {
for keys in transfer_key_filters(*address) {
let req = SubscribeEventsRequest {
from_address: None,
keys: Some(keys),
block_id,
finality_status: Some(L2TransactionFinalityStatus::AcceptedOnL2),
};
send_events_subscription(
write,
state,
SubscriptionKind::Transfers { address: *address },
req,
)
.await?;
}
debug!(address = %format!("{:#x}", address), ?from_block, "Sent keyed Transfer subscriptions (in+out)");
}
WsCommand::UnsubscribeAddress { .. } => {
}
}
Ok(())
}
async fn send_events_subscription(
write: &mut (impl SinkExt<Message, Error = tokio_tungstenite::tungstenite::Error> + Unpin),
state: &mut ConnectionState,
kind: SubscriptionKind,
req: SubscribeEventsRequest,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
let id = state.next_id();
let msg = build_subscribe_msg(id, "starknet_subscribeEvents", serde_json::to_value(&req)?);
write.send(Message::Text(msg.into())).await?;
state.pending.insert(id, kind);
if req.block_id.is_some() {
state.fallbacks.insert(
id,
SubscribeEventsRequest {
block_id: None,
..req
},
);
}
Ok(())
}
async fn handle_message(
text: &str,
write: &mut (impl SinkExt<Message, Error = tokio_tungstenite::tungstenite::Error> + Unpin),
state: &mut ConnectionState,
data_source: &Arc<dyn DataSource>,
response_tx: &mpsc::UnboundedSender<Action>,
head_block: &Arc<super::HeadTracker>,
block_tx: &mpsc::UnboundedSender<Value>,
) {
let raw: RawMessage = match serde_json::from_str(text) {
Ok(m) => m,
Err(e) => {
warn!(error = %e, "Failed to parse WS message");
return;
}
};
if let Some(id_val) = &raw.id {
let req_id = id_val.as_u64().unwrap_or(0);
if let Some(err) = &raw.error {
let kind = state.pending.remove(&req_id);
if let (Some(kind), Some(req)) = (kind, state.fallbacks.remove(&req_id)) {
info!(req_id, error = %err.message, "Event replay rejected; subscribing from the tip");
if let Err(e) = send_events_subscription(write, state, kind, req).await {
warn!(error = %e, "Failed to re-send event subscription");
}
return;
}
warn!(req_id, error = %err.message, "Subscribe/unsubscribe failed");
return;
}
if let Some(result) = &raw.result {
state.fallbacks.remove(&req_id);
if let Ok(sub_id) = serde_json::from_value::<SubscriptionId>(result.clone()) {
debug!(req_id, sub_id = %sub_id.0, "Subscription confirmed");
state.confirm_subscribe(req_id, sub_id.0);
}
return;
}
}
if let Some(method) = &raw.method
&& !method.starts_with("starknet_subscription")
{
debug!(method, "Ignoring non-subscription notification");
return;
}
let params = match raw.params {
Some(p) => p,
None => return,
};
let sub_id_str = match ¶ms.subscription_id {
Value::String(s) => s.clone(),
Value::Number(n) => n.to_string(),
other => {
warn!(value = ?other, "Unexpected subscription_id type");
return;
}
};
let kind = match state.subscription_kind(&sub_id_str) {
Some(k) => k.clone(),
None => {
debug!(
sub_id = sub_id_str,
"Notification for unknown subscription, ignoring"
);
return;
}
};
match kind {
SubscriptionKind::NewHeads => {
if let Some(n) = handle_new_head(params.result, head_block, block_tx) {
state.last_head = state.last_head.max(Some(n));
}
}
SubscriptionKind::Events { address } => {
handle_event(¶ms.result, address, data_source, response_tx);
}
SubscriptionKind::Transfers { address } => {
handle_event(¶ms.result, address, data_source, response_tx);
}
SubscriptionKind::Transactions { address } => {
handle_new_transaction(¶ms.result, address, response_tx);
}
}
let _ = write; }
fn handle_new_head(
result: Value,
head_block: &Arc<super::HeadTracker>,
block_tx: &mpsc::UnboundedSender<Value>,
) -> Option<u64> {
let Some(block_number) = result["block_number"].as_u64() else {
warn!("NewHeads notification missing block_number: {result}");
return None;
};
head_block.update(block_number);
info!(block_number, "New block header via WebSocket");
let _ = block_tx.send(result);
Some(block_number)
}
async fn fetch_new_blocks(
mut block_rx: mpsc::UnboundedReceiver<Value>,
data_source: Arc<dyn DataSource>,
response_tx: mpsc::UnboundedSender<Action>,
) {
while let Some(raw) = block_rx.recv().await {
let Some(block_number) = raw["block_number"].as_u64() else {
continue;
};
match data_source.get_block(block_number).await {
Ok(block) => {
let _ = response_tx.send(Action::NewBlock(block));
}
Err(e) => {
warn!(block_number, error = %e, "Failed to fetch full block via RPC, using WS header");
if let Some(block) = block_from_raw(&raw) {
let _ = response_tx.send(Action::NewBlock(block));
}
}
}
}
}
fn handle_event(
result: &Value,
address: Felt,
data_source: &Arc<dyn DataSource>,
response_tx: &mpsc::UnboundedSender<Action>,
) {
let event: EmittedEventWithFinality = match serde_json::from_value(result.clone()) {
Ok(e) => e,
Err(e) => {
warn!(error = %e, "Failed to deserialize event notification");
return;
}
};
let tx_hash = event.emitted_event.transaction_hash;
let block_number = event.emitted_event.block_number.unwrap_or(0);
let sn_event = SnEvent {
from_address: event.emitted_event.from_address,
keys: event.emitted_event.keys.clone(),
data: event.emitted_event.data.clone(),
transaction_hash: tx_hash,
block_number,
event_index: event.emitted_event.event_index,
};
debug!(
address = %format!("{:#x}", address),
tx = %format!("{:#x}", tx_hash),
block = block_number,
"Received event via WS → cache + single broadcast"
);
data_source.append_address_events(&address, std::slice::from_ref(&sn_event));
let _ = response_tx.send(Action::AddressWsEvent {
address,
event: sn_event,
});
}
pub(crate) fn tx_executed_selector() -> Felt {
use std::sync::OnceLock;
static SELECTOR: OnceLock<Felt> = OnceLock::new();
*SELECTOR.get_or_init(|| {
Felt::from_hex(crate::data::pathfinder::TRANSACTION_EXECUTED_SELECTOR)
.expect("TRANSACTION_EXECUTED_SELECTOR is a valid felt")
})
}
fn transfer_selector() -> Felt {
use std::sync::OnceLock;
static SELECTOR: OnceLock<Felt> = OnceLock::new();
*SELECTOR.get_or_init(|| {
Felt::from_hex(crate::data::pathfinder::TRANSFER_SELECTOR)
.expect("TRANSFER_SELECTOR is a valid felt")
})
}
pub(crate) fn transfer_key_filters(address: Felt) -> [Vec<Vec<Felt>>; 2] {
let sel = transfer_selector();
[
vec![vec![sel], vec![], vec![address]], vec![vec![sel], vec![address], vec![]], ]
}
fn handle_new_transaction(
result: &Value,
address: Felt,
response_tx: &mpsc::UnboundedSender<Action>,
) {
let summary = if let Ok(tx) = serde_json::from_value::<Transaction>(result.clone()) {
tx_to_summary(&tx)
} else {
tx_from_raw(result)
};
let summary = match summary {
Some(s) => s,
None => {
debug!("Could not build summary from transaction notification");
return;
}
};
debug!(
address = %format!("{:#x}", address),
tx = %format!("{:#x}", summary.hash),
"Received transaction via WS"
);
let _ = response_tx.send(Action::AddressTxsStreamed {
address,
source: Source::Ws,
tx_summaries: vec![summary],
complete: false,
});
}
fn tx_to_summary(tx: &Transaction) -> Option<AddressTxSummary> {
let (hash, nonce, tx_type, sender) = match tx {
Transaction::Invoke(invoke) => match invoke {
starknet::core::types::InvokeTransaction::V0(t) => {
(t.transaction_hash, 0u64, "INVOKE", None::<Felt>)
}
starknet::core::types::InvokeTransaction::V1(t) => (
t.transaction_hash,
felt_to_u64(&t.nonce),
"INVOKE",
Some(t.sender_address),
),
starknet::core::types::InvokeTransaction::V3(t) => (
t.transaction_hash,
felt_to_u64(&t.nonce),
"INVOKE",
Some(t.sender_address),
),
},
Transaction::Declare(declare) => match declare {
starknet::core::types::DeclareTransaction::V0(t) => {
(t.transaction_hash, 0u64, "DECLARE", Some(t.sender_address))
}
starknet::core::types::DeclareTransaction::V1(t) => (
t.transaction_hash,
felt_to_u64(&t.nonce),
"DECLARE",
Some(t.sender_address),
),
starknet::core::types::DeclareTransaction::V2(t) => (
t.transaction_hash,
felt_to_u64(&t.nonce),
"DECLARE",
Some(t.sender_address),
),
starknet::core::types::DeclareTransaction::V3(t) => (
t.transaction_hash,
felt_to_u64(&t.nonce),
"DECLARE",
Some(t.sender_address),
),
},
Transaction::DeployAccount(deploy_acc) => match deploy_acc {
starknet::core::types::DeployAccountTransaction::V1(t) => {
(t.transaction_hash, 0u64, "DEPLOY_ACCOUNT", None)
}
starknet::core::types::DeployAccountTransaction::V3(t) => {
(t.transaction_hash, 0u64, "DEPLOY_ACCOUNT", None)
}
},
Transaction::Deploy(t) => (t.transaction_hash, 0u64, "DEPLOY", None),
Transaction::L1Handler(t) => (t.transaction_hash, 0u64, "L1_HANDLER", None),
};
Some(AddressTxSummary {
hash,
nonce,
block_number: 0, timestamp: 0,
endpoint_names: String::new(),
total_fee_fri: 0,
tip: 0,
tx_type: tx_type.to_string(),
status: "?".to_string(), sender,
called_contracts: Vec::new(),
})
}
fn tx_from_raw(v: &Value) -> Option<AddressTxSummary> {
let hash_str = v["transaction_hash"].as_str()?;
let hash = Felt::from_hex(hash_str).ok()?;
let nonce = v["nonce"]
.as_str()
.and_then(|s| u64::from_str_radix(s.trim_start_matches("0x"), 16).ok())
.unwrap_or(0);
let tx_type = v["type"].as_str().unwrap_or("INVOKE").to_string();
let sender = v["sender_address"]
.as_str()
.and_then(|s| Felt::from_hex(s).ok());
Some(AddressTxSummary {
hash,
nonce,
block_number: 0,
timestamp: 0,
endpoint_names: String::new(),
total_fee_fri: 0,
tip: 0,
tx_type,
status: "?".to_string(),
sender,
called_contracts: Vec::new(),
})
}
fn block_from_raw(v: &Value) -> Option<crate::data::types::SnBlock> {
let block_number = v["block_number"].as_u64()?;
let block_hash = Felt::from_hex(v["block_hash"].as_str()?).ok()?;
let parent_hash = Felt::from_hex(v["parent_hash"].as_str().unwrap_or("0x0")).ok()?;
let timestamp = v["timestamp"].as_u64().unwrap_or(0);
let sequencer_address =
Felt::from_hex(v["sequencer_address"].as_str().unwrap_or("0x0")).ok()?;
let starknet_version = v["starknet_version"].as_str().unwrap_or("").to_string();
let transaction_count = v["transaction_count"].as_u64().unwrap_or(0) as usize;
let gas_fri = |field: &str| -> u128 {
v[field]["price_in_fri"]
.as_str()
.and_then(|s| u128::from_str_radix(s.trim_start_matches("0x"), 16).ok())
.unwrap_or(0)
};
let gas_wei = |field: &str| -> u128 {
v[field]["price_in_wei"]
.as_str()
.and_then(|s| u128::from_str_radix(s.trim_start_matches("0x"), 16).ok())
.unwrap_or(0)
};
Some(crate::data::types::SnBlock {
number: block_number,
hash: block_hash,
parent_hash,
timestamp,
sequencer_address,
transaction_count,
l1_gas_price_fri: gas_fri("l1_gas_price"),
l1_gas_price_wei: gas_wei("l1_gas_price"),
l2_gas_price_fri: gas_fri("l2_gas_price"),
l1_data_gas_price_fri: gas_fri("l1_data_gas_price"),
starknet_version,
status: v["status"].as_str().unwrap_or("ACCEPTED_ON_L2").to_string(),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::data::types::{SnBlock, SnReceipt, SnTransaction};
use async_trait::async_trait;
use starknet::core::types::{AddressFilter, ContractClass};
struct TestDataSource;
#[async_trait]
impl DataSource for TestDataSource {
async fn get_latest_block_number(&self) -> crate::error::Result<u64> {
unimplemented!()
}
async fn get_block(&self, _number: u64) -> crate::error::Result<SnBlock> {
unimplemented!()
}
async fn get_block_by_hash(&self, _hash: Felt) -> crate::error::Result<u64> {
unimplemented!()
}
async fn get_block_with_txs(
&self,
_number: u64,
) -> crate::error::Result<(SnBlock, Vec<SnTransaction>)> {
unimplemented!()
}
async fn get_transaction(&self, _hash: Felt) -> crate::error::Result<SnTransaction> {
unimplemented!()
}
async fn get_receipt(&self, _hash: Felt) -> crate::error::Result<SnReceipt> {
unimplemented!()
}
async fn get_nonce(&self, _address: Felt) -> crate::error::Result<Felt> {
unimplemented!()
}
async fn get_class_hash(&self, _address: Felt) -> crate::error::Result<Felt> {
unimplemented!()
}
async fn get_class(&self, _class_hash: Felt) -> crate::error::Result<ContractClass> {
unimplemented!()
}
async fn get_trace(
&self,
_hash: Felt,
) -> crate::error::Result<starknet::core::types::TransactionTrace> {
unimplemented!()
}
async fn get_recent_blocks(&self, _count: usize) -> crate::error::Result<Vec<SnBlock>> {
unimplemented!()
}
async fn get_events_for_address(
&self,
_address: Felt,
_from_block: Option<u64>,
_to_block: Option<u64>,
_limit: usize,
) -> crate::error::Result<Vec<SnEvent>> {
unimplemented!()
}
async fn call_contract(
&self,
_contract_address: Felt,
_selector: Felt,
_calldata: Vec<Felt>,
) -> crate::error::Result<Vec<Felt>> {
unimplemented!()
}
}
fn test_data_source() -> Arc<dyn DataSource> {
Arc::new(TestDataSource)
}
#[test]
fn build_subscribe_new_heads_msg() {
let params = serde_json::to_value(SubscribeNewHeadsRequest { block_id: None }).unwrap();
let msg = build_subscribe_msg(1, "starknet_subscribeNewHeads", params);
let v: Value = serde_json::from_str(&msg).unwrap();
assert_eq!(v["jsonrpc"], "2.0");
assert_eq!(v["id"], 1);
assert_eq!(v["method"], "starknet_subscribeNewHeads");
}
#[test]
fn build_subscribe_events_msg_serializes_address() {
let address = Felt::from_hex_unchecked(
"0x04270219d365d6b017231b52e92b3fb5d7c8378b05e9abc97724537a80e93b0f",
);
let req = SubscribeEventsRequest {
from_address: Some(AddressFilter::Single(address)),
keys: None,
block_id: None,
finality_status: Some(L2TransactionFinalityStatus::AcceptedOnL2),
};
let params = serde_json::to_value(req).unwrap();
let msg = build_subscribe_msg(2, "starknet_subscribeEvents", params);
let v: Value = serde_json::from_str(&msg).unwrap();
assert_eq!(v["method"], "starknet_subscribeEvents");
assert!(v["params"]["from_address"].is_string());
}
#[test]
fn build_subscribe_transactions_msg_serializes_sender() {
let address = Felt::from_hex_unchecked(
"0x01176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
);
let req = SubscribeNewTransactionsRequest {
sender_address: Some(vec![address]),
finality_status: Some(vec![L2TransactionStatus::AcceptedOnL2]),
tags: None,
};
let params = serde_json::to_value(req).unwrap();
let msg = build_subscribe_msg(3, "starknet_subscribeNewTransactions", params);
let v: Value = serde_json::from_str(&msg).unwrap();
assert_eq!(v["method"], "starknet_subscribeNewTransactions");
assert!(v["params"]["sender_address"].is_array());
}
#[test]
fn transfer_key_filters_pin_to_and_from_slots() {
let address = Felt::from_hex_unchecked(
"0x03a496b92d292386ad70dab94ae181a06d289440e3b632a2435721b4280874c4",
);
let sel = transfer_selector();
assert_eq!(
sel,
starknet::core::utils::get_selector_from_name("Transfer").unwrap(),
"TRANSFER_SELECTOR must equal sn_keccak(\"Transfer\")"
);
let [incoming, outgoing] = transfer_key_filters(address);
assert_eq!(incoming, vec![vec![sel], vec![], vec![address]]);
assert_eq!(outgoing, vec![vec![sel], vec![address], vec![]]);
let req = SubscribeEventsRequest {
from_address: None,
keys: Some(incoming),
block_id: None,
finality_status: Some(L2TransactionFinalityStatus::AcceptedOnL2),
};
let v = serde_json::to_value(req).unwrap();
assert!(v.get("from_address").is_none() || v["from_address"].is_null());
assert_eq!(v["keys"][0][0], format!("{sel:#x}"));
assert_eq!(v["keys"][2][0], format!("{address:#x}"));
}
#[test]
fn handle_event_carries_real_event_index() {
use crate::app::actions::Action;
use tokio::sync::mpsc;
let address = Felt::from_hex_unchecked(
"0x03a496b92d292386ad70dab94ae181a06d289440e3b632a2435721b4280874c4",
);
let transfer = crate::data::pathfinder::TRANSFER_SELECTOR;
let mk = |from_token: &str, idx: u64| {
format!(
r#"{{
"from_address": "{from_token}",
"keys": ["{transfer}", "0xsomefrom", "{address:#x}"],
"data": ["0x2f2c5624", "0x0"],
"block_hash": "0xabc",
"block_number": 11117243,
"transaction_hash": "0x21a4",
"transaction_index": 0,
"event_index": {idx},
"finality_status": "ACCEPTED_ON_L2"
}}"#
)
.replace(
"0xsomefrom",
"0x1b6f560def289b32e2a7b0920909615531a4d9d5636ca509045843559dc23d5",
)
};
let (tx, mut rx) = mpsc::unbounded_channel();
let ds = test_data_source();
let eth = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
let strk = "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d";
let r6: Value = serde_json::from_str(&mk(eth, 6)).unwrap();
let r7: Value = serde_json::from_str(&mk(strk, 7)).unwrap();
super::handle_event(&r6, address, &ds, &tx);
super::handle_event(&r7, address, &ds, &tx);
let mut indices: Vec<u64> = Vec::new();
while let Ok(a) = rx.try_recv() {
if let Action::AddressWsEvent { event, .. } = a {
assert_eq!(event.transaction_hash, Felt::from_hex_unchecked("0x21a4"));
indices.push(event.event_index);
}
}
indices.sort_unstable();
assert_eq!(
indices,
vec![6, 7],
"both transfers must broadcast with their real, distinct event_index"
);
}
#[test]
fn parse_subscription_confirmation() {
let json = r#"{"jsonrpc":"2.0","result":"0xdeadbeef","id":1}"#;
let raw: RawMessage = serde_json::from_str(json).unwrap();
assert!(raw.id.is_some());
assert!(raw.error.is_none());
let sub_id: SubscriptionId = serde_json::from_value(raw.result.unwrap()).unwrap();
assert_eq!(sub_id.0, "0xdeadbeef");
}
#[test]
fn parse_subscription_error() {
let json =
r#"{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":1}"#;
let raw: RawMessage = serde_json::from_str(json).unwrap();
assert!(raw.result.is_none());
assert_eq!(raw.error.unwrap().message, "Method not found");
}
#[test]
fn parse_event_notification_pathfinder_style() {
let json = r#"{
"jsonrpc": "2.0",
"method": "starknet_subscriptionEvents",
"params": {
"subscription": "0x1",
"result": {
"from_address": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
"keys": ["0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"],
"data": ["0x0", "0x1"],
"block_hash": "0xabc",
"block_number": 100,
"transaction_hash": "0xdef",
"transaction_index": 0,
"event_index": 0,
"finality_status": "ACCEPTED_ON_L2"
}
}
}"#;
let raw: RawMessage = serde_json::from_str(json).unwrap();
assert_eq!(raw.method.as_deref(), Some("starknet_subscriptionEvents"));
let params = raw.params.unwrap();
assert_eq!(params.subscription_id, serde_json::json!("0x1"));
let event: EmittedEventWithFinality = serde_json::from_value(params.result).unwrap();
assert_eq!(
event.emitted_event.from_address,
Felt::from_hex_unchecked(
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
)
);
assert_eq!(event.emitted_event.block_number, Some(100));
}
#[test]
fn parse_event_notification_spec_style() {
let json = r#"{
"jsonrpc": "2.0",
"method": "starknet_subscription",
"params": {
"subscription_id": "0x42",
"result": {
"from_address": "0x1",
"keys": ["0x2"],
"data": [],
"block_hash": "0x3",
"block_number": 200,
"transaction_hash": "0x4",
"transaction_index": 0,
"event_index": 1,
"finality_status": "ACCEPTED_ON_L2"
}
}
}"#;
let raw: RawMessage = serde_json::from_str(json).unwrap();
let params = raw.params.unwrap();
assert_eq!(params.subscription_id, serde_json::json!("0x42"));
let event: EmittedEventWithFinality = serde_json::from_value(params.result).unwrap();
assert_eq!(event.emitted_event.block_number, Some(200));
}
#[test]
fn block_from_raw_extracts_fields() {
let json = serde_json::json!({
"block_number": 12345,
"block_hash": "0xabc",
"parent_hash": "0xdef",
"timestamp": 1700000000u64,
"sequencer_address": "0x1",
"starknet_version": "0.13.4",
"transaction_count": 42,
"l1_gas_price": { "price_in_fri": "0x100", "price_in_wei": "0x200" },
"l2_gas_price": { "price_in_fri": "0x50" },
"l1_data_gas_price": { "price_in_fri": "0x10" }
});
let block = block_from_raw(&json).expect("block");
assert_eq!(block.number, 12345);
assert_eq!(block.transaction_count, 42);
assert_eq!(block.l1_gas_price_fri, 0x100);
assert_eq!(block.l1_gas_price_wei, 0x200);
assert_eq!(block.starknet_version, "0.13.4");
}
#[test]
fn connection_state_tracks_subscriptions() {
let mut state = ConnectionState::new();
let addr = Felt::from_hex_unchecked("0x123");
state
.pending
.insert(1, SubscriptionKind::Events { address: addr });
state
.pending
.insert(2, SubscriptionKind::Transactions { address: addr });
state.confirm_subscribe(1, "sub_events".to_string());
state.confirm_subscribe(2, "sub_txs".to_string());
assert!(state.subscriptions.contains_key("sub_events"));
assert!(state.subscriptions.contains_key("sub_txs"));
assert_eq!(state.address_subs[&addr].len(), 2);
let removed = state.remove_address(addr);
assert_eq!(removed.len(), 2);
assert!(state.subscriptions.is_empty());
}
#[test]
fn handle_event_tx_executed_broadcasts_ws_event() {
use crate::app::actions::Action;
use tokio::sync::mpsc;
let address = Felt::from_hex_unchecked(
"0x03a496b92d292386ad70dab94ae181a06d289440e3b632a2435721b4280874c4",
);
let tx_hash_hex = "0x0136e683b9f88958252cc44987fabb06483ead59d65b86a8521886637a5bd08d";
let selector = crate::data::pathfinder::TRANSACTION_EXECUTED_SELECTOR;
let event_json = format!(
r#"{{
"from_address": "{address:#x}",
"keys": ["{sel}"],
"data": [],
"block_hash": "0xabc",
"block_number": 8914198,
"transaction_hash": "{tx}",
"transaction_index": 0,
"event_index": 0,
"finality_status": "ACCEPTED_ON_L2"
}}"#,
sel = selector,
tx = tx_hash_hex,
);
let result: Value = serde_json::from_str(&event_json).unwrap();
let (tx, mut rx) = mpsc::unbounded_channel();
let ds = test_data_source();
super::handle_event(&result, address, &ds, &tx);
let mut actions: Vec<Action> = Vec::new();
while let Ok(a) = rx.try_recv() {
actions.push(a);
}
let ws_event = actions.iter().find_map(|a| match a {
Action::AddressWsEvent { address: ca, event } if *ca == address => Some(event),
_ => None,
});
let ev = ws_event.expect("TRANSACTION_EXECUTED must emit AddressWsEvent");
assert_eq!(
ev.keys.first().copied(),
Some(super::tx_executed_selector()),
"first key must be TRANSACTION_EXECUTED selector so the reducer \
dispatches ClassifyPotentialMetaTx"
);
assert_eq!(ev.transaction_hash, Felt::from_hex_unchecked(tx_hash_hex));
assert_eq!(ev.block_number, 8914198);
}
#[test]
fn handle_event_non_tx_executed_broadcasts_with_other_key() {
use crate::app::actions::Action;
use tokio::sync::mpsc;
let address = Felt::from_hex_unchecked(
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
);
let other_selector = "0x0099cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9";
let event_json = format!(
r#"{{
"from_address": "{address:#x}",
"keys": ["{sel}"],
"data": [],
"block_hash": "0xabc",
"block_number": 100,
"transaction_hash": "0xdef",
"transaction_index": 0,
"event_index": 0,
"finality_status": "ACCEPTED_ON_L2"
}}"#,
sel = other_selector,
);
let result: Value = serde_json::from_str(&event_json).unwrap();
let (tx, mut rx) = mpsc::unbounded_channel();
let ds = test_data_source();
super::handle_event(&result, address, &ds, &tx);
let mut actions: Vec<Action> = Vec::new();
while let Ok(a) = rx.try_recv() {
actions.push(a);
}
let ws_event = actions.iter().find_map(|a| match a {
Action::AddressWsEvent { address: ca, event } if *ca == address => Some(event),
_ => None,
});
let ev = ws_event.expect("non-TRANSACTION_EXECUTED event must still emit AddressWsEvent");
assert_ne!(
ev.keys.first().copied(),
Some(super::tx_executed_selector()),
"first key must NOT match TRANSACTION_EXECUTED selector"
);
}
#[test]
fn resume_replays_from_last_head_within_node_window() {
let mut r = Resume::default();
assert_eq!(r.replay_from(Some(1_000)), None, "nothing seen yet → tip");
r.last_head = Some(10_000);
assert_eq!(r.replay_from(None), Some(10_000 - RESUME_OVERLAP_BLOCKS));
assert_eq!(
r.replay_from(Some(10_100)),
Some(10_000 - RESUME_OVERLAP_BLOCKS)
);
assert_eq!(
r.replay_from(Some(50_000)),
Some(50_000 - MAX_RESUME_BLOCKS)
);
let a = Felt::from(1_u64);
r.add(a);
r.add(a);
assert_eq!(r.addresses, vec![a]);
r.remove(a);
assert!(r.addresses.is_empty());
}
fn test_sink() -> (
impl SinkExt<Message, Error = tokio_tungstenite::tungstenite::Error> + Unpin,
futures::channel::mpsc::UnboundedReceiver<Message>,
) {
let (tx, rx) = futures::channel::mpsc::unbounded::<Message>();
let sink = tx.sink_map_err(|_| tokio_tungstenite::tungstenite::Error::ConnectionClosed);
(sink, rx)
}
fn sent_json(rx: &mut futures::channel::mpsc::UnboundedReceiver<Message>) -> Value {
match rx.try_recv().expect("a frame was sent") {
Message::Text(t) => serde_json::from_str(&t).unwrap(),
other => panic!("unexpected frame {other:?}"),
}
}
#[tokio::test]
async fn replay_subscribe_carries_block_id() {
let (mut sink, mut rx) = test_sink();
let mut state = ConnectionState::new();
let address = Felt::from(0x49d_u64);
send_subscribe_cmd(
&mut sink,
&mut state,
&WsCommand::SubscribeTransfers { address },
Some(123),
)
.await
.unwrap();
for _ in 0..2 {
let v = sent_json(&mut rx);
assert_eq!(v["params"]["block_id"]["block_number"], 123);
}
assert_eq!(
state.fallbacks.len(),
2,
"each replaying request keeps a fallback"
);
let mut fresh = ConnectionState::new();
send_subscribe_cmd(
&mut sink,
&mut fresh,
&WsCommand::SubscribeEvents { address },
None,
)
.await
.unwrap();
assert!(sent_json(&mut rx)["params"].get("block_id").is_none());
assert!(fresh.fallbacks.is_empty());
}
#[tokio::test]
async fn rejected_replay_resubscribes_from_tip() {
let (mut sink, mut rx) = test_sink();
let mut state = ConnectionState::new();
let address = Felt::from(0x49d_u64);
send_subscribe_cmd(
&mut sink,
&mut state,
&WsCommand::SubscribeEvents { address },
Some(123),
)
.await
.unwrap();
let req_id = sent_json(&mut rx)["id"].as_u64().unwrap();
let (resp_tx, _resp_rx) = tokio::sync::mpsc::unbounded_channel();
let (block_tx, _block_rx) = tokio::sync::mpsc::unbounded_channel();
let head = Arc::new(crate::network::HeadTracker::new());
let err = format!(
r#"{{"jsonrpc":"2.0","error":{{"code":68,"message":"Cannot go back more than 1024 blocks"}},"id":{req_id}}}"#
);
handle_message(
&err,
&mut sink,
&mut state,
&test_data_source(),
&resp_tx,
&head,
&block_tx,
)
.await;
let retry = sent_json(&mut rx);
assert_eq!(retry["method"], "starknet_subscribeEvents");
assert!(retry["params"].get("block_id").is_none());
let retry_id = retry["id"].as_u64().unwrap();
assert!(matches!(
state.pending.get(&retry_id),
Some(SubscriptionKind::Events { address: a }) if *a == address
));
assert!(
state.fallbacks.is_empty(),
"the tip retry has no further fallback"
);
}
}