Tezos Bundler Node

Common errors

• Error: Cannot find module 'arweave'

  cause The 'arweave' package is not installed as a dependency.
  fix Run `npm install arweave` or `yarn add arweave` in your project directory.

• TypeError: TezosBundler is not a constructor

  cause Attempting to import `TezosBundler` as a named export when it is a default export.
  fix Change `import { TezosBundler } from 'tezos-bundler'` to `import TezosBundler from 'tezos-bundler'`.

• UnhandledPromiseRejectionWarning: Error: connect ECONNREFUSED 127.0.0.1:1984

  cause The configured Arweave instance (e.g., ArLocal) is not running or is inaccessible at the specified host and port.
  fix Ensure 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

  cause The `arweaveJWK` variable does not contain a valid JSON Web Key object, or the file path to the JWK is incorrect/corrupted.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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).
  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.
• gotcha Incorrect configuration of the `Arweave` client (host, port, protocol) can prevent `tezos-bundler` from connecting to the Arweave network, leading to failed bundle submissions.
  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.

Install

• npm install tezos-bundler npm
• yarn add tezos-bundler yarn
• pnpm add tezos-bundler pnpm

Imports

• TezosBundler
  wrong:

  import { TezosBundler } from 'tezos-bundler'

  correct:

  import TezosBundler from 'tezos-bundler'

  TezosBundler is a default export of the package.
• Arweave
  wrong:

  const Arweave = require('arweave')

  correct:

  import Arweave from '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
  wrong:

  export default tezosBundler.app.callback

  correct:

  const callback = tezosBundler.app.callback()

  The `callback` method must be invoked to return the actual middleware function, not just referenced.

Quickstart

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();