yellowstone-fumarole-client 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

yellowstone_fumarole_client/__init__.py

@@ -3,18 +3,21 @@ import logging
 from yellowstone_fumarole_client.grpc_connectivity import (
     FumaroleGrpcConnector,
 )
-from typing import Dict, Optional
+from typing import AsyncGenerator, Optional
 from dataclasses import dataclass
 from yellowstone_fumarole_client.config import FumaroleConfig
 from yellowstone_fumarole_client.runtime.aio import (
     AsyncioFumeDragonsmouthRuntime,
-    FumaroleSM,
     DEFAULT_GC_INTERVAL,
     DEFAULT_SLOT_MEMORY_RETENTION,
     GrpcSlotDownloader,
 )
+from yellowstone_fumarole_client.runtime.state_machine import (
+    FumaroleSM,
+    FumeOffset,
+)
 from yellowstone_fumarole_proto.geyser_pb2 import SubscribeRequest, SubscribeUpdate
-from yellowstone_fumarole_proto.fumarole_v2_pb2 import (
+from yellowstone_fumarole_proto.fumarole_pb2 import (
     ControlResponse,
     VersionRequest,
     VersionResponse,
@@ -29,9 +32,11 @@ from yellowstone_fumarole_proto.fumarole_v2_pb2 import (
     CreateConsumerGroupRequest,
     CreateConsumerGroupResponse,
 )
-from yellowstone_fumarole_proto.fumarole_v2_pb2_grpc import FumaroleStub
+from yellowstone_fumarole_proto.fumarole_pb2_grpc import FumaroleStub
 import grpc
 
+from yellowstone_fumarole_client import config
+
 __all__ = [
     "FumaroleClient",
     "FumaroleConfig",
@@ -44,7 +49,7 @@ __all__ = [
 ]
 
 # Constants
-DEFAULT_DRAGONSMOUTH_CAPACITY = 10000
+DEFAULT_DRAGONSMOUTH_CAPACITY = 100000
 DEFAULT_COMMIT_INTERVAL = 5.0  # seconds
 DEFAULT_MAX_SLOT_DOWNLOAD_ATTEMPT = 3
 DEFAULT_CONCURRENT_DOWNLOAD_LIMIT_PER_TCP = 10
@@ -72,10 +77,23 @@ class FumaroleSubscribeConfig:
     # The interval at which to perform garbage collection on the slot memory.
     gc_interval: int = DEFAULT_GC_INTERVAL
 
-    # The retention period for slot memory in seconds.
+    # How many processed slot numbers to retain in memory to avoid duplication.
     slot_memory_retention: int = DEFAULT_SLOT_MEMORY_RETENTION
 
 
+@dataclass
+class FumaroleSubscribeStats:
+    """Commit/slot statistics for the Fumarole subscribe session."""
+
+    # Last committed log offset in Fumarole -- this is a low-level, implementation detail.
+    # NOTE: this should not be part as business logic, can change any time.
+    log_committed_offset: FumeOffset
+    # NOTE:: this is a low-level information, can change any time.
+    log_committable_offset: FumeOffset
+    # Max slot seen by the in the current session - does not mean it has been processed.
+    max_slot_seen: int
+
+
 # DragonsmouthAdapterSession
 @dataclass
 class DragonsmouthAdapterSession:
@@ -85,10 +103,31 @@ class DragonsmouthAdapterSession:
     sink: asyncio.Queue
 
     # The queue for receiving SubscribeUpdate from the dragonsmouth stream.
-    source: asyncio.Queue
+    source: AsyncGenerator[SubscribeUpdate, None]
 
     # The task handle for the fumarole runtime.
-    fumarole_handle: asyncio.Task
+    _fumarole_handle: asyncio.Task
+
+    _sm: FumaroleSM
+
+    async def __aenter__(self):
+        """Enter the session context."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        self.sink.shutdown()
+        self._fumarole_handle.cancel()
+
+    def stats(self) -> FumaroleSubscribeStats:
+        """Get low-level statistics of the Fumarole state-machine."""
+        commitable = self._sm.committable_offset
+        committed = self._sm.last_committed_offset
+        max_slot = self._sm.max_slot_detected
+        return FumaroleSubscribeStats(
+            log_committed_offset=committed,
+            log_committable_offset=commitable,
+            max_slot_seen=max_slot,
+        )
 
 
 # FumaroleClient
@@ -162,7 +201,7 @@ class FumaroleClient:
                 try:
                     update = await fume_control_plane_q.get()
                     yield update
-                except asyncio.QueueShutDown:
+                except (asyncio.CancelledError, asyncio.QueueShutDown):
                     break
 
         fume_control_plane_stream_rx: grpc.aio.StreamStreamCall = self.stub.Subscribe(
@@ -187,8 +226,12 @@ class FumaroleClient:
                         await fume_control_plane_rx_q.put(update)
                 except asyncio.QueueShutDown:
                     break
+                except asyncio.CancelledError:
+                    break
+                finally:
+                    fume_control_plane_rx_q.shutdown()
 
-        _cp_src_task = asyncio.create_task(control_plane_source())
+        control_plane_src_task = asyncio.create_task(control_plane_source())
 
         FumaroleClient.logger.debug(f"Control response: {control_response}")
 
@@ -219,12 +262,38 @@ class FumaroleClient:
             max_concurrent_download=config.concurrent_download_limit,
         )
 
-        fumarole_handle = asyncio.create_task(rt.run())
-        FumaroleClient.logger.debug(f"Fumarole handle created: {fumarole_handle}")
+        async def rt_run(rt):
+            async with rt as rt:
+                await rt.run()
+
+        rt_task = asyncio.create_task(rt_run(rt))
+
+        async def fumarole_overseer():
+            done, pending = await asyncio.wait(
+                [rt_task, control_plane_src_task], return_when=asyncio.FIRST_COMPLETED
+            )
+            for t in pending:
+                t.cancel()
+
+        fumarole_handle = asyncio.create_task(fumarole_overseer())
+
+        async def source_gen() -> AsyncGenerator[SubscribeUpdate, None]:
+            try:
+                while True:
+                    update = await dragonsmouth_outlet.get()
+                    yield update
+            except asyncio.CancelledError:
+                pass
+            except asyncio.Queue:
+                pass
+            finally:
+                dragonsmouth_outlet.shutdown()
+
         return DragonsmouthAdapterSession(
             sink=subscribe_request_queue,
-            source=dragonsmouth_outlet,
-            fumarole_handle=fumarole_handle,
+            source=source_gen(),
+            _fumarole_handle=fumarole_handle,
+            _sm=sm,
         )
 
     async def list_consumer_groups(

yellowstone_fumarole_client/config.py

@@ -1,14 +1,19 @@
 from dataclasses import dataclass
-from typing import Dict, Optional
+from typing import Dict, Literal, Optional
 import yaml
 
 
+SUPPORTED_COMPRESSION = ["gzip"]
+SupportedCompression = Literal["gzip"]
+
+
 @dataclass
 class FumaroleConfig:
     endpoint: str
     x_token: Optional[str] = None
     max_decoding_message_size_bytes: int = 512_000_000
     x_metadata: Dict[str, str] = None
+    response_compression: Optional[SupportedCompression] = None
 
     def __post_init__(self):
         self.x_metadata = self.x_metadata or {}
@@ -16,6 +21,14 @@ class FumaroleConfig:
     @classmethod
     def from_yaml(cls, fileobj) -> "FumaroleConfig":
         data = yaml.safe_load(fileobj)
+        response_compression = data.get(
+            "response_compression", cls.response_compression
+        )
+        if (
+            response_compression is not None
+            and response_compression not in SUPPORTED_COMPRESSION
+        ):
+            raise ValueError(f"response_compression must be in {SUPPORTED_COMPRESSION}")
         return cls(
             endpoint=data["endpoint"],
             x_token=data.get("x-token") or data.get("x_token"),
@@ -23,4 +36,7 @@ class FumaroleConfig:
                 "max_decoding_message_size_bytes", cls.max_decoding_message_size_bytes
             ),
             x_metadata=data.get("x-metadata", {}),
+            response_compression=data.get(
+                "response_compression", cls.response_compression
+            ),
         )

yellowstone_fumarole_client/grpc_connectivity.py

@@ -2,7 +2,7 @@ import logging
 from typing import Optional
 import grpc
 from yellowstone_fumarole_client.config import FumaroleConfig
-from yellowstone_fumarole_proto.fumarole_v2_pb2_grpc import FumaroleStub
+from yellowstone_fumarole_proto.fumarole_pb2_grpc import FumaroleStub
 
 X_TOKEN_HEADER = "x-token"
 
@@ -31,34 +31,8 @@ class TritonAuthMetadataPlugin(grpc.AuthMetadataPlugin):
         return _triton_sign_request(callback, self.x_token, None)
 
 
-def grpc_channel(endpoint: str, x_token=None, compression=None, *grpc_options):
-    options = [("grpc.max_receive_message_length", 111111110), *grpc_options]
-    if x_token is not None:
-        auth = TritonAuthMetadataPlugin(x_token)
-        # ssl_creds allow you to use our https endpoint
-        # grpc.ssl_channel_credentials with no arguments will look through your CA trust store.
-        ssl_creds = grpc.ssl_channel_credentials()
-
-        # call credentials will be sent on each request if setup with composite_channel_credentials.
-        call_creds: grpc.CallCredentials = grpc.metadata_call_credentials(auth)
-
-        # Combined creds will store the channel creds aswell as the call credentials
-        combined_creds = grpc.composite_channel_credentials(ssl_creds, call_creds)
-
-        return grpc.secure_channel(
-            endpoint,
-            credentials=combined_creds,
-            compression=compression,
-            options=options,
-        )
-    else:
-        return grpc.insecure_channel(endpoint, compression=compression, options=options)
-
-
 # Because of a bug in grpcio library, multiple inheritance of ClientInterceptor subclasses does not work.
 # You have to create a new class for each type of interceptor you want to use.
-
-
 class MetadataInterceptor(
     grpc.aio.UnaryStreamClientInterceptor,
     grpc.aio.StreamUnaryClientInterceptor,
@@ -166,6 +140,11 @@ class FumaroleGrpcConnector:
     async def connect(self, *grpc_options) -> FumaroleStub:
         options = [("grpc.max_receive_message_length", 111111110), *grpc_options]
         interceptors = MetadataInterceptor(self.config.x_metadata).interceptors()
+        compression = (
+            grpc.Compression.Gzip
+            if self.config.response_compression == "gzip"
+            else None
+        )
         if self.config.x_token is not None:
             auth = TritonAuthMetadataPlugin(self.config.x_token)
             # ssl_creds allow you to use our https endpoint
@@ -184,6 +163,7 @@ class FumaroleGrpcConnector:
                 self.endpoint,
                 credentials=combined_creds,
                 options=options,
+                compression=compression,
                 interceptors=interceptors,
             )
         else:
@@ -191,7 +171,10 @@ class FumaroleGrpcConnector:
                 "Using insecure channel without authentication"
             )
             channel = grpc.aio.insecure_channel(
-                self.endpoint, options=options, interceptors=interceptors
+                self.endpoint,
+                options=options,
+                interceptors=interceptors,
+                compression=compression,
             )
 
         return FumaroleStub(channel)

yellowstone_fumarole_client/runtime/aio.py

@@ -1,10 +1,9 @@
 # DataPlaneConn
 from abc import abstractmethod, ABC
 import asyncio
-import uuid
 import grpc
-from typing import Optional, List
-from collections import abc, deque
+from typing import Optional
+from collections import deque
 from dataclasses import dataclass
 import time
 from yellowstone_fumarole_client.runtime.state_machine import (
@@ -19,7 +18,7 @@ from yellowstone_fumarole_proto.geyser_pb2 import (
     SubscribeUpdateSlot,
     CommitmentLevel as ProtoCommitmentLevel,
 )
-from yellowstone_fumarole_proto.fumarole_v2_pb2 import (
+from yellowstone_fumarole_proto.fumarole_pb2 import (
     ControlCommand,
     PollBlockchainHistory,
     CommitOffset,
@@ -27,7 +26,7 @@ from yellowstone_fumarole_proto.fumarole_v2_pb2 import (
     DownloadBlockShard,
     BlockFilters,
 )
-from yellowstone_fumarole_proto.fumarole_v2_pb2_grpc import (
+from yellowstone_fumarole_proto.fumarole_pb2_grpc import (
     FumaroleStub,
 )
 from yellowstone_fumarole_client.utils.aio import Interval
@@ -84,6 +83,12 @@ class AsyncSlotDownloader(ABC):
         pass
 
 
+SUBSCRIBE_REQ_UPDATE_TYPE_MARKER: int = 1
+CONTROL_PLANE_RESP_TYPE_MARKER: int = 2
+COMMIT_TICK_TYPE_MARKER: int = 3
+DOWNLOAD_TASK_TYPE_MARKER: int = 4
+
+
 # TokioFumeDragonsmouthRuntime
 class AsyncioFumeDragonsmouthRuntime:
     """Asynchronous runtime for Fumarole with Dragonsmouth-like stream support."""
@@ -119,17 +124,32 @@ class AsyncioFumeDragonsmouthRuntime:
         """
         self.sm = sm
         self.slot_downloader: AsyncSlotDownloader = slot_downloader
-        self.subscribe_request_update_q = subscribe_request_update_q
+        self.subscribe_request_update_rx: asyncio.Queue = subscribe_request_update_q
         self.subscribe_request = subscribe_request
         self.consumer_group_name = consumer_group_name
-        self.control_plane_tx = control_plane_tx_q
-        self.control_plane_rx = control_plane_rx_q
-        self.dragonsmouth_outlet = dragonsmouth_outlet
+        self.control_plane_tx: asyncio.Queue = control_plane_tx_q
+        self.control_plane_rx: asyncio.Queue = control_plane_rx_q
+        self.dragonsmouth_outlet: asyncio.Queue = dragonsmouth_outlet
         self.commit_interval = commit_interval
         self.gc_interval = gc_interval
         self.max_concurrent_download = max_concurrent_download
+
+        # holds metadata about the download task
         self.download_tasks = dict()
-        self.inner_runtime_channel: asyncio.Queue = asyncio.Queue()
+        self.inflight_tasks = dict()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await self.aclose()
+
+    async def aclose(self):
+        self.control_plane_tx.shutdown()
+        self.dragonsmouth_outlet.shutdown()
+        for t, kind in self.inflight_tasks.items():
+            LOGGER.debug(f"closing {kind} task")
+            t.cancel()
 
     def _build_poll_history_cmd(
         self, from_offset: Optional[FumeOffset]
@@ -195,8 +215,9 @@ class AsyncioFumeDragonsmouthRuntime:
             coro = self.slot_downloader.run_download(
                 self.subscribe_request, download_task_args
             )
-            donwload_task = asyncio.create_task(coro)
-            self.download_tasks[donwload_task] = download_request
+            download_task = asyncio.create_task(coro)
+            self.download_tasks[download_task] = download_request
+            self.inflight_tasks[download_task] = DOWNLOAD_TASK_TYPE_MARKER
             LOGGER.debug(f"Scheduling download task for slot {download_request.slot}")
 
     def _handle_download_result(self, download_result: DownloadTaskResult):
@@ -219,10 +240,10 @@ class AsyncioFumeDragonsmouthRuntime:
         )
 
     async def _commit_offset(self):
+        self.last_commit = time.time()
         if self.sm.last_committed_offset < self.sm.committable_offset:
             LOGGER.debug(f"Committing offset {self.sm.committable_offset}")
             await self._force_commit_offset()
-        self.last_commit = time.time()
 
     async def _drain_slot_status(self):
         """Drains the slot status from the state machine and sends updates to the Dragonsmouth outlet."""
@@ -245,8 +266,10 @@ class AsyncioFumeDragonsmouthRuntime:
                     matched_filters.append(filter_name)
                 elif not filter.filter_by_commitment:
                     matched_filters.append(filter_name)
-
             if matched_filters:
+                LOGGER.debug(
+                    f"Matched {len(matched_filters)} filters for SlotStatus Update"
+                )
                 update = SubscribeUpdate(
                     filters=matched_filters,
                     created_at=None,
@@ -257,10 +280,7 @@ class AsyncioFumeDragonsmouthRuntime:
                         dead_error=slot_status.dead_error,
                     ),
                 )
-                try:
-                    await self.dragonsmouth_outlet.put(update)
-                except asyncio.QueueFull:
-                    return
+                await self.dragonsmouth_outlet.put(update)
 
             self.sm.mark_event_as_processed(slot_status.session_sequence)
 
@@ -286,16 +306,19 @@ class AsyncioFumeDragonsmouthRuntime:
         LOGGER.debug("Initial commit offset command sent")
         ticks = 0
 
-        task_map = {
+        self.inflight_tasks = {
+            asyncio.create_task(
+                self.subscribe_request_update_rx.get()
+            ): SUBSCRIBE_REQ_UPDATE_TYPE_MARKER,
+            asyncio.create_task(
+                self.control_plane_rx.get()
+            ): CONTROL_PLANE_RESP_TYPE_MARKER,
             asyncio.create_task(
-                self.subscribe_request_update_q.get()
-            ): "dragonsmouth_bidi",
-            asyncio.create_task(self.control_plane_rx.get()): "control_plane_rx",
-            asyncio.create_task(Interval(self.commit_interval).tick()): "commit_tick",
+                Interval(self.commit_interval).tick()
+            ): COMMIT_TICK_TYPE_MARKER,
         }
 
-        pending = set(task_map.keys())
-        while pending:
+        while self.inflight_tasks:
             ticks += 1
             LOGGER.debug(f"Runtime loop tick")
             if ticks % self.gc_interval == 0:
@@ -306,58 +329,51 @@ class AsyncioFumeDragonsmouthRuntime:
             await self.poll_history_if_needed()
             LOGGER.debug("Scheduling download tasks if any")
             self._schedule_download_task_if_any()
-            for t in self.download_tasks.keys():
-                pending.add(t)
-                task_map[t] = "download_task"
-
             download_task_inflight = len(self.download_tasks)
             LOGGER.debug(
                 f"Current download tasks in flight: {download_task_inflight} / {self.max_concurrent_download}"
             )
-            done, pending = await asyncio.wait(
-                pending, return_when=asyncio.FIRST_COMPLETED
+            done, _pending = await asyncio.wait(
+                self.inflight_tasks.keys(), return_when=asyncio.FIRST_COMPLETED
             )
             for t in done:
                 result = t.result()
-                name = task_map.pop(t)
-                match name:
-                    case "dragonsmouth_bidi":
-                        LOGGER.debug("Dragonsmouth subscribe request received")
-                        assert isinstance(
-                            result, SubscribeRequest
-                        ), "Expected SubscribeRequest"
-                        self.handle_new_subscribe_request(result)
-                        new_task = asyncio.create_task(
-                            self.subscribe_request_update_q.get()
-                        )
-                        task_map[new_task] = "dragonsmouth_bidi"
-                        pending.add(new_task)
-                        pass
-                    case "control_plane_rx":
-                        LOGGER.debug("Control plane response received")
-                        if not await self._handle_control_plane_resp(result):
-                            LOGGER.debug("Control plane error")
-                            return
-                        new_task = asyncio.create_task(self.control_plane_rx.get())
-                        task_map[new_task] = "control_plane_rx"
-                        pending.add(new_task)
-                    case "download_task":
-                        LOGGER.debug("Download task result received")
-                        assert self.download_tasks.pop(t)
-                        self._handle_download_result(result)
-                    case "commit_tick":
-                        LOGGER.debug("Commit tick reached")
-                        await self._commit_offset()
-                        new_task = asyncio.create_task(
-                            Interval(self.commit_interval).tick()
-                        )
-                        task_map[new_task] = "commit_tick"
-                        pending.add(new_task)
-                    case unknown:
-                        raise RuntimeError(f"Unexpected task name: {unknown}")
+                sigcode = self.inflight_tasks.pop(t)
+                if sigcode == SUBSCRIBE_REQ_UPDATE_TYPE_MARKER:
+                    LOGGER.debug("Dragonsmouth subscribe request received")
+                    assert isinstance(
+                        result, SubscribeRequest
+                    ), "Expected SubscribeRequest"
+                    self.handle_new_subscribe_request(result)
+                    new_task = asyncio.create_task(
+                        self.subscribe_request_update_rx.get()
+                    )
+                    self.inflight_tasks[new_task] = SUBSCRIBE_REQ_UPDATE_TYPE_MARKER
+                    pass
+                elif sigcode == CONTROL_PLANE_RESP_TYPE_MARKER:
+                    LOGGER.debug("Control plane response received")
+                    if not await self._handle_control_plane_resp(result):
+                        LOGGER.debug("Control plane error")
+                        return
+                    new_task = asyncio.create_task(self.control_plane_rx.get())
+                    self.inflight_tasks[new_task] = CONTROL_PLANE_RESP_TYPE_MARKER
+                elif sigcode == DOWNLOAD_TASK_TYPE_MARKER:
+                    LOGGER.debug("Download task result received")
+                    assert self.download_tasks.pop(t)
+                    self._handle_download_result(result)
+                elif sigcode == COMMIT_TICK_TYPE_MARKER:
+                    LOGGER.debug("Commit tick reached")
+                    await self._commit_offset()
+                    new_task = asyncio.create_task(
+                        Interval(self.commit_interval).tick()
+                    )
+                    self.inflight_tasks[new_task] = COMMIT_TICK_TYPE_MARKER
+                else:
+                    raise RuntimeError(f"Unexpected task name: {sigcode}")
 
             await self._drain_slot_status()
 
+        self.aclose()
         LOGGER.debug("Fumarole runtime exiting")
 
 

yellowstone_fumarole_client/runtime/state_machine.py

@@ -1,12 +1,11 @@
-from typing import Optional, List, Dict, Set, Deque, Tuple, Any, Sequence
+from typing import Optional, Set, Deque, Sequence
 from collections import deque, defaultdict
-from yellowstone_fumarole_proto.fumarole_v2_pb2 import (
+from yellowstone_fumarole_proto.fumarole_pb2 import (
     CommitmentLevel,
     BlockchainEvent,
 )
 from yellowstone_fumarole_client.utils.collections import OrderedSet
 import heapq
-import uuid
 from enum import Enum
 
 __all__ = [

yellowstone_fumarole_client/utils/aio.py

@@ -1,6 +1,5 @@
 import asyncio
 import logging
-from typing import Any, Coroutine
 
 LOGGER = logging.getLogger(__name__)
 

{yellowstone_fumarole_client-0.1.0.dist-info → yellowstone_fumarole_client-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: yellowstone-fumarole-client
-Version: 0.1.0
+Version: 0.2.0
 Summary: Yellowstone Fumarole Python Client
 Home-page: https://github.com/rpcpool/yellowstone-fumarole
 Author: Louis-Vincent
@@ -9,7 +9,7 @@ Requires-Python: >=3.13,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: grpcio (>=1.71.1,<2.0.0)
-Requires-Dist: protobuf (>=5.29.1,<6.0.0)
+Requires-Dist: protobuf (>=6.32.0,<7.0.0)
 Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
 Project-URL: Repository, https://github.com/rpcpool/yellowstone-fumarole
 Description-Content-Type: text/markdown
@@ -78,33 +78,43 @@ async def dragonsmouth_like_session(fumarole_config):
     session = await client.dragonsmouth_subscribe(
         consumer_group_name="test",
         request=SubscribeRequest(
-            # accounts={"fumarole": SubscribeRequestFilterAccounts()},
+            accounts={"fumarole": SubscribeRequestFilterAccounts()},
             transactions={"fumarole": SubscribeRequestFilterTransactions()},
             blocks_meta={"fumarole": SubscribeRequestFilterBlocksMeta()},
             entry={"fumarole": SubscribeRequestFilterEntry()},
             slots={"fumarole": SubscribeRequestFilterSlots()},
         ),
     )
-    dragonsmouth_source = session.source
-    handle = session.fumarole_handle
-    block_map = defaultdict(BlockConstruction)
-    while True:
-        tasks = [asyncio.create_task(dragonsmouth_source.get()), handle]
-        done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
-        for t in done:
-            if tasks[0] == t:
-                result: SubscribeUpdate = t.result()
-                if result.HasField("block_meta"):
-                    block_meta: SubscribeUpdateBlockMeta = result.block_meta
-                elif result.HasField("transaction"):
-                    tx: SubscribeUpdateTransaction = result.transaction
-                elif result.HasField("account"):
-                    account: SubscribeUpdateAccount = result.account
-                elif result.HasField("entry"):
-                    entry: SubscribeUpdateEntry = result.entry
-                elif result.HasField("slot"):
-                    result: SubscribeUpdateSlot = result.slot
-            else:
-                result = t.result()
-                raise RuntimeError("failed to get dragonsmouth source: %s" % result)
+    async with session:
+        dragonsmouth_like_source = session.source
+        # result: SubscribeUpdate
+        async for result in dragonsmouth_like_source:
+            if result.HasField("block_meta"):
+                block_meta: SubscribeUpdateBlockMeta = result.block_meta
+            elif result.HasField("transaction"):
+                tx: SubscribeUpdateTransaction = result.transaction
+            elif result.HasField("account"):
+                account: SubscribeUpdateAccount = result.account
+            elif result.HasField("entry"):
+                entry: SubscribeUpdateEntry = result.entry
+            elif result.HasField("slot"):
+                result: SubscribeUpdateSlot = result.slot
+
+    # OUTSIDE THE SCOPE, YOU SHOULD NEVER USE `session` again.
+```
+
+
+At any point you can get a rough estimate if you are progression through the slot using `DragonsmouthAdapterSession.stats()` call:
+
+```python
+
+async with session:
+    stats: FumaroleSubscribeStats = session.stats()
+    print(f"{stats.log_committed_offset}, {stats.log_committable_offset}, {stats.max_slot_seen}")
 ```
+
+`log_committed_offset` : what have been ACK so for to fumarole remote service.
+`log_committable_offset` : what can be ACK to next commit call.
+`max_slot_seen` : maximum slot seen in the inner fumarole client state -- not yet processed by your code.
+
+

yellowstone_fumarole_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+yellowstone_fumarole_client/__init__.py,sha256=-UQcnKGG7D7cTcMMXE98y8nIqc-Xqm0qXA3R0iQ6uks,13381
+yellowstone_fumarole_client/config.py,sha256=aclhCPUy6RO-xtXR9w8otmt1RzFZyFnbF28jk115C2g,1394
+yellowstone_fumarole_client/grpc_connectivity.py,sha256=Sex_x6_Bha0wGD7rRqr-V_slsohX1tDFeiHdqahLJ4Q,6639
+yellowstone_fumarole_client/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yellowstone_fumarole_client/runtime/aio.py,sha256=ydcfIP-FpQ4Cgd5drd35Zm9fd_g6qEhpKkdPQHO7gJM,21364
+yellowstone_fumarole_client/runtime/state_machine.py,sha256=d4blPv62UcqZ0HigRK2IXTd_8MeRrRjhclDVpE0PMnQ,12634
+yellowstone_fumarole_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yellowstone_fumarole_client/utils/aio.py,sha256=lm_BNkPiw5CJ6FjDlQUPoCKAqY3eYFAedAJB8mhNbzE,639
+yellowstone_fumarole_client/utils/collections.py,sha256=BO0kADUKIRkpQ-fRpBtmn5rA7Xu4P4MkJ2rsU2FxfBc,979
+yellowstone_fumarole_proto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yellowstone_fumarole_proto/fumarole_pb2.py,sha256=aF869yXAjiTE5hqpKatzql42N1saAO0ayVQOJJ8sxVs,14315
+yellowstone_fumarole_proto/fumarole_pb2.pyi,sha256=eJgwihIU5wzJVlEZvYlG_F0vaW-z-axONwOoCQtnI-s,20092
+yellowstone_fumarole_proto/fumarole_pb2_grpc.py,sha256=t-d3wKHd8xbHjct7h0IVmeFN3PTP7WPinYwxgDs6mO0,19117
+yellowstone_fumarole_proto/geyser_pb2.py,sha256=95QrgJGuWll2t7XQiLunY20a9prhK4F1tclzXIQS0I0,20169
+yellowstone_fumarole_proto/geyser_pb2.pyi,sha256=7P9cFmkhK05NhTBlPtzPitzXZeAS_kGBbt6teu2PyGk,27187
+yellowstone_fumarole_proto/geyser_pb2_grpc.py,sha256=JCEz0KM_jg_610HyQI_F1K4kJlRGkGsP192XEDTCoYM,15342
+yellowstone_fumarole_proto/solana_storage_pb2.py,sha256=LS-P5EPyS0n1pO9_U73rA6SPlbGSTEC2qYhuS3skzA8,8443
+yellowstone_fumarole_proto/solana_storage_pb2.pyi,sha256=HivhoN4VEe_W7kB4lc2Un5AeTAv3xiKR_HLI096qmyA,13040
+yellowstone_fumarole_proto/solana_storage_pb2_grpc.py,sha256=-rb9Dr0HXohIrHrnxukYrmUYl6OCVbkQYh2-pCO6740,895
+yellowstone_fumarole_client-0.2.0.dist-info/METADATA,sha256=P90eNzQ2clW8LALfQZfvye9h5YtxZYB1sEdwIo-7uQk,4156
+yellowstone_fumarole_client-0.2.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+yellowstone_fumarole_client-0.2.0.dist-info/RECORD,,