Update docs for Whisper v6 API

ethereum · Apr 23, 2018 · 27a7f38 · 27a7f38
1 parent 20cb2a0
commit 27a7f38
Show file tree

Hide file tree

Showing 3 changed files with 153 additions and 45 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -54,7 +54,7 @@
 
 # General information about the project.
 project = u'Web3.py'
-copyright = u'2017, Piper Merriam, Jason Carver'
+copyright = u'2018, Piper Merriam, Jason Carver'
 
 __version__ = setup_version
 # The version info for the project you're documenting, acts as replacement for

diff --git a/docs/web3.shh.rst b/docs/web3.shh.rst
@@ -24,108 +24,216 @@ The following properties are available on the ``web.shh`` namespace.
     .. code-block:: python
 
         >>>web3.shh.version
-        2
+        6.0
+
+.. py:attribute:: Shh.info
+
+    The information and properties currently set for the Whisper protocol
+
+    .. code-block:: python
+
+        >>>web3.shh.info
+        {'maxMessageSize': 1024, 'memory': 240, 'messages': 0, 'minPow': 0.2}
 
 Methods
 -------
 
 The following methods are available on the ``web3.shh`` namespace.
 
 
-.. py:method:: Shh.post(self, params)
+.. py:method:: Shh.post(self, message)
 
     * Delegates to ``shh_post`` RPC method
 
-    * ``params`` cannot be ``None`` and should contain ``topics`` and ``payload``
+    * ``message`` cannot be ``None`` and should contain a ``payload``
 
-    * Returns ``True`` if the message was succesfully sent,otherwise ``False``
+    * Returns ``True`` if the message was succesfully sent, otherwise ``False``
 
     .. code-block:: python
 
-        >>>web3.shh.post({"topics":[web3.toHex(text="test_topic")],"payload":web3.toHex(text="test_payload")})
+        >>>web3.shh.post({'payload': web3.toHex(text="test_payload"), 'pubKey': recipient_public, 'topic': '0x12340000', 'powTarget': 2.5, 'powTime': 2})
         True
 
-.. py:method:: Shh.newIdentity(self)
+.. py:method:: Shh.newMessageFilter(self, criteria, poll_interval=None)
+
+    * Delegates to ``shh_newMessageFilter`` RPC method
 
-    * Delegates to ``shh_newIdentity`` RPC method
+    * If a ``poll_interval`` is specified, the client will asynchronously poll for new messages
 
-    * Returns ``address`` of newly created identity.
+    * Returns ``ShhFilter`` which you can either ``watch(callback)`` or request ``get_new_entries()``
 
     .. code-block:: python
 
-        >>>web3.shh.newIdentity()
-        u'0x045ed8042f436e1b546afd16e1f803888b896962484c0154fcc7c5fc43e276972af85f29a995a3beb232a4e9a0648858c0c8c0639d709f5d3230807d084b2d5030'
+        >>>web3.shh.newMessageFilter({'topic': '0x12340000', 'privateKeyID': recipient_private})
+        ShhFilter({'filter_id': 'b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554'})
 
-.. py:method:: Shh.hasIdentity(self, identity)
+.. py:method:: Shh.deleteMessageFilter(self, filter_id)
 
-    * Delegates to ``shh_hasIdentity`` RPC method
+    * Delegates to ``shh_deleteMessageFilter`` RPC Method
 
-    * Returns ``True`` if the client holds the private key for the given identity,otherwise ``False``
+    * Returns ``True`` if the filter was sucesfully uninstalled, otherwise ``False``
 
     .. code-block:: python
 
