Skip to content

Commit a509a6f

Browse files
NoahMaizelsNoahMaizels
committed
added gsoc page
1 parent ef8434a commit a509a6f

File tree

1 file changed

+143
-1
lines changed

1 file changed

+143
-1
lines changed

‎docs/documentation/gsoc.md‎

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,146 @@ This section is still being worked on. Check back soon for updates!
1515

1616
* Show mining the writer private key for the targeted overlay address [Gist](https://gist.github.com/Cafe137/e76ef081263aaec7a715139d700f3433)
1717
* Show a simple listener, and a simple send invocation [Gist1](https://gist.github.com/Cafe137/7f02fb54ad5a79833f3b718b94df0d41) [Gist2](https://gist.github.com/Cafe137/6277f1d112b3b78ba36f717551357c3b)
18-
* Show Identifier class usage [Gist](https://gist.github.com/Cafe137/25a244d85758480aa1e15c80ff147b72)
18+
* Show Identifier class usage [Gist](https://gist.github.com/Cafe137/25a244d85758480aa1e15c80ff147b72)
19+
20+
21+
The GSOC (Graffiti Several Owner Chunk) feature allows a **full node** to receive messages from many other nodes using a shared Single Owner Chunk (SOC). This enables real-time communication and notification over Swarm.
22+
23+
## Overview
24+
25+
GSOC messages are updates to a pre-mined SOC that lands in the **neighborhood** of the recipient node. Only full nodes receive these updates because light nodes do not sync neighborhood chunks. However, **any node** (light or full) can send GSOC messages.
26+
27+
### GSOC vs PSS
28+
29+
GSOC shares some similarities with PSS - both features allow for full nodes to receive messages from other nodes.
30+
31+
However, there are several key differences:
32+
33+
- Unlike PSS, **GSOC only needs to mine the target chunk once**—multiple messages reuse it, making it **faster, cheaper**, and **more efficient** for recurring updates.
34+
- Unlike PSS, **No encryption** is used by default, making it unsuitable for handling sensitive data.
35+
36+
37+
## Requirements
38+
39+
To use the example scripts below, you need:
40+
41+
- A Bee full node with a fully synced reserve for receiving GSOC messages.
42+
- A light node for sending GSOC messages.
43+
- 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.
44+
45+
## 1. Create an Identifier (Receiver and Sender)
46+
47+
Identifiers in GSOC are similar to topics in PSS — they define the stream of messages a receiver node is subscribed to. The sender must use the same identifier so that their messages are received.
48+
49+
Each identifier is a 64-digit hex string (32 bytes). It can be initialized with an a hex string of your choice or any arbitrary string using the `Identifier` utility class. You can also use the zero-initialized `NULL_IDENTIFIER` as a default identifier for cases where you don't need a unique identifier:
50+
51+
52+
```js
53+
import { Identifier, NULL_IDENTIFIER } from '@ethersphere/bee-js'
54+
55+
// Use default (all zeros):
56+
const identifier = NULL_IDENTIFIER
57+
58+
// From a hex string:
59+
const identifier = new Identifier('6527217e549e84f98e51b1d8b1ead62ff5cad59acd9713825754555d6975f103')
60+
61+
// From a human-readable string:
62+
const identifier = Identifier.fromString('chat:v1')
63+
```
64+
65+
- Use `NULL_IDENTIFIER` is a 64 digit hex string of all zeros - use it for quick testing or when uniqueness doesn't matter.
66+
- Use any hex string to initialize a new `Identifier` object .
67+
- Use `Identifier.fromString()` to generate an identifier derived from your string of choice (allows for easy to remember human readable identifiers `"notifications"`, `"chat:user1"`).
68+
69+
## 2. Get Target Overlay (Receiver Node)
70+
71+
This step **is performed by the receiving full node** to retrieve its overlay address. This overlay address is then shared with the sender node to use as a target overlay for its GSOC messages:
72+
73+
```js
74+
import { Bee } from '@ethersphere/bee-js'
75+
76+
const bee = new Bee('http://localhost:1633')
77+
78+
async function checkAddresses() {
79+
const addresses = await bee.getNodeAddresses()
80+
console.log('Node Addresses:', addresses)
81+
}
82+
83+
checkAddresses()
84+
```
85+
86+
Example output:
87+
88+
```bash
89+
Node Addresses:
90+
Overlay: 1e2054bec3e681aeb0b365a1f9a574a03782176bd3ec0bcf810ebcaf551e4070
91+
Ethereum: 9a73f283cd9211b96b5ec63f7a81a0ddc847cd93
92+
Public Key: 7d0c4759f689ea3dd3eb79222870671c492cb99f3fade275bcbf0ea39cd0ef6e25edd43c99985983e49aa528f3f2b6711085354a31acb4e7b03559b02ec868f0
93+
PSS Public Key: 5ade58d20be7e04ee8f875eabeebf9c53375a8fc73917683155c7c0b572f47ef790daa3328f48482663954d12f6e4739f748572c1e86bfa89af99f17e7dd4d33
94+
Underlay: [
95+
'/ip4/127.0.0.1/tcp/1634/p2p/QmcpSJPHuuQYRgDkNfwziihVcpuVteoNxePvfzaJyp9z7j',
96+
'/ip4/172.17.0.2/tcp/1634/p2p/QmcpSJPHuuQYRgDkNfwziihVcpuVteoNxePvfzaJyp9z7j',
97+
'/ip6/::1/tcp/1634/p2p/QmcpSJPHuuQYRgDkNfwziihVcpuVteoNxePvfzaJyp9z7j'
98+
]
99+
```
100+
101+
The `Overlay` should be saved and shared with sender nodes.
102+
103+
## 3. Set Up a Listener (Receiver Node)
104+
105+
This must be run on a full node. It mines a key that lands within its own neighborhood and starts listening.
106+
107+
```js
108+
import { Bee, Identifier, NULL_IDENTIFIER } from '@ethersphere/bee-js'
109+
110+
const bee = new Bee('http://localhost:1633')
111+
const identifier = Identifier.fromString(NULL_IDENTIFIER)
112+
113+
async function listen() {
114+
const { overlay } = await bee.getNodeAddresses()
115+
116+
// The signer is initialized using the receiving node's own overlay and chosen identifier
117+
const signer = bee.gsocMine(overlay, identifier)
118+
119+
// A GSOC subscription is established using the blockchain address derived from the signer and the identifier
120+
bee.gsocSubscribe(signer.publicKey().address(), identifier, {
121+
// A callback function is used to handle incoming updates - you can include your application logic here
122+
onMessage: message => console.log('Received:', message.toUtf8()),
123+
onError: error => console.error('Subscription error:', error),
124+
})
125+
126+
console.log('Listening for GSOC updates...')
127+
}
128+
129+
listen()
130+
```
131+
132+
## 4. Send a Message (Sender Node)
133+
134+
The sending node must have a ***usable postage batch id*** and also know the ***target overlay address*** and ***identifier*** in order to send a message:
135+
136+
```js
137+
import { Bee, Identifier, NULL_IDENTIFIER } from '@ethersphere/bee-js'
138+
139+
const bee = new Bee('http://localhost:1643')
140+
141+
// The identifier is initialized using the same data as the receiving node
142+
const identifier = Identifier.fromString(NULL_IDENTIFIER)
143+
const batchId = '6c84b6d3f5273b969c3df875cde7ccd9920f5580122929aedaf440bfe4484405'
144+
145+
const recipientOverlay = '1e2054bec3e681aeb0b365a1f9a574a03782176bd3ec0bcf810ebcaf551e4070'
146+
147+
async function sendMessage() {
148+
// The signer is initialized using the overlay address and identifier shared by the receiving node
149+
const signer = bee.gsocMine(recipientOverlay, identifier)
150+
151+
// bee.gsocSend is called with the batch id, initialized signer, identifier, and message payload in order to send a GSOC message
152+
await bee.gsocSend(batchId, signer, identifier, 'Hello via GSOC!')
153+
console.log('Message sent')
154+
}
155+
156+
sendMessage()
157+
```
158+
159+
For more information about GSOC, refer to the [Bee documentation](https://docs.ethswarm.org/docs/develop/tools-and-features/gsoc).
160+

0 commit comments

Comments
 (0)