3.0.ipv8.overlay
================

.. py:module:: 3.0.ipv8.overlay


Attributes
----------

.. autoapisummary::

   3.0.ipv8.overlay.SettingsClass


Classes
-------

.. autoapisummary::

   3.0.ipv8.overlay.Settings
   3.0.ipv8.overlay.Overlay


Module Contents
---------------

.. py:class:: Settings

   Bases: :py:obj:`types.SimpleNamespace`


   Overlay settings, extensible for Overlay subclasses.


   .. py:attribute:: community_id
      :type:  bytes

      The byte-string used to identify this overlay.



   .. py:attribute:: my_peer
      :type:  3.0.ipv8.types.Peer

      The (private key) peer of this peer.



   .. py:attribute:: endpoint
      :type:  3.0.ipv8.types.Endpoint

      The endpoint to use for messaging.



   .. py:attribute:: network
      :type:  3.0.ipv8.peerdiscovery.network.Network

      The network graph backend.



.. py:data:: SettingsClass

.. py:class:: Overlay(settings: SettingsClass)

   Bases: :py:obj:`3.0.ipv8.messaging.interfaces.endpoint.EndpointListener`, :py:obj:`3.0.ipv8.taskmanager.TaskManager`, :py:obj:`Generic`\ [\ :py:obj:`SettingsClass`\ ]


   Interface for an Internet overlay.


   .. py:attribute:: settings_class
      :type:  type[SettingsClass]


   .. py:attribute:: serializer


   .. py:attribute:: crypto


   .. py:attribute:: community_id


   .. py:attribute:: my_peer


   .. py:attribute:: logger


   .. py:attribute:: network


   .. py:method:: discover_lan_addresses() -> None
      :async:


      Called for discovering LAN addresses.



   .. py:method:: unload() -> None
      :async:


      Called when this overlay needs to shut down.



   .. py:method:: get_serializer() -> 3.0.ipv8.messaging.serialization.Serializer

      Get a Serializer for this Overlay.



   .. py:method:: on_packet(packet: tuple[3.0.ipv8.types.Address, bytes]) -> None
      :abstractmethod:


      Callback for when data is received on this endpoint.

      :param packet: the received packet, in (source, binary string) format.



   .. py:property:: global_time
      :type: int


      The lamport timestamp of this overlay.



   .. py:method:: claim_global_time() -> int

      Increments the current global time by one and returns this value.



   .. py:method:: update_global_time(global_time: int) -> None

      Increase the local global time if the given GLOBAL_TIME is larger.



   .. py:method:: get_available_strategies() -> dict[str, type[3.0.ipv8.peerdiscovery.discovery.DiscoveryStrategy]]

      Supply custom DiscoveryStrategies for use with this Overlay.
      This is used by the configuration system to allow for non-globally defined strategies.

      :return: a dictionary of names and DiscoveryStrategy subclass classes
      :rtype: {str: class<DiscoveryStrategy>}



   .. py:method:: bootstrap() -> None

      Perform introduction logic to get into the network.



   .. py:method:: walk_to(address: 3.0.ipv8.types.Address) -> None
      :abstractmethod:


      Puncture the NAT of an address.

      :param address: the address to walk to (ip, port)



   .. py:method:: get_new_introduction(from_peer: 3.0.ipv8.types.Peer | None = None) -> None
      :abstractmethod:


      Get a new IP address to walk to from a random, or selected peer.

      :param from_peer: the peer to ask for an introduction



   .. py:method:: get_peers() -> list[3.0.ipv8.types.Peer]
      :abstractmethod:


      Get the peers for this specific overlay.

      :return: the peers in the Network that use this overlay



   .. py:method:: get_walkable_addresses() -> list[3.0.ipv8.types.Address]
      :abstractmethod:


      Get the list of IPv4 addresses we can walk to on this overlay.

      :return: a list of IPv4 addresses
      :rtype: [(str, int)]



   .. py:method:: get_peer_for_introduction(exclude: 3.0.ipv8.types.Peer | None = None) -> 3.0.ipv8.types.Peer | None

      Get a peer for introduction.

      :param: exclude: optionally specify a peer that is not considered eligible for introduction
      :return: a Peer to send an introduction request to, or None if there are no available