-        >>>web3.shh.hasIdentity(u'0x045ed8042f436e1b546afd16e1f803888b896962484c0154fcc7c5fc43e276972af85f29a995a3beb232a4e9a0648858c0c8c0639d709f5d3230807d084b2d5030')
+        >>>web3.shh.deleteMessageFilter('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
         True
 
-.. py:method:: Shh.newGroup(self)
+.. py:method:: Shh.getMessages(self, filter_id)
 
-    * Delegates to ``shh_newGroup`` RPC method
+    * Delegates to ``shh_getMessages`` RPC Method
 
-    * Returns ``address`` of newly created group.
+    * Returns all new messages since the last invocation
 
-    .. note:: This method is not implemented yet in ``Geth``. `Open Issue <https://github.com/ethereum/go-ethereum/issues/310>`_
+    .. code-block:: python
+
+        >>>web3.shh.getMessages('b37c3106cfb683e8f01b5019342399e0d1d74e9160f69b27625faba7a6738554')
+        [{
+            'ttl': 50,
+            'timestamp': 1524497850,
+            'topic': HexBytes('0x13370000'),
+            'payload': HexBytes('0x74657374206d657373616765203a29'),
+            'padding': HexBytes('0x50ab643f1b23bc6df1b1532bb6704ad947c2453366754aade3e3597553eeb96119f4f4299834d9989dc4ecc67e6b6470317bb3f7396ace0417fc0d6d2023900d3'),
+            'pow': 6.73892030848329,
+            'hash': HexBytes('0x7418f8f0989655ed2f4f9b496e6b1d9be51ef9f0f5ad89f6f750b0eee268b02f'),
+            'recipientPublicKey': HexBytes('0x047d36c9e45fa82fcd27d35bc7d2fd41a2e41e512feec9e4b90ee4293ab12dc2cfc98250a6f5689b07650f8a5ca3a6e0fa8808cd0ce1a1962f2551354487a8fc79')
+        }]
 
-.. py:method:: Shh.addToGroup(self, identity)
+---------------
+Asymmetric Keys
+---------------
 
-    * Delegates to ``shh_addToGroup`` RPC Method
+.. py:method:: Shh.newKeyPair(self)
 
-    * Returns ``True`` if the identity was succesfully added to the group,otherwise ``False``
+    * Delegates to ``shh_newKeyPair`` RPC method. Generates a new cryptographic identity for the client, and injects it into the known identities for message decryption
 
-    .. note:: This method is not implemented yet in ``Geth``. `Open Issue <https://github.com/ethereum/go-ethereum/issues/310>`_
+    * Returns the new key pair's identity
+
+    .. code-block:: python
 
-.. py:method:: Shh.filter(self, filter_params)
+        >>>web3.shh.newKeyPair()
+        '86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb'
 
-    * Delegates to ``shh_newFilter`` RPC Method
+.. py:method:: Shh.addPrivateKey(self, key)
 
-    * ``filter_params`` should contain the ``topics`` to subscribe
+    * Delegates to ``shh_addPrivateKey`` RPC method
 
-    * Returns an instance of ``ShhFilter`` on succesful creation of filter,otherwise raises ``ValueError`` exception
+    * Returns ``True`` if the key pair was added, otherwise ``False``
 
     .. code-block:: python
 
-        >>>shh_filter = shh.filter({"topics":[web.toHex(text="topic_to_subscribe")]})
-        >>>shh_filter.filter_id
-        u'0x0'
+        >>>web3.shh.addPrivateKey('0x7b8190d96cd061a102e551ee36d08d4f3ca1f56fb0008ef5d70c56271d8c46d0')
+        True
 
-.. py:method:: Shh.uninstallFilter(self, filter_id)
+.. py:method:: Shh.deleteKeyPair(self, id)
 
-    * Delegates to ``shh_uninstallFilter`` RPC Method
+    * Delegates to ``shh_deleteKeyPair`` RPC method
 
-    * Returns ``True`` if the filter was sucesfully uninstalled ,otherwise ``False``
+    * Returns ``True`` if the key pair was deleted, otherwise ``False``
 
     .. code-block:: python
 
-        >>>web3.shh.uninstallFilter("0x2")
+        >>>web3.shh.deleteKeyPair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
         True
 
-.. py:method:: Shh.getFilterChanges(self, filter_id)
+.. py:method:: Shh.hasKeyPair(self, id)
 
-    * Delegates to ``shh_getFilterChanges`` RPC Method
+    * Delegates to ``shh_hasKeyPair`` RPC method
 
-    * Returns list of messages recieved since last poll
+    * Returns ``True`` if the key pair exists, otherwise ``False``
 
     .. code-block:: python
 
-        >>>web3.shh.getFilterChanges(self,"0x2")
-        [{u'from': u'0x0', u'to': u'0x0', u'ttl': 50, u'hash': u'0xf84900b57d856a6ab1b41afc9784c31be48e841b9bcfc6accac14d05d7189f2f', u'payload': u'0x746573696e67', u'sent': 1476625149}]
+        >>>web3.shh.hasKeyPair('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        False
 
-.. py:method:: Shh.getMessages(self, filter_id)
+.. py:method:: Shh.getPublicKey(self, id)
 
-    * Delegates to ``shh_getMessages`` RPC Method
+    * Delegates to ``shh_getPublicKey`` RPC method
+
+    * Returns the public key associated with the key pair
+
+    .. code-block:: python
+
+        >>>web3.shh.getPublicKey('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        '0x041b0777ceb8cf8748fe0bba5e55039d650a03eb0239a909f9ee345bbbad249f2aa236a4b8f41f51bd0a97d87c08e69e67c51f154d634ba51a224195212fc31e4e'
+
+.. py:method:: Shh.getPrivateKey(self, id)
+
+    * Delegates to ``shh_getPrivateKey`` RPC method
+
+    * Returns the private key associated with the key pair
+
+    .. code-block:: python
+
+        >>>web3.shh.getPrivateKey('86e658cbc6da63120b79b5eec0c67d5dcfb6865a8f983eff08932477282b77bb')
+        '0x7b8190d96cd061a102e551ee36d08d4f3ca1f56fb0008ef5d70c56271d8c46d0'
+
+---------------
+Symmetric Keys
+---------------
+
+.. py:method:: Shh.newSymKey(self)
+
+    * Delegates to ``shh_newSymKey`` RPC method. Generates a random symmetric key and stores it under id, which is then returned. Will be used in the future for session key exchange
+
+    * Returns the new key pair's identity
+
+    .. code-block:: python
+
+        >>>web3.shh.newSymKey()
+        '6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c'
+
+.. py:method:: Shh.addSymKey(self, key)
+
+    * Delegates to ``shh_addSymKey`` RPC method
+
+    * Returns ``True`` if the key was added, otherwise ``False``
+
+    .. code-block:: python
+
+        >>>web3.shh.addSymKey('0x58f6556e56a0d41b464a083161377c8a9c2e95156921f954f99ef97d41cebaa2')
+        True
+
+.. py:method:: Shh.generateSymKeyFromPassword(self)
+
+    * Delegates to ``shh_generateSymKeyFromPassword`` RPC method
+
+    * Returns the new key pair's identity
+
+    .. code-block:: python
+
+        >>>web3.shh.generateSymKeyFromPassword('shh secret pwd')
+        '6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c'
+
+.. py:method:: Shh.deleteSymKey(self, id)
+
+    * Delegates to ``shh_deleteSymKey`` RPC method
+
+    * Returns ``True`` if the key pair was deleted, otherwise ``False``
+
+    .. code-block:: python
+
+        >>>web3.shh.deleteSymKey('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        True
+
+.. py:method:: Shh.hasSymKey(self, id)
+
+    * Delegates to ``shh_hasSymKey`` RPC method
+
+    * Returns ``True`` if the key exists, otherwise ``False``
+
+    .. code-block:: python
+
+        >>>web3.shh.hasSymKey('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        False
+
+.. py:method:: Shh.getSymKey(self, id)
+
+    * Delegates to ``shh_getSymKey`` RPC method
 
-    * Returns a list of all messages
+    * Returns the public key associated with the key pair
 
     .. code-block:: python
 
-        >>>web3.shh.getMessages("0x2")
-        [{u'from': u'0x0', u'to': u'0x0', u'ttl': 50, u'hash': u'0x808d74d003d1dcbed546cca29d7a4e839794c226296b613b0fa7a8c670f84146', u'payload': u'0x746573696e67617364', u'sent': 1476625342}, {u'from': u'0x0', u'to': u'0x0', u'ttl': 50, u'hash': u'0x62a2eb9a19968d59d8a85e6dc8d73deb9b4cd40c83d95b796262d6affe6397c6', u'payload': u'0x746573696e67617364617364', u'sent': 1476625369}]
+        >>>web3.shh.getSymKey('6c388d63003deb378700c9dad87f67df0247e660647d6ba1d04321bbc2f6ce0c')
+        '0x58f6556e56a0d41b464a083161377c8a9c2e95156921f954f99ef97d41cebaa2'
diff --git a/web3/shh.py b/web3/shh.py
@@ -68,7 +68,7 @@ def post(self, message):
                 "message cannot be None or does not contain field 'payload'"
             )
 
-    def filter(self, criteria, poll_interval=None):
+    def newMessageFilter(self, criteria, poll_interval=None):
         filter_id = self.web3.manager.request_blocking("shh_newMessageFilter", [criteria])
         return ShhFilter(self.web3, filter_id, poll_interval=poll_interval)