Skip to content

Commit d0527d5

Browse files
NoahMaizelsNoahMaizels
committed
formatting
1 parent 17ee51a commit d0527d5

File tree

1 file changed

+102
-93
lines changed

1 file changed

+102
-93
lines changed

‎docs/develop/access-the-swarm/upload-and-download.md‎

Lines changed: 102 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,27 @@ title: Upload & Download
33
id: upload-and-download
44
---
55

6-
76
Uploading to Swarm has two steps: (1) **buy storage** as a **postage stamp batch** with a unique **batch ID**—and (2) **upload using the batch ID**. The upload returns a **Swarm reference hash**, anyone with that reference can download the content.
87

9-
108
**Before you begin:**
11-
* You need a running Bee node connected to Gnosis Chain and funded with **xBZZ** and **xDAI**.
12-
* Uploads always require a **postage stamp batch**.
13-
* Ultra-light nodes can download but **cannot upload**.
149

10+
- You need a running Bee node connected to Gnosis Chain and funded with **xBZZ** and **xDAI**.
11+
- Uploads always require a **postage stamp batch**.
12+
- Ultra-light nodes can download but **cannot upload**.
1513

16-
## Upload & Download with bee-js
14+
## Upload & Download with bee-js
1715

1816
The `bee-js` library is the **official SDK for building Swarm-based applications**. It works in both **browser** and **Node.js** environments and **greatly simplifies development** compared with using the Bee HTTP API directly. It is the recommended method for developing applications on Swarm.
1917

