Skip to content

Commit a6933d4

Browse files
NoahMaizelsNoahMaizels
committed
proofread act page
1 parent 3c88bca commit a6933d4

File tree

1 file changed

+109
-61
lines changed

1 file changed

+109
-61
lines changed

‎docs/documentation/act.md‎

Lines changed: 109 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -12,35 +12,44 @@ When you upload data to Swarm using ACT, only the original uploader and users wi
1212
ACT is ideal for use cases such as the serialized release of content like a podcast or newsletter where the publisher wishes to limit access to subscribers only.
1313

1414
:::warning
15-
Once a file is uploaded with ACT, any node that is is on the ACT grantees list referenced during the upload ***will have permanent access to that file*** as long as they have the file reference and history reference returned from the upload.
15+
Once a file is uploaded with ACT, any node whose public key is on the ACT grantees list referenced during the upload ***will have permanent access to that file*** as long as the file reference and history reference returned from the upload has been shared with them.
1616

1717
Updating the grantees list to remove a public key ***will not revoke access*** to the content retroactively.
1818

19-
Likewise, re-uploading the content the content using the new grantees list will also ***not retroactively revoke access*** to the content.
19+
Likewise, re-uploading the content using the new grantees list will also ***not retroactively revoke access*** to the content.
2020
:::
2121

2222
## Create Grantees List
2323

24-
First we create a grantees list with the public keys of anyone we want to grant access to:
24+
First we create a grantees list with the public keys of anyone we want to grant access to.
25+
26+
### Example Script
27+
28+
The example script below performs the following key operations:
29+
30+
1. Initializes a Bee client.
31+
2. Defines a list of grantee public keys.
32+
3. Specifies a valid postage batch ID.
33+
4. Calls `bee.createGrantees()` to create a new grantee list.
34+
5. Logs the resulting `ref` and `historyref`.
2535

