.. _API Reference:

*************************
API reference
*************************



HTTP
=========================

+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name          | Method | Descriptors   |                                                                                                                                                                                                                                                                                                                                                             |
+===============+========+===============+=============================================================================================================================================================================================================================================================================================================================================================+
| bzz           | GET    | Purpose       | retrieve document at domain/some/path allowing domain to resolve via the :ref:`Ethereum Name Service`                                                                                                                                                                                                                                                       |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz:/<domain_part>/<resource_path>                                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | domain part: mandatory - ENS name or a valid Swarm hash. path part: optional - a case insensitive path to match for in the manifest                                                                                                                                                                                                                         |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 300; 404; 500                                                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | The content stored at the resolved ENS entry (or the matched path) with the appropriate Content-Type as stored in the manifest                                                                                                                                                                                                                              |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               | POST   | Purpose       | post an application/x-tar or multipart/form-data (or any other Content-Type for that matter); create an appropriate manifest and retrieve the associated hash. if an existing manifest address is given with the according path to update - a copy of the manifest will be created with the updated entry and the hash of the new manifest will be returned |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz:/<manifest_hash?>/<resource_path?>/<encrypt?>                                                                                                                                                                                                                                                                                                           |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | manifest hash - optional - an existing manifest address to update a resource included in the manifest. resource path - optional - which resource to update in the manifest. encrypt - optional flag to enable encryption                                                                                                                                    |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200                                                                                                                                                                                                                                                                                                                                                         |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | a hash of a newly created manifest                                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               | DELETE | Purpose       | delete a resource from a manifest by unlinking it from the existing manifest                                                                                                                                                                                                                                                                                |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz:/<domain>/<path>                                                                                                                                                                                                                                                                                                                                        |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | domain part - mandatory - a valid ENS hash or a valid Swarm manifest hash. path part - mandatory - a path to the resource to be removed from the manifest                                                                                                                                                                                                   |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | the hash of the new manifest which does not have component ``path``                                                                                                                                                                                                                                                                                         |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bzz-immutable | GET    | Purpose       | The same as the generic scheme but there is no ENS domain resolution. the domain part of the path needs to be a valid hash. This is also a read-only scheme but explicit in its integrity protection. A particular bzz-immutable url will always necessarily address the exact same fixed immutable content.                                                |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-immutable:/<hash>                                                                                                                                                                                                                                                                                                                                       |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | hash part - a valid Swarm hash that points to a manifest                                                                                                                                                                                                                                                                                                    |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | the resolved content at the specified address with a valid content-type as stored in the manifest                                                                                                                                                                                                                                                           |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       | use bzz-hash to resolve the ens name into a hash then use it with immutable                                                                                                                                                                                                                                                                                 |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bzz-raw       | GET    | Purpose       | When responding to GET requests with the bzz-raw scheme swarm does not assume a manifest but just serves the asset addressed by the url directly. The ``content_type`` query parameter can be supplied to specify the mime type you are requesting otherwise content is served as an octet stream per default.                                              |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-raw:/<content_hash>?content_type=<mime>                                                                                                                                                                                                                                                                                                                 |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | content hash - mandatory - a valid Swarm content hash. content type - optional - the mime type to serve the content as. defaults to application/octet-stream                                                                                                                                                                                                |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       | a pdf document (not the manifest wrapping it) resides at hash 6a182226... then the following url will properly serve it: GET http://localhost:8500/bzz-raw:/6a18222637cafb4ce692fa11df886a03e6d5e63432c53cbf7846970aa3e6fdf5?content_type=application/pdf                                                                                                   |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               | POST   | Purpose       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bzz-list      | GET    | Purpose       | Returns a list of all files contained in <manifest> under <path> grouped into common prefixes using ``/`` as a delimiter. If path is ``/`` - all files in manifest are returned. The response is a JSON-encoded object with ``common_prefixes`` string field and ``entries`` list field.                                                                    |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-list:/<domain>/<path>                                                                                                                                                                                                                                                                                                                                   |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | domain part - mandatory - a valid ENS entry that points to a valid manifest hash or a valid manifest hash. path part - optional - path to look for inside the manifest                                                                                                                                                                                      |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bzz-hash      | GET    | Purpose       | responds with the hash value of the raw content - the same content returned by requests with bzz-raw scheme. Hash of the manifest is also the hash stored in ENS so bzz-hash can be used for ENS domain resolution                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-hash:/<domain>                                                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | domain part - mandatory. a valid ENS name                                                                                                                                                                                                                                                                                                                   |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 404; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | text/plain                                                                                                                                                                                                                                                                                                                                                  |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| bzz-feed      | GET    | Purpose       | Retrieve a Feed update                                                                                                                                                                                                                                                                                                                                      |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-feed:/<hash>?user=<user>&topic=<topic>&name=<name>&time=<t>                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | hash - optional - manifest hash of the Feed, otherwise user param required. user - optional - Ethereum address of the user who publishes the Feed. topic - optional - Feed topic, encoded as a hex string, default: 0. name - optional - subtopic that is combined with the topic, default: "".                                                             |
|               |        |               | time - optional - The last update before that time (unix time) will be looked up, default: most recent update. meta - optional - Just return the Feed metadata, default 0 (false).                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 400; 404; 500                                                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | The content stored in the requested Feed update                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               | GET    | Purpose       | Get Feed metadata, used to help publishing updates                                                                                                                                                                                                                                                                                                          |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-feed:/<hash>?user=<user>&topic=<topic>&name=<name>&meta=1                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | hash - optional - manifest hash of the Feed, otherwise user param required. user - optional - Ethereum address of the account that owns the Feed. topic - optional - Feed topic, encoded as a hex string, default: 0. name - optional - subtopic that is combined with the topic, default: "".                                                              |
|               |        |               | meta - required - Return the Feed metadata instead of the Feed content.                                                                                                                                                                                                                                                                                     |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 400; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with | application/json                                                                                                                                                                                                                                                                                                                                            |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               | POST   | Purpose       | Post an update to a Feed                                                                                                                                                                                                                                                                                                                                    |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator       | bzz-feed:/<hash>?user=<user>&topic=<topic>&level=<level>&time=<time>&protocolVersion=<ver>&signature=<sig>                                                                                                                                                                                                                                                  |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Locator Parts | hash - optional - manifest hash of the Feed, otherwise user param required. user - optional - Ethereum address of the account that owns the Feed. topic - optional - Feed topic, encoded as a hex string, default: 0. level - optional - suggested frequency level (retreived above). time - optional - suggested timestamp (retrieved above).              |
|               |        |               | protocolVersion - optional - Feed protocol version, default: current version. signature - required - Feed signature hex encoded                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | HTTP Codes    | 200; 400; 500                                                                                                                                                                                                                                                                                                                                               |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Responds with |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|               |        | Example       |                                                                                                                                                                                                                                                                                                                                                             |
+---------------+--------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

