BSV blockchainBSV blockchain

Supported runtimes

Use this reference to check what @bsv/sdk needs from the JavaScript environment you target, such as Node.js, a browser app built with a bundler, a plain web page, a worker or React Native, and how to load it there. Read this before you add the SDK to a new kind of project, or when the SDK raises an error about randomness or HTTP that it does not raise elsewhere. This page was written against @bsv/sdk 4.0.1.

What the SDK needs

@bsv/sdk has no runtime dependencies, and its runtime code does not use the Node.js Buffer. Its TypeScript declarations do use the Buffer type, so a TypeScript project needs @types/node and "types": ["node"] in tsconfig.json, even when it targets a browser, as Install the SDK in Node or React explains. The SDK asks the runtime for three things:

NeedWhat the SDK usesUsed for
A module loaderAn ES module build (dist/esm), a CommonJS build (dist/cjs) and a UMDUniversal Module Definition, a single file that a page loads with a script tag and that defines a global variable bundle (dist/umd/bundle.js)Loading the package in any of the environments below
Secure random numberscrypto.getRandomValues of the global object, self or window, or else randomBytes from node:cryptoGenerating keys, such as PrivateKey.fromRandom(), and the random values used in encryption, such as ECIESElliptic Curve Integrated Encryption Scheme, which encrypts a message to a public key
HTTP requestsThe global fetch, or else the node:https module when the code runs as CommonJSBroadcasting transactions and calling services such as WhatsOnChain

Building and signing a transaction need neither randomness nor HTTP, but the defaults of two Transaction methods make HTTP calls. With no argument, fee() fetches the current fee rate and verify() checks block headers through a Mainnet chain tracker. On a runtime without HTTP, pass a fixed rate such as fee(new SatoshisPerKilobyte(1)), and call verify('scripts only'), which skips the block header check, or pass a chain tracker of your own. See SDK default values.

Supported environments

The BSV team declares the supported runtimes of each package in the stack facts of the TypeScript stack. For @bsv/sdk they are Node.js 22 or newer, browsers and the UMD bundle, and the support policy makes the latest published release the supported version:

EnvironmentHow to load itWhat to check
Node.js 22 or newerimport from @bsv/sdk (ES modules) or require('@bsv/sdk') (CommonJS)The package declares "node": ">=22" in its engines field. See Install the SDK in Node or React
Browser app with a bundler, such as Viteimport from @bsv/sdkThe bundler picks the ES module build. No polyfill is needed
Web page without a bundler<script src="bundle.js"> with the file dist/umd/bundle.js of the packageThe bundle defines the global bsv, such as bsv.PrivateKey

Other environments

Web Workers and React Native are not declared runtimes of @bsv/sdk, so test your app there before you rely on it:

  • In a module Web Worker, import from @bsv/sdk as in a browser app. Workers expose crypto.getRandomValues and fetch on self, which the SDK reads.
  • In React Native, a runtime with no crypto.getRandomValues needs a polyfill that defines it, imported before @bsv/sdk. For a wallet that runs inside a React Native app, the stack declares a separate package, @bsv/wallet-toolbox-mobile.

To reach the user’s wallet from any of these environments, WalletClient tries its substrates in turn and uses the first that answers, such as the HTTP port of BSV Desktop or the React Native WebView bridge. See Connect to a wallet with WalletClient.

Troubleshooting

Key creation throws because the runtime has no secure random source #

The error is No secure random number generator is available in this environment.. The runtime has no crypto.getRandomValues and no node:crypto, so PrivateKey.fromRandom() and any other call that needs randomness throw this error. In React Native, install a polyfill for crypto.getRandomValues and import it before @bsv/sdk. In other runtimes, check that the global crypto object is not removed or replaced.

Broadcast returns code 500 "Internal Server Error" before reaching the server #

The ARCThe service that receives your transaction and passes it to miners, Teranode and WhatsOnChain broadcaster classes return { status: 'error', code: '500', description: 'Internal Server Error' } when its HTTP request throws before it reaches the server. One cause is a runtime with no fetch that loads the SDK as an ES module, where the node:https fallback is not available. Provide a global fetch, or pass an HTTP client of your own to the broadcaster. The same result can also come from the server itself, so check the network log first.

To learn more about setting up the SDK in BSV, review these articles: