Bee-JS


> JavaScript SDK for the Swarm decentralised storage.

> Supports Node.js 18+, Vite and Webpack.

> Write your code in CJS, MJS or TypeScript.

> Intended to be used with Bee version 2.5.0.

Quick start

Start a Swarm project using TypeScript:

``sh
npm init swarm-app@latest my-dapp node-ts
`

or using Vite and TypeScript:

`sh
npm init swarm-app@latest my-dapp vite-tsx
`

Supported types are node, node-esm, node-ts and vite-tsx. Replace my-dapp with your project name.

Install

`sh
npm install @ethersphere/bee-js
`

Import

$3

`js
const { Bee } = require('@ethersphere/bee-js')
`

$3

`ts
import { Bee } from '@ethersphere/bee-js'
`

$3

Loading this module through a script tag will make the BeeJs object available in the global namespace.

`html

`

Overview

$3

NumberString is a branded type for marking strings that represent numbers. It interops with string and bigint
types. Where NumberString is present, number is disallowed in order to avoid pitfalls with unsafe large values.

$3

All the classes below extend Bytes, therefor the following methods are available on all of them: toUint8Array,
toHex, toBase64, toBase32, toUtf8, toJSON, static keccak256, static fromUtf8.

The toString method uses toHex.

Bytes and its subclasses may be constructed with new from Uint8Array or hex string.

#### Elliptic

| Name | Description | Methods |
| ---------- | ------------------------- | ------------------------------------------------------ |
| PrivateKey | 32 bytes private key | publicKey, sign |
| PublicKey | 64 bytes public key | address, toCompressedUint8Array, toCompressedHex |
| EthAddress | 20 bytes Ethereum address | toChecksum |
| Signature | 65 bytes signature | recoverPublicKey |

#### Swarm

| Name | Description | Methods |
| ------------- | ----------------------------------- | ------------------------------- |
| Reference | 32/64 bytes reference (chunk, feed) | toCid |
| Identifier | 32 bytes identifier (SOC, Feed) | - |
| TransactionId | 32 bytes transaction ID | - |
| FeedIndex | 8 bytes feed index (BE) | static fromBigInt, toBigInt |
| Topic | 32 bytes topic | static fromString |
| PeerAddress | 32 bytes peer address | - |
| BatchId | 32 bytes batch ID | - |
| Span | 8 bytes span (LE) | static fromBigInt, toBigInt |

$3

| Name | Description | Methods |
| ---- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| DAI | ERC20 DAI token (18 digits) | static fromDecimalString, static fromWei, toWeiString, toWeiBigInt, toDecimalString |
| BZZ | ERC20 BZZ token (16 digits) | static fromDecimalString, static fromPLUR, toPLURString, toPLURBigInt, toDecimalString |

$3

| Name | Description | Creation |
| ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------- |
| Chunk | Span, max. 4096 bytes payload; address dervied from content | makeContentAddressedChunk |
| SingleOwnerChunk | Identifier, signature, span, max. 4096 bytes payload; address derived from identifier and owner | makeSingleOwnerChunk |

$3

| Name | Description | Methods |
| ------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| MantarayNode | Compact trie with reference values and JSON metadata | addFork, removeFork, calculateSelfAddress, find, findClosest, collect, marshal, unmarshal, saveRecursively, loadRecursively |
| MerkleTree | Streaming BMT of chunks | append, finalize, static root |

$3

| Name | Description | Creation |
| ---------- | ----------------------- | -------------------- |
| SOCWriter | SingleOwnerChunk writer | bee.makeSOCWriter |
| SOCReader | SingleOwnerChunk reader | bee.makeSOCReader |
| FeedWriter | Feed writer | bee.makeFeedWriter |
| FeedReader | Feed reader | bee.makeFeedReader |

$3

- ❌❌✅ - Full node only
- ❌✅✅ - Light node and full node
- ✅✅✅ - Ultra-light node, light node and full node

| JS Call | Bee Endpoint | Bee Mode |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| uploadFile | POST /bzz 🔗 | ❌✅✅ |
| uploadFilesFromDirectory _Node.js_ | POST /bzz 🔗 | ❌✅✅ |
| uploadFiles | POST /bzz 🔗 | ❌✅✅ |
| uploadCollection | POST /bzz 🔗 | ❌✅✅ |
| uploadData | POST /bytes 🔗 | ❌✅✅ |
| uploadChunk | POST /chunks 🔗 | ❌✅✅ |
| streamDirectory _Node.js_ | POST /chunks 🔗 | ❌✅✅ |
| streamFiles _Browser_ | POST /chunks 🔗 | ❌✅✅ |
| SOCWriter.upload | POST /soc/:owner/:identifier 🔗 | ❌✅✅ |
| FeedReader.download | GET /feeds/:owner/:topic 🔗 | ✅✅✅ |
| FeedWriter.updateFeed | POST /soc/:owner/:identifier 🔗 | ❌✅✅ |
| downloadFile | GET /bzz/:reference 🔗 | ✅✅✅ |
| downloadFile | GET /bzz/:reference/:path 🔗 | ✅✅✅ |
| downloadReadableFile | GET /bzz/:reference 🔗 | ✅✅✅ |
| downloadData | GET /bytes/:reference 🔗 | ✅✅✅ |
| downloadReadableData | GET /bytes/:reference 🔗 | ✅✅✅ |
| downloadChunk | GET /chunks/:reference 🔗 | ✅✅✅ |
| createFeedManifest | POST /feeds/:owner/:topic 🔗 | ❌✅✅ |
| isConnected | GET / | ✅✅✅ |
| getHealth | GET /health 🔗 | ✅✅✅ |
| getReadiness | GET /readiness 🔗 | ✅✅✅ |
| getNodeInfo | GET /node 🔗 | ✅✅✅ |
| getChainState | GET /chainstate 🔗 | ❌✅✅ |
| getRedistributionState | GET /redistributionstate 🔗 | ❌❌✅ |
| getReserveState | GET /reservestate 🔗 | ❌❌✅ |
| getStatus | GET /status 🔗 | ✅✅✅ |
| getWallet | GET /wallet 🔗 | ❌✅✅ |
| getTopology | GET /topology 🔗 | ✅✅✅ |
| getAddresses | GET /addresses 🔗 | ✅✅✅ |
| getPeers | GET /peers 🔗 | ✅✅✅ |
| getAllBalances | GET /balances 🔗 | ❌✅✅ |
| getPeerBalance | GET /balances/:peer 🔗 | ❌✅✅ |
| getPastDueConsumptionBalances | GET /consumed 🔗 | ❌✅✅ |
| getPastDueConsumptionPeerBalance | GET /consumed/:peer 🔗 | ❌✅✅ |
| getAllSettlements | GET /settlements 🔗 | ❌✅✅ |
| getSettlements | GET /settlements/:peer 🔗 | ❌✅✅ |
| getChequebookAddress | GET /chequebook/address 🔗 | ❌✅✅ |
| getChequebookBalance | GET /chequebook/balance 🔗 | ❌✅✅ |
| getLastCheques | GET /chequebook/cheque 🔗 | ❌✅✅ |
| getLastChequesForPeer | GET /chequebook/cheque/:peer 🔗 | ❌✅✅ |
| getLastCashoutAction | GET /chequebook/cashout/:peer 🔗 | ❌✅✅ |
| cashoutLastCheque | POST /chequebook/cashout/:peer 🔗 | ❌✅✅ |
| depositTokens | POST /chequebook/deposit 🔗 | ❌✅✅ |
| withdrawTokens | POST /chequebook/withdraw 🔗 | ❌✅✅ |
| getAllPendingTransactions | GET /transactions 🔗 | ❌✅✅ |
| getPendingTransaction | GET /transactions/:id 🔗 | ❌✅✅ |
| rebroadcastTransaction | POST /transactions/:id 🔗 | ❌✅✅ |
| cancelTransaction | DELETE /transactions/:id 🔗 | ❌✅✅ |
| createTag | POST /tags 🔗 | ❌✅✅ |
| retrieveTag | GET /tags/:id 🔗 | ❌✅✅ |
| getAllTags | GET /tags 🔗 | ❌✅✅ |
| deleteTag | DELETE /tags/:id 🔗 | ❌✅✅ |
| updateTag | PATCH /tags/:id 🔗 | ❌✅✅ |
| pin | POST /pins/:reference 🔗 | ✅✅✅ |
| getAllPins | GET /pins 🔗 | ✅✅✅ |
| getPin | GET /pins/:reference 🔗 | ✅✅✅ |
| isReferenceRetrievable | GET /stewardship/:reference 🔗 | ✅✅✅ |
| reuploadPinnedData | PUT /stewardship/:reference 🔗 | ❌✅✅ |
| unpin | DELETE /pins/:reference 🔗 | ✅✅✅ |
| getGrantees | GET /grantee/:reference 🔗 | ❌✅✅ |
| createGrantees | POST /grantee 🔗 | ❌✅✅ |
| patchGrantees | PATCH /grantee/:reference 🔗 | ❌✅✅ |
| pssSend | POST /pss/send/:topic/:target 🔗 | ❌✅✅ |
| pssSubscribe _Websocket_ | GET /pss/subscribe/:topic 🔗 | ❌❌✅ |
| pssReceive | GET /pss/subscribe/:topic 🔗 | ❌❌✅ |
| getPostageBatches | GET /stamps 🔗 | ❌✅✅ |
| getGlobalPostageBatches | GET /batches 🔗 | ❌✅✅ |
| getPostageBatch | GET /stamps/:batchId 🔗 | ❌✅✅ |
| getPostageBatchBuckets | GET /stamps/:batchId/buckets 🔗 | ❌✅✅ |
| createPostageBatch | POST /stamps/:amount/:depth 🔗 | ❌✅✅ |
| topUpBatch | PATCH /stamps/topup/:batchId/:amount 🔗 | ❌✅✅ |
| diluteBatch | PATCH /stamps/dilute/:batchId/:depth 🔗 | ❌✅✅ |
| createEnvelope | POST /envelope/:reference 🔗 | ❌✅✅ |
| getStake | GET /stake 🔗 | ❌❌✅ |
| depositStake | POST /stake 🔗 | ❌❌✅ |

$3

#### General

- getCollectionSize
- getFolderSize

#### PSS

- makeMaxTarget

#### Erasure Coding

- approximateOverheadForRedundancyLevel
- getRedundancyStat
- getRedundancyStats

#### Stamps

- getAmountForTtl
- getDepthForCapacity
- getStampCost
- getStampEffectiveBytes
- getStampMaximumCapacityBytes
- getStampTtlSeconds
- getStampUsage

Usage

$3

`js
import { Bee, NULL_STAMP, SWARM_GATEWAY_URL } from '@ethersphere/bee-js'

main()

async function main() {
const bee = new Bee(SWARM_GATEWAY_URL)
const { reference } = await bee.uploadData(NULL_STAMP, 'Hello, World!')
console.log(reference.toHex())
}
`

$3

Swarm incentivizes nodes in the network to store content, therefor all uploads require a paid
postage batch.

`js
import { Bee } from '@ethersphere/bee-js'

async function getOrCreatePostageBatch() {
const bee = new Bee('http://localhost:1633')
let batchId

const batches = await bee.getPostageBatches()
const usable = batches.find(x => x.usable)

if (usable) {
batchId = usable.batchID
} else {
batchId = await bee.buyStorage(Size.fromGigabytes(1), Duration.fromDays(7))
}
}
`

> The following examples all assume an existing batchId.

$3

`js
import { Bee } from '@ethersphere/bee-js'

const bee = new Bee('http://localhost:1633')

const uploadResult = await bee.uploadData(batchId, 'Bee is awesome!')
const data = await bee.downloadData(uploadResult.reference)

console.log(data.toUtf8()) // prints 'Bee is awesome!'
`

$3

`js
import { Bee } from '@ethersphere/bee-js'

const bee = new Bee('http://localhost:1633')
const result = await bee.uploadFile(batchId, file)
`

$3

`js
import { Bee } from '@ethersphere/bee-js'

const bee = new Bee('http://localhost:1633')
const result = await bee.uploadFiles(batchId, fileList)
`

$3

`js
import { Bee } from '@ethersphere/bee-js'
import { createReadStream } from 'fs'

const bee = new Bee('http://localhost:1633')
const readable = createReadStream('./path/to/large.bin')
const uploadResult = await bee.uploadFile(batchId, readable)
`

$3

`js
import { Bee } from '@ethersphere/bee-js'
import { createReadStream } from 'fs'

const bee = new Bee('http://localhost:1633')
const uploadResult = await bee.uploadFilesFromDirectory(batchId, './path/to/gallery/')
`

$3

`js
const bee = new Bee('http://localhost:1633', {
httpAgent: new http.Agent({ keepAlive: true }),
httpsAgent: new https.Agent({ keepAlive: true }),
headers: {
Authorization: 'Basic ' + Buffer.from('username:password').toString('base64'),
},
})
`

Contribute

Stay up to date by joining the official Discord and by keeping an eye on the
releases tab.

We are using Conventional Commits for our commit messages and pull
requests, following the Semantic Versioning rules.

There are some ways you can make this module better:

- Consult our open issues and take on one of them
- Help our tests reach 100% coverage!
- Join us in our Discord chat in the #develop-on-swarm channel if you have questions or
want to give feedback

$3

Install project dependencies:

`sh
npm install
`

Build the project:

`sh
npm run build
`

After making changes, link the package to your project by running npm link in the Bee-JS project root, and
npm link @ethersphere/bee-js` in your project root.

$3

Code coverage

Tests are currently run against a mainnet Bee nodes. This is temporary and this section will be revised in the future.

License

BSD-3-Clause