{"id":15855,"library":"tezos-bundler","title":"Tezos Bundler Node","description":"tezos-bundler is a JavaScript/TypeScript library, currently stable at version 1.0.2, designed to facilitate cross-chain interactions between the Tezos and Arweave ecosystems. It provides a REST API endpoint for accepting Arweave ANS-104 bundles that have been cryptographically signed using a Tezos wallet keypair. This functionality enables developers to build applications where Tezos users can directly and securely publish immutable data to the Arweave permaweb. The library's core differentiator is its integrated Tezos signature verification for Arweave bundles, simplifying the deployment of decentralized applications that leverage both chains. It requires a specific Node.js environment (v16.13.2) and relies on a configured Arweave instance (e.g., a production gateway or a local ArLocal server) to function correctly. While a formal release cadence isn't explicitly stated, its current version suggests active development and maintenance.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install tezos-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add tezos-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add tezos-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for interacting with the Arweave network; required for bundle submission.","package":"arweave","optional":false}],"imports":[{"note":"TezosBundler is a default export of the package.","wrong":"import { TezosBundler } from 'tezos-bundler'","symbol":"TezosBundler","correct":"import TezosBundler from 'tezos-bundler'"},{"note":"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.","wrong":"const Arweave = require('arweave')","symbol":"Arweave","correct":"import Arweave from 'arweave'"},{"note":"The `callback` method must be invoked to return the actual middleware function, not just referenced.","wrong":"export default tezosBundler.app.callback","symbol":"app.callback","correct":"const callback = tezosBundler.app.callback()"}],"quickstart":{"code":"import Arweave from 'arweave'\nimport TezosBundler from 'tezos-bundler'\nimport path from 'path'\nimport fs from 'fs'\n\n// In a real application, securely load your Arweave JWK, e.g., from environment variables or a secure vault.\n// For this example, we'll simulate loading from a local file.\n// DO NOT commit your private keys to version control.\nconst arweaveJWKPath = path.join(process.cwd(), 'my-arweave-keyfile.json');\nlet arweaveJWK;\ntry {\n  if (fs.existsSync(arweaveJWKPath)) {\n    arweaveJWK = JSON.parse(fs.readFileSync(arweaveJWKPath, 'utf-8'));\n  } else {\n    console.warn(`Warning: Arweave JWK file not found at ${arweaveJWKPath}. Using placeholder; this will likely fail.`)\n    arweaveJWK = { /* Placeholder for invalid JWK */ };\n  }\n} catch (error) {\n  console.error('Failed to load arweave JWK:', error);\n  arweaveJWK = { /* Placeholder for invalid JWK */ };\n}\n\n// Configure Arweave client. Use ArLocal defaults for testing, or a production gateway.\nconst arweave = new Arweave({\n  host: process.env.ARWEAVE_HOST ?? '127.0.0.1', // e.g., 'arweave.net'\n  port: parseInt(process.env.ARWEAVE_PORT ?? '1984'), // e.g., 443\n  protocol: process.env.ARWEAVE_PROTOCOL ?? 'http' // e.g., 'https'\n});\n\nconst tezosBundler = new TezosBundler(arweaveJWK, arweave);\n\nasync function startBundler() {\n  try {\n    await tezosBundler.start();\n    console.log('Tezos Bundler Node started successfully.');\n    console.log('REST API available at POST /bundle/xtz');\n  } catch (error) {\n    console.error('Failed to start Tezos Bundler Node:', error);\n    // Gracefully handle startup failure, perhaps exit the process or retry.\n    process.exit(1);\n  }\n}\n\nstartBundler();\n\n// Example for server middleware (e.g., Next.js API route or Nuxt.js server middleware)\n// export default tezosBundler.app.callback();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure 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.","message":"The 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.","severity":"breaking","affected_versions":"<1.0.2 || >1.0.2 (if new major versions don't specify)"},{"fix":"Never 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.","message":"Handling 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before 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.","message":"When 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify 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.","message":"Incorrect configuration of the `Arweave` client (host, port, protocol) can prevent `tezos-bundler` from connecting to the Arweave network, leading to failed bundle submissions.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install arweave` or `yarn add arweave` in your project directory.","cause":"The 'arweave' package is not installed as a dependency.","error":"Error: Cannot find module 'arweave'"},{"fix":"Change `import { TezosBundler } from 'tezos-bundler'` to `import TezosBundler from 'tezos-bundler'`.","cause":"Attempting to import `TezosBundler` as a named export when it is a default export.","error":"TypeError: TezosBundler is not a constructor"},{"fix":"Ensure your Arweave gateway or ArLocal instance is running and reachable. Check firewall rules and the `Arweave` client configuration (host, port, protocol).","cause":"The configured Arweave instance (e.g., ArLocal) is not running or is inaccessible at the specified host and port.","error":"UnhandledPromiseRejectionWarning: Error: connect ECONNREFUSED 127.0.0.1:1984"},{"fix":"Verify that your `my-arweave-keyfile.json` is a valid JSON file containing your Arweave JWK, and that the path to it is correct.","cause":"The `arweaveJWK` variable does not contain a valid JSON Web Key object, or the file path to the JWK is incorrect/corrupted.","error":"Failed to load arweave JWK: SyntaxError: Unexpected token 'o' in JSON at position 1"}],"ecosystem":"npm"}