v0.3.12-pre.008

crates/ksp-onchain-transport-lib/src/grpc_stream.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/grpc_stream.rs
-// version: 3
+// version: 4
 
 use tonic_prost::prost::Message; // rust-rules: trait-import
 
@@ -39,6 +39,43 @@ pub struct YellowstoneGrpcSubscribeSnapshot {
     terminal_error_code: std::option::Option<ksp_core_lib::ErrorCode>,
 }
 
+/// Cloneable latest-value observer for one standard Yellowstone Subscribe session snapshot.
+///
+/// The observer exposes only the already-safe transport snapshot and keeps the internal Tokio watch channel private. Cloning the observer does not duplicate
+/// the gRPC stream, request state or reconnect actor.
+#[derive(Clone)]
+pub struct YellowstoneGrpcSubscribeSnapshotSource {
+    receiver: tokio::sync::watch::Receiver<crate::YellowstoneGrpcSubscribeSnapshot>,
+}
+
+impl crate::YellowstoneGrpcSubscribeSnapshotSource {
+    fn new(receiver: tokio::sync::watch::Receiver<crate::YellowstoneGrpcSubscribeSnapshot>) -> Self {
+        return Self { receiver };
+    }
+
+    /// Returns the current safe reconnect/replay snapshot without waiting for another actor transition.
+    #[must_use]
+    pub fn current(&self) -> crate::YellowstoneGrpcSubscribeSnapshot {
+        return *self.receiver.borrow();
+    }
+
+    /// Waits for one newer safe reconnect/replay snapshot.
+    ///
+    /// `None` means the owning Subscribe actor dropped the latest-value publisher and no further snapshot can arrive.
+    pub async fn wait_for_change(&mut self) -> std::option::Option<crate::YellowstoneGrpcSubscribeSnapshot> {
+        return match self.receiver.changed().await {
+            std::result::Result::Ok(()) => std::option::Option::Some(*self.receiver.borrow_and_update()),
+            std::result::Result::Err(_) => std::option::Option::None,
+        };
+    }
+}
+
+impl std::fmt::Debug for crate::YellowstoneGrpcSubscribeSnapshotSource {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.debug_struct("YellowstoneGrpcSubscribeSnapshotSource").field("current", &self.current()).finish();
+    }
+}
+
 impl YellowstoneGrpcSubscribeSnapshot {
     const fn new(initial_from_slot: std::option::Option<u64>) -> Self {
         return Self {
@@ -154,6 +191,12 @@ impl SolanaYellowstoneGrpcSubscribeSession {
         return *self.snapshot_rx.borrow();
     }
 
+    /// Returns one cloneable latest-value observer for reconnect/replay snapshot transitions.
+    #[must_use]
+    pub fn snapshot_source(&self) -> crate::YellowstoneGrpcSubscribeSnapshotSource {
+        return crate::YellowstoneGrpcSubscribeSnapshotSource::new(self.snapshot_rx.clone());
+    }
+
     /// Queues one complete standard Yellowstone request mutation without waiting for network dispatch.
     ///
     /// The mutation is rejected synchronously when local validation fails, the encoded request exceeds the configured outbound bound, the bounded request

crates/ksp-onchain-transport-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/lib.rs
-// version: 45
+// version: 46
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -143,6 +143,8 @@ pub use self::grpc_settings::YellowstoneGrpcTransportSettings;
 pub use self::grpc_stream::SolanaYellowstoneGrpcSubscribeSession;
 /// Safe Yellowstone reconnect/replay continuity snapshot.
 pub use self::grpc_stream::YellowstoneGrpcSubscribeSnapshot;
+/// Cloneable latest-value observer for one standard Yellowstone Subscribe session snapshot.
+pub use self::grpc_stream::YellowstoneGrpcSubscribeSnapshotSource;
 /// Safe Yellowstone bidirectional Subscribe lifecycle state.
 pub use self::grpc_stream::YellowstoneGrpcSubscribeState;
 /// One validated standard Yellowstone account predicate.