@tetherto/wdk-worklet-bundler

CLI tool for generating optimized WDK worklet bundles. This tool packages specific blockchain modules (Wallets, Protocols) into a single artifact designed to run in a separate Bare runtime thread, isolated from your main React Native application loop.

This architecture ensures:

• Performance: Heavy cryptographic operations do not block the UI thread.
• Compatibility: Provides a Node.js-like environment (via bare-node-runtime) for standard crypto libraries.
• Isolation: Securely encapsulates wallet logic and private keys.

Installation

# Global installation
npm install -g @tetherto/wdk-worklet-bundler

# Or as a project dependency (recommended)
npm install --save-dev @tetherto/wdk-worklet-bundler

# Or run directly without installation
npx @tetherto/wdk-worklet-bundler

Quick Start

1. Initialize a configuration in your React Native project:

   wdk-worklet-bundler init

2. Configure your networks in wdk.config.js:

   module.exports = {
     networks: {
       ethereum: {
         package: '@tetherto/wdk-wallet-evm-erc-4337'
       },
       bitcoin: {
         package: '@tetherto/wdk-wallet-btc'
       }
     }
   };

3. Generate the bundle:

   # Automatically installs missing WDK modules to your dependencies
   wdk-worklet-bundler generate --install

4. Use it in your App:

   import { WdkAppProvider } from '@tetherto/pear-wrk-wdk';
   // Import the generated bundle asset (handled by metro/webpack as a static asset)
   const workletBundle = require('./.wdk-bundle/wdk-worklet.bundle.js');
   
   function App() {
     return (
       <WdkAppProvider bundle={{ bundle: workletBundle }}>
         {/* Your App Content */}
       </WdkAppProvider>
     );
   }

Architecture

The bundler orchestrates the creation of a standalone JavaScript environment ("Worklet") that communicates with your main application.

• Host (React Native App): Your UI layer. It loads the generated bundle and communicates with it via HRPC (Host-Remote Procedure Call).
• Guest (Worklet Bundle): A compact, optimized bundle containing your selected Wallet and Protocol modules. It runs inside the Bare runtime (a minimal Node.js-compatible runtime for mobile).
• Bundler (The Chef): This CLI tool. It resolves dependencies, generates the entry point code, and compiles everything using bare-pack.

We recommend installing all WDK modules and the core library as dependencies. The bundler compiles them into the separate worklet artifact, but having them in dependencies ensures proper resolution and type availability.

Commands

generate

Builds the worklet bundle.

wdk-worklet-bundler generate [options]

Options:

• -c, --config <path>: Path to config file.
• --install: Automatically install missing modules listed in your config (saves to devDependencies).
• --keep-artifacts: Keep the intermediate .wdk/ folder (useful for debugging generated source code). By default, this is cleaned up.
• --source-only: Generate the entry files but skip the final bare-pack bundling step.
• --skip-generation: Skip artifact generation and use existing files.
• --dry-run: Print what would happen without writing files.
• --no-types: Skip generating TypeScript definitions (index.d.ts).
• -v, --verbose: Show verbose output.

init

Creates a fresh wdk.config.js file.

wdk-worklet-bundler init [options]

Options:

• -y, --yes: Use defaults without prompting.

validate

Checks if your configuration is valid and if all required dependencies are installed.

wdk-worklet-bundler validate [options]

Options:

• -c, --config <path>: Path to config file.

list-modules

List available WDK modules.

wdk-worklet-bundler list-modules [options]

Options:

• --json: Output as JSON.

clean

Remove generated .wdk folder.

wdk-worklet-bundler clean [options]

Options:

• -y, --yes: Skip confirmation.

Configuration Reference (wdk.config.js)

module.exports = {
  // Map logical network names to WDK wallet packages
  networks: {
    ethereum: { 
      package: '@tetherto/wdk-wallet-evm-erc-4337' 
    },
    local_dev: {
      package: './local-packages/my-custom-wallet' // Local paths supported
    }
  },

  // Map logical protocol names to WDK protocol packages
  protocols: {
    aaveEvm: {
      package: '@tetherto/wdk-protocol-aave-lending-evm'
    }
  },

  // Native addons to preload (e.g. for specific crypto requirements)
  preloadModules: [
    'spark-frost-bare-addon'
  ],

  // Customize output locations
  output: {
    bundle: './.wdk-bundle/wdk-worklet.bundle.js',
    types: './.wdk/index.d.ts'
  },

  // Build options
  options: {
    minify: false, // Optional: Minify the bundle
    sourceMaps: false, // Optional: Generate source maps
    targets: ['ios-arm64', 'android-arm64'] // bare-pack targets
  }
};

Troubleshooting

"Module not found" during generation: Run wdk-worklet-bundler generate --install. This ensures all packages defined in your config (plus the core @tetherto/pear-wrk-wdk) are present in your node_modules.

"Missing dependency" inside the worklet: If you see runtime errors about missing modules inside the worklet, ensure pear-wrk-wdk is properly installed. The bundler treats it as an external dependency that must be present.

License

Apache-2.0