3.0.ipv8.attestation.tokentree.tree
===================================

.. py:module:: 3.0.ipv8.attestation.tokentree.tree


Classes
-------

.. autoapisummary::

   3.0.ipv8.attestation.tokentree.tree.TokenTree


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

.. py:class:: TokenTree(public_key: 3.0.ipv8.types.PublicKey | None = None, private_key: 3.0.ipv8.types.PrivateKey | None = None)

   Raw datatype for chains of double pointers (Tokens).

   It takes the following form:

       SHA3-256(PUBLIC KEY) <- TOKEN <- TOKEN <- ...

   Each token also has a SHA3-256 pointer to external content.

   Note that the public key has to be known to fulfil the genesis pointer to the SHA3-256 hash (the public key is not
   stored in the Tokens themselves).


   .. py:attribute:: _logger


   .. py:attribute:: elements
      :type:  dict[bytes, 3.0.ipv8.attestation.tokentree.token.Token]


   .. py:attribute:: unchained
      :type:  collections.OrderedDict


   .. py:attribute:: unchained_max_size
      :value: 100



   .. py:attribute:: genesis_hash


   .. py:method:: add(content: bytes, after: 3.0.ipv8.attestation.tokentree.token.Token | None = None) -> 3.0.ipv8.attestation.tokentree.token.Token

      Tokenize new content and add it to this chain.

      :param content: the content to tokenize and add to this chain.
      :param after: the token to succeed.
      :returns: the newly added Token.



   .. py:method:: add_by_hash(content_hash: bytes, after: 3.0.ipv8.attestation.tokentree.token.Token | None = None) -> 3.0.ipv8.attestation.tokentree.token.Token

      Add the promise of tokenized content to this chain.

      :param content_hash: the hash of the content to add to this chain.
      :param after: the token to succeed.
      :returns: the newly added Token.



   .. py:method:: gather_token(token: 3.0.ipv8.attestation.tokentree.token.Token) -> 3.0.ipv8.attestation.tokentree.token.Token | None

      Attempt to add received data to this chain.
      Data may be pending missing Tokens before being added to the chain structure.

      :param token: the token to attempt to add.
      :returns: the newly added token or None if the operation was not successful.



   .. py:method:: get_missing() -> set[bytes]

      Gather all the preceding hashes that have been specified but not collected.

      :returns: the set of missing hashes.



   .. py:method:: verify(token: 3.0.ipv8.attestation.tokentree.token.Token, maxdepth: int = 1000) -> bool

      Verify the chain integrity: all preceding tokens are correctly signed and stored.

      Should only be done when loading from database or direct writing (don't do that) by programmers.

      :param token: the token to start checking from.
      :param maxdepth: the maximum amount of steps to verify (after which this returns False).
      :returns: whether all preceding tokens were correct and signed.



   .. py:method:: get_root_path(token: 3.0.ipv8.attestation.tokentree.token.Token, maxdepth: int = 1000) -> list[3.0.ipv8.attestation.tokentree.token.Token]

      Calculate the path back to the root, including this token.

      :param token: the token to start checking from.
      :param maxdepth: the maximum amount of steps (after which this returns an empty list).
      :returns: the length of the path back to the root or an empty list if it doesn't exist.



   .. py:method:: serialize_public(up_to: 3.0.ipv8.attestation.tokentree.token.Token | None = None) -> bytes

      Serialize all the signed double pointers of this chain.

      :param up_to: the token to work back from to the root of the tree.



   .. py:method:: unserialize_public(s: bytes) -> bool

      Given a serialized tree format, unserialize with the tree's public key.

      :param s: the serialized tree data.
      :returns: if all information was correctly unserialized.



   .. py:method:: _append(token: 3.0.ipv8.attestation.tokentree.token.Token) -> 3.0.ipv8.attestation.tokentree.token.Token

      Append a token to this tree. Never call this directly: use add() instead!

      :param token: the token to append to the chain.
      :returns: the appended token.



   .. py:method:: _append_chain_reaction_token(token: 3.0.ipv8.attestation.tokentree.token.Token) -> None

      Append the given token and wake up any tokens stored in `unchained` that pointed to it.

      :param token: the token to append to the chain.