Websockets docs

docs/api.rst

@@ -22,3 +22,4 @@ API
    api/serializers
    api/proxy_resolvers
    api/typed_data
+   api/websocket_client

docs/api/websocket_client.rst

@@ -0,0 +1,8 @@
+WebsocketClient
+===============
+
+.. py:module:: starknet_py.net.websockets.websocket_client
+
+.. autoclass-with-examples:: WebsocketClient
+    :members:
+    :member-order: groupwise

docs/guide.rst

@@ -10,3 +10,4 @@ Guide
     guide/serialization
     guide/signing
     guide/generating_key_pair
+    guide/websockets

docs/guide/websockets.rst

@@ -0,0 +1,98 @@
+Websockets
+==========
+
+Introduction
+------------
+Apart from interacting with Starknet by request-response model, you can also rely on real-time notifications.
+Here comes :class:`~starknet_py.net.websockets.websocket_client.WebsocketClient` which allows to establish a connection with Starknet node and listen for events.
+
+Connecting
+----------
+
+To begin interacting with Starknet via websockets, create a new instance of :class:`~starknet_py.net.websockets.websocket_client.WebsocketClient` and connect to the node.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: connect
+    :end-before: docs-end: connect
+
+Different subscription methods
+------------------------------
+
+New block headers
+#################
+
+To subscribe to new block headers, use :meth:`~starknet_py.net.websockets.websocket_client.WebsocketClient.subscribe_new_heads`.
+Every time a new block is created, the event will be fired.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: subscribe_new_heads
+    :end-before: docs-end: subscribe_new_heads
+
+New events
+##########
+
+To subscribe to new events, use :meth:`~starknet_py.net.websockets.websocket_client.WebsocketClient.subscribe_events`.
+Every time a new event is emitted, the event will be fired.
+
+It's possible to filter events by contract addresses, keys and block id. See all options in the method documentation.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: subscribe_events
+    :end-before: docs-end: subscribe_events
+
+
+Transaction status
+##################
+
+To subscribe to transaction status changes, use :meth:`~starknet_py.net.websockets.websocket_client.WebsocketClient.subscribe_transaction_status`.
+Every time a transaction status changes, the event will be fired.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: subscribe_transaction_status
+    :end-before: docs-end: subscribe_transaction_status
+
+
+Pending transactions
+####################
+
+To subscribe to pending transactions, use :meth:`~starknet_py.net.websockets.websocket_client.WebsocketClient.subscribe_pending_transactions`.
+Every time a new pending transaction is added, the event will be fired.
+
+It's possible to filter pending transactions by sender address.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: subscribe_pending_transactions
+    :end-before: docs-end: subscribe_pending_transactions
+
+Handling chain reorganization notifications
+###########################################
+
+When subscribing to new block headers, events, or transaction statuses, you also receive notifications of chain reorganizations. For example, if two blocks are produced nearly simultaneously and one replaces the other as the canonical block, you'll get an update indicating that the chain has restructured.
+To handle them, you need to set the ``on_chain_reorg`` to your custom function.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: on_chain_reorg
+    :end-before: docs-end: on_chain_reorg
+
+Disconnecting
+-------------
+
+To disconnect from the node, use :meth:`~starknet_py.net.websockets.websocket_client.WebsocketClient.disconnect`.
+
+.. codesnippet:: ../../starknet_py/tests/e2e/docs/code_examples/test_websocket_client.py
+    :language: python
+    :dedent: 4
+    :start-after: docs-start: disconnect
+    :end-before: docs-end: disconnect

starknet_py/net/websockets/websocket_client.py

