0.17.0 • Published 4 months ago

@upcoming/bee-js v0.17.0

Weekly downloads
-
License
BSD-3-Clause
Repository
github
Last release
4 months ago

Bee-JS

npm.io FOSSA Status standard-readme compliant js-standard-style npm.io npm.io

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.4.0.

Quick start

Start a Swarm project using TypeScript:

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

or using Vite and TypeScript:

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

npm install @ethersphere/bee-js

Import

CJS

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

MJS and TypeScript

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

Script tag

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

<script src="https://unpkg.com/@ethersphere/bee-js/dist/index.browser.min.js"></script>

Overview

Type interfaces

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.

Byte primitives

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

NameDescriptionMethods
PrivateKey32 bytes private keypublicKey, sign
PublicKey64 bytes public keyaddress, toCompressedUint8Array, toCompressedHex
EthAddress20 bytes Ethereum addresstoChecksum
Signature65 bytes signaturerecoverPublicKey

Swarm

NameDescriptionMethods
Reference32/64 bytes reference (chunk, feed)toCid
Identifier32 bytes identifier (SOC, Feed)-
TransactionId32 bytes transaction ID-
FeedIndex8 bytes feed index (BE)static fromBigInt, toBigInt
Topic32 bytes topicstatic fromString
PeerAddress32 bytes peer address-
BatchId32 bytes batch ID-
Span8 bytes span (LE)static fromBigInt, toBigInt

Tokens

NameDescriptionMethods
DAIERC20 DAI token (18 digits)static fromDecimalString, static fromWei, toWeiString, toWeiBigInt, toDecimalString
BZZERC20 BZZ token (16 digits)static fromDecimalString, static fromPLUR, toPLURString, toPLURBigInt, toDecimalString

Swarm chunks

NameDescriptionCreation
ChunkSpan, max. 4096 bytes payload; address dervied from contentmakeContentAddressedChunk
SingleOwnerChunkIdentifier, signature, span, max. 4096 bytes payload; address derived from identifier and ownermakeSingleOwnerChunk

Swarm primitives

NameDescriptionMethods
MantarayNodeCompact trie with reference values and JSON metadataaddFork, removeFork, calculateSelfAddress, find, findClosest, collect, marshal, unmarshal, saveRecursively, loadRecursively
MerkleTreeStreaming BMT of chunksappend, finalize, static root

Swarm objects

NameDescriptionCreation
SOCWriterSingleOwnerChunk writerbee.makeSOCWriter
SOCReaderSingleOwnerChunk readerbee.makeSOCReader
FeedWriterFeed writerbee.makeFeedWriter
FeedReaderFeed readerbee.makeFeedReader

Bee API

  • ❌❌✅ - Full node only
  • ❌✅✅ - Light node and full node
  • ✅✅✅ - Ultra-light node, light node and full node
