update docs

Author: abramsymons

docs/source/chainio.rst renamed to docs/source/eigensdk.chainio.rst

@@ -1,4 +1,4 @@
-.. _chainio:
+.. _eigensdk.chainio:
 
 eigensdk.chainio
 ================

docs/source/crypto.rst renamed to docs/source/eigensdk.crypto.rst

@@ -1,4 +1,4 @@
-.. _crypto:
+.. _eigensdk.crypto:
 
 eigensdk.crypto
 ===============

docs/source/eigensdk.metrics.rst

@@ -0,0 +1,6 @@
+.. _eigensdk.metrics:
+
+eigensdk.metrics
+================
+
+Metrics

docs/source/nodeapi.rst renamed to docs/source/eigensdk.nodeapi.rst

@@ -1,4 +1,4 @@
-.. _nodeapi:
+.. _eigensdk.nodeapi:
 
 eigensdk.nodeapi
 ================

docs/source/eigensdk.services.rst

@@ -0,0 +1,184 @@
+.. _eigensdk.services:
+
+eigensdk.services
+=================
+
+eigensdk.services.operatorsinfo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``OperatorsInfoServiceInMemory`` is a service designed to manage and maintain a local in-memory store of operator details such as public keys and network socket information. It periodically updates its data by querying the blockchain through an ``AvsRegistryReader`` instance.
+
+Initialization
+--------------
+
+The service is initialized with the following parameters:
+
+- **avs_registry_reader**: An instance of ``AvsRegistryReader`` used to access operator-related data on the blockchain.
+- **start_block_pub**: The starting block number for querying registered public keys.
+- **start_block_socket**: The starting block number for querying socket information.
+- **check_interval**: The interval in seconds between checks for updates.
+- **log_filter_query_block_range**: The range of blocks to query in one request.
+- **logger**: An optional logger instance for logging events and errors.
+
+.. py:class:: OperatorsInfoServiceInMemory(avs_registry_reader: AvsRegistryReader, start_block_pub: int = 0, start_block_socket: int = 0, check_interval: int = 10, log_filter_query_block_range: int = 10000, logger: Optional[logging.Logger] = None)
+
+    Initializes a new instance of the ``OperatorsInfoServiceInMemory``.
+
+    :param avs_registry_reader: Instance of ``AvsRegistryReader`` for blockchain queries.
+    :param start_block_pub: Starting block number for public key queries.
+    :param start_block_socket: Starting block number for socket info queries.
+    :param check_interval: Time interval between update checks.
+    :param log_filter_query_block_range: Block range for each query to the blockchain.
+    :param logger: Logger for event logging.
+
+Functionality
+-------------
+
+The service runs continuously in a separate thread, periodically updating its internal data stores based on the latest information from the blockchain. It supports the following functionalities:
+
+- **Operator Public Key Retrieval**: Fetches and stores the latest public keys registered on the blockchain.
+- **Operator Socket Information Retrieval**: Fetches and stores the latest socket information registered on the blockchain.
+- **Operator Info Retrieval**: Provides a method to retrieve detailed information about an operator given their address.
+
+.. py:method:: get_operator_info(operator_addr: Address) -> OperatorInfo
+
+    Retrieves detailed information about an operator, including their socket information and public keys.
+
+    :param operator_addr: The blockchain address of the operator.
+    :return: An instance of ``OperatorInfo`` containing the operator's details.
+
+Example Usage
+-------------
+
+The service can be used in an application that requires up-to-date information about blockchain operators, such as in a decentralized application (dApp) that interacts with various blockchain services:
+
+.. code-block:: python
+
+    >>> operator_info_service = OperatorsInfoServiceInMemory(clients.avs_registry_reader)
+    >>> operator_info = operator_info_service.get_operator_info('0x123...')
+    >>> print(f"Operator Socket: {operator_info.socket}, Public Keys: {operator_info.pub_keys}")
+
+
+This example initializes the service and retrieves operator information, demonstrating how to integrate and utilize the ``OperatorsInfoServiceInMemory`` within larger systems.
+
+eigensdk.services.avsregistry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``AvsRegistryService`` is designed to aggregate and provide access to detailed state information about operators and their stakes across different quorums. It utilizes data from both the ``AvsRegistryReader`` and ``OperatorsInfoServiceInMemory`` to construct comprehensive views of the AVS (Autonomous Validation Services) landscape at specific blockchain states.
+
+Initialization
+--------------
+
+The service is initialized with instances of ``AvsRegistryReader`` and ``OperatorsInfoServiceInMemory``, along with a logger for event logging.
+
+.. py:class:: AvsRegistryService(avs_registry_reader: AvsRegistryReader, operator_info_service: OperatorsInfoServiceInMemory, logger: logging.Logger)
+
+    Initializes a new instance of the ``AvsRegistryService``.
+
+    :param avs_registry_reader: Instance of ``AvsRegistryReader`` for reading blockchain data.
+    :param operator_info_service: Instance of ``OperatorsInfoServiceInMemory`` for managing in-memory operator data.
+    :param logger: Logger for event logging.
+
+Functionality
+-------------
+
+The service offers functionalities to retrieve aggregated operator states and quorum states at specific blocks, helping in the analysis and management of AVS.
+
+.. py:method:: get_operators_avs_state_at_block(quorum_numbers: List[int], block_number: int) -> Dict[bytes, OperatorAvsState]
+
+    Retrieves the AVS state of operators at a specific blockchain block.
+
+    :param quorum_numbers: List of quorum numbers to query.
+    :param block_number: The blockchain block number at which to get the state.
+    :return: A dictionary mapping operator IDs to their ``OperatorAvsState``.
+
+.. py:method:: get_quorums_avs_state_at_block(quorum_numbers: List[int], block_number: int) -> Dict[int, Dict[str, Union[int, G1Point]]]
+
+    Aggregates the state of specified quorums at a given block number, including the aggregated public keys and total stakes.
+
+    :param quorum_numbers: List of quorum numbers to aggregate.
+    :param block_number: The blockchain block number at which to aggregate the state.
+    :return: A dictionary with quorum numbers as keys and details including aggregated public keys, total stakes, and block numbers.
+
+Example Usage
+-------------
+
+The following example demonstrates how to use the ``AvsRegistryService`` to fetch and display operator and quorum states at a specific blockchain block:
+
+.. code-block:: python
+
+    >>> avs_registry_service = AvsRegistryService(clients.avs_registry_reader, operator_info_service, logger)
+    >>> quorum_numbers = [0, 1]
+    >>> block_number = 12345
+    >>> operators_state = avs_registry_service.get_operators_avs_state_at_block(quorum_numbers, block_number)
+    >>> print(operators_state)
+    >>> quorums_state = avs_registry_service.get_quorums_avs_state_at_block(quorum_numbers, block_number)
+    >>> print(quorums_state)
+
+This example shows how to initialize the service and retrieve detailed state information for operators and quorums, providing insights into the current and historical configurations of the AVS within the blockchain.
+
+
+eigensdk.services.bls_aggregation.blsagg
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``BlsAggregationService`` is integral to aggregating Boneh-Lynn-Shacham (BLS) signatures in distributed validation systems, ensuring task authenticity and integrity across multiple nodes.
+
+Initialization
+--------------
+
+The service is initiated with an instance of ``AvsRegistryService`` and a cryptographic hash function. These components enable it to verify and aggregate signatures while interacting with blockchain state data.
+
+.. py:class:: BlsAggregationService(avs_registry_service: AvsRegistryService, hash_function: any)
+
+    Initializes a new instance of ``BlsAggregationService``.
+
+    :param avs_registry_service: An instance of ``AvsRegistryService`` used for querying blockchain data.
+    :param hash_function: A cryptographic hash function used for digest generation.
+
+Functionality
+-------------
+
+The service provides methods to initialize new tasks, process new signatures, and retrieve aggregated responses. It verifies signatures against blockchain data and aggregates them if they meet predefined quorum requirements.
+
+.. py:method:: initialize_new_task(task_index: int, task_created_block: int, quorum_numbers: List[int], quorum_threshold_percentages: List[int], time_to_expiry: int)
+
+    Prepares a new task for aggregation, setting initial parameters and storing them internally.
+
+.. py:method:: process_new_signature(task_index: int, task_response: str, bls_signature: Signature, operator_id: int)
+
+    Processes and aggregates a new BLS signature related to a specific task, verifying its authenticity and adding it to the aggregate.
+
+.. py:method:: get_aggregated_responses() -> Iterator[BlsAggregationServiceResponse]
+
+    Yields completed task responses once they meet aggregation criteria, indicating successful validation.
+
+Data Structures
+---------------
+
+- **TaskListItem**: Maintains task-specific data, including state of operator signatures and stake thresholds.
+- **AggregatedOperators**: Stores aggregated public keys and signatures for operators who have signed a specific task response.
+
+Example Usage
+-------------
+
+The following example demonstrates initializing the service, managing task signatures, and validating task completion:
+
+.. code-block:: python
+
+    >>> bls_aggregation_service = BlsAggregationService(avs_registry_service, hash_function)
+    >>> task_index = 1
+    >>> quorum_numbers = [0, 1]
+    >>> quorum_thresholds = [70, 70]
+    >>> # Initialize a new task
+    >>> bls_aggregation_service.initialize_new_task(task_index, 123456, quorum_numbers, quorum_thresholds, 3600)
+    >>> # Process a new signature
+    >>> operator_id = 101
+    >>> task_response = 'response data'
+    >>> bls_signature = Signature(...)  # Assuming a valid BLS signature
+    >>> bls_aggregation_service.process_new_signature(task_index, task_response, bls_signature, operator_id)
+    >>> # Retrieve and handle aggregated responses
+    >>> for response in bls_aggregation_service.get_aggregated_responses():
+    ...     print(response)
+
+This service is crucial for ensuring tasks are validated correctly and efficiently, using cryptographic guarantees provided by BLS signatures and blockchain data.
+

docs/source/index.rst

@@ -5,10 +5,17 @@ EigenSDK Python Documentation
 
 It enables BLS `signing <https://eth2book.info/capella/part2/building_blocks/signatures/>`_ and `aggregation <https://eth2book.info/capella/part2/building_blocks/signatures/#aggregation>`_, while also providing a wrapper for interacting with both EigenLayer's `core contracts <https://github.com/Layr-Labs/eigenlayer-contracts>`_ and `AVS-specific contracts <https://github.com/Layr-Labs/eigenlayer-middleware/>`_. Additionally, the SDK includes implementations of `NodeAPI <https://docs.eigenlayer.xyz/category/avs-node-api>`_ and `Metrics API <https://docs.eigenlayer.xyz/category/metrics>`_, offering essential tools for effective monitoring and management of AVS operations, ensuring a cohesive development environment within the EigenLayer ecosystem.
 
+Getting Started
+~~~~~~~~~~~~~~~
+
 .. warning::
 
    This library is a PoC implemented for the EigenLayer hackathon. Do not use it in Production, testnet only.
 
+- Ready to code? → :ref:`quickstart`
+- Example AVS using this SDK? → `Incredible Squaring AVS <https://github.com/zellular-xyz/incredible-squaring-avs-python>`_
+- Read the source? → `Github <https://github.com/zellular-xyz/eigensdk-python>`_
+
 Table of Contents
 -----------------
 
@@ -22,8 +29,8 @@ Table of Contents
     :maxdepth: 1
     :caption: API
 
-    chainio
-    crypto
-    services
-    nodeapi
-    metrics
+    eigensdk.chainio
+    eigensdk.crypto
+    eigensdk.services
+    eigensdk.nodeapi
+    eigensdk.metrics

docs/source/metrics.rst

@@ -24,7 +24,6 @@ def is_json_serializable(obj):
 
 @dataclass
 class BlsAggregationServiceResponse:
-    err: Exception = None  # if err is not None, the other fields are not valid
     task_index: int = None  # unique identifier of the task
     task_response: any = None  # the task response that was signed
     task_response_digest: any = None  # digest of the task response that was signed
@@ -115,7 +114,7 @@ def initialize_new_task(
         quorum_numbers: list[int],
         quorum_threshold_percentages: list[int],
         time_to_expiry: int,
-    ) -> Exception: ...
+    ): ...
 
     # ProcessNewSignature processes a new signature over a taskResponseDigest for a particular taskIndex by a particular operator
     # It verifies that the signature is correct and returns an error if it is not, and then aggregates the signature and stake of
@@ -128,7 +127,7 @@ def process_new_signature(
         taskResponse: any,
         blsSignature: Signature,
         operatorId: int,
-    ) -> Exception: ...
+    ): ...
 
     # GetResponseChannel returns the single channel that meant to be used as the response channel
     # Any task that is completed (see the completion criterion in the comment above InitializeNewTask)
@@ -177,7 +176,7 @@ def initialize_new_task(
         quorum_numbers: list[int],
         quorum_threshold_percentages: list[int],
         time_to_expiry: int,
-    ) -> Exception:
+    ):
         if task_index in self.responses:
             raise ValueError("Task alredy initialized")
 
@@ -319,7 +318,6 @@ def process_new_signature(
             )
 
             result = BlsAggregationServiceResponse(
-                err=None,
                 task_index=task_index,
                 task_response=task_response,
                 task_response_digest=task_response_digest,
@@ -368,11 +366,11 @@ def __verify_signature(
         task_index: int,
         signed_task_response_digest: SignedTaskResponseDigest,
         operators_avs_state_dict: dict[int, OperatorAvsState],
-    ) -> Exception:
+    ):
         operator_id = signed_task_response_digest.operator_id
 
         if operator_id not in operators_avs_state_dict:
-            return ValueError(f"Operator {operator_id} is not part of task quorum")
+            raise ValueError(f"Operator {operator_id} is not part of task quorum")
 
         task_response_digest = self.hash_function(
             signed_task_response_digest.task_response
@@ -382,13 +380,11 @@ def __verify_signature(
             operator_id
         ].operator_info.pub_keys.g2_pub_key
         if not operator_g2_pub_key:
-            return ValueError(
+            raise ValueError(
                 f"TaskId: {task_index} operator G2 PubKey not fount for operator {operator_id}"
             )
 
         signature = signed_task_response_digest.bls_signature
         verified = signature.verify(operator_g2_pub_key, task_response_digest)
         if not verified:
-            return ValueError("Incorrect signature error")
-
-        return None
+            raise ValueError("Incorrect signature error")