Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TezosBundler
✓ import TezosBundler from 'tezos-bundler'
✗ import { TezosBundler } from 'tezos-bundler'
TezosBundler is a default export of the package.
Arweave
✓ import Arweave from 'arweave'
✗ const Arweave = require('arweave')
The Arweave client library is typically imported as a default export in modern ESM contexts. CJS require() is still common but may cause issues in mixed environments.
app.callback
✓ const callback = tezosBundler.app.callback()
✗ export default tezosBundler.app.callback
The `callback` method must be invoked to return the actual middleware function, not just referenced.
This quickstart demonstrates how to programmatically initialize and start the TezosBundler node, including secure (simulated) JWK loading and Arweave client configuration for local or remote instances.
import Arweave from 'arweave'
import TezosBundler from 'tezos-bundler'
import path from 'path'
import fs from 'fs'
// In a real application, securely load your Arweave JWK, e.g., from environment variables or a secure vault.
// For this example, we'll simulate loading from a local file.
// DO NOT commit your private keys to version control.
const arweaveJWKPath = path.join(process.cwd(), 'my-arweave-keyfile.json');
let arweaveJWK;
try {
if (fs.existsSync(arweaveJWKPath)) {
arweaveJWK = JSON.parse(fs.readFileSync(arweaveJWKPath, 'utf-8'));
} else {
console.warn(`Warning: Arweave JWK file not found at ${arweaveJWKPath}. Using placeholder; this will likely fail.`)
arweaveJWK = { /* Placeholder for invalid JWK */ };
}
} catch (error) {
console.error('Failed to load arweave JWK:', error);
arweaveJWK = { /* Placeholder for invalid JWK */ };
}
// Configure Arweave client. Use ArLocal defaults for testing, or a production gateway.
const arweave = new Arweave({
host: process.env.ARWEAVE_HOST ?? '127.0.0.1', // e.g., 'arweave.net'
port: parseInt(process.env.ARWEAVE_PORT ?? '1984'), // e.g., 443
protocol: process.env.ARWEAVE_PROTOCOL ?? 'http' // e.g., 'https'
});
const tezosBundler = new TezosBundler(arweaveJWK, arweave);
async function startBundler() {
try {
await tezosBundler.start();
console.log('Tezos Bundler Node started successfully.');
console.log('REST API available at POST /bundle/xtz');
} catch (error) {
console.error('Failed to start Tezos Bundler Node:', error);
// Gracefully handle startup failure, perhaps exit the process or retry.
process.exit(1);
}
}
startBundler();
// Example for server middleware (e.g., Next.js API route or Nuxt.js server middleware)
// export default tezosBundler.app.callback();
Debug
Known issues
breakingThe package explicitly requires Node.js `v16.13.2`. Using other major or minor Node.js versions might lead to compatibility issues or unexpected behavior, especially with underlying dependencies.fixEnsure your development and deployment environments run Node.js `v16.13.2` to avoid runtime errors or package conflicts. Use nvm or similar tools to manage Node.js versions.
affects: <1.0.2 || >1.0.2 (if new major versions don't specify)
gotchaHandling of the Arweave JWK keyfile (e.g., `my-arweave-keyfile.json`) requires extreme caution. Exposing this file can compromise your Arweave wallet and funds. The quickstart code merely simulates loading.fixNever commit private keys or JWK files to version control. Load JWKs from secure environment variables, a secrets manager, or a hardware security module in production environments.
affects: >=1.0.0
gotchaWhen running `tezos-bundler` locally for development, `ArLocal` is a required dev dependency. Ensure `ArLocal` is running and the wallet address used with `TezosBundler` is sufficiently funded (via `mint/<address>/<amount>` on ArLocal).fixBefore starting `tezos-bundler` in a dev environment, start `ArLocal` in a separate process and mint AR tokens to the Arweave wallet address associated with your JWK.
affects: >=1.0.0
gotchaIncorrect configuration of the `Arweave` client (host, port, protocol) can prevent `tezos-bundler` from connecting to the Arweave network, leading to failed bundle submissions.fixVerify that your `Arweave` client configuration matches your target Arweave gateway (e.g., `arweave.net` or your `ArLocal` instance) and that network firewalls are not blocking access.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'arweave'
The 'arweave' package is not installed as a dependency.
fixRun `npm install arweave` or `yarn add arweave` in your project directory.
TypeError: TezosBundler is not a constructor
Attempting to import `TezosBundler` as a named export when it is a default export.
fixChange `import { TezosBundler } from 'tezos-bundler'` to `import TezosBundler from 'tezos-bundler'`. UnhandledPromiseRejectionWarning: Error: connect ECONNREFUSED 127.0.0.1:1984
The configured Arweave instance (e.g., ArLocal) is not running or is inaccessible at the specified host and port.
fixEnsure your Arweave gateway or ArLocal instance is running and reachable. Check firewall rules and the `Arweave` client configuration (host, port, protocol).
Failed to load arweave JWK: SyntaxError: Unexpected token 'o' in JSON at position 1
The `arweaveJWK` variable does not contain a valid JSON Web Key object, or the file path to the JWK is incorrect/corrupted.
fixVerify that your `my-arweave-keyfile.json` is a valid JSON file containing your Arweave JWK, and that the path to it is correct.
Audit
Dependencies
arweaverequiredCore dependency for interacting with the Arweave network; required for bundle submission.