o jh @sddlmZmZddlmZmZmZmZmZddl m Z ddl m Z ddl mZddlmZmZmZmZddlmZddlZdd lmZdd lmZmZmZdd lmZmZm Z m!Z!m"Z"dd l#m$Z$dd l%m&Z&m'Z'ddl(m)Z)ddl*m+m,m-Z,ddl.m/Z/erddl0m1Z1ddl2m3Z3ddl4m5Z5ddl6m7Z7ddl8m9Z9ddl:m;Z;ddl GdddeZ?Gddde?e>Z@GdddeZAGdd d e'ed ZBGd!d"d"e'ZCGd#d$d$e&ZDGd%d&d&eZEGd'd(d(eZFGd)d*d*eZGGd+d,d,eZHGd-d.d.eZIGd/d0d0eZJGd1d2d2eEeFeGeHeIeJZKGd3d4d4eZLGd5d6d6eZMe Gd7d8d8ZNGd9d:d:eMe=ZOGd;d<dd>eZQGd?d@d@eZRGdAdBdBeZSGdCdDdDeZTGdEdFdFeZUGdGdHdHeZVGdIdJdJeZWGdKdLdLeZXGdMdNdNeZYGdOdPdPeZZGdQdRdReZ[GdSdTdTedTee;j\Z]GdUdVdVeZ^GdWdXdXe=Z_GdYdZdZeZ`dS)[)ABCabstractmethod) AsyncIterable AsyncIteratorIterableKeysViewSequence)AbstractAsyncContextManager) dataclass) TracebackType) TYPE_CHECKINGAnyAsyncContextManagerOptional) MultiaddrN)ConnectionType)KeyPair PrivateKey PublicKey) MetadataValueStreamHandlerFnTHandler TProtocol ValidatorFn)EventBus)CloserReadWriteCloser)ID)PeerInfo)TagStore)Envelope) PeerRecord) Multiselect)Pubsub)rpc_pb2) ServiceAPIc@sBeZdZUdZeed<edeefddZ ede fddZ dS) IRawConnectionz Interface for a raw connection. This interface provides a basic reader/writer connection abstraction. Attributes ---------- is_initiator (bool): True if the local endpoint initiated the connection. is_initiatorreturncCdS)z Get the actual transport addresses used by this connection. Returns the real IP/port addresses, not peerstore addresses. For relayed connections, should include /p2p-circuit in the path. Nselfr*r*-/Users/sumanjeet/code/py-libp2p/libp2p/abc.pyget_transport_addressesZsz&IRawConnection.get_transport_addressescCr)zD Get the type of connection (direct, relayed, etc.) Nr*r+r*r*r-get_connection_typedz"IRawConnection.get_connection_typeN) __name__ __module__ __qualname____doc__bool__annotations__rlistrr.rr0r*r*r*r-r&Js   r&c@sXeZdZdZedefddZedefddZedefddZ ede fd d Z d S) AbstractSecureConnz Abstract interface for secure connections. Represents a secured connection object, including details about the security involved in the connection. r(cCr))z\ Retrieve the local peer's identifier. :return: The local peer ID. Nr*r+r*r*r-get_local_peer}z!AbstractSecureConn.get_local_peercCr))zm Retrieve the local peer's private key. :return: The private key of the local peer. Nr*r+r*r*r-get_local_private_keyr;z(AbstractSecureConn.get_local_private_keycCr))z^ Retrieve the remote peer's identifier. :return: The remote peer ID. Nr*r+r*r*r-get_remote_peerr;z"AbstractSecureConn.get_remote_peercCr))zm Retrieve the remote peer's public key. :return: The public key of the remote peer. Nr*r+r*r*r-get_remote_public_keyr;z(AbstractSecureConn.get_remote_public_keyN) r2r3r4r5rrr:rr<r=rr>r*r*r*r-r9tsr9c@seZdZdZdS) ISecureConnzv Interface for a secure connection. Combines secure connection functionalities with raw I/O operations. N)r2r3r4r5r*r*r*r-r?sr?c@seZdZUdZeed<ejed<ede deddfddZ e ede fd d Z edd d Zedd dZe ede fddZe ede fddZedddZedddZedeefddZedefddZdS) IMuxedConnaS Interface for a multiplexed connection. References ---------- https://github.com/libp2p/go-stream-muxer/blob/master/muxer.go Attributes ---------- peer_id (ID): The identifier of the connected peer. event_started (trio.Event): An event that signals when the multiplexer has started. peer_id event_startedconnr(NcCr))z Initialize a new multiplexed connection. :param conn: An instance of a secure connection used for new multiplexed streams. :param peer_id: The peer ID associated with the connection. Nr*r,rCrAr*r*r-__init__r;zIMuxedConn.__init__cCr))z Determine if this connection is the initiator. :return: True if this connection initiated the connection, otherwise False. Nr*r+r*r*r-r'r;zIMuxedConn.is_initiatorcdS)z) Start the multiplexer. Nr*r+r*r*r-startzIMuxedConn.startcrF)z4 Close the multiplexed connection. Nr*r+r*r*r-closerHzIMuxedConn.closecCr))z Check if the connection is fully established and ready for streams. :return: True if the connection is established, otherwise False. Nr*r+r*r*r-is_establishedr;zIMuxedConn.is_establishedcCr)z Check if the connection is fully closed. :return: True if the connection is closed, otherwise False. Nr*r+r*r*r- is_closedr;zIMuxedConn.is_closed IMuxedStreamcrF)zm Create and open a new multiplexed stream. :return: A new instance of IMuxedStream. Nr*r+r*r*r- open_streamrHzIMuxedConn.open_streamcrF)z Accept a new multiplexed stream initiated by the remote peer. :return: A new instance of IMuxedStream. Nr*r+r*r*r- accept_streamrHzIMuxedConn.accept_streamcCr))zH Get transport addresses by delegating to secured_conn. Nr*r+r*r*r-r.r1z"IMuxedConn.get_transport_addressescCr))zD Get connection type by delegating to secured_conn. Nr*r+r*r*r-r0 r1zIMuxedConn.get_connection_typer(Nr(rM)r2r3r4r5rr7trioEventrr?rEpropertyr6r'rGrIrJrLrNrOr8rr.rr0r*r*r*r-r@sB        r@c@sveZdZUdZeed<edddZededdfdd Z edd d Z d e e dBd e dBde dBddfddZdS)rMz Interface for a multiplexed stream. Represents a stream multiplexed over a single connection. Attributes ---------- muxed_conn (IMuxedConn): The underlying multiplexed connection. muxed_connr(NcrF)z Reset the stream. This method closes both ends of the stream, instructing the remote side to hang up. Nr*r+r*r*r-reset$rHzIMuxedStream.resetttlcCr))z Set a deadline for the stream. :param ttl: Time-to-live for the stream in seconds. :raises ValueError: if ttl is invalid (e.g. negative). Nr*r,rWr*r*r- set_deadline-r;zIMuxedStream.set_deadlinecs|S)z Enter the async context manager.r*r+r*r*r- __aenter__6zIMuxedStream.__aenter__exc_typeexc_valexc_tbcs|IdHdS)z4Exit the async context manager and close the stream.N)rI)r,r\r]r^r*r*r- __aexit__;szIMuxedStream.__aexit__rPrQ)r2r3r4r5r@r7rrVintrYrZtype BaseExceptionr r_r*r*r*r-rMs$     rMc@sfeZdZUdZeed<ejedBed<e de dBfddZ e de ddfd d Z e d d d Z dS) INetStreamz Interface for a network stream. Represents a network stream operating over a multiplexed connection. Attributes ---------- muxed_conn (IMuxedConn): The multiplexed connection that this stream belongs to. rUNmetric_send_channelr(cCr))z Retrieve the protocol identifier for the stream. :return: The protocol ID associated with the stream. Nr*r+r*r*r- get_protocolXr;zINetStream.get_protocol protocol_idcCr))z Set the protocol identifier for the stream. :param protocol_id: The protocol ID to assign to the stream. Nr*r,rfr*r*r- set_protocol`r;zINetStream.set_protocolcrF)z` Reset the network stream. This method closes both ends of the stream. Nr*r+r*r*r-rVhrHzINetStream.resetrP)r2r3r4r5r@r7rRMemorySendChannelr rrrerhrVr*r*r*r-rcHs  rcc@seZdZUdZeed<ejed<ee de fddZ e de fddZ e dee d ffd d Ze deefd d Ze defddZdS)INetConna> Interface for a network connection. Defines a network connection capable of creating and managing streams. Attributes ---------- muxed_conn (IMuxedConn): The underlying multiplexed connection. event_started (trio.Event): Event signaling when the connection has started. rUrBr(cCr)rKr*r+r*r*r-rLr;zINetConn.is_closedcrF)zr Create a new network stream over the connection. :return: A new instance of INetStream. Nr*r+r*r*r- new_streamrHzINetConn.new_stream.cCr))z Retrieve all active streams associated with this connection. :return: A tuple containing instances of INetStream. Nr*r+r*r*r- get_streamsr;zINetConn.get_streamscCr))a$ Retrieve the actual transport addresses used by this connection. Returns the real IP/port addresses, not peerstore addresses. For relayed connections, should include /p2p-circuit in the path. :return: A list of multiaddresses used by the transport. Nr*r+r*r*r-r.r;z INetConn.get_transport_addressescCr)r/r*r+r*r*r-r0r1zINetConn.get_connection_typeN)r2r3r4r5r@r7rRrSrTrr6rLrcrktuplerlr8rr.rr0r*r*r*r-rjts   rjc @s^eZdZdZedededefddZededededdfd d Z ededdfd d Z dS) IPeerMetadataz Interface for managing peer metadata. Provides methods for storing and retrieving metadata associated with peers. rAkeyr(cCr))a Retrieve metadata for a specified peer. :param peer_id: The ID of the peer. :param key: The key for the metadata to retrieve. :return: The metadata value associated with the key. :raises Exception: If the peer ID is not found. Nr*r,rAror*r*r-getr;zIPeerMetadata.getvalNcCr))z Store metadata for a specified peer. :param peer_id: The ID of the peer. :param key: The key for the metadata. :param val: The value to store. :raises Exception: If the operation is unsuccessful. Nr*r,rArorrr*r*r-putr;zIPeerMetadata.putcCr))z Remove all stored metadata for the specified peer. Parameters ---------- peer_id : ID The peer identifier whose metadata are to be removed. Nr*r,rAr*r*r-clear_metadatar;zIPeerMetadata.clear_metadata) r2r3r4r5rrstrrrqrtrvr*r*r*r-rns  rnc @seZdZdZededededdfddZeded e ededdfd d Z edede efd d Z ededdfddZ ede efddZdS) IAddrBookz[ Interface for an address book. Provides methods for managing peer addresses. rAaddrrWr(NcCr))a Add a single address for a given peer. This method calls ``add_addrs(peer_id, [addr], ttl)``. Parameters ---------- peer_id : ID The peer identifier for which to add the address. addr : Multiaddr The multiaddress of the peer. ttl : int The time-to-live for the address, after which it is no longer valid. Nr*r,rAryrWr*r*r-add_addrr;zIAddrBook.add_addraddrscCr))aE Add multiple addresses for a given peer, all with the same TTL. If an address already exists with a longer TTL, no action should be taken. If an address exists with a shorter TTL, its TTL should be extended to match the provided TTL. Parameters ---------- peer_id : ID The peer identifier for which to add addresses. addrs : Sequence[Multiaddr] A sequence of multiaddresses to add. ttl : int The time-to-live for the addresses, after which they become invalid. Nr*r,rAr|rWr*r*r- add_addrsr;zIAddrBook.add_addrscCr))aD Retrieve all known and valid addresses for the specified peer. Parameters ---------- peer_id : ID The peer identifier whose addresses are requested. Returns ------- list[Multiaddr] A list of valid multiaddresses for the given peer. Nr*rur*r*r-r|r;zIAddrBook.addrscCr))z Remove all stored addresses for the specified peer. Parameters ---------- peer_id : ID The peer identifier whose addresses are to be removed. Nr*rur*r*r- clear_addrs r;zIAddrBook.clear_addrscCr))z Retrieve all peer identifiers that have stored addresses. Returns ------- list[ID] A list of peer IDs with stored addresses. Nr*r+r*r*r-peers_with_addrs,r;zIAddrBook.peers_with_addrs)r2r3r4r5rrrr`r{rr~r8r|rrr*r*r*r-rxs  rxc@sZeZdZdZedddedefddZedede dfd d Z ededd fd d Z d S)ICertifiedAddrBookzh Interface for a certified address book. Provides methods for managing signed peer records enveloper rWr(cCr))a! Accept and store a signed PeerRecord, unless it's older than the one already stored. This function: - Extracts the peer ID and sequence number from the envelope - Rejects the record if it's older (lower seq) - Updates the stored peer record and replaces associated addresses if accepted Parameters ---------- envelope: Signed envelope containing a PeerRecord. ttl: Time-to-live for the included multiaddrs (in seconds). Nr*r,rrWr*r*r-consume_peer_recordAr;z&ICertifiedAddrBook.consume_peer_recordrAcCr)a Retrieve the most recent signed PeerRecord `Envelope` for a peer, if it exists and is still relevant. First, it runs cleanup via `maybe_delete_peer_record` to purge stale data. Then it checks whether the peer has valid, unexpired addresses before returning the associated envelope. Parameters ---------- peer_id : ID The peer to look up. Nr*rur*r*r-get_peer_recordWr;z"ICertifiedAddrBook.get_peer_recordNcCr))a Delete the signed peer record for a peer if it has no know (non-expired) addresses. This is a garbage collection mechanism: if all addresses for a peer have expired or been cleared, there's no point holding onto its signed `Envelope` Parameters ---------- peer_id : ID The peer whose record we may delete. Nr*rur*r*r-maybe_delete_peer_recordir;z+ICertifiedAddrBook.maybe_delete_peer_record) r2r3r4r5rr`r6rrrrrr*r*r*r-r:src@seZdZdZededefddZededefddZ edededd fd d Z eded edd fd dZ edede dd fddZ edeefddZededd fddZd S)IKeyBookz[ Interface for an key book. Provides methods for managing cryptographic keys. rAr(cCr))z Returns the public key of the specified peer Parameters ---------- peer_id : ID The peer identifier whose public key is to be returned. Nr*rur*r*r-pubkeyr;zIKeyBook.pubkeycCr))z Returns the private key of the specified peer Parameters ---------- peer_id : ID The peer identifier whose private key is to be returned. Nr*rur*r*r-privkeyr;zIKeyBook.privkeyrNcCr))z Adds the public key for a specified peer Parameters ---------- peer_id : ID The peer identifier whose public key is to be added pubkey: PublicKey The public key of the peer Nr*r,rArr*r*r- add_pubkeyr;zIKeyBook.add_pubkeyrcCr))z Adds the private key for a specified peer Parameters ---------- peer_id : ID The peer identifier whose private key is to be added privkey: PrivateKey The private key of the peer Nr*r,rArr*r*r- add_privkeyr;zIKeyBook.add_privkeykey_paircCr))z Adds the key pair for a specified peer Parameters ---------- peer_id : ID The peer identifier whose key pair is to be added key_pair: KeyPair The key pair of the peer Nr*r,rArr*r*r- add_key_pairr;zIKeyBook.add_key_paircCr)z/Returns all the peer IDs stored in the AddrBookNr*r+r*r*r-peer_with_keysr;zIKeyBook.peer_with_keyscCr)z Remove all stored keydata for the specified peer. Parameters ---------- peer_id : ID The peer identifier whose keys are to be removed. Nr*rur*r*r- clear_keydatar;zIKeyBook.clear_keydata)r2r3r4r5rrrrrrrrrrr8rrr*r*r*r-r}s      rc@sVeZdZdZedededdfddZededefdd Zededdfd d Z dS) IMetricszd Interface for metrics of peer interaction. Provides methods for managing the metrics. rARTTr(NcCr)am Records a new round-trip time (RTT) latency value for the specified peer using Exponentially Weighted Moving Average (EWMA). Parameters ---------- peer_id : ID The identifier of the peer for which latency is being recorded. RTT : float The round-trip time latency value to record. Nr*r,rArr*r*r-record_latencyr;zIMetrics.record_latencycCr)a Returns the current latency value for the specified peer using Exponentially Weighted Moving Average (EWMA). Parameters ---------- peer_id : ID The identifier of the peer whose latency EWMA is to be returned. Nr*rur*r*r- latency_EWMAr;zIMetrics.latency_EWMAcCr)z Clears the stored latency metrics for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer whose latency metrics are to be cleared. Nr*rur*r*r- clear_metricsr;zIMetrics.clear_metrics) r2r3r4r5rrfloatrrrr*r*r*r-rs rc@seZdZdZededeefddZedede eddfdd Z edede eddfd d Z edede eddfd d Z edede edeefddZ edede edefddZededdfddZdS) IProtoBookzl Interface for a protocol book. Provides methods for managing the list of supported protocols. rAr(cCr))z Returns the list of protocols associated with the specified peer. Parameters ---------- peer_id : ID The identifier of the peer whose supported protocols are to be returned. Nr*rur*r*r- get_protocolsr;zIProtoBook.get_protocols protocolsNcCr))a- Adds the given protocols to the specified peer's protocol list. Parameters ---------- peer_id : ID The identifier of the peer to which protocols will be added. protocols : Sequence[str] A sequence of protocol strings to add. Nr*r,rArr*r*r- add_protocols!r;zIProtoBook.add_protocolscCr))a8 Replaces the existing protocols of the specified peer with the given list. Parameters ---------- peer_id : ID The identifier of the peer whose protocols are to be set. protocols : Sequence[str] A sequence of protocol strings to assign. Nr*rr*r*r- set_protocols0r;zIProtoBook.set_protocolscCr)a3 Removes the specified protocols from the peer's protocol list. Parameters ---------- peer_id : ID The identifier of the peer from which protocols will be removed. protocols : Sequence[str] A sequence of protocol strings to remove. Nr*rr*r*r-remove_protocols?r;zIProtoBook.remove_protocolscCr)am Returns the list of protocols from the input sequence that the peer supports. Parameters ---------- peer_id : ID The identifier of the peer to check for protocol support. protocols : Sequence[str] A sequence of protocol strings to check against the peer's supported protocols. Nr*rr*r*r-supports_protocolsNr;zIProtoBook.supports_protocolscCr)a Returns the first protocol from the input list that the peer supports. Parameters ---------- peer_id : ID The identifier of the peer to check for supported protocols. protocols : Sequence[str] A sequence of protocol strings to check. Returns ------- str The first matching protocol string, or an empty string if none are supported. Nr*rr*r*r-first_supported_protocol^r;z#IProtoBook.first_supported_protocolcCr)z Clears all protocol data associated with the specified peer. Parameters ---------- peer_id : ID The identifier of the peer whose protocol data will be cleared. Nr*rur*r*r-clear_protocol_datasr;zIProtoBook.clear_protocol_data)r2r3r4r5rrr8rwrrrrrrrrr*r*r*r-rs   rc @sxeZdZdZedededefddZededededdfd d Z ededdfd d Z eded e de ddfddZ ededee de ddfddZededee fddZededdfddZedeefddZededfddZedYddZeddde defd d!Zedededfd"d#Zededdfd$d%Zededefd&d'Zededefd(d)Zeded*eddfd+d,Zeded-eddfd.d/Z eded0e!ddfd1d2Z"edeefd3d4Z#ededdfd5d6Z$eded7e%ddfd8d9Z&edede%fd:d;Z'ededdfdd?Z)eded@eeddfdAdBZ*eded@eeddfdCdDZ+eded@eeddfdEdFZ,eded@eedeefdGdHZ-eded@eedefdIdJZ.ededdfdKdLZ/edede0fdMdNZ1edeefdOdPZ2ededefdQdRZ3ededdfdSdTZ4edZdVe ddfdWdXZ5dS)[ IPeerStorez Interface for a peer store. Provides methods for managing peer information including address management, protocol handling, and key storage. rAror(cCr))a Retrieve the value associated with a key for a specified peer. Parameters ---------- peer_id : ID The identifier of the peer. key : str The key to look up. Returns ------- MetadataValue The value corresponding to the specified key. Raises ------ PeerStoreError If the peer ID or value is not found. Nr*rpr*r*r-rqr;zIPeerStore.getrrNcCr))a Store a key-value pair for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. key : str The key for the data. val : MetadataValue The value to store. Nr*rsr*r*r-rtr;zIPeerStore.putcCr)rr*rur*r*r-rvr;zIPeerStore.clear_metadataryrWcCr))a Add an address for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. addr : Multiaddr The multiaddress to add. ttl : int The time-to-live for the record. Nr*rzr*r*r-r{r;zIPeerStore.add_addrr|cCr))a9 Add multiple addresses for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. addrs : Sequence[Multiaddr] A sequence of multiaddresses to add. ttl : int The time-to-live for the record. Nr*r}r*r*r-r~r;zIPeerStore.add_addrscCr))a Retrieve the addresses for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Returns ------- list[Multiaddr] A list of multiaddresses. Nr*rur*r*r-r|r;zIPeerStore.addrscCr))z Clear all addresses for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Nr*rur*r*r-rr;zIPeerStore.clear_addrscCr))z Retrieve all peer identifiers with stored addresses. Returns ------- list[ID] A list of peer IDs. Nr*r+r*r*r-rr;zIPeerStore.peers_with_addrsr cCr))z-Get the local-peer-record wrapped in EnvelopeNr*r+r*r*r-get_local_recordr;zIPeerStore.get_local_recordrcCr))z-Set the local-peer-record wrapped in EnvelopeNr*)r,rr*r*r-set_local_recordr;zIPeerStore.set_local_recordcCr))a Accept and store a signed PeerRecord, unless it's older than the one already stored. This function: - Extracts the peer ID and sequence number from the envelope - Rejects the record if it's older (lower seq) - Updates the stored peer record and replaces associated addresses if accepted Parameters ---------- envelope: Signed envelope containing a PeerRecord. ttl: Time-to-live for the included multiaddrs (in seconds). Nr*rr*r*r-rr;zIPeerStore.consume_peer_recordcCr)rr*rur*r*r-r+r;zIPeerStore.get_peer_recordcCr))a Delete the signed peer record for a peer if it has no know (non-expired) addresses. This is a garbage collection mechanism: if all addresses for a peer have expired or been cleared, there's no point holding onto its signed `Envelope` Parameters ---------- peer_id : ID The peer whose record we may delete. Nr*rur*r*r-r=r;z#IPeerStore.maybe_delete_peer_recordcCr))a` Retrieve the public key for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Returns ------- PublicKey The public key of the peer. Raises ------ PeerStoreError If the peer ID is not found. Nr*rur*r*r-rOr;zIPeerStore.pubkeycCr))ac Retrieve the private key for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Returns ------- PrivateKey The private key of the peer. Raises ------ PeerStoreError If the peer ID is not found. Nr*rur*r*r-rer;zIPeerStore.privkeyrcCr))aI Add a public key for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. pubkey : PublicKey The public key to add. Raises ------ PeerStoreError If the peer already has a public key set. Nr*rr*r*r-r{r;zIPeerStore.add_pubkeyrcCr))aN Add a private key for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. privkey : PrivateKey The private key to add. Raises ------ PeerStoreError If the peer already has a private key set. Nr*rr*r*r-rr;zIPeerStore.add_privkeyrcCr))aP Add a key pair for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. key_pair : KeyPair The key pair to add. Raises ------ PeerStoreError If the peer already has a public or private key set. Nr*rr*r*r-rr;zIPeerStore.add_key_paircCr)rr*r+r*r*r-rr;zIPeerStore.peer_with_keyscCr)rr*rur*r*r-rr;zIPeerStore.clear_keydatarcCr)rr*rr*r*r-rr;zIPeerStore.record_latencycCr)rr*rur*r*r-rr;zIPeerStore.latency_EWMAcCr)rr*rur*r*r-rr;zIPeerStore.clear_metricscCr))ao Retrieve the protocols associated with the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Returns ------- list[str] A list of protocol identifiers. Raises ------ PeerStoreError If the peer ID is not found. Nr*rur*r*r-rr;zIPeerStore.get_protocolsrcCr))z Add additional protocols for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. protocols : Sequence[str] The protocols to add. Nr*rr*r*r-rr;zIPeerStore.add_protocolscCr))z Set the protocols for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. protocols : Sequence[str] The protocols to set. Nr*rr*r*r-rr;zIPeerStore.set_protocolscCr)rr*rr*r*r-r!r;zIPeerStore.remove_protocolscCr)rr*rr*r*r-r0r;zIPeerStore.supports_protocolscCr)rr*rr*r*r-r@r;z#IPeerStore.first_supported_protocolcCr)rr*rur*r*r-rUr;zIPeerStore.clear_protocol_datacCr))a Retrieve the peer information for the specified peer. Parameters ---------- peer_id : ID The identifier of the peer. Returns ------- PeerInfo The peer information object for the given peer. Nr*rur*r*r- peer_infobr;zIPeerStore.peer_infocCr))z Retrieve all peer identifiers stored in the peer store. Returns ------- list[ID] A list of all peer IDs in the store. Nr*r+r*r*r-peer_idssr;zIPeerStore.peer_idscCr))a Return True if ``peer_id`` is known to this store. This MUST be O(1)-ish (in-memory map / single key lookup) and MUST NOT materialize the full peer list: ``peer_ids()`` on persistent stores reconstructs and hashes every peer, which is far too expensive for hot paths (e.g. per-connection checks). Parameters ---------- peer_id : ID The peer ID to check. Returns ------- bool True if the peer is known to the store. Nr*rur*r*r-has_peerr;zIPeerStore.has_peercCr))clear_peerdataNr*rur*r*r-rr;zIPeerStore.clear_peerdatacleanup_intervalcrF)z=Start periodic cleanup of expired peer records and addresses.Nr*)r,rr*r*r-start_cleanup_taskrHzIPeerStore.start_cleanup_task)rr r(N)r)6r2r3r4r5rrrwrrqrtrvrr`r{rr~r8r|rrrrrr6rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr*r*r*r-rs             rc@sNeZdZdZededdfddZedeedffdd Zed d d Z dS) IListenerz Interface for a network listener. Provides methods for starting a listener, retrieving its addresses, and closing it. maddrr(NcrF)an Start listening on the specified multiaddress. The listener manages its own background tasks internally and keeps them alive until :meth:`close` is called. Callers do not need to supply a nursery. Parameters ---------- maddr : Multiaddr The multiaddress on which to listen. Raises ------ Exception Transport-specific listener exception, such as ``OpenConnectionError`` (TCP/WebSocket) or ``QUICListenError`` (QUIC), if listening fails (e.g. missing/invalid port or failed start). Nr*r,rr*r*r-listenrHzIListener.listen.cCr))z Retrieve the list of addresses on which the listener is active. Returns ------- tuple[Multiaddr, ...] A tuple of multiaddresses. Nr*r+r*r*r- get_addrsr;zIListener.get_addrscrF)z& Close the listener. Nr*r+r*r*r-rIzIListener.closerP) r2r3r4r5rrrrmrrIr*r*r*r-rs rc@sxeZdZUdZeed<eeee fed<ee e fed<e defddZ e d*d edBdee fd d Ze deeee ffd d Ze d ede dBfddZe d edee fddZe d edefddZe ded ede fddZe dededefddZe deddfddZe dedefddZe d+d"d#Ze d+d$d%Ze d,d&d'Ze d eddfd(d)Z dS)-INetworka Interface for the network. Provides methods for managing connections, streams, and listeners. Attributes ---------- peerstore : IPeerStore The peer store for managing peer information. connections : dict[ID, list[INetConn]] A mapping of peer IDs to lists of network connections (multiple connections per peer). listeners : dict[str, IListener] A mapping of listener identifiers to listener instances. peerstoreZ connections listenersr(cCr))z Retrieve the peer identifier for this network. Returns ------- ID The identifier of this peer. Nr*r+r*r*r- get_peer_idr;zINetwork.get_peer_idNrAcCr))a Get connections for peer (like JS getConnections, Go ConnsToPeer). Parameters ---------- peer_id : ID | None The peer ID to get connections for. If None, returns all connections. Returns ------- list[INetConn] List of connections to the specified peer, or all connections if peer_id is None. Nr*rur*r*r-get_connectionsr;zINetwork.get_connectionscCr))z Get all connections map (like JS getConnectionsMap). Returns ------- dict[ID, list[INetConn]] The complete mapping of peer IDs to their connection lists. Nr*r+r*r*r-get_connections_map r;zINetwork.get_connections_mapcCr))a7 Get single connection for backward compatibility. Parameters ---------- peer_id : ID The peer ID to get a connection for. Returns ------- INetConn | None The first available connection, or None if no connections exist. Nr*rur*r*r-get_connectionr;zINetwork.get_connectioncrF)a Create connections to the specified peer with load balancing. Parameters ---------- peer_id : ID The identifier of the peer to dial. Returns ------- list[INetConn] List of established connections to the peer. Raises ------ SwarmException If an error occurs during dialing. Nr*rur*r*r- dial_peer)rHzINetwork.dial_peercrF)a Create a new network stream to the specified peer. Parameters ---------- peer_id : ID The identifier of the destination peer. Returns ------- INetStream The newly created network stream. Nr*rur*r*r-rk?rHzINetwork.new_streamraw_conncrF)a  Secure and upgrade a raw outbound connection to a multiplexed network connection Parameters ---------- raw_conn : IRawConnection The raw connection to upgrade. peer_id : ID The peer to which this connection is established. Returns ------- INetConn The upgraded, secure, and multiplexed network connection. Raises ------ SwarmException If upgrading security or multiplexing the connection fails. Nr*r,rrAr*r*r-upgrade_outbound_raw_connPrHz"INetwork.upgrade_outbound_raw_connrcrF)a4 Secure and upgrade a raw inbound connection to a multiplexed network connection Parameters ---------- raw_conn : IRawConnection The incoming raw connection to upgrade. maddr : Multiaddr The multiaddress on which the connection was received. Returns ------- IMuxedConn The upgraded, secure, and multiplexed network connection. Raises ------ SwarmException If upgrading security or multiplexing the connection fails. Nr*r,rrr*r*r-upgrade_inbound_raw_connjrHz!INetwork.upgrade_inbound_raw_connstream_handlercCr))z Set the stream handler for incoming streams. Parameters ---------- stream_handler : StreamHandlerFn The handler function to process incoming streams. Nr*)r,rr*r*r-set_stream_handlerr;zINetwork.set_stream_handler multiaddrscrF)aT Start listening on one or more multiaddresses. Parameters ---------- multiaddrs : Sequence[Multiaddr] One or more multiaddresses on which to start listening. Returns ------- bool True if at least one listener started successfully, otherwise False. Nr*)r,rr*r*r-rrHzINetwork.listennotifeeINotifeecCr))z Register a notifee instance to receive network events. Parameters ---------- notifee : INotifee An object implementing the INotifee interface. Nr*r,rr*r*r-register_notifeer;zINetwork.register_notifeecCr))z Unregister a notifee instance so it stops receiving network events. Parameters ---------- notifee : INotifee The notifee previously passed to ``register_notifee``. Nr*rr*r*r-remove_notifeer;zINetwork.remove_notifeecrF)zQ Close the network and all associated connections and listeners. Nr*r+r*r*r-rIrHzINetwork.closecrF)z Close the connection to the specified peer. Parameters ---------- peer_id : ID The identifier of the peer whose connection should be closed. Nr*rur*r*r- close_peerrHzINetwork.close_peerN)rrr(NrP)!r2r3r4r5rr7dictrr8rjrwrrrrrrrrcrkr&rrr@rrrr6rrrrIrr*r*r*r-rsZ         rc@s>eZdZUdZeed<eed<eed<eed<edBed<dS)CMInfou  Unified snapshot of connection manager state. Equivalent to go-libp2p's connmgr.CMInfo snapshot returned by BasicConnMgr.GetInfo() — providing a single call-site for all watermark / live-count / grace / last-trim data needed by operators and metrics exporters. Attributes ---------- low_watermark : int Target connection count after pruning. high_watermark : int Connection count that triggers pruning. connected_count : int Current number of live connections. grace_period : float Seconds a new connection is exempt from pruning. last_trim : float | None Unix timestamp of the most recent prune cycle, or None if the connection count has never exceeded the high watermark. Z low_watermarkZhigh_watermarkZconnected_countZ grace_periodNZ last_trim)r2r3r4r5r`r7rr*r*r*r-rs rc @seZdZUdZeed<edefddZede e effddZ ede d e d edd fd d Z ede d e dd fddZede defddZede d e dd fddZede d e defddZedde d e defddZedefddZd S)INetworkServicez Interface for a network service with connection management capabilities. Extends INetwork with go-libp2p style connection manager methods. Zconnection_gater(cCr))z Get total number of connections (inbound + outbound). Returns ------- int Total number of active connections. Nr*r+r*r*r-get_total_connectionsr;z%INetworkService.get_total_connectionscCr))z Get connection metrics (go-libp2p style). Returns ------- dict[str, int] Connection metrics including total, inbound, and outbound counts. Nr*r+r*r*r- get_metricsr;zINetworkService.get_metricsrAtagvalueNcCr))a Tag a peer with a string, associating a weight with the tag. Parameters ---------- peer_id : ID The peer to tag. tag : str The tag name. value : int The weight/value associated with the tag. Nr*)r,rArrr*r*r-tag_peerr;zINetworkService.tag_peercCr))z Remove the tagged value from the peer. Parameters ---------- peer_id : ID The peer to untag. tag : str The tag name to remove. Nr*r,rArr*r*r- untag_peerr;zINetworkService.untag_peercCr))a Get the metadata associated with a peer. Parameters ---------- peer_id : ID The peer to get info for. Returns ------- Any The tag info for the peer, or None if no tags recorded. Nr*rur*r*r- get_tag_info,r;zINetworkService.get_tag_infocCr))z Protect a peer from having its connection(s) pruned. Parameters ---------- peer_id : ID The peer to protect. tag : str Protection tag. Nr*rr*r*r-protect=r;zINetworkService.protectcCr))aS Remove a protection that may have been placed on a peer. Parameters ---------- peer_id : ID The peer to unprotect. tag : str The protection tag to remove. Returns ------- bool True if the peer is still protected by other tags. Nr*rr*r*r- unprotectKr;zINetworkService.unprotectcCr))a8 Check if a peer is protected. Parameters ---------- peer_id : ID The peer to check. tag : str If provided, check if protected by this specific tag. Returns ------- bool True if the peer is protected. Nr*rr*r*r- is_protected^r;zINetworkService.is_protectedcCr))ur Return a unified snapshot of connection manager state. Provides a single call-site for watermarks, live connection count, grace period, and the timestamp of the last prune — matching go-libp2p's BasicConnMgr.GetInfo(). Returns ------- CMInfo Snapshot of current connection manager state. Nr*r+r*r*r-get_conn_mgr_infoqr;z!INetworkService.get_conn_mgr_info)r)r2r3r4r5r r7rr`rrrwrrrrrrr6rrrrr*r*r*r-rs*     rc@seZdZdZedddeddfddZedddeddfd d Zeddd eddfd d Z eddd eddfddZ eddde ddfddZ eddde ddfddZ dS)rz Interface for a network service. Extends the INetwork interface with additional service management capabilities. networkrstreamr(NcrF)z Called when a new stream is opened. Parameters ---------- network : INetwork The network instance on which the stream was opened. stream : INetStream The stream that was opened. Nr*r,rrr*r*r- opened_streamrHzINotifee.opened_streamcrF)z Called when a stream is closed. Parameters ---------- network : INetwork The network instance on which the stream was closed. stream : INetStream The stream that was closed. Nr*rr*r*r- closed_streamrHzINotifee.closed_streamrCcrF)a  Called when a new connection is established. Parameters ---------- network : INetwork The network instance where the connection was established. conn : INetConn The connection that was opened. Nr*r,rrCr*r*r- connectedrHzINotifee.connectedcrF)z Called when a connection is closed. Parameters ---------- network : INetwork The network instance where the connection was closed. conn : INetConn The connection that was closed. Nr*rr*r*r- disconnectedrHzINotifee.disconnected multiaddrcrF)a# Called when a listener starts on a multiaddress. Parameters ---------- network : INetwork The network instance where the listener is active. multiaddr : Multiaddr The multiaddress on which the listener is listening. Nr*r,rrr*r*r-rrHzINotifee.listencrF)a. Called when a listener stops listening on a multiaddress. Parameters ---------- network : INetwork The network instance where the listener was active. multiaddr : Multiaddr The multiaddress that is no longer being listened on. Nr*rr*r*r- listen_closerHzINotifee.listen_close)r2r3r4r5rrcrrrjrrrrrr*r*r*r-rs     rc @seZdZdZedefddZedefddZede fddZ ede fd d Z ed@d d Z edeefddZedeefddZedefddZeedAddZedeefddZedeefddZeejddeedededfdd Zed!ed"eddfd#d$Z ed!eddfd%d&Z!edej"edBfd'd(Z#edBd*d+Z$edCd,e%dBddfd-d.Z&ed/ed0eede'fd1d2Z(ed3e)ddfd4d5Z*ed/eddfd6d7Z+edDd8d9Z,ed:e-d/ede.fd;d<Z/ed:e-d=ede0fd>d?Z1dS)EIHostz Interface for the host. Provides methods for retrieving host information, managing connections and streams, and running the host. r(cCr))z Retrieve the host's peer identifier. Returns ------- ID The host's peer identifier. Nr*r+r*r*r-get_idr;z IHost.get_idcCr))z Retrieve the public key of the host. Returns ------- PublicKey The public key belonging to the host. Nr*r+r*r*r-get_public_keyr;zIHost.get_public_keycCr))z Retrieve the private key of the host. Returns ------- PrivateKey The private key belonging to the host. Nr*r+r*r*r-get_private_keyr;zIHost.get_private_keycCr))z Retrieve the network service instance associated with the host. Returns ------- INetworkService The network instance of the host. Nr*r+r*r*r- get_networkr;zIHost.get_networkr"cCr))z Retrieve the muxer instance for the host. Returns ------- Any The muxer instance of the host. Nr*r+r*r*r-get_muxr;z IHost.get_muxcCr))a Return the addresses this host advertises to other peers. These may differ from the actual listen addresses when ``announce_addrs`` is configured. Each address includes a ``/p2p/{peer_id}`` suffix. Returns ------- list[Multiaddr] A list of advertised multiaddresses, each with a ``/p2p/{peer_id}`` suffix. Nr*r+r*r*r-r+r;zIHost.get_addrscCr))z Retrieve the raw multiaddr addresses this host is listening to, without the /p2p/{peer_id} suffix. Returns ------- list[Multiaddr] A list of raw multiaddresses. Nr*r+r*r*r-get_transport_addrs;r;zIHost.get_transport_addrscCr))z4 :return: the peerstore of the host Nr*r+r*r*r- get_peerstoreHr;zIHost.get_peerstorercCr))u Return the connection manager (TagStore) for this host. Provides access to tag_peer, untag_peer, upsert_tag, protect, unprotect, and is_protected without going through the network layer — matching go-libp2p's h.ConnManager(). Returns ------- TagStore The tag store managing peer priorities and protections. Nr*r+r*r*r- conn_managerNr;zIHost.conn_managercCr))z Retrieve the identifiers of peers currently connected to the host. Returns ------- list[ID] A list of peer identifiers. Nr*r+r*r*r-get_connected_peers_r;zIHost.get_connected_peerscCr))zH :return: List of peer IDs that have active connections Nr*r+r*r*r-get_live_peerskr;zIHost.get_live_peers) task_status listen_addrsrNcCr))aL Run the host and start listening on the specified multiaddresses. Parameters ---------- listen_addrs : Sequence[Multiaddr] A sequence of multiaddresses on which the host should listen. task_status : Any Task status for trio nursery compatibility (ignored). Nr*)r,rrr*r*r-runqr;z IHost.runrfrcCr))a  Set the stream handler for the specified protocol. Parameters ---------- protocol_id : TProtocol The protocol identifier used on the stream. stream_handler : StreamHandlerFn The stream handler function to be set. Nr*)r,rfrr*r*r-rr;zIHost.set_stream_handlercCr))z Remove the stream handler for the specified protocol. Parameters ---------- protocol_id : TProtocol The protocol identifier to remove the handler for. Nr*rgr*r*r-remove_stream_handlerr;zIHost.remove_stream_handlercCr))zP Returns the recving end of the channel, used for metric events Nr*r+r*r*r-get_metrics_recv_channelr;zIHost.get_metrics_recv_channelrcCr))ai Return the host's event bus (INotifee-style listener fan-out). Modules emit typed events on the bus whenever something happens; any number of listeners can register to be notified (the Prometheus metrics exporter being one). Returns ------- EventBus The host's event bus instance. Nr*r+r*r*r- get_event_busr;zIHost.get_event_bus public_ipcrF)zS Initiate the ACME-AUTO-TLS-BROKER negotiation for TLS certificate Nr*)r,rr*r*r-initiate_autotls_procedurerHz IHost.initiate_autotls_procedurerA protocol_idscrF)a Create a new stream to the specified peer. Parameters ---------- peer_id : ID The identifier of the peer to connect. protocol_ids : Sequence[TProtocol] A sequence of available protocol identifiers to use for the stream. Returns ------- INetStream The newly created network stream. Nr*)r,rArr*r*r-rkrHzIHost.new_streamrcrF)a0 Establish a connection to the specified peer. This method ensures there is a connection between the host and the peer represented by the provided peer information. It also absorbs the addresses from ``peer_info`` into the host's internal peerstore. If no active connection exists, the host will dial the peer and block until a connection is established or an error occurs. Parameters ---------- peer_info : PeerInfo The peer information of the peer to connect to. Nr*)r,rr*r*r-connectrHz IHost.connectcrF)z Disconnect from the specified peer. Parameters ---------- peer_id : ID The identifier of the peer to disconnect from. Nr*rur*r*r- disconnectrHzIHost.disconnectcrF)zN Close the host and all underlying connections and services. Nr*r+r*r*r-rIrHz IHost.closercrF)a Upgrade a raw outbound connection to a fully secure and multiplexed network connection for the specified peer. Parameters ---------- raw_conn : IRawConnection The raw (unencrypted/unmultiplexed) connection to upgrade. peer_id : ID The ID of the peer this connection is being established to. Returns ------- INetConn The upgraded and authenticated network connection with security and multiplexing. Raises ------ SwarmException If the upgrade process (security handshake or multiplexer negotiation) fails Nr*rr*r*r-upgrade_outbound_connectionrHz!IHost.upgrade_outbound_connectionrcrF)ac Upgrade a raw inbound connection to a fully secure and multiplexed network connection for the given multiaddress. Parameters ---------- raw_conn : IRawConnection The inbound raw connection to upgrade. maddr : Multiaddr The multiaddress this connection arrived on. Returns ------- IMuxedConn The upgraded and authenticated inbound muxed connection. Raises ------ SwarmException If the upgrade process (security handshake or multiplexer negotiation) fails Nr*rr*r*r-upgrade_inbound_connection rHz IHost.upgrade_inbound_connection)r(r")r(r)r(rrrP)2r2r3r4r5rrrrrrrrrrr8rrrrrrTrrrrRTASK_STATUS_IGNOREDrr r rrrrrMemoryReceiveChannelrrrwrrcrkrrrrIr&rjrr@rr*r*r*r-rs              rc@speZdZdZedefddZedefddZede j fddZ edefd d Z ed e defd d ZdS) IPeerRecorda Interface for a libp2p PeerRecord object. A PeerRecord contains metadata about a peer such as its ID, public addresses, and a strictly increasing sequence number for versioning. PeerRecords are used in signed routing Envelopes for secure peer data propagation. r(cCr))z Return the domain string for this record type. Used in envelope validation to distinguish different record types. Nr*r+r*r*r-domain; r;zIPeerRecord.domaincCr))z Return a binary codec prefix that identifies the PeerRecord type. This is prepended in signed envelopes to allow type-safe decoding. Nr*r+r*r*r-codecC r;zIPeerRecord.codeccCr))z Convert this PeerRecord into its Protobuf representation. :raises ValueError: if serialization fails (e.g., invalid peer ID). :return: A populated protobuf `PeerRecord` message. Nr*r+r*r*r- to_protobufK r;zIPeerRecord.to_protobufcCr))z Serialize this PeerRecord into a byte string. Used when signing or sealing the record in an envelope. :raises ValueError: if protobuf serialization fails. :return: Byte-encoded PeerRecord. Nr*r+r*r*r-marshal_recordT r;zIPeerRecord.marshal_recordothercCr))aY Compare this PeerRecord with another for equality. Two PeerRecords are considered equal if: - They have the same `peer_id` - Their `seq` numbers match - Their address lists are identical and ordered :param other: Object to compare with. :return: True if equal, False otherwise. Nr*r,rr*r*r-equal_ r;zIPeerRecord.equalN)r2r3r4r5rrwr bytesr pbr!r robjectr6rr*r*r*r-r 1 s  r c@sXeZdZedefddZededdfddZedd d Zed e de fd d Z dS) IEnveloper(cCr))z Serialize this Envelope into its protobuf wire format. Converts all envelope fields into a `pb.Envelope` protobuf message and returns the serialized bytes. :return: Serialized envelope as bytes. Nr*r+r*r*r-marshal_envelopep r;zIEnvelope.marshal_enveloper NcCr))aM Verify the envelope's signature within the given domain scope. This ensures that the envelope has not been tampered with and was signed under the correct usage context. :param domain: Domain string that contextualizes the signature. :raises ValueError: If the signature is invalid. Nr*)r,r r*r*r-validate{ r;zIEnvelope.validater!cCr))a{ Lazily decode and return the embedded PeerRecord. This method unmarshals the payload bytes into a `PeerRecord` instance, using the registered codec to identify the type. The decoded result is cached for future use. :return: Decoded PeerRecord object. :raises Exception: If decoding fails or payload type is unsupported. Nr*r+r*r*r-record r;zIEnvelope.recordrcCr))ad Compare this Envelope with another for structural equality. Two envelopes are considered equal if: - They have the same public key - The payload type and payload bytes match - Their signatures are identical :param other: Another object to compare. :return: True if equal, False otherwise. Nr*rr*r*r-r r;zIEnvelope.equal)r(r!) r2r3r4rrrrwrrr r6rr*r*r*r-ro s   rc@s$eZdZdZedeefddZedeeddfddZ edeeddfd d Z edeeddfd d Z edeedeefd dZ edeedefddZ ed@ddZedeeddfddZedeefddZed@ddZedededdfddZededefddZed@d d!Zed"eddfd#d$Zedefd%d&Zed'eddfd(d)Zedefd*d+Zed@d,d-Zed.eddfd/d0Zedefd1d2Z ed@d3d4Z!ed@d5d6Z"ede#fd7d8Z$ede#fd9d:Z%ed;e#ddfdd?Z(dS)A IPeerDataz Interface for managing peer data. Provides methods for handling protocols, addresses, metadata, and keys associated with a peer. r(cCr))z Retrieve all protocols associated with the peer. Returns ------- list[str] A list of protocols associated with the peer. Nr*r+r*r*r-r r;zIPeerData.get_protocolsrNcCr))z Add one or more protocols to the peer's data. Parameters ---------- protocols : Sequence[str] A sequence of protocols to add. Nr*r,rr*r*r-r r;zIPeerData.add_protocolscCr))z Set the protocols for the peer. Parameters ---------- protocols : Sequence[str] A sequence of protocols to set. Nr*rr*r*r-r r;zIPeerData.set_protocolscCr))z Removes the specified protocols from this peer's list of supported protocols. Parameters ---------- protocols : Sequence[str] A sequence of protocol strings to be removed. Nr*rr*r*r-r r;zIPeerData.remove_protocolscCr))a Returns the list of protocols from the input sequence that are supported by this peer. Parameters ---------- protocols : Sequence[str] A sequence of protocol strings to check against this peer's supported protocols. Returns ------- list[str] A list of protocol strings that are supported. Nr*rr*r*r-r r;zIPeerData.supports_protocolscCr))ad Returns the first protocol from the input list that this peer supports. Parameters ---------- protocols : Sequence[str] A sequence of protocol strings to check for support. Returns ------- str The first matching protocol, or an empty string if none are supported. Nr*rr*r*r-r r;z"IPeerData.first_supported_protocolcCr))zE Clears all protocol data associated with this peer. Nr*r+r*r*r-r r;zIPeerData.clear_protocol_datar|cCr))z Add multiple multiaddresses to the peer's data. Parameters ---------- addrs : Sequence[Multiaddr] A sequence of multiaddresses to add. ttl: inr Time to live for the peer record Nr*)r,r|r*r*r-r~ r;zIPeerData.add_addrscCr))z Retrieve all multiaddresses associated with the peer. Returns ------- list[Multiaddr] A list of multiaddresses. Nr*r+r*r*r-r r;zIPeerData.get_addrscCr))z@ Clear all addresses associated with the peer. Nr*r+r*r*r-r" r;zIPeerData.clear_addrsrorrcCr))z Store a metadata key-value pair for the peer. Parameters ---------- key : str The metadata key. val : MetadataValue The value to associate with the key. Nr*)r,rorrr*r*r- put_metadata) r;zIPeerData.put_metadatacCr))aO Retrieve metadata for a given key. Parameters ---------- key : str The metadata key. Returns ------- MetadataValue The metadata value for the given key. Raises ------ PeerDataError If the key is not found. Nr*)r,ror*r*r- get_metadata7 r;zIPeerData.get_metadatacCr))zH Clears all metadata entries associated with this peer. Nr*r+r*r*r-rvM r;zIPeerData.clear_metadatarcCr))z Add a public key to the peer's data. Parameters ---------- pubkey : PublicKey The public key to add. Nr*)r,rr*r*r-rS r;zIPeerData.add_pubkeycCr))z Retrieve the public key for the peer. Returns ------- PublicKey The public key of the peer. Raises ------ PeerDataError If the public key is not found. Nr*r+r*r*r- get_pubkey_ r;zIPeerData.get_pubkeyrcCr))z Add a private key to the peer's data. Parameters ---------- privkey : PrivateKey The private key to add. Nr*)r,rr*r*r-rp r;zIPeerData.add_privkeycCr))z Retrieve the private key for the peer. Returns ------- PrivateKey The private key of the peer. Raises ------ PeerDataError If the private key is not found. Nr*r+r*r*r- get_privkey| r;zIPeerData.get_privkeycCr))z~ Clears all cryptographic key data associated with this peer, including both public and private keys. Nr*r+r*r*r-r r;zIPeerData.clear_keydata new_latencycCr))a! Records a new latency measurement using Exponentially Weighted Moving Average (EWMA). Parameters ---------- new_latency : float The new round-trip time (RTT) latency value to incorporate into the EWMA calculation. Nr*)r,rr*r*r-r r;zIPeerData.record_latencycCr))z Returns the current EWMA value of the recorded latency. Returns ------- float The current latency estimate based on EWMA. Nr*r+r*r*r-r r;zIPeerData.latency_EWMAcCr))zS Clears all latency-related metrics and resets the internal state. Nr*r+r*r*r-r r;zIPeerData.clear_metricscCr))z4 Updates timestamp to current time. Nr*r+r*r*r-update_last_identified r;z IPeerData.update_last_identifiedcCr))z Fetch the last identified timestamp Returns ------- last_identified_timestamp The lastIdentified time of peer. Nr*r+r*r*r-get_last_identified r;zIPeerData.get_last_identifiedcCr))z Get ttl value for the peer for validity check Returns ------- int The ttl of the peer. Nr*r+r*r*r-get_ttl r;zIPeerData.get_ttlrWcCr))z Set ttl value for the peer for validity check Parameters ---------- ttl : int The ttl for the peer. Nr*rXr*r*r-set_ttl r;zIPeerData.set_ttlcCr))z Check if the peer is expired based on last_identified and ttl Returns ------- bool True, if last_identified + ttl > current_time Nr*r+r*r*r- is_expired r;zIPeerData.is_expiredrP))r2r3r4r5rr8rwrrrrrrrrrr~rrrrrrvrrrrrrrrrrrr r`r!r"r#r6r$r*r*r*r-r sl                  rc@s8eZdZdZededdfddZedefddZdS) IMultiselectCommunicatorz Communicator helper for multiselect. Ensures that both the client and multistream module follow the same multistream protocol. msg_strr(NcrF)z Write a message to the stream. Parameters ---------- msg_str : str The message string to write. Nr*)r,r&r*r*r-write rHzIMultiselectCommunicator.writecrF)z Read a message from the stream until EOF. Returns ------- str The message read from the stream. Nr*r+r*r*r-read rHzIMultiselectCommunicator.read)r2r3r4r5rrwr'r(r*r*r*r-r% s  r%c@s^eZdZdZededdfddZedeededefdd Z eded edefd d Z dS) IMultiselectClientz Client for multiselect negotiation. Communicates with the receiver's multiselect module to select a protocol for communication. communicatorr(NcrF)a Ensure that the client and multiselect module are using the same multiselect protocol. Parameters ---------- communicator : IMultiselectCommunicator The communicator used for negotiating the multiselect protocol. Raises ------ Exception If there is a multiselect protocol ID mismatch. Nr*r,r*r*r*r- handshake rHzIMultiselectClient.handshakercrF)a Select one protocol from a sequence by communicating with the multiselect module. For each protocol in the provided sequence, the client sends a selection message and expects the multiselect module to confirm the protocol. The first confirmed protocol is returned. Parameters ---------- protocols : Sequence[TProtocol] The protocols to attempt selection. communicator : IMultiselectCommunicator The communicator used for negotiating the protocol. Returns ------- TProtocol The protocol selected by the multiselect module. Nr*)r,rr*r*r*r- select_one_of, rHz IMultiselectClient.select_one_ofprotocolcrF)a Attempt to select the given protocol. Parameters ---------- communicator : IMultiselectCommunicator The communicator used to interact with the counterparty. protocol : TProtocol The protocol to select. Returns ------- TProtocol The protocol if successfully selected. Raises ------ Exception If protocol selection fails. Nr*)r,r*r.r*r*r- try_selectF rHzIMultiselectClient.try_select) r2r3r4r5rr%r,rrr-r/r*r*r*r-r) s( r)c@seZdZUdZeedBedBfed<edededdfddZ ededdfd d Z ede edBd ffd d Z ede de edBedBffddZdS)IMultiselectMuxerz Multiselect module for protocol negotiation. Responsible for responding to a multiselect client by selecting a protocol and its corresponding handler for communication. Nhandlersr.handlerr(cCr))a Store a handler for the specified protocol. Parameters ---------- protocol : TProtocol The protocol name. handler : StreamHandlerFn The handler function associated with the protocol. Nr*)r,r.r2r*r*r- add_handlern r;zIMultiselectMuxer.add_handlercCr))z Remove the handler for the specified protocol. Parameters ---------- protocol : TProtocol The protocol name to remove. Nr*)r,r.r*r*r-remove_handler| r;z IMultiselectMuxer.remove_handler.cCr))z Retrieve the protocols for which handlers have been registered. Returns ------- tuple[TProtocol, ...] A tuple of registered protocol names. Nr*r+r*r*r-r r;zIMultiselectMuxer.get_protocolsr*crF)a Negotiate a protocol selection with a multiselect client. Parameters ---------- communicator : IMultiselectCommunicator The communicator used to negotiate the protocol. Returns ------- tuple[TProtocol, StreamHandlerFn] A tuple containing the selected protocol and its handler. Raises ------ Exception If negotiation fails. Nr*r+r*r*r- negotiate rHzIMultiselectMuxer.negotiate)r2r3r4r5rrrr7rr3r4rmrr%r5r*r*r*r-r0d s    r0c@sJeZdZdZed dededdfddZeded ede e fd d Z dS) IContentRoutingzm Interface for content routing. Provides methods to advertise and search for content providers. Tcidannouncer(NcCr))a Advertise that the host can provide content identified by the given CID. If ``announce`` is True, the content is announced; otherwise, it is only recorded locally. Parameters ---------- cid : bytes The content identifier. announce : bool, optional Whether to announce the provided content (default is True). Nr*)r,r7r8r*r*r-provide r;zIContentRouting.providecountcCr))a Search for peers that can provide the content identified by the given CID. Parameters ---------- cid : bytes The content identifier. count : int The maximum number of providers to return. Returns ------- Iterable[PeerInfo] An iterator of PeerInfo objects for peers that provide the content. Nr*)r,r7r:r*r*r-find_provider_iter r;z"IContentRouting.find_provider_iter)T) r2r3r4r5rrr6r9r`rrr;r*r*r*r-r6 s  r6c@s*eZdZdZedededBfddZdS) IPeerRoutingzZ Interface for peer routing. Provides methods to search for a specific peer. rAr(NcrF)a$ Search for a peer with the specified peer ID. Parameters ---------- peer_id : ID The identifier of the peer to search for. Returns ------- PeerInfo The peer information containing relevant addresses. Nr*rur*r*r- find_peer rHzIPeerRouting.find_peer)r2r3r4r5rrrr=r*r*r*r-r< sr<c@s@eZdZdZededefddZedededefddZ d S) ISecureTransporta Interface for a security transport. Used to secure connections by performing handshakes and negotiating secure channels between peers. References ---------- https://github.com/libp2p/go-conn-security/blob/master/interface.go rCr(crF)a Secure an inbound connection (when we are not the initiator). This method secures the connection by either performing local operations or communicating with the opposing node. Parameters ---------- conn : IRawConnection The raw connection to secure. Returns ------- ISecureConn The secured connection instance. Nr*)r,rCr*r*r-secure_inbound rHzISecureTransport.secure_inboundrAcrF)a Secure an outbound connection (when we are the initiator). This method secures the connection by either performing local operations or communicating with the opposing node. Parameters ---------- conn : IRawConnection The raw connection to secure. peer_id : ID The identifier of the remote peer. Returns ------- ISecureConn The secured connection instance. Nr*rDr*r*r-secure_outbound rHz ISecureTransport.secure_outboundN) r2r3r4r5rr&r?r?rr@r*r*r*r-r> s  r>c@seZdZUdZdZeed<edede fddZ ede de fd d Z ededefd d Zededefd dZedeefddZdS) ITransportzt Interface for a transport. Provides methods for dialing peers and creating listeners on a transport. Fprovides_native_muxingrr(crF)a  Dial a peer on the specified multiaddress. Parameters ---------- maddr : Multiaddr The multiaddress of the peer to dial. Returns ------- IRawConnection The raw connection established to the peer. Nr*rr*r*r-dial@ rHzITransport.dialhandler_functioncCr))a Create a listener on the transport. Parameters ---------- handler_function : THandler A function that is called when a new connection is received. The function should accept a connection (that implements the connection interface) as its argument. Returns ------- IListener A listener instance. Nr*)r,rDr*r*r-create_listenerQ r;zITransport.create_listenercCr))a Return True if this transport can dial the given multiaddr. The TransportManager calls this method before attempting a dial to route the connection to the correct transport. Parameters ---------- maddr : Multiaddr The multiaddress to check. Returns ------- bool True if this transport can dial maddr, False otherwise. Examples -------- - TCP returns True for ``/ip4/127.0.0.1/tcp/4001`` - WebSocket returns True for ``/ip4/127.0.0.1/tcp/8080/ws`` - QUIC returns True for ``/ip4/127.0.0.1/udp/4001/quic-v1`` Nr*rr*r*r-can_diald r;zITransport.can_dialcCr))u Return True if this transport can listen on the given multiaddr. Often identical to :meth:`can_dial` but may differ — e.g. a relay transport can dial outbound but cannot accept inbound connections. Parameters ---------- maddr : Multiaddr The multiaddress to check. Returns ------- bool True if this transport can listen on maddr, False otherwise. Nr*rr*r*r- can_listen~ r;zITransport.can_listencCr))a Return the list of multiaddr protocol names this transport handles. Used by :class:`~libp2p.transport.manager.TransportManager` as a fast pre-filter: if the multiaddr contains none of the listed protocol names, ``can_dial`` / ``can_listen`` are not called. Returns ------- list[str] Protocol name strings, e.g. ``["tcp"]``, ``["ws", "wss"]``, or ``["quic", "quic-v1"]``. Nr*r+r*r*r-r r;zITransport.protocolsN)r2r3r4r5rBr6r7rrr&rCrrrErFrGr8rwrr*r*r*r-rA3 s  rAc@s2eZdZdZedddZedejfddZdS) ISubscriptionAPIz} Interface for a subscription in pubsub. Combines asynchronous context management and iteration over messages. r(NcrF)z6 Unsubscribe from the current topic. Nr*r+r*r*r- unsubscribe rzISubscriptionAPI.unsubscribecrF)z Retrieve the next message from the subscription. Returns ------- rpc_pb2.Message The next pubsub message. Nr*r+r*r*r-rq  zISubscriptionAPI.getrP) r2r3r4r5rrIr$Messagerqr*r*r*r-rH s  rHc@s6eZdZUdZeeeefed<eeeefed<eee fed<e ed<e de e fddZ e d%d d Ze dede d Bdd fddZe dedd fddZe dejdedd fddZe dedejdd fddZe dedd fddZe dedd fdd Zdedd fd!d"Zdededd fd#d$Zd S)& IPubsubRouterz Interface for a pubsub router. Provides methods to manage protocol support, peer attachments, and message handling for pubsub. meshZfanoutZ peer_protocoldegreer(cCr))z Retrieve the list of protocols supported by the router. Returns ------- list[TProtocol] A list of supported protocol identifiers. Nr*r+r*r*r-r r;zIPubsubRouter.get_protocolspubsubr#NcCr))z Attach the router to a newly initialized PubSub instance. Parameters ---------- pubsub : Pubsub The PubSub instance to attach to. Nr*)r,rOr*r*r-attach r;zIPubsubRouter.attachrArfcCr))a Notify the router that a new peer has connected. Parameters ---------- peer_id : ID The identifier of the peer. protocol_id : TProtocol The protocol the peer supports (e.g., floodsub, gossipsub). Nr*)r,rArfr*r*r-add_peer r;zIPubsubRouter.add_peercCr))z Notify the router that a peer has disconnected. Parameters ---------- peer_id : ID The identifier of the peer to remove. Nr*rur*r*r- remove_peer r;zIPubsubRouter.remove_peerrpcsender_peer_idcrF)a Process an RPC message received from a peer. Parameters ---------- rpc : rpc_pb2.RPC The RPC message to process. sender_peer_id : ID The identifier of the peer that sent the message. Nr*)r,rSrTr*r*r- handle_rpc rHzIPubsubRouter.handle_rpc msg_forwarder pubsub_msgcrF)z Forward a validated pubsub message. Parameters ---------- msg_forwarder : ID The identifier of the message sender. pubsub_msg : rpc_pb2.Message The pubsub message to forward. Nr*)r,rVrWr*r*r-publish rHzIPubsubRouter.publishtopiccrF)z Join a topic to receive and forward messages. Parameters ---------- topic : str The topic to join. Nr*r,rYr*r*r-join$ rHzIPubsubRouter.joincrF)z Leave a topic, stopping message forwarding for that topic. Parameters ---------- topic : str The topic to leave. Nr*rZr*r*r-leave0 rHzIPubsubRouter.leavecrF)a Send messages the router queued while the peer was still connecting. Optional hook, invoked once the outbound stream for the peer is registered and again when the peer announces a new subscription. Routers that do not queue during connection setup keep the no-op. Parameters ---------- peer_id : ID The peer whose queued messages should be sent. Nr*rur*r*r-flush_pending_messages< rHz$IPubsubRouter.flush_pending_messagescrF)a Replay recently seen messages for a topic to a peer. Optional hook, invoked when a peer that is subscribed to the topic becomes writable. Routers without a message cache keep the no-op. Parameters ---------- peer_id : ID The peer to replay messages to. topic : str The topic to replay messages for. Nr*)r,rArYr*r*r-send_recent_messagesK rHz"IPubsubRouter.send_recent_messages)rOr#r(N)r2r3r4r5rrwsetrr7rr`rr8rrPrQrRr$ZRPCrUrKrXr[r\r]r^r*r*r*r-rL s0         rLc @s,eZdZdZeedefddZeedee dffddZ eede e fdd Z ed e d ed edd fddZed e dd fddZed#ddZede defddZede dd fddZede ee Bdedd fddZed$dededd fdd Ze d$dede dedd fd!d"Zd S)%IPubsubz Interface for the pubsub system. Provides properties and methods to manage topics, subscriptions, and message publishing. r(cCr))z Retrieve the identifier for this pubsub instance. Returns ------- ID The pubsub identifier. Nr*r+r*r*r-my_idd  z IPubsub.my_id.cCr))z Retrieve the protocols used by the pubsub system. Returns ------- tuple[TProtocol, ...] A tuple of protocol identifiers. Nr*r+r*r*r-rr rbzIPubsub.protocolscCr))z Retrieve the set of topic identifiers. Returns ------- KeysView[str] A view of the topic identifiers. Nr*r+r*r*r- topic_ids rbzIPubsub.topic_idsrY validatoris_async_validatorNcCr))aB Set a validator for a specific topic. Parameters ---------- topic : str The topic for which to set the validator. validator : ValidatorFn The validator function. is_async_validator : bool Whether the validator is asynchronous. Nr*)r,rYrdrer*r*r-set_topic_validator szIPubsub.set_topic_validatorcCr))z Remove the validator for a specific topic. Parameters ---------- topic : str The topic whose validator should be removed. Nr*rZr*r*r-remove_topic_validator s zIPubsub.remove_topic_validatorcrF)zO Wait until the pubsub system is fully initialized and ready. Nr*r+r*r*r-wait_until_ready rzIPubsub.wait_until_readytopic_idcrF)a Subscribe to a topic. Parameters ---------- topic_id : str The identifier of the topic to subscribe to. Returns ------- ISubscriptionAPI An object representing the subscription. Nr*r,rir*r*r- subscribe szIPubsub.subscribecrF)z Unsubscribe from a topic. Parameters ---------- topic_id : str The identifier of the topic to unsubscribe from. Nr*rjr*r*r-rI rJzIPubsub.unsubscribedatacrF)a Publish a message to a topic or multiple topics. Parameters ---------- topic_id : str | list[str] The identifier of the topic (str) or topics (list[str]). data : bytes The data to publish. Nr*)r,rirlr*r*r-rX s zIPubsub.publish@rAtimeoutcrF)a Wait until a pubsub stream with the given peer has been established. This method blocks until the given peer has been added to the pubsub peers map, indicating that a pubsub protocol stream exists. Use this instead of arbitrary trio.sleep() calls to avoid race conditions. The implementation uses an event-based approach with :class:`trio.Event` so the task consumes zero CPU while waiting. Parameters ---------- peer_id : ID The identifier of the peer to wait for. timeout : float Maximum time to wait in seconds. Defaults to 5.0. Raises ------ trio.TooSlowError If the peer stream is not established within the timeout period. Example:: await connect(host1, host2) await pubsub1.wait_for_peer(host2.get_id()) # Now safe to publish or check peer_topics Nr*)r,rArnr*r*r- wait_for_peer szIPubsub.wait_for_peercrF)a Wait until a specific peer has subscribed to a topic. This method blocks until the given peer appears in the peer_topics map for the specified topic, indicating that they have sent a subscription message. Use this instead of arbitrary trio.sleep() calls to avoid race conditions. The implementation uses an event-based approach with :class:`trio.Event` so the task consumes zero CPU while waiting. Parameters ---------- peer_id : ID The identifier of the peer to wait for. topic_id : str The topic to check subscription for. timeout : float Maximum time to wait in seconds. Defaults to 5.0. Raises ------ trio.TooSlowError If the peer does not subscribe within the timeout period. Example:: await connect(host1, host2) await pubsub1.wait_for_subscription(host2.get_id(), "my-topic") # Now safe to assert subscription state Nr*)r,rArirnr*r*r-wait_for_subscriptions$zIPubsub.wait_for_subscriptionrP)rm)r2r3r4r5rTrrrarmrrrrwrcrr6rfrgrhrHrkrIr8rrXrrorpr*r*r*r-r`\ sX       r`c @s`eZdZdZedddZedddZedefdd Zed e d e d e de e fd dZ dS)IPerfzv Interface for the perf protocol service. Spec: https://github.com/libp2p/specs/blob/master/perf/perf.md r(NcrF)z9Start the perf service and register the protocol handler.Nr*r+r*r*r-rG6r[z IPerf.startcrF)z:Stop the perf service and unregister the protocol handler.Nr*r+r*r*r-stop;r[z IPerf.stopcCr))z*Check if the service is currently running.Nr*r+r*r*r- is_started@szIPerf.is_startedr send_bytes recv_bytescCr))a Measure transfer performance to a remote peer. Parameters ---------- multiaddr : Multiaddr The address of the remote peer to test against. send_bytes : int Number of bytes to upload to the remote peer. recv_bytes : int Number of bytes to request the remote peer to send back. Yields ------ PerfOutput Progress reports during the transfer, with a final summary at the end. Nr*)r,rrtrur*r*r-measure_performanceEszIPerf.measure_performancerP)r2r3r4r5rrGrrr6rsrr`rr rvr*r*r*r-rq/s$  rq)aabcrrcollections.abcrrrrr contextlibr dataclassesr typesr typingr r rrrrrRZlibp2p.connection_typesrlibp2p.crypto.keysrrrlibp2p.custom_typesrrrrrZlibp2p.events.busrZ libp2p.io.abcrrlibp2p.peer.idrZlibp2p.peer.pb.peer_record_pb2ZpeerrZpeer_record_pb2Zlibp2p.peer.peerinforZlibp2p.network.tag_storerZlibp2p.peer.enveloper Zlibp2p.peer.peer_recordr!Z!libp2p.protocol_muxer.multiselectr"libp2p.pubsub.pubsubr#Zlibp2p.pubsub.pbr$Zlibp2p.tools.anyio_service.apir%r&r9r?r@rMrcrjrnrxrrrrrrrrrrrr rrr%r)r0r6r<r>rArKrHrLr`rqr*r*r*r-s               %* k3,A-XC]4 u "7u aM>7J$RL,; u T