2018
Refer to the [`bee-js` documentation](https://bee-js.ethswarm.org/) for more usage guides.
2119

2220
:::tip
2321
**Environment-specific methods:**
24-
* **Browser-only:** [`uploadFiles`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfiles) (multi-file via `File[]`/`FileList`)
25-
* **Node.js-only:** [`uploadFilesFromDirectory`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfiles) (recursively reads local filesystem to upload multiple files in a directory using `fs`),
26-
* **Both:** [`uploadFile`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfile) (with some environment specific usage), [`downloadFile`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#downloadfile)
27-
:::
22+
23+
- **Browser-only:** [`uploadFiles`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfiles) (multi-file via `File[]`/`FileList`)
24+
- **Node.js-only:** [`uploadFilesFromDirectory`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfiles) (recursively reads local filesystem to upload multiple files in a directory using `fs`),
25+
- **Both:** [`uploadFile`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#uploadfile) (with some environment specific usage), [`downloadFile`](https://bee-js.ethswarm.org/docs/api/classes/Bee/#downloadfile)
26+
:::
2827

2928
### Single file — Node.js
3029

@@ -51,43 +50,46 @@ Refer to the [`bee-js` documentation](https://bee-js.ethswarm.org/) for more usa
5150
`const file = await bee.downloadFile(reference)`
5251

5352
6. Log the downloaded file’s title and metadata:
54-
55-
`console.log(file.name)`
5653

57-
`console.log(file.contentType)`
54+
`console.log(file.name)`
55+
56+
`console.log(file.contentType)`
5857

59-
`console.log(file.data.toUtf8())`
58+
`console.log(file.data.toUtf8())`
6059

61-
6260
**Full example:**
6361

6462
```js
65-
import { Bee, Size, Duration } from "@ethersphere/bee-js"
66-
import { readFile } from "node:fs/promises"
63+
import { Bee, Size, Duration } from "@ethersphere/bee-js";
64+
import { readFile } from "node:fs/promises";
6765

6866
// 1) Connect to your Bee node HTTP API
69-
const bee = new Bee("http://localhost:1633")
67+
const bee = new Bee("http://localhost:1633");
7068

7169
// 2) Buy storage (postage stamp batch) for this session
72-
const batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(1))
70+
const batchId = await bee.buyStorage(
71+
Size.fromGigabytes(1),
72+
Duration.fromDays(1)
73+
);
7374

7475
// 3) Read the file from disk as bytes
75-
const data = await readFile("./hello.txt")
76+
const data = await readFile("./hello.txt");
7677

7778
// 4) Upload the bytes with a filename and content type; capture the reference
78-
const { reference } = await bee.uploadFile(batchId, data, "hello.txt", { contentType: "text/plain" })
79-
console.log("Uploaded reference:", reference.toHex())
79+
const { reference } = await bee.uploadFile(batchId, data, "hello.txt", {
80+
contentType: "text/plain",
81+
});
82+
console.log("Uploaded reference:", reference.toHex());
8083

8184
// 5) Download the file back using the reference
82-
const file = await bee.downloadFile(reference)
85+
const file = await bee.downloadFile(reference);
8386

8487
// 6) Log the file's metadata and contents to the terminal
85-
console.log(file.name) // "hello.txt"
86-
console.log(file.contentType) // "text/plain"
87-
console.log(file.data.toUtf8()) // Prints file content
88+
console.log(file.name); // "hello.txt"
89+
console.log(file.contentType); // "text/plain"
90+
console.log(file.data.toUtf8()); // Prints file content
8891
```
8992

90-
9193
### Single file — Browser
9294

9395
:::info
@@ -106,7 +108,7 @@ When working with browsers you can use the [`File` interface](https://developer.
106108

107109
3. Create a `File` object:
108110

109-
`const file = new File(["Hello Swarm!"], "hello.txt", { type: "text/plain" })`
111+
`const file = new File(["Hello Swarm!"], "hello.txt", { type: "text/plain" })`
110112

111113
4. Use batch ID to upload → get reference:
112114

@@ -118,54 +120,57 @@ When working with browsers you can use the [`File` interface](https://developer.
118120

119121
6. Log the downloaded file’s title and metadata:
120122

121-
`console.log(downloaded.name) // "hello.txt"`
123+
`console.log(downloaded.name) // "hello.txt"`
122124

123-
`console.log(file.contentType) // "text/plain"`
124-
125-
`console.log(downloaded.data.toUtf8()) // prints file content`
125+
`console.log(file.contentType) // "text/plain"`
126126

127+
`console.log(downloaded.data.toUtf8()) // prints file content`
127128

128129
```js
129-
130-
import { Bee, Size, Duration } from "@ethersphere/bee-js"
130+
import { Bee, Size, Duration } from "@ethersphere/bee-js";
131131

132132
// 1) Connect to your Bee node HTTP API
133-
const bee = new Bee("http://localhost:1633")
133+
const bee = new Bee("http://localhost:1633");
134134

135135
// 2) Buy storage (postage stamp batch) for this session
136-
const batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(1))
137-
console.log("Batch ID:", String(batchId))
136+
const batchId = await bee.buyStorage(
137+
Size.fromGigabytes(1),
138+
Duration.fromDays(1)
139+
);
140+
console.log("Batch ID:", String(batchId));
138141

139142
// 3) Upload a single file created in code
140-
const file = new File(["Hello Swarm!"], "hello.txt", { type: "text/plain" })
141-
const { reference } = await bee.uploadFile(batchId, file)
142-
console.log("Reference:", String(reference))
143+
const file = new File(["Hello Swarm!"], "hello.txt", { type: "text/plain" });
144+
const { reference } = await bee.uploadFile(batchId, file);
145+
console.log("Reference:", String(reference));
143146

144147
// 4) Download and print name + contents
145-
const downloaded = await bee.downloadFile(reference)
146-
console.log(downloaded.name) // "hello.txt"
147-
console.log(file.contentType) // "text/plain"
148-
console.log(downloaded.data.toUtf8()) // prints file content
148+
const downloaded = await bee.downloadFile(reference);
149+
console.log(downloaded.name); // "hello.txt"
150+
console.log(file.contentType); // "text/plain"
151+
console.log(downloaded.data.toUtf8()); // prints file content
149152
```
150153

151-
### Multiple files — Browser
154+
### Multiple files — Browser
152155

153156
Use **`uploadFiles`** for multi-file upload in the browser. It accepts `File[]`/`FileList`. When using `<input type="file" webkitdirectory multiple>`, each file’s **relative path** is preserved. To download a specific file later, pass the **collection reference** plus the **same relative path**.
154157

155-
156158
1. Initialize a Bee object using the API endpoint of a Bee node:
157159
`const bee = new Bee("http://localhost:1633")`
158160

159161
2. Buy storage and get postage stamp batch ID:
160162
`const batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(1))`
161163

162164
3. Create files for upload:
163-
```js
164-
const files = [
165+
166+
```js
167+
const files = [
165168
new File(["<h1>Hello Swarm</h1>"], "index.html", { type: "text/html" }),
166-
new File(["body{font-family:sans-serif}"], "assets/main.css", { type: "text/css" })
167-
]
168-
```
169+
new File(["body{font-family:sans-serif}"], "assets/main.css", {
170+
type: "text/css",
171+
}),
172+
];
173+
```
169174

170175
4. Upload multiple files (collection) → get collection reference:
171176
`const res = await bee.uploadFiles(batchId, files)`
@@ -175,44 +180,45 @@ Use **`uploadFiles`** for multi-file upload in the browser. It accepts `File[]`/
175180

176181
6. Log the downloaded file’s title and contents:
177182

178-
`console.log(page.name) // "index.html"`
179-
180-
`console.log(page.data.toUtf8()) // prints file content`
183+
`console.log(page.name) // "index.html"`
181184

185+
`console.log(page.data.toUtf8()) // prints file content`
182186

183187
```js
184-
import { Bee, Size, Duration } from "@ethersphere/bee-js"
188+
import { Bee, Size, Duration } from "@ethersphere/bee-js";
185189

186190
// 1. Initialize a Bee object
187-
const bee = new Bee("http://localhost:1633")
191+
const bee = new Bee("http://localhost:1633");
188192

189193
// 2. Buy storage and get batch ID
190-
const batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(1))
191-
console.log("Batch ID:", String(batchId))
194+
const batchId = await bee.buyStorage(
195+
Size.fromGigabytes(1),
196+
Duration.fromDays(1)
197+
);
198+
console.log("Batch ID:", String(batchId));
192199

193200
// 3. Create files for upload
194201
const files = [
195202
new File(["<h1>Hello Swarm</h1>"], "index.html", { type: "text/html" }),
196-
new File(["body{font-family:sans-serif}"], "assets/main.css", { type: "text/css" })
197-
]
203+
new File(["body{font-family:sans-serif}"], "assets/main.css", {
204+
type: "text/css",
205+
}),
206+
];
198207

199208
// 4. Upload multiple files (collection) → get collection reference
200-
const res = await bee.uploadFiles(batchId, files)
201-
console.log("Collection ref:", String(res.reference))
209+
const res = await bee.uploadFiles(batchId, files);
210+
console.log("Collection ref:", String(res.reference));
202211

203212
// 5. Download files by relative path
204-
const page = await bee.downloadFile(res.reference, "index.html")
205-
console.log(page.name) // "index.html"
206-
console.log(page.data.toUtf8()) // prints file content
213+
const page = await bee.downloadFile(res.reference, "index.html");
214+
console.log(page.name); // "index.html"
215+
console.log(page.data.toUtf8()); // prints file content
207216

208-
const style = await bee.downloadFile(res.reference, "assets/main.css")
209-
console.log(style.name) // "main.css"
210-
console.log(style.data.toUtf8()) // prints file content
217+
const style = await bee.downloadFile(res.reference, "assets/main.css");
218+
console.log(style.name); // "main.css"
219+
console.log(style.data.toUtf8()); // prints file content
211220
```
212221

213-
214-
215-
216222
### Multiple files — Node.js
217223

218224
**Step-by-step Walkthrough:**
@@ -242,34 +248,39 @@ console.log(style.data.toUtf8()) // prints file content
242248
**Full example:**
243249

244250
```js
245-
import { Bee, Size, Duration } from "@ethersphere/bee-js"
251+
import { Bee, Size, Duration } from "@ethersphere/bee-js";
246252

247253
// 1) Connect to your Bee node HTTP API
248-
const bee = new Bee("http://localhost:1633")
254+
const bee = new Bee("http://localhost:1633");
249255

250256
// 2) Buy storage (postage stamp batch)
251-
const batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(1))
257+
const batchId = await bee.buyStorage(
258+
Size.fromGigabytes(1),
259+
Duration.fromDays(1)
260+
);
252261

253262
// 3) Upload all files under ./files (relative paths preserved); get reference
254-
const res = await bee.uploadFilesFromDirectory(batchId, "./files")
255-
console.log("Directory uploaded. Collection reference:", res.reference.toHex())
263+
const res = await bee.uploadFilesFromDirectory(batchId, "./files");
264+
console.log("Directory uploaded. Collection reference:", res.reference.toHex());
256265

257266
// 4) Download files from the collection by original relative paths
258-
const page = await bee.downloadFile(res.reference, "root.txt")
259-
const stylesheet = await bee.downloadFile(res.reference, "subdirectory/example.txt")
267+
const page = await bee.downloadFile(res.reference, "root.txt");
268+
const stylesheet = await bee.downloadFile(
269+
res.reference,
270+
"subdirectory/example.txt"
271+
);
260272

261273
// 5) Log the file name and contents to the terminal
262-
console.log(page.name) // "root.txt"
263-
console.log(page.data.toUtf8()) // prints file content
274+
console.log(page.name); // "root.txt"
275+
console.log(page.data.toUtf8()); // prints file content
264276

265-
console.log(stylesheet.name) // "example.txt"
266-
console.log(stylesheet.data.toUtf8()) // prints file content
277+
console.log(stylesheet.name); // "example.txt"
278+
console.log(stylesheet.data.toUtf8()); // prints file content
267279
```
268280

269-
270281
## Upload & Download with Swarm CLI
271282

272-
The `swarm-cli` tool offers a convenient command-line interface for Bee node interaction. It's a convenient tool for node management or one-off uploads and downloads.
283+
The `swarm-cli` tool offers a convenient command-line interface for Bee node interaction. It's a convenient tool for node management or one-off uploads and downloads.
273284

274285
Refer to [the official README](https://github.com/ethersphere/swarm-cli/blob/master/README.md) for a more complete usage guide.
275286

@@ -336,7 +347,6 @@ swarm-cli upload <PATH_TO_FILE>
336347

337348
And an interactive prompt will walk your through stamp selection and the rest of the upload.
338349

339-
340350
Upon upload, a Swarm reference hash will be returned which can then be used to download content:
341351

342352
```bash
@@ -351,14 +361,13 @@ Refer to the [Bee API reference specification](https://docs.ethswarm.org/api/) f
351361

352362
The Bee API exposes three HTTP endpoints:
353363

354-
* **`/bzz`** — upload & download files/directories (most common)
355-
* **`/bytes`** — upload & download raw data
356-
* **`/chunks`** — upload & download individual chunks
357-
364+
- **`/bzz`** — upload & download files/directories (most common)
365+
- **`/bytes`** — upload & download raw data
366+
- **`/chunks`** — upload & download individual chunks
358367

359368
#### Upload with **/bzz**
360369

361-
While both `swarm-cli` and `bee-js` allow for postage stamp batches to be purchased by specifying the storage duration and data size, the actual call to the Bee API requires an `amount` and `depth` parameters. The relationship between these parameters and the storage size and duration of the batch is complex. Therefore `bee-js` and `swarm-cli` (which allow batches to be purchased by data size/duration which are then converted to `depth`/`amount`) are strongly encouraged for newcomers to development on Swarm. [Learn more](/docs/develop/tools-and-features/buy-a-stamp-batch).
370+
While both `swarm-cli` and `bee-js` allow for postage stamp batches to be purchased by specifying the storage duration and data size, the actual call to the Bee API requires an `amount` and `depth` parameters. The relationship between these parameters and the storage size and duration of the batch is complex. Therefore `bee-js` and `swarm-cli` (which allow batches to be purchased by data size/duration which are then converted to `depth`/`amount`) are strongly encouraged for newcomers to development on Swarm. [Learn more](/docs/develop/tools-and-features/buy-a-stamp-batch).
362371

363372
1. Buy a postage batch:
364373

@@ -379,13 +388,13 @@ curl -X POST \
379388
Response:
380389

381390
```json
382-
{ "reference": "22cbb9cedca08ca8d50b0319a32016174ceb8fbaa452ca5f0a77b804109baa00" }
391+
{
392+
"reference": "22cbb9cedca08ca8d50b0319a32016174ceb8fbaa452ca5f0a77b804109baa00"
393+
}
383394
```
384395

385396
3. Download with `/bzz`
386397

387398
```bash
388399
curl http://localhost:1633/bzz/<REFERENCE> -o output.txt
389400
```
390-
391-

0 commit comments

Comments
 (0)