2636
```js
2737
import { Bee, PublicKey, BatchId } from '@ethersphere/bee-js';
2838

2939
// Initialize Bee instance
30-
const bee = new Bee('http://localhost:1643');
40+
const bee = new Bee('http://localhost:1633');
3141

32-
// Grantee's public key (replace with the actual key)
42+
// Grantee's public key (replace with the actual key(s) of the node(s) you wish to grant access to)
3343
const grantees = [
3444
new PublicKey('027d0c4759f689ea3dd3eb79222870671c492cb99f3fade275bcbf0ea39cd0ef6e'),
3545
];
3646

37-
// Your postage batch ID (replace with a valid one)
38-
const postageBatchId = new BatchId('b680c04c49d246538284cadd143cf6e623cd6581347e1bb7d9b62e36334757db');
47+
// Your postage batch ID (replace with your own valid postage batch ID)
48+
const postageBatchId = new BatchId('0258a225fe8da54cc6537eb8b12fcf6706c7873dbe19b9381d31729aa0405398');
3949

40-
// Function to create grantees list
4150
async function createGranteeList() {
4251
try {
43-
// Create the grantee list using `createGrantees`
52+
// Create the grantee list using `bee.createGrantees()` method
4453
const response = await bee.createGrantees(postageBatchId, grantees);
4554

4655
// Log the response (ref and history ref)
@@ -60,49 +69,60 @@ Example output:
6069

6170
```bash
6271
Grantee List Created Successfully:
63-
Reference: a1206faf621e645027bf853ed06e85d3fd7499eb37859f5fba9cdc50d0d822cfef4c524879b8dedcc521f7db2bb09d81d765d01a7e4427093149cbfac9b0f54c
64-
History Reference: 8e74e7dc0c94786b576b55d32c238ebcb4da633ee36ae9beae11aaa98defbb3d
72+
Reference: 69da034fdae049eed9a22ec48b98a08ed5d363d48076f88c44ffe3367a18e306cae6aaf1cfce72d59262b9fb9293e15469c01c6a2626bb62478116cc98fb303b
73+
History Reference: 18d6f58a1d3c8253a5fc47023d49e9011236ead43724e595e898e1b422b77b19
6574
```
6675

67-
The first reference `Reference` is used on its own for reviewing the list contents and updating the list. It is encrypted so only the list creator can view the list contents.
76+
The first 64 byte (128 hex digit) reference `Grantee List Reference` (`ref`) is used on its own for reviewing the list contents and updating the list.
6877

69-
The seconde reference `History Reference` is used along with the first `Reference` for creating a new grantee list based on the list referred to by the `Reference`.
78+
The second reference 32 byte (64 hex digit) `History Reference` (`historyref`) is used for uploading with ACT and is also used along with the first `ref` for creating a new updated grantee list based on the original list referred to by the `ref`.
7079

71-
## Update Grantees
72-
73-
In order to update grantees we pass an object in this format to the `bee.patchGrantees` method containing the public keys we wish to add or remove from the list along with the `History Reference` and the grantee list `Reference` and a valid postage stamp:
80+
## Update Grantees List
7481

7582
:::info
76-
Although we refer to the process as "updating", since data on Swarm is immutable, the original grantees list is never modified. Rather, a new version of the list is created based on the original one with the specified public keys removed or added.
83+
Although we refer to this operation as an "update", due to Swarm's immutable nature, the original list is not modified by this operation. Rather a new list is created with the specified grantee keys added or removed from the original list. This operation ***DOES NOT*** retroactively add or remove access to content uploaded with the original ACT list.
7784
:::
7885

86+
To update a grantees list, call the `bee.patchGrantees()` method with the following arguments:
87+
88+
* A valid postage batch ID
89+
* The original list’s `ref` and `historyref`
90+
* An object specifying public keys to `add` or `revoke`
91+
7992
```js
80-
bee.patchGrantees(postageBatchId, granteeListRef, granteeHistoryRef, {
81-
add: [grantee1, grantee2], // Add the new grantee
82-
revoke: [],
83-
});
93+
bee.patchGrantees(postageBatchId, ref, historyref, {
94+
add: [grantee1, grantee2],
95+
revoke: [],
96+
});
8497
```
8598

86-
Calling this method will create an entirely new grantees list based on our first list and will return the `Reference` and `History Reference` for the new list.
99+
Calling this method returns the new list’s updated `ref` and `historyref`, which you should use for future updates or access.
87100

88-
Full example script:
101+
### Example Script
102+
103+
The example script below performs the following key steps:
104+
105+
1. Initializes the Bee client and defines two public keys to add as grantees.
106+
2. Provides the existing grantee list’s `ref` and `historyref`, and a valid postage batch ID.
107+
3. Calls `bee.patchGrantees()` to add the new keys to the list.
108+
4. Logs the updated grantee list’s `ref` and `historyref`.
89109

90110
```js
91111
import { Bee, PublicKey, BatchId, Reference } from '@ethersphere/bee-js';
92112

93113
// Initialize Bee instance
94-
const bee = new Bee('http://localhost:1643'); // Correct port is 1643
114+
const bee = new Bee('http://localhost:1633');
95115

96-
// Grantee's public key to be added (replace with the actual key)
116+
// Grantee's public key(s) to be added (replace with the actual key)
97117
const grantee1 = new PublicKey('027d0c4759f689ea3dd3eb79222870671c492cb99f3fade275bcbf0ea39cd0ef6e');
98118
const grantee2 = new PublicKey('03636056d1e08f100c5acaf14d10070102de9444c97b2e8215305ab3e97254ede6');
99119

100-
// Grantee list reference and history reference (replace with actual references from `createGrantees`)
101-
const granteeListRef = new Reference('98bc4076efe5736aa682649c1928cbc9e0ac11d395f7ed0e67126ff660f5410a238e14f8b1d74f7df6121b8450d79ca789a257eeb84c5ca7dda3ed08a6859934')
102-
const granteeHistoryRef = new Reference('06ee838e1f9b26c6d44077a2e63ad5ba9ecc143f278f9301f477eb99391f5796')
120+
// Grantee list reference and history reference returned from initial list creation
121+
const granteeListRef = new Reference('69da034fdae049eed9a22ec48b98a08ed5d363d48076f88c44ffe3367a18e306cae6aaf1cfce72d59262b9fb9293e15469c01c6a2626bb62478116cc98fb303b')
122+
const granteeHistoryRef = new Reference('18d6f58a1d3c8253a5fc47023d49e9011236ead43724e595e898e1b422b77b19')
103123