JS CallBee EndpointBee Mode
uploadFilePOST /bzz 🔗❌✅✅
uploadFilesFromDirectory Node.jsPOST /bzz 🔗❌✅✅
uploadFilesPOST /bzz 🔗❌✅✅
uploadCollectionPOST /bzz 🔗❌✅✅
uploadDataPOST /bytes 🔗❌✅✅
uploadChunkPOST /chunks 🔗❌✅✅
streamDirectory Node.jsPOST /chunks 🔗❌✅✅
streamFiles BrowserPOST /chunks 🔗❌✅✅
SOCWriter.uploadPOST /soc/:owner/:identifier 🔗❌✅✅
FeedReader.downloadGET /feeds/:owner/:topic 🔗✅✅✅
FeedWriter.updateFeedPOST /soc/:owner/:identifier 🔗❌✅✅
downloadFileGET /bzz/:reference 🔗✅✅✅
downloadFileGET /bzz/:reference/:path 🔗✅✅✅
downloadReadableFileGET /bzz/:reference 🔗✅✅✅
downloadDataGET /bytes/:reference 🔗✅✅✅
downloadReadableDataGET /bytes/:reference 🔗✅✅✅
downloadChunkGET /chunks/:reference 🔗✅✅✅
createFeedManifestPOST /feeds/:owner/:topic 🔗❌✅✅
isConnectedGET /✅✅✅
getHealthGET /health 🔗✅✅✅
getReadinessGET /readiness 🔗✅✅✅
getNodeInfoGET /node 🔗✅✅✅
getChainStateGET /chainstate 🔗❌✅✅
getRedistributionStateGET /redistributionstate 🔗❌❌✅
getReserveStateGET /reservestate 🔗❌❌✅
getStatusGET /status 🔗✅✅✅
getWalletGET /wallet 🔗❌✅✅
getTopologyGET /topology 🔗✅✅✅
getAddressesGET /addresses 🔗✅✅✅
getPeersGET /peers 🔗✅✅✅
getAllBalancesGET /balances 🔗❌✅✅
getPeerBalanceGET /balances/:peer 🔗❌✅✅
getPastDueConsumptionBalancesGET /consumed 🔗❌✅✅
getPastDueConsumptionPeerBalanceGET /consumed/:peer 🔗❌✅✅
getAllSettlementsGET /settlements 🔗❌✅✅
getSettlementsGET /settlements/:peer 🔗❌✅✅
getChequebookAddressGET /chequebook/address 🔗❌✅✅
getChequebookBalanceGET /chequebook/balance 🔗❌✅✅
getLastChequesGET /chequebook/cheque 🔗❌✅✅
getLastChequesForPeerGET /chequebook/cheque/:peer 🔗❌✅✅
getLastCashoutActionGET /chequebook/cashout/:peer 🔗❌✅✅
cashoutLastChequePOST /chequebook/cashout/:peer 🔗❌✅✅
depositTokensPOST /chequebook/deposit 🔗❌✅✅
withdrawTokensPOST /chequebook/withdraw 🔗❌✅✅
getAllPendingTransactionsGET /transactions 🔗❌✅✅
getPendingTransactionGET /transactions/:id 🔗❌✅✅
rebroadcastTransactionPOST /transactions/:id 🔗❌✅✅
cancelTransactionDELETE /transactions/:id 🔗❌✅✅
createTagPOST /tags 🔗❌✅✅
retrieveTagGET /tags/:id 🔗❌✅✅
getAllTagsGET /tags 🔗❌✅✅
deleteTagDELETE /tags/:id 🔗❌✅✅
updateTagPATCH /tags/:id 🔗❌✅✅
pinPOST /pins/:reference 🔗✅✅✅
getAllPinsGET /pins 🔗✅✅✅
getPinGET /pins/:reference 🔗✅✅✅
isReferenceRetrievableGET /stewardship/:reference 🔗✅✅✅
reuploadPinnedDataPUT /stewardship/:reference 🔗❌✅✅
unpinDELETE /pins/:reference 🔗✅✅✅
getGranteesGET /grantee/:reference 🔗❌✅✅
createGranteesPOST /grantee 🔗❌✅✅
patchGranteesPATCH /grantee/:reference 🔗❌✅✅
pssSendPOST /pss/send/:topic/:target 🔗❌✅✅
pssSubscribe WebsocketGET /pss/subscribe/:topic 🔗❌❌✅
pssReceiveGET /pss/subscribe/:topic 🔗❌❌✅
getAllPostageBatchGET /stamps 🔗❌✅✅
getGlobalPostageBatchesGET /batches 🔗❌✅✅
getPostageBatchGET /stamps/:batchId 🔗❌✅✅
getPostageBatchBucketsGET /stamps/:batchId/buckets 🔗❌✅✅
createPostageBatchPOST /stamps/:amount/:depth 🔗❌✅✅
topUpBatchPATCH /stamps/topup/:batchId/:amount 🔗❌✅✅
diluteBatchPATCH /stamps/dilute/:batchId/:depth 🔗❌✅✅
createEnvelopePOST /envelope/:reference 🔗❌✅✅
getStakeGET /stake 🔗❌❌✅
depositStakePOST /stake 🔗❌❌✅

Utils

General

  • getCollectionSize
  • getFolderSize

PSS

  • makeMaxTarget

Erasure Coding

  • approximateOverheadForRedundancyLevel
  • getRedundancyStat
  • getRedundancyStats

Stamps

  • getAmountForTtl
  • getDepthForCapacity
  • getStampCost
  • getStampEffectiveBytes
  • getStampMaximumCapacityBytes
  • getStampTtlSeconds
  • getStampUsage

Usage

Upload via Swarm Gateway

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)
}

Create or select an existing postage batch

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

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

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

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

  if (usable) {
    batchId = usable.batchID
  } else {
    batchId = await bee.createPostageBatch('500000000', 20)
  }
}

The following examples all assume an existing batchId.

Upload simple data (Browser + Node.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!'

Upload data from a file input (React)

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

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

Upload multiple files or a directory (React)

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

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

Upload arbitrary large file (Node.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)

Upload arbitrary large directories (Node.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/')

Customize http/https agent and headers

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.

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

Setup

Install project dependencies:

npm install

Build the project:

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.

Test

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

FOSSA Status

0.14.0

4 months ago

0.15.0

4 months ago

0.16.0

4 months ago

0.15.1

4 months ago

0.17.0

4 months ago

0.16.1

4 months ago

0.10.0

5 months ago

0.11.0

5 months ago

0.10.1

5 months ago

0.9.0

5 months ago

0.12.0

5 months ago

0.13.0

5 months ago

0.8.1

5 months ago

0.8.0

5 months ago

0.7.1

5 months ago

0.5.4

5 months ago

0.5.3

5 months ago

0.5.5

5 months ago

0.7.0

5 months ago

0.5.2

5 months ago

0.6.0

5 months ago

0.5.1

5 months ago

0.5.0

5 months ago

0.4.0

5 months ago

0.3.0

5 months ago

0.2.0

5 months ago

0.1.0

5 months ago