Skip to content

Commit 5004db5

Browse files
vojtechsimetkasignificance
vojtechsimetka
and
significance
authored
feat: documentation for PSS (#23)
* feat: documentation for PSS * chore: grammar suggestion by @significance Co-authored-by: significance <[email protected]> * chore: apply language suggestions from code review but @agazso * chore: added warning about privacy for unencrypted PSS communication Co-authored-by: significance <[email protected]>
1 parent 385cded commit 5004db5

File tree

2 files changed

+177
-2
lines changed

2 files changed

+177
-2
lines changed

‎docs/user-documentation/pss.md

Lines changed: 175 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,184 @@
11
---
22
title: Postal Service over Swarm
3-
hide_title: true
43
id: pss
54
slug: /pss
65
sidebar_label: Postal Service over Swarm
76
---
87

98
import Tabs from '@theme/Tabs'
109
import TabItem from '@theme/TabItem'
10+
11+
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.
12+
13+
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.
14+
15+
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.
16+
17+
## Getting the relevant data
18+
When you start `bee`, you may find all the necessary information in the log:
19+
```sh
20+
INFO using existing swarm network address: 9e2ebf266369090091620db013aab164afb1574aedb3fcc08ce8dc6e6f28ef54
21+
INFO swarm public key 03e0cee7e979fa99350fc2e2f8c81d857b525b710380f238742af269bb794dfd3c
22+
INFO pss public key 02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa
23+
INFO using ethereum address 5f5505033e3b985b88e20616d95201596b463c9a
24+
```
25+
Let's break it down:
26+
- **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.
27+
- 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.
28+
- **PSS public key** can be used by others to encrypt their messages for you.
29+
30+
<!---
31+
### Deriving swarm address from ethereum address
32+
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.
33+
-->
34+
35+
## Sending message
36+
37+
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.
38+
:::caution Your communication privacy may be at risk
39+
When sending PSS messages without encryption key, any Bee node through which the trojan chunk passes would be able to read the message.
40+
:::
41+
42+
<Tabs
43+
groupId="lang_preferrence"
44+
defaultValue="ts"
45+
values={[
46+
{label: 'TypeScript', value: 'ts'},
47+
{label: 'JavaScript', value: 'js'},
48+
]}>
49+
<TabItem value="ts">
50+
51+
```ts
52+
/**
53+
* @param {string} topic
54+
* @param {string} targetPrefix
55+
* @param {string|Uint8Array} data
56+
* @param {string} encryptionKey
57+
*/
58+
bee.pssSend('topic', '9e2e', 'Hello!')
59+
```
60+
61+
</TabItem>
62+
<TabItem value="js">
63+
64+
```js
65+
/**
66+
* @param {string} topic
67+
* @param {string} targetPrefix
68+
* @param {string|Uint8Array} data
69+
* @param {string} encryptionKey
70+
*/
71+
bee.pssSend('topic', '9e2e', 'Hello!')
72+
```
73+
74+
</TabItem>
75+
</Tabs>
76+
77+
If you want to encrypt the message, you may provide the recipient's PSS public key.
78+
79+
<Tabs
80+
groupId="lang_preferrence"
81+
defaultValue="ts"
82+
values={[
83+
{label: 'TypeScript', value: 'ts'},
84+
{label: 'JavaScript', value: 'js'},
85+
]}>
86+
<TabItem value="ts">
87+
88+
```ts
89+
bee.pssSend(
90+
'topic',
91+
'9e2e',
92+
'Encrypted Hello!',
93+
'02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa',
94+
)
95+
```
96+
97+
</TabItem>
98+
<TabItem value="js">
99+
100+
```js
101+
bee.pssSend(
102+
'topic',
103+
'9e2e',
104+
'Encrypted Hello!',
105+
'02fa24cac43531176d21678900b37bd800c93da3b02c5e11572fb6a96ec49527fa',
106+
)
107+
```
108+
109+
</TabItem>
110+
</Tabs>
111+
112+
## Retrieving message
113+
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.
114+
115+
<Tabs
116+
groupId="lang_preferrence"
117+
defaultValue="ts"
118+
values={[
119+
{label: 'TypeScript', value: 'ts'},
120+
{label: 'JavaScript', value: 'js'},
121+
]}>
122+
<TabItem value="ts">
123+
124+
```ts
125+
const message = await bee.pssReceive('topic')
126+
127+
console.log(new TextDecoder("utf-8").decode(message)) // prints the received message
128+
```
129+
130+
</TabItem>
131+
<TabItem value="js">
132+
133+
```js
134+
const message = await bee.pssReceive('topic')
135+
136+
console.log(new TextDecoder("utf-8").decode(message)) // prints the received message
137+
```
138+
139+
</TabItem>
140+
</Tabs>
141+
142+
If you want to subscribe to multiple messagees, use the `pssSubscribe` method.
143+
144+
145+
<Tabs
146+
groupId="lang_preferrence"
147+
defaultValue="ts"
148+
values={[
149+
{label: 'TypeScript', value: 'ts'},
150+
{label: 'JavaScript', value: 'js'},
151+
]}>
152+
<TabItem value="ts">
153+
154+
```ts
155+
const handler = {
156+
onMessage: (message: Uint8Array) => {console.log(new TextDecoder("utf-8").decode(message))},
157+
onError: (error: BeeError) => {console.log(error)}
158+
}
159+
160+
// Subscribe
161+
const subscription = bee.pssSubscribe('topic', handler)
162+
163+
// Terminate the subscription
164+
subscription.cancel()
165+
```
166+
167+
</TabItem>
168+
<TabItem value="js">
169+
170+
```js
171+
const handler = {
172+
onMessage: (message: Uint8Array) => {console.log(new TextDecoder("utf-8").decode(message))},
173+
onError: (error: BeeError) => {console.log(error)}
174+
}
175+
176+
// Subscribe
177+
const subscription = bee.pssSubscribe('topic', handler)
178+
179+
// Terminate the subscription
180+
subscription.cancel()
181+
```
182+
183+
</TabItem>
184+
</Tabs>

‎sidebars.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ module.exports = {
88
'user-documentation/getting-started',
99
'user-documentation/upload-download',
1010
'user-documentation/track-upload',
11-
// 'user-documentation/pss',
11+
'user-documentation/pss',
12+
// 'user-documentation/feeds',
1213
],
1314
collapsed: false
1415
},

0 commit comments

Comments
 (0)