104124
// Your postage batch ID (replace with a valid one)
105-
const postageBatchId = new BatchId('b680c04c49d246538284cadd143cf6e623cd6581347e1bb7d9b62e36334757db');
125+
const postageBatchId = new BatchId('0258a225fe8da54cc6537eb8b12fcf6706c7873dbe19b9381d31729aa0405398');
106126

107127
// Function to update the grantee list by adding the new public key
108128
async function updateGranteeList() {
@@ -120,7 +140,7 @@ async function updateGranteeList() {
120140
} catch (error) {
121141
console.error('Error updating grantee list:', error.message);
122142
if (error.response) {
123-
// If there's a response object, log the full response for more details
143+
// If there's an error, log the full response for more details
124144
console.error('Response Status:', error.response.status);
125145
console.error('Response Body:', JSON.stringify(error.response.body, null, 2));
126146
}
@@ -135,29 +155,38 @@ Example output:
135155

136156
```bash
137157
Grantee List Updated Successfully:
138-
Updated Reference: 50b611b5253a8e1c63dc2d285fd1ee6501eaae626146ac032d3eff537ad1d1c46b032a6ea526e5cf88d6801c854bc9cde4418e87972c010f85a6f70e0beb1d0d
139-
Updated History Reference: 7fd72a4d7a175c6d709c799b990adc8b200ec3e0f413c2ae48026a316bb4810c
158+
Updated Reference: a029324c42e7911032b83155f487d545b6e07b521a90fce90a266f308c0a455417e71bc03621868da2f6e84357ba772cb03b408fce79862b03d2e082004eccd8
159+
Updated History Reference: d904f0790acb7edfda6a078176d64ec026b40298bfdbceb82956533e31489fcd
140160
```
141161

142162
## Get Grantees List
143163

144-
In order to view the members of our grantees list we need to use the `Reference` returned when we create or update a list. We will view both our original list and the updated list based on the original list using the respective `Reference` from each list:
164+
In order to view the members of our grantees list we need to use the 64 byte `ref` returned when we create or update a list. We will view both our original list and the updated list based on the original list using the respective `ref` from each list:
145165

146166
:::info
147-
The grantee list is encrypted, and only the owner can view the grantee list, make sure to use the owner node when using the `getGrantees` method.
167+
The grantee list is encrypted, and only the owner can view the grantee list, make sure to use the owner node when using the `bee.getGrantees()` method.
148168
:::
149169

170+
### Example Script
171+
172+
The example script below performs the following operations:
173+
174+
1. Initializes a Bee client.
175+
2. Defines two existing grantee list 64 byte `ref` copied from the results of our previous example scripts.
176+
3. Calls `bee.getGrantees()` for each `ref` to retrieve the corresponding grantee list.
177+
4. Logs the status, status text, and list of grantee public keys in compressed hex format.
178+
150179

151180
```js
152181
import { Bee, Reference } from '@ethersphere/bee-js';
153182

154-
// Initialize Bee instance with the correct port (1643)
155-
const bee = new Bee('http://localhost:1643');
183+
// Initialize Bee instance
184+
const bee = new Bee('http://localhost:1633');
156185

157186

158-
// Grantee list references (the reference returned from the `createGrantees` function)
159-
const granteeListRef_01 = new Reference('98bc4076efe5736aa682649c1928cbc9e0ac11d395f7ed0e67126ff660f5410a238e14f8b1d74f7df6121b8450d79ca789a257eeb84c5ca7dda3ed08a6859934');
160-
const granteeListRef_02 = new Reference('59c7d5223aa6fe0e66c72752690954c01747352d95b3c26281ac06b45a767d9759b5872a825aaa0eae5b4570816cacadd24065ecc195e77044977260efa70417');
187+
// Grantee list references (the reference returned from the `bee.createGrantees()` function)
188+
const granteeListRef_01 = new Reference('69da034fdae049eed9a22ec48b98a08ed5d363d48076f88c44ffe3367a18e306cae6aaf1cfce72d59262b9fb9293e15469c01c6a2626bb62478116cc98fb303b');
189+
const granteeListRef_02 = new Reference('a029324c42e7911032b83155f487d545b6e07b521a90fce90a266f308c0a455417e71bc03621868da2f6e84357ba772cb03b408fce79862b03d2e082004eccd8');
161190

162191
// Function to get the grantee list
163192
async function getGranteeList(granteeListRef) {
@@ -170,7 +199,7 @@ async function getGranteeList(granteeListRef) {
170199
console.log('Status:', result.status);
171200
console.log('Status Text:', result.statusText);
172201

173-
// Log the as an array of their string representations (compressed hex values)
202+
// Log the grantee lists as arrays of their hex string representations
174203
console.log('Grantees:', result.grantees.map(grantee => grantee.toCompressedHex()));
175204

176205
} catch (error) {
@@ -207,23 +236,33 @@ The first list of grantees contains the first public key we gave access to when
207236

208237
We can upload our content with either of the two lists we created depending on which set of users we wish to give access too. In the example below, we use both lists.
209238

239+
### Example Script
240+
241+
The example script below performs the following operations:
242+
243+
1. Initializes a Bee client.
244+
2. Defines a postage batch ID and two ACT grantee list 32 byte `historyref` hashes returned from the operations in the previous examples.
245+
3. Defines a string to upload as a sample file.
246+
4. Calls `bee.uploadFile()` twice with ACT enabled, specifying a `historyRef` each time to enforce access control.
247+
5. Logs the resulting Swarm reference and history reference after each upload.
248+
210249
```js
211250
import { Bee, BatchId, Reference } from '@ethersphere/bee-js';
212251

213-
// Initialize Bee instance with the correct port (1643)
214-
const bee = new Bee('http://localhost:1643');
252+
// Initialize Bee instance
253+
const bee = new Bee('http://localhost:1633');
215254

216255
// Your postage batch ID (replace with a valid one)
217-
const postageBatchId = new BatchId('b680c04c49d246538284cadd143cf6e623cd6581347e1bb7d9b62e36334757db');
256+
const postageBatchId = new BatchId('0258a225fe8da54cc6537eb8b12fcf6706c7873dbe19b9381d31729aa0405398');
218257

219-
// Grantee list reference (the reference returned from the `createGrantees` function)
220-
const historyRef_01 = new Reference('73b516518a2c1c5730bea115393dde6ece5d6ad4fe9a31f12073693ec2180f91');
221-
const historyRef_02 = new Reference('1de158acf997a3ee91cf6c5bc60ee3c69e72ae7863fed346f859d79dcab82825');
258+
// Grantee list reference (the reference returned from the `bee.createGrantees()` function)
259+
const historyRef_01 = new Reference('18d6f58a1d3c8253a5fc47023d49e9011236ead43724e595e898e1b422b77b19');
260+
const historyRef_02 = new Reference('d904f0790acb7edfda6a078176d64ec026b40298bfdbceb82956533e31489fcd');
222261

223262
// Sample data to upload
224-
const fileData = 'This is a sample string that will be uploaded securely using ACT. 01.';
263+
const fileData = 'This is a sample string that will be uploaded securely using ACT.';
264+
225265

226-
// Function to upload the data with ACT
227266
async function uploadWithACT(historyRef) {
228267
try {
229268
// Upload the string with ACT enabled
@@ -242,7 +281,7 @@ async function uploadWithACT(historyRef) {
242281
}
243282
}
244283

245-
// Call the function to upload the file
284+
// Call the function to upload the file with each `historyref`
246285
uploadWithACT(historyRef_01);
247286
uploadWithACT(historyRef_02);
248287
```
@@ -251,24 +290,32 @@ Example output:
251290

252291
```bash
253292
File uploaded successfully with ACT:
254-
Reference: 14bc3765a893f7bac1d179f2606997ece06389b20cedc4b7f707f98e8e3dca5f
293+
Reference: e227acea84e1d55e90baa93a698e79577a5b1c54513925b61476386798b41728
255294
History reference
256-
8e74e7dc0c94786b576b55d32c238ebcb4da633ee36ae9beae11aaa98defbb3d
295+
18d6f58a1d3c8253a5fc47023d49e9011236ead43724e595e898e1b422b77b19
257296
File uploaded successfully with ACT:
258-
Reference: 14bc3765a893f7bac1d179f2606997ece06389b20cedc4b7f707f98e8e3dca5f
297+
Reference: e227acea84e1d55e90baa93a698e79577a5b1c54513925b61476386798b41728
259298
History reference
260-
7fd72a4d7a175c6d709c799b990adc8b200ec3e0f413c2ae48026a316bb4810c
299+
d904f0790acb7edfda6a078176d64ec026b40298bfdbceb82956533e31489fcd
261300
```
262301

263-
The reference hash is the same for each upload since the content is the same. The reference hash along with a `History Reference` and the uploader's public key are required in order to access the content uploaded with ACT.
302+
The reference hash is the same for each upload since the content is the same. The reference hash along with a `historyref` and the uploader's public key are required in order to access the content uploaded with ACT.
264303

265-
You can choose which `History Reference` to share depending on which set of public keys you wish to authorize to download the content.
304+
You can choose which `historyref` to share depending on which set of public keys you wish to authorize to download the content.
266305

267306
## Download With ACT
268307

269-
270308
In order to download using ACT, we must pass in the public key from the grantee list creator along with the file reference and history reference returned from the file upload operation:
271309

310+
### Example Script
311+
312+
The example script below performs the following operations:
313+
314+
1. Initializes a Bee client.
315+
2. Defines a publisher public key and associated file reference + history references for ACT-protected content using the references returned from the upload operation.
316+
3. Calls `bee.downloadFile()` with ACT options (`actPublisher` and `actHistoryAddress`) to access protected data.
317+
4. Logs the decoded file content.
318+
272319

273320
```js
274321
import { Bee, Reference, PublicKey } from '@ethersphere/bee-js'
@@ -281,8 +328,8 @@ const bee = new Bee('http://localhost:1633')
281328
const publisherPublicKey = new PublicKey('0295562f9c1013d1db29f7aaa0c997c4bb3f1fc053bd0ed49a3d98584490cc8f96');
282329

283330
// File reference and history reference returned from upload operation
284-
const fileRef_01 = new Reference('14bc3765a893f7bac1d179f2606997ece06389b20cedc4b7f707f98e8e3dca5f');
285-
const historyRef_01 = new Reference('8e74e7dc0c94786b576b55d32c238ebcb4da633ee36ae9beae11aaa98defbb3d');
331+
const fileRef_01 = new Reference('e227acea84e1d55e90baa93a698e79577a5b1c54513925b61476386798b41728');
332+
const historyRef_01 = new Reference('18d6f58a1d3c8253a5fc47023d49e9011236ead43724e595e898e1b422b77b19');
286333

287334

288335
// Function to download ACT-protected content
@@ -299,7 +346,6 @@ async function downloadWithACT(fileRef, historyRef, publisherPubKey) {
299346
}
300347
}
301348

302-
// Download using two sets of file + history references
303349
downloadWithACT(
304350
fileRef_01,
305351
historyRef_01,
@@ -310,7 +356,9 @@ downloadWithACT(
310356
Example terminal output:
311357

312358
```bash
313-
Content: This is a sample string that will be uploaded securely using ACT. 01.
359+
Content: This is a sample string that will be uploaded securely using ACT.
314360
```
315361

316-
In the example above, we used the history reference from the file uploaded using the grantees list with only one public key included (`027d0c4759f689ea3dd3eb79222870671c492cb99f3fade275bcbf0ea39cd0ef6e`), and so it will only be able to be retrieved and decrypted by the node with that public key.
362+
In the example above, we used the history reference from the file uploaded using the grantees list with only one public key included (`027d0c4759f689ea3dd3eb79222870671c492cb99f3fade275bcbf0ea39cd0ef6e`), and so it will only be able to be retrieved and decrypted by the node with that public key.
363+
364+
If any other node attempts to download this content then a 404 error will be returned.

0 commit comments

Comments
 (0)