Skip to main content

Migrating from v12 to v13

Version 13 reorganizes the bee-js surface. The Bee class had grown to well over a hundred methods, so they are now grouped into namespaces by subject, and the Swarm primitives that need no network access were moved into a separate package.

Almost nothing was removed in the process. Every v12 method but one has a v13 equivalent, and the renames can be rewritten automatically.

Run the codemod​

A codemod ships with the library. It reads your project's types to work out which variables hold a Bee instance, then rewrites the call sites in place:

npx bee-js-codemod ./src --from v12

Requirements and behavior:

  • typescript 5.x must be installed in your project, since the codemod uses the TypeScript compiler API to resolve types. TypeScript 7 removed that API and is not supported.
  • It rewrites .ts, .tsx, .js and .jsx files, skipping node_modules, dist and .git.
  • It edits files in place, so commit or stash your work first.
  • The target can be a directory or a single file.

It handles the method renames below, the MerkleTree rename, the @upcoming/swarm-core import path, and jest.spyOn calls that reference method names as strings. It cannot see through dynamic property access such as bee[methodName](), so check for those by hand.

What changed​

Methods moved into namespaces​

bee.uploadData is now bee.data.upload, bee.getAllPostageBatch is now bee.stamp.getAll, and so on. See the full mapping below.

A few methods stayed directly on bee because they do not belong to any one subject: makeContentAddressedChunk, unmarshalContentAddressedChunk, makeSingleOwnerChunk, unmarshalSingleOwnerChunk, calculateSingleOwnerChunkAddress, createEnvelope and rchash.

Swarm primitives moved to @ethersphere/core-sdk​

The byte wrappers, chunk construction, the Mantaray trie, erasure coding, encryption and postage stamp signing now live in @ethersphere/core-sdk, which performs no network I/O.

bee-js depends on it and re-exports everything you are likely to need, so existing imports keep working:

import { Bee, Bytes, PrivateKey, Reference, Topic } from '@ethersphere/bee-js'

Install core-sdk directly when you want the primitives without the HTTP client, for example in a worker or on a server that never contacts a Bee node.

If you were using the @upcoming/swarm-core prerelease, the package is now @ethersphere/core-sdk. The codemod rewrites that import path.

MerkleTree is now ChunkSplitter​

MerkleTree was renamed to ChunkSplitter, and ChunkBuilder.hash() returns a Reference instead of a Uint8Array. The codemod renames the class and appends .toUint8Array() to hash() calls so the result type stays the same.

ChunkJoiner is the counterpart that reassembles a chunk tree back into bytes.

bee.stamp and bee.storage​

Postage batch operations are split across two namespaces. bee.stamp is the low-level view, taking an amount and a depth. bee.storage is the ergonomic view, taking a Size and a Duration. The old createPostageBatch maps to bee.stamp.create, and the old buyStorage maps to bee.storage.buy.

waitForUsablePostageStamp is gone​

bee.waitForUsablePostageStamp(batchId) is the one v12 method with no direct v13 replacement, and the codemod cannot rewrite it. It is no longer needed in most cases: bee.stamp.create and bee.storage.buy wait for the new batch to become usable before resolving, and you can opt out with waitForUsable: false or change the deadline with waitForUsableTimeout.

Aside from that one method, the codemod covers every public method the Bee class had in v12.

Also worth checking​

These are not v13 changes, but they are easy to miss when upgrading from older code or from examples written against earlier versions.

PSS and GSOC handlers require onClose​

Since v10, the handler object passed to bee.messaging.pssSubscribe and bee.messaging.gsocSubscribe must provide all three callbacks. A handler without onClose throws Expected function for onClose, got: undefined before the subscription is opened:

const subscription = bee.messaging.pssSubscribe(topic, {
  onMessage: message => console.log(message.toUtf8()),
  onError: error => console.error(error),
  onClose: () => console.log('subscription closed'),
})

This is not something the codemod can fill in for you, since only you know what closing should do.

Ambiguous feed methods are deprecated​

FeedWriter.upload() and FeedReader.download() still work, but it is ambiguous whether the value being written or read is a payload or a reference. Use the explicit pairs instead:

DeprecatedUse instead
writer.upload(batchId, value)writer.uploadReference(batchId, reference) or writer.uploadPayload(batchId, payload)
reader.download()reader.downloadReference() or reader.downloadPayload()

Full mapping​

bee.data​

v12v13
bee.downloadDatabee.data.download
bee.downloadReadableDatabee.data.downloadReadable
bee.isReferenceRetrievablebee.data.isRetrievable
bee.probeDatabee.data.probe
bee.uploadDatabee.data.upload

bee.file​

v12v13
bee.downloadFilebee.file.download
bee.downloadReadableFilebee.file.downloadReadable
bee.uploadFilebee.file.upload

bee.collection​

v12v13
bee.hashDirectorybee.collection.hashDirectory
bee.streamFilesbee.collection.stream
bee.streamDirectorybee.collection.streamFromDirectory
bee.uploadCollectionbee.collection.upload
bee.uploadFilesFromDirectorybee.collection.uploadFromDirectory
bee.uploadFilesbee.collection.uploadFromFileList

bee.chunk​

v12v13
bee.downloadChunkbee.chunk.download
bee.uploadChunkbee.chunk.upload

bee.feed​

v12v13
bee.createFeedManifestbee.feed.createManifest
bee.fetchLatestFeedUpdatebee.feed.fetchLatestUpdate
bee.isFeedRetrievablebee.feed.isRetrievable
bee.makeFeedReaderbee.feed.makeReader
bee.makeFeedWriterbee.feed.makeWriter

bee.soc​

v12v13
bee.makeSOCReaderbee.soc.makeReader
bee.makeSOCWriterbee.soc.makeWriter

