You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Swarm supports sending encrypted messages over the network using a system called **Postal Service over Swarm** (PSS). These messages are embedded in regular Swarm traffic and routed to specific nodes based on their overlay address.
10
9
11
-
This section is still being worked on. Check back soon for updates!
10
+
## What Is PSS?
12
11
13
-
:::
12
+
PSS provides a pub/sub-like functionality for secure messaging. Full nodes can listen for messages on a specific **topic**, and other nodes (light or full) can send them payloads using the recipient node's **overlay address** and optionally encrypted using the recipient's **PSS public key**.
14
13
14
+
Messages can be received via **subscription** or by a **one-off listener**.
15
15
16
-
* Remove the unrelated intro section
17
-
* Show a listener
18
-
* Show a one time receive
19
-
* Show a send invocation
20
-
* Move it towards the end of the chapters, it is not very important
16
+
:::caution
17
+
Only full nodes can receive messages since PSS messages are sent as a part of the chunk syncing process which only full nodes take part in.
18
+
:::
21
19
20
+
## Requirements
22
21
23
-
import Tabs from '@theme/Tabs'
24
-
import TabItem from '@theme/TabItem'
22
+
To use the example scripts below, you need:
25
23
26
-
Swarm provides the ability to send messages that appear to be normal Swarm traffic, but are in fact messages that may be received and decrypted to reveal their content only to specific nodes that were intended to receive them.
24
+
- A Bee full node with a fully synced reserve for receiving PSS messages.
25
+
- A light node for sending PSS messages.
26
+
- The batch ID of a usable postage batch. If you don't have one already, you will need to [buy a batch](/docs/storage/#purchasing-storage) to upload data. If you do have one, you will need to [get and save](/docs/storage/#selecting-a-batch) its batch ID.
27
27
28
-
PSS provides a pub-sub facility that can be used for a variety of tasks. Nodes are able to listen to messages received for a specific topic in their nearest neighbourhood and create messages destined for another neighbourhood which are sent over the network using Swarm's usual data dissemination protocols.
29
28
30
-
The intended use of PSS is to communicate privately with a publicly known identity (to for example initiate further communication directly). Due to the cost of mining the trojan chunks, it is not recommended to use as an instant messaging system.
29
+
## Get Recipient Info (Full Node Only)
31
30
32
-
:::caution Light nodes are unreachable
33
-
Be aware! You can not send message to Light nodes! This is because light nodes does not fully participate
34
-
in the data exchange in Swarm network and hence the message won't arrive to them.
35
-
:::
31
+
This step **must be performed by the receiving full node**. It retrieves the node’s **overlay address** and **PSS public key**, which must then be shared with the sending node:
36
32
37
-
## Getting the relevant data
38
-
When you start `bee`, you may find all the necessary information in the log:
39
-
```sh
40
-
INFO using existing swarm network address: 9e2ebf266369090091620db013aab164afb1574aedb3fcc08ce8dc6e6f28ef54
41
-
INFO swarm public key 03e0cee7e979fa99350fc2e2f8c81d857b525b710380f238742af269bb794dfd3c
42
-
INFO pss public key 02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa
43
-
INFO using ethereum address 5f5505033e3b985b88e20616d95201596b463c9a
44
-
```
45
-
Let's break it down:
46
-
-**Ethereum address** is the public address of your node wallet. Together with the corresponding private key, it is used for things such as making Ethereum transactions (receiving and sending ETH and BZZ); receiving, claiming and singing cheques and the Swarm network address is also derived from it.
47
-
- The **Swarm network address** defines your location in the kademlia and within the context of PSS is used for addressing the trojan chunks to you. In other words, others may use it to send you a message.
48
-
-**PSS public key** can be used by others to encrypt their messages for you.
33
+
- The **overlay address** is **required** as the routing target.
34
+
- The **PSS public key** is **optional** and only needed for encryption.
49
35
50
-
<!---
51
-
### Deriving swarm address from ethereum address
52
-
This section will need a lot of love and testing, probably should be in some advanced page but leaving it here as comment since we want to write it at some point.
53
-
-->
36
+
```js
37
+
import { Bee } from'@ethersphere/bee-js'
54
38
55
-
## Sending message
39
+
constbee=newBee('http://localhost:1633')
56
40
57
-
To send data simply define a topic, prefix of the recipient's swarm network address (we recommend 4-6 character prefix length) and the data to be send.
58
-
:::caution Your communication privacy may be at risk
59
-
When sending PSS messages without encryption key, any Bee node through which the trojan chunk passes would be able to read the message.
60
-
:::
41
+
asyncfunctioncheckAddresses() {
42
+
constaddresses=awaitbee.getNodeAddresses()
61
43
62
-
<Tabs
63
-
groupId="lang_preferrence"
64
-
defaultValue="ts"
65
-
values={[
66
-
{label: 'TypeScript', value: 'ts'},
67
-
{label: 'JavaScript', value: 'js'},
68
-
]}>
69
-
<TabItemvalue="ts">
70
-
71
-
```ts
72
-
/**
73
-
* @param{string}topic
74
-
* @param{string}targetPrefix
75
-
* @param{string|Uint8Array}data
76
-
* @param{string}encryptionKey
77
-
*/
78
-
bee.pssSend('topic', '9e2e', 'Hello!')
79
-
```
80
-
81
-
</TabItem>
82
-
<TabItemvalue="js">
44
+
console.log('Node Addresses:', addresses)
45
+
}
83
46
84
-
```js
85
-
/**
86
-
* @param{string}topic
87
-
* @param{string}targetPrefix
88
-
* @param{string|Uint8Array}data
89
-
* @param{string}encryptionKey
90
-
*/
91
-
bee.pssSend('topic', '9e2e', 'Hello!')
47
+
checkAddresses()
92
48
```
93
49
94
-
</TabItem>
95
-
</Tabs>
96
-
97
-
If you want to encrypt the message, you may provide the recipient's PSS public key.
The `Overlay` and `PSS Public Key` values should be shared with the sending node.
116
65
117
-
</TabItem>
118
-
<TabItemvalue="js">
66
+
The sender (which can be a light node or a full node) needs the **overlay address** to generate the message target, and can optionally use the **PSS public key** to encrypt the message.
You can listen on a topic using both **continuous subscription** and **one-time receive**:
131
71
132
-
## Retrieving message
133
-
As a recipient, you have two ways how to receive the message. If you are expecting one off message (which is the intended PSS use case to exchange credentials for further direct communication), you can use the `pssReceive` method.
134
72
135
-
<Tabs
136
-
groupId="lang_preferrence"
137
-
defaultValue="ts"
138
-
values={[
139
-
{label: 'TypeScript', value: 'ts'},
140
-
{label: 'JavaScript', value: 'js'},
141
-
]}>
142
-
<TabItemvalue="ts">
73
+
-`bee.pssSubscribe` is used to set up a continuous subscription.
74
+
-`bee.pssReceive` is used to set up a listener on a timeout which closes after receiving a message.
143
75
144
-
```ts
145
-
const message =awaitbee.pssReceive('topic')
76
+
```js
77
+
import { Bee, Topic } from'@ethersphere/bee-js'
78
+
79
+
constbee=newBee('http://localhost:1633')
80
+
81
+
// Generate a topic from a unique string
82
+
consttopic=Topic.fromString('pss-demo')
83
+
84
+
console.log('Subscribing to topic:', topic.toHex())
85
+
86
+
// Continuous subscription
87
+
bee.pssSubscribe(topic, {
88
+
onMessage:msg=>console.log('Received via subscription:', msg.toUtf8()),
console.error('pssReceive error or timeout:', err.message)
100
+
}
101
+
}
146
102
147
-
console.log(message.text()) // prints the received message
103
+
receiveOnce()
148
104
```
149
105
150
-
</TabItem>
151
-
<TabItemvalue="js">
106
+
In this script we generate a `topic` from our chosen string with the `Topic.fromString` method. Then we subscribe to listen for incoming pss messages for that topic with the `bee.pssSubscribe` method, and we also set up a listener for receiving a single message with the `bee.pssReceive` method. When a chunk with a PSS message for that topic is synced into our node's neighborhood, it will be received and handled by our node with the `onMessage` callback function when using the `bee.pssSubscribe` or through the return value of the `bee.pssReceive` method in our `receiveOnce` function.
107
+
108
+
## Send Message (Light or Full Node)
109
+
110
+
The sender must provide:
111
+
112
+
- A valid **postage batch ID**
113
+
- The recipient’s **overlay address** (used to generate the routing target)
114
+
- Optionally the **PSS public key** for encryption
The message will then be encrypted using the PSS public key of the recipient node before sending and will only be decryptable by the recipient node (although the message bearing the PSS chunk will be received by all nodes in the same neighborhood as the recipient, it will only be decryptable by the recipient node).
0 commit comments