@@ -187,9 +187,9 @@ async def subscribe_pending_transactions(
         While there is no mempool, this notifies of transactions in the pending block.
 
         :param handler: The function to call when a new pending transaction is received.
-        :param transaction_details: Whether to include transaction details in the notification.
-        If false, only hash is returned.
+        :param transaction_details: If false, only hash is returned, otherwise full transaction details.
         :param sender_address: The sender address to filter transactions by.
+
         :return: The subscription ID.
         """
         params = {}
@@ -220,7 +220,7 @@ def on_chain_reorg(
     @on_chain_reorg.setter
     def on_chain_reorg(self, handler: Callable[[ReorgNotification], Any]):
         """
-        Sets the handler for reorg notifications.
+        Sets the handler for chain reorg notifications.
 
         :param handler: The handler for chain reorg notifications.
         """

starknet_py/tests/e2e/client/websocket_client_test.py

@@ -1,68 +1,13 @@
-import asyncio
-from typing import List, Optional, Union
+from typing import Optional
 
 import pytest
 
 from starknet_py.devnet_utils.devnet_client import DevnetClient
-from starknet_py.hash.selector import get_selector_from_name
-from starknet_py.net.account.base_account import BaseAccount
-from starknet_py.net.client_models import (
-    BlockHeader,
-    Call,
-    EmittedEvent,
-    StarknetBlock,
-    TransactionExecutionStatus,
-    TransactionStatus,
-)
+from starknet_py.net.client_models import BlockHeader, StarknetBlock
 from starknet_py.net.full_node_client import FullNodeClient
-from starknet_py.net.models import StarknetChainId
 from starknet_py.net.websockets.errors import WebsocketClientError
-from starknet_py.net.websockets.models import (
-    NewEventsNotification,
-    NewHeadsNotification,
-    NewTransactionStatus,
-    PendingTransactionsNotification,
-    ReorgData,
-    ReorgNotification,
-    Transaction,
-    TransactionStatusNotification,
-)
+from starknet_py.net.websockets.models import NewHeadsNotification
 from starknet_py.net.websockets.websocket_client import WebsocketClient
-from starknet_py.tests.e2e.fixtures.constants import MAX_RESOURCE_BOUNDS
-
-
-@pytest.mark.asyncio
-async def test_connect_and_disconnect(devnet_ws: str):
-    websocket_client = WebsocketClient(devnet_ws)
-    assert not await websocket_client.is_connected
-
-    await websocket_client.connect()
-    assert await websocket_client.is_connected
-
-    await websocket_client.disconnect()
-    assert not await websocket_client.is_connected
-
-
-@pytest.mark.asyncio
-async def test_subscribe_new_heads(
-    websocket_client: WebsocketClient,
-    devnet_client: DevnetClient,
-):
-    received_block: Optional[BlockHeader] = None
-
-    def handler(new_heads_notification: NewHeadsNotification):
-        nonlocal received_block
-        received_block = new_heads_notification.result
-
-    subscription_id = await websocket_client.subscribe_new_heads(handler=handler)
-
-    new_block_hash = await devnet_client.create_block()
-
-    assert received_block is not None
-    assert int(new_block_hash, 16) == received_block.block_hash
-
-    unsubscribe_result = await websocket_client.unsubscribe(subscription_id)
-    assert unsubscribe_result is True
 
 
 @pytest.mark.asyncio
@@ -156,164 +101,6 @@ async def test_subscribe_new_heads_too_many_blocks_back(
         )
 
 
-@pytest.mark.asyncio
-async def test_subscribe_events(
-    websocket_client: WebsocketClient,
-    deployed_balance_contract,
-    argent_account_v040: BaseAccount,
-):
-    emitted_events: List[EmittedEvent] = []
-
-    def handler(new_events_notification: NewEventsNotification):
-        nonlocal emitted_events
-        emitted_events.append(new_events_notification.result)
-
-    subscription_id = await websocket_client.subscribe_events(
-        handler=handler, from_address=argent_account_v040.address
-    )
-
-    increase_balance_call = Call(
-        to_addr=deployed_balance_contract.address,
-        selector=get_selector_from_name("increase_balance"),
-        calldata=[100],
-    )
-    execute = await argent_account_v040.execute_v3(
-        calls=increase_balance_call, resource_bounds=MAX_RESOURCE_BOUNDS
-    )
-    await argent_account_v040.client.wait_for_tx(tx_hash=execute.transaction_hash)
-    await argent_account_v040.client.get_transaction_receipt(
-        tx_hash=execute.transaction_hash
-    )
-
-    assert len(emitted_events) > 0
-    for emitted_event in emitted_events:
-        assert emitted_event.from_address == argent_account_v040.address
-
-    unsubscribe_result = await websocket_client.unsubscribe(subscription_id)
-    assert unsubscribe_result is True
-
-
-@pytest.mark.asyncio
-async def test_subscribe_transaction_status(
-    websocket_client: WebsocketClient,
-    deployed_balance_contract,
-    argent_account_v040: BaseAccount,
-):
-    new_transaction_status: Optional[NewTransactionStatus] = None
-
-    def handler(transaction_status_notification: TransactionStatusNotification):
-        nonlocal new_transaction_status
-        new_transaction_status = transaction_status_notification.result
-
-    increase_balance_call = Call(
-        to_addr=deployed_balance_contract.address,
-        selector=get_selector_from_name("increase_balance"),
-        calldata=[100],
-    )
-    execute = await argent_account_v040.execute_v3(
-        calls=increase_balance_call, resource_bounds=MAX_RESOURCE_BOUNDS
-    )
-
-    subscription_id = await websocket_client.subscribe_transaction_status(
-        handler=handler, transaction_hash=execute.transaction_hash
-    )
-
-    await argent_account_v040.client.wait_for_tx(tx_hash=execute.transaction_hash)
-    await argent_account_v040.client.get_transaction_receipt(
-        tx_hash=execute.transaction_hash
-    )
-
-    await asyncio.sleep(5)
-
-    assert new_transaction_status is not None
-    assert new_transaction_status.transaction_hash == execute.transaction_hash
-    assert (
-        new_transaction_status.status.finality_status
-        == TransactionStatus.ACCEPTED_ON_L2
-    )
-    assert (
-        new_transaction_status.status.execution_status
-        == TransactionExecutionStatus.SUCCEEDED
-    )
-    assert new_transaction_status.status.failure_reason is None
-
-    unsubscribe_result = await websocket_client.unsubscribe(subscription_id)
-    assert unsubscribe_result is True
-
-
-@pytest.mark.asyncio
-async def test_subscribe_pending_transactions(
-    websocket_client: WebsocketClient,
-    deployed_balance_contract,
-    argent_account_v040: BaseAccount,
-):
-    pending_transactions: List[Union[int, Transaction]] = []
-
-    def handler(pending_transaction_notification: PendingTransactionsNotification):
-        nonlocal pending_transactions
-        pending_transactions.append(pending_transaction_notification.result)
-
-    subscription_id = await websocket_client.subscribe_pending_transactions(
-        handler=handler,
-        sender_address=[argent_account_v040.address],
-    )
-
-    increase_balance_call = Call(
-        to_addr=deployed_balance_contract.address,
-        selector=get_selector_from_name("increase_balance"),
-        calldata=[100],
-    )
-    execute = await argent_account_v040.execute_v3(
-        calls=increase_balance_call, resource_bounds=MAX_RESOURCE_BOUNDS
-    )
-
-    await argent_account_v040.client.wait_for_tx(tx_hash=execute.transaction_hash)
-    await argent_account_v040.client.get_transaction_receipt(
-        tx_hash=execute.transaction_hash
-    )
-
-    assert len(pending_transactions) == 1
-    pending_transaction = pending_transactions[0]
-
-    transaction_hash = (
-        execute.transaction_hash
-        if isinstance(pending_transaction, int)
-        else pending_transaction.calculate_hash(StarknetChainId.SEPOLIA)
-    )
-    assert execute.transaction_hash == transaction_hash
-
-    unsubscribe_result = await websocket_client.unsubscribe(subscription_id)
-    assert unsubscribe_result is True
-
-
-@pytest.mark.asyncio
-async def test_receive_reorg_notification(
-    websocket_client: WebsocketClient,
-    devnet_client: DevnetClient,
-):
-    reorg_data: Optional[ReorgData] = None
-
-    def handler_reorg(reorg_notification: ReorgNotification):
-        nonlocal reorg_data
-        reorg_data = reorg_notification.result
-
-    subscription_id = await websocket_client.subscribe_new_heads(handler=lambda _: _)
-
-    websocket_client.on_chain_reorg = handler_reorg
-    new_block_hash = await devnet_client.create_block()
-
-    await devnet_client.abort_block(block_hash=new_block_hash)
-
-    await asyncio.sleep(5)
-
-    assert reorg_data is not None
-    assert reorg_data.starting_block_hash == int(new_block_hash, 16)
-    assert reorg_data.ending_block_hash == int(new_block_hash, 16)
-
-    unsubscribe_result = await websocket_client.unsubscribe(subscription_id)
-    assert unsubscribe_result is True
-
-
 @pytest.mark.asyncio
 async def test_unsubscribe_with_non_existing_id(
     websocket_client: WebsocketClient,