bee.messaging​

v12v13
bee.gsocMinebee.messaging.gsocMine
bee.gsocSendbee.messaging.gsocSend
bee.gsocSubscribebee.messaging.gsocSubscribe
bee.pssReceivebee.messaging.pssReceive
bee.pssSendbee.messaging.pssSend
bee.pssSubscribebee.messaging.pssSubscribe

bee.stamp​

v12v13
bee.calculateTopUpForBzzbee.stamp.calculateTopUpForBZZ
bee.createPostageBatchbee.stamp.create
bee.diluteBatchbee.stamp.dilute
bee.getPostageBatchbee.stamp.get
bee.getAllPostageBatchbee.stamp.getAll
bee.getPostageBatchesbee.stamp.getAll
bee.getAllGlobalPostageBatchbee.stamp.getAllGlobal
bee.getGlobalPostageBatchesbee.stamp.getAllGlobal
bee.getPostageBatchBucketsbee.stamp.getBuckets
bee.getGlobalPostageBatchbee.stamp.getGlobal
bee.topUpBatchbee.stamp.topUp
bee.updatePostageBatchLabelbee.stamp.updateLabel

bee.storage​

v12v13
bee.buyStoragebee.storage.buy
bee.extendStoragebee.storage.extend
bee.extendStorageDurationbee.storage.extendDuration
bee.extendStorageSizebee.storage.extendSize
bee.getStorageCostbee.storage.getCost
bee.getDurationExtensionCostbee.storage.getDurationExtensionCost
bee.getExtensionCostbee.storage.getExtensionCost
bee.getSizeExtensionCostbee.storage.getSizeExtensionCost
bee.renameStoragebee.storage.rename

bee.tag​

v12v13
bee.createTagbee.tag.create
bee.deleteTagbee.tag.delete
bee.retrieveTagbee.tag.get
bee.getAllTagsbee.tag.getAll
bee.updateTagbee.tag.update

bee.pin​

v12v13
bee.pinbee.pin.add
bee.getPinbee.pin.get
bee.getAllPinsbee.pin.getAll
bee.unpinbee.pin.remove
bee.reuploadPinnedDatabee.pin.reuploadData

bee.grantee​

v12v13
bee.createGranteesbee.grantee.create
bee.getGranteesbee.grantee.get
bee.patchGranteesbee.grantee.patch

bee.stake​

v12v13
bee.depositStakebee.stake.deposit
bee.getStakebee.stake.get
bee.getRedistributionStatebee.stake.getRedistributionState
bee.getWithdrawableStakebee.stake.getWithdrawable
bee.migrateStakebee.stake.migrate
bee.withdrawSurplusStakebee.stake.withdrawSurplus

bee.status​

v12v13
bee.getStatusbee.status.get
bee.getChainStatebee.status.getChainState
bee.getHealthbee.status.getHealth
bee.getNodeInfobee.status.getNodeInfo
bee.getReadinessbee.status.getReadiness
bee.getReserveStatebee.status.getReserveState
bee.getVersionsbee.status.getVersions
bee.isSupportedApiVersionbee.status.isSupportedApiVersion
bee.isSupportedExactVersionbee.status.isSupportedExactVersion

bee.connectivity​

v12v13
bee.checkConnectionbee.connectivity.checkConnection
bee.getBlocklistbee.connectivity.getBlocklist
bee.getNodeAddressesbee.connectivity.getNodeAddresses
bee.getPeersbee.connectivity.getPeers
bee.getTopologybee.connectivity.getTopology
bee.isConnectedbee.connectivity.isConnected
bee.isGatewaybee.connectivity.isGateway
bee.pingPeerbee.connectivity.ping
bee.removePeerbee.connectivity.removePeer

bee.wallet​

v12v13
bee.getWalletBalancebee.wallet.getBalance
bee.withdrawBZZToExternalWalletbee.wallet.withdrawBZZ
bee.withdrawDAIToExternalWalletbee.wallet.withdrawDAI

bee.chequebook​

v12v13
bee.depositBZZToChequebookbee.chequebook.deposit
bee.depositTokensbee.chequebook.deposit
bee.getChequebookAddressbee.chequebook.getAddress
bee.getChequebookBalancebee.chequebook.getBalance
bee.withdrawBZZFromChequebookbee.chequebook.withdraw
bee.withdrawTokensbee.chequebook.withdraw

bee.cheque​

v12v13
bee.cashoutLastChequebee.cheque.cashoutLast
bee.getLastChequesbee.cheque.getAllLatest
bee.getLastChequesForPeerbee.cheque.getAllLatestForPeer
bee.getLastCashoutActionbee.cheque.getLastCashoutAction

bee.balance​

v12v13
bee.getAllBalancesbee.balance.getAll
bee.getPastDueConsumptionBalancesbee.balance.getAllPastDueConsumption
bee.getPastDueConsumptionPeerBalancebee.balance.getAllPastDueConsumptionForPeer
bee.getPeerBalancebee.balance.getPeer

bee.settlement​

v12v13
bee.getSettlementsbee.settlement.get
bee.getAllSettlementsbee.settlement.getAll

bee.transaction​

v12v13
bee.cancelPendingTransactionbee.transaction.cancel
bee.getPendingTransactionbee.transaction.get
bee.getAllPendingTransactionsbee.transaction.getAll
bee.rebroadcastPendingTransactionbee.transaction.rebroadcast

After migrating​

  • Run your type checker. Argument order and types are unchanged for every renamed method, so a clean type check is a strong signal the migration is complete.
  • Search for remaining bare method names in strings, dynamic property access, and comments. The codemod resolves types, not string keys other than jest.spyOn.
  • Add onClose to every PSS and GSOC handler.
💬 Get Help