JavaScript
========================
Swarm currently supports a Javascript API through a few packages:

erebos
^^^^^^^^^^^^^^^

`erebos <https://erebos.js.org>`_ is available through `NPM <https://www.npmjs.com/package/@erebos/swarm>`_ by issuing
the following command:

.. code-block:: none

  npm install @erebos/swarm-browser # browser only
  npm install @erebos/swarm-node # node only
  npm install @erebos/swarm # universal


.. note:: Full documentation is available on the `documentation website <https://erebos.js.org>`_.

swarm-js
^^^^^^^^^^^^^^^

`swarm-js <https://github.com/MaiaVictor/swarm-js>`_ is available through `NPM <https://www.npmjs.com/package/swarm-js>`_ by issuing
the following command:

.. code-block:: none
  
  npm install swarm-js


.. note:: Full documentation is available on the `GitHub <https://github.com/MaiaVictor/swarm-js>`_ page.

swarmgw
^^^^^^^^^^

`swarmgw <https://github.com/axic/swarmgw>`_ is available through `NPM <https://www.npmjs.com/package/swarmgw>`_ by issuing
the following command:

.. code-block:: none
  
  npm install swarmgw

When installed globally, it can also be used directly from the CLI:

.. code-block:: none

  npm install -g swarmgw

.. note:: Full documentation is available on the `GitHub <https://github.com/axic/swarmgw>`_ page.





RPC
========================

Swarm exposes an IPC API under the ``bzz`` namespace.


FUSE
^^^^^^

``swarmfs.mount(HASH|domain, mountpoint))``
  mounts Swarm contents represented by a Swarm hash or a ens domain name to the specified local directory. The local directory has to be writable and should be empty.
  Once this command is succesfull, you should see the contents in the local directory. The HASH is mounted in a rw mode, which means any change insie the directory will be automatically reflected in Swarm. Ex: if you copy a file from somewhere else in to mountpoint, it is equvivalent of using a ``swarm up <file>`` command.    

``swarmfs.unmount(mountpoint)``
  This command unmounts the HASH|domain mounted in the specified mountpoint. If the device is busy, unmounting fails. In that case make sure you exit the process that is using the directory and try unmounting again.

``swarmfs.listmounts()``
  For every active mount, this command display three things. The mountpoint, start HASH supplied and the latest HASH. Since the HASH is mounted in rw mode, when ever there is a change to the file system (adding file, removing file etc), a new HASH is computed. This hash is called the latest HASH.

PSS
^^^^^

``pss`` methods are by default exposed via IPC. If websockets are activated on the node, they will also be available there *if* the ``pss`` module is explicitly specified.

All parameters are hex-encoded bytes or strings unless otherwise noted.

``pss.getPublicKey()``
  Retrieves the public key of the node, in hex format

``pss.baseAddr()``
  Retrieves the Swarm overlay address of the node, in hex format

``pss.stringToTopic(name)``
  Creates a deterministic 4 byte topic value from an input name, returned in hex format

``pss.setPeerPublicKey(publickey, topic, address)``
  Register a peer's public key. This is done once for every topic that will be used with the peer. Address can be anything from 0 to 32 bytes inclusive of the peer's swarm address. The method has no return value.

``pss.sendAsym(publickey, topic, message)``
  Encrypts the message using the provided public key, and signs it using the node's private key. It then wraps it in an envelope containing the topic, and sends it to the network. The method has no return value.

``pss.setSymmetricKey(symkey, topic, address, bool decryption)``
  Register a symmetric key shared with a peer. This is done once for every topic that will be used with the peer. Address can be anything from 0 to 32 bytes inclusive of the peer's Swarm overlay address. If the fourth parameter is false, the key will not be added to the list of symmetric keys used for decryption attempts. The method returns an id used to reference the symmetric key in consecutive calls.

``pss.sendSym(symkeyid, topic, message)``
  Encrypts the message using the provided symmetric key, wraps it in an envelope containing the topic, and sends it to the network. The method has no return value.

``pss.GetSymmetricAddressHint(topic, symkeyid)``
  Return the Swarm address associated with the peer registered with the given symmetric key and topic combination. If a match is found it returns the address data in hex format.

``pss.GetAsymmetricAddressHint(topic, publickey)``
  Return the Swarm address associated with the peer registered with the given asymmetric key and topic combination. If a match is found it returns the address data in hex format.

.. note:: The following methods are used to control the optional pss handshake module. This is an advanced feature, and not required for sending and receiving messages using pss. 

``pss.addHandshake(topic)``
  Activate handshake functionality on the specified topic. The method has no return value.

``pss.removeHandshake(topic)``
  Remove handshake functionality on the specified topic. The method has no return value.

``pss.handshake(publickey, topic, bool block, bool flush)``
  Instantiate handshake with peer, refreshing symmetric encryption keys. If parameter 3 is false the handshake will happen asynchronously. If parameter 4 is true, it will force expiry of all existing keys. The method returns a list of symmetric key ids created by the handshake. If the handshake is asynchronous, however, returned array will be empty.

``pss.getHandshakeKeys(publickey, topic, bool incoming, bool outgoing)``
  Returns the set of valid symmetric encryption keys for a specified peer and topic. If the incoming and outgoing parameters are set, the keys valid for the respective communcations directions are included.

``pss.getHandshakeKeyCapacity(symkeyid)``
  Returns the number of messages (uint16) a symmetric handshake key is valid for.

``pss.getHandshakePublicKey(symkeyid)``
  Returns the public key associated with the specified symmetric handshake key.

``pss.releaseHandshakeKey(publickey, topic, symkeyid, bool instant)`` 
  Invalidate the specified symmetric handshake key. Normally, the key will be kept for a grace period to allow decryption of messages not yet received at the time of release. If the instant parameter is set, this grace period is omitted, and the key removed instantaneously. This method has no return value.


.. uncommentthisChequebook IPC API
.. uncommentthis------------------------------

.. uncommentthisSwarm also exposes an IPC API for the chequebook offering the followng methods:

.. uncommentthis``chequebook.balance()``
.. uncommentthis  Returns the balance of your swap chequebook contract in wei.
.. uncommentthis  It errors if no chequebook is set.

.. uncommentthis``chequebook.issue(beneficiary, value)``
.. uncommentthis  Issues a cheque to beneficiary (an ethereum address) in the amount of value (given in wei). The json structure returned can be copied and sent to beneficiary who in turn can cash it using ``chequebook.cash(cheque)``.
.. uncommentthis  It errors if no chequebook is set.

.. uncommentthis``chequebook.cash(cheque)``
.. uncommentthis  Cashes the cheque issued. Note that anyone can cash a cheque. Its success only depends on the cheque's validity and the solvency of the issuers chequbook contract up to the amount specified in the cheque. The tranasction is paid from your bzz base account.
.. uncommentthis  Returns the transaction hash.
.. uncommentthis  It errors if no chequebook is set or if your account has insufficient funds to send the transaction.

.. uncommentthis``chequebook.deposit(amount)``
.. uncommentthis  Transfers funds of amount  wei from your bzz base account to your swap chequebook contract.
.. uncommentthis  It errors if no chequebook is set  or if your account has insufficient funds.