🚀 TransactionKit

The framework-agnostic Etherspot Transaction Kit that makes blockchain transactions feel like a walk in the park! 🌳

Ever felt like blockchain transactions were more complex than explaining quantum physics to a cat? Well, fret no more! TransactionKit is here to turn your transaction woes into smooth sailing. Choose between Etherspot's Modular SDK for traditional smart accounts or cutting-edge EIP-7702 delegated EOAs - this library brings you a delightful, method-chained API that makes sending transactions as easy as ordering coffee. ☕

✨ What Makes TransactionKit Special?

• 🔗 Method Chainable: Fluent API that reads like poetry
• 🌳 Tree Shakeable: Only bundle what you actually use - your users will thank you
• 🎯 Framework Agnostic: Works with React, Vue, vanilla JS, or whatever floats your boat
• ⚡ TypeScript First: Full type safety with beautiful IntelliSense
• 🛡️ Error Handling: Graceful error handling that won't make you pull your hair out
• 📦 Batch Support: Send multiple transactions in one go - efficiency is key!
• 🔧 Debug Mode: When things go sideways, we've got your back with detailed logging
• 🔐 EIP-7702 Support: Native support for delegated EOA (Externally Owned Account) functionality
• 🏗️ Multiple Wallet Modes: Choose between modular smart accounts or delegated EOA accounts (EIP-7702)
• 🌐 Multi-Chain: Enhanced batch operations with intelligent chain-based grouping
• ⚙️ Flexible Bundler Configuration: Custom bundler URLs with flexible API key formats

🎯 Target Environments

TransactionKit is designed to work across the entire JavaScript ecosystem:

• 🌐 Browsers: Modern browsers with Web3 wallet support
• 📱 React Native: Mobile apps that need blockchain functionality
• 🖥️ Node.js: Server-side transaction processing
• ⚛️ React: Web applications (with our React hooks coming soon!)
• 🎨 Vue: Vue.js applications
• 🔄 Angular: Angular applications
• 🛠️ Vanilla JS: When you want to keep it simple

📦 Installation

# Using npm
npm install @etherspot/transaction-kit

# Using yarn
yarn add @etherspot/transaction-kit

# Using pnpm (because we're modern like that)
pnpm add @etherspot/transaction-kit

🚀 Quick Start

Quick Start with Modular Mode

Basic Transaction Sending

Here's how to send a simple transaction with the modular smart account - it's easier than making toast! 🍞

import { TransactionKit } from '@etherspot/transaction-kit';
import { createWalletClient, custom } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { polygon } from 'viem/chains';

// Set up your wallet provider (this is just an example)
const account = privateKeyToAccount('0x...your-private-key...');
const client = createWalletClient({
  account,
  chain: polygon,
  transport: custom(window.ethereum!),
});

// Initialize TransactionKit
const kit = TransactionKit({
  provider: client,
  chainId: 137, // Polygon mainnet
  bundlerApiKey: 'your-bundler-api-key', // Optional but recommended
  walletMode: 'modular', // Optional: this is the default
});

// Send a transaction - it's that simple!
const sendTransaction = async () => {
  try {
    // Create and name your transaction
    const transaction = kit
      .transaction({
        to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6', // Recipient address
        value: '1000000000000000000', // 1 ETH in wei
        chainId: 137, // Polygon
      })
      .name({ transactionName: 'my-first-tx' });

    // Estimate the transaction cost
    const estimate = await transaction.estimate();
    console.log('Transaction cost:', estimate.cost);

    // Send the transaction
    const result = await transaction.send();

    if (result.isSentSuccessfully) {
      console.log('🎉 Transaction sent successfully!');
      console.log('Transaction hash:', result.userOpHash);
    } else {
      console.log('❌ Transaction failed:', result.errorMessage);
    }
  } catch (error) {
    console.error('Something went wrong:', error);
  }
};

Quick Start with Delegated EOA Mode (EIP-7702)

For users who want to use EIP-7702 delegated EOAs:

import { TransactionKit } from '@etherspot/transaction-kit';

// Initialize TransactionKit
const kit = TransactionKit({
  chainId: 137, // Polygon mainnet
  privateKey: '0x...your-private-key...', // Required for EIP-7702 (either privateKey or viemLocalAccount)
  bundlerApiKey: 'your-bundler-api-key', // Optional but recommended
  walletMode: 'delegatedEoa', // Required for EIP-7702
});

// Send a transaction with delegated EOA
const sendDelegatedTransaction = async () => {
  try {
    // Check if EOA is delegated
    const isDelegated = await kit.isDelegateSmartAccountToEoa(137);

    if (!isDelegated) {
      // Delegate EOA to smart account first
      await kit.delegateSmartAccountToEoa({
        chainId: 137,
        delegateImmediately: true,
      });
    }

    // Create and send transaction
    const transaction = kit
      .transaction({
        to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
        value: '1000000000000000000', // 1 ETH
        chainId: 137,
      })
      .name({ transactionName: 'delegated-tx' });

    const result = await transaction.send();

    if (result.isSentSuccessfully) {
      console.log('🎉 Delegated EOA transaction sent!');
    }
  } catch (error) {
    console.error('Transaction failed:', error);
  }
};

Batch Transactions in Modular and Delegated EOA modes

Want to send multiple transactions at once? We've got you covered! 🎯

// Create multiple transactions and add them to a batch
const sendBatchTransactions = async () => {
  try {
    // First transaction
    kit
      .transaction({
        to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
        value: '500000000000000000', // 0.5 ETH
        chainId: 137, // Optional but recommended for batched transaction
      })
      .name({ transactionName: 'tx1' })
      .addToBatch({ batchName: 'my-batch' });

    // Second transaction
    kit
      .transaction({
        to: '0x1234567890123456789012345678901234567890',
        value: '300000000000000000', // 0.3 ETH
        chainId: 137, // Optional but recommended for batched transaction
      })
      .name({ transactionName: 'tx2' })
      .addToBatch({ batchName: 'my-batch' });

    // Send the entire batch
    const result = await kit.sendBatches();

    if (result.isSentSuccessfully) {
      console.log('🎉 Batch sent successfully!');
      Object.entries(result.batches).forEach(([batchName, batchResult]) => {
        console.log(`Batch "${batchName}":`, batchResult.userOpHash);
      });
    }
  } catch (error) {
    console.error('Batch failed:', error);
  }
};

Advanced Usage in Modular and Delegated EOA modes

// Update existing transactions
const updateTransaction = () => {
  const namedTx = kit.name({ transactionName: 'my-tx' });

  // Update the transaction details
  namedTx
    .transaction({
      to: '0xNewAddress123456789012345678901234567890',
      value: '2000000000000000000', // 2 ETH
      chainId: 137, // Optional
    })
    .update();
};

// Remove transactions or batches
const cleanup = () => {
  // Remove a specific transaction
  kit.name({ transactionName: 'my-tx' }).remove();

  // Remove an entire batch
  kit.batch({ batchName: 'my-batch' }).remove();
};

// Get wallet address
const getWalletAddress = async () => {
  const address = await kit.getWalletAddress(137); // Polygon
  console.log('Your wallet address:', address);
};

// Enable debug mode for troubleshooting
kit.setDebugMode(true);

EIP-7702 Delegated EOA Examples

For EIP-7702 specific functionalities:

// Initialize with delegated EOA mode
const kit = TransactionKit({
  chainId: 137, // Polygon
  privateKey: '0x...your-private-key...', // Required for EIP-7702 (either privateKey or viemLocalAccount)
  bundlerApiKey: 'your-bundler-api-key',
  walletMode: 'delegatedEoa',
});

// Check if EOA is delegated to a smart account
const isDelegated = await kit.isDelegateSmartAccountToEoa(137);
console.log('Is EOA delegated:', isDelegated);

// Delegate EOA to smart account (if not already delegated)
if (!isDelegated) {
  const delegationResult = await kit.delegateSmartAccountToEoa({
    chainId: 137,
    delegateImmediately: true, // Set to false to get the authorization object and not execute
  });

  console.log('Delegation result:', delegationResult);
  console.log('EOA Address:', delegationResult.eoaAddress);
  console.log('Delegate Address:', delegationResult.delegateAddress);
  console.log('Already installed:', delegationResult.isAlreadyInstalled);
}

// Send transactions using delegated EOA
const sendWithDelegatedEoa = async () => {
  const transaction = kit
    .transaction({
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
      value: '1000000000000000000', // 1 ETH
      chainId: 137,
    })
    .name({ transactionName: 'delegated-tx' });

  const result = await transaction.send();

  if (result.isSentSuccessfully) {
    console.log('🎉 Delegated EOA transaction sent!');
    console.log('UserOp Hash:', result.userOpHash);
  }
};

// Remove delegation (if needed)
const removeDelegation = async () => {
  const undelegationResult = await kit.undelegateSmartAccountToEoa({
    chainId: 137,
    delegateImmediately: true, // Set to false to get the authorization object and not execute
  });

  console.log('Undelegation result:', undelegationResult);
};

Using the authorization parameter (delegatedEoa mode)

You can perform EOA delegation and a transaction atomically by passing a freshly signed authorization to estimate(), send(), estimateBatches(), or sendBatches().

Single Transaction Example

// 1) Get a signed authorization without executing the installation
const { authorization } = await kit.delegateSmartAccountToEoa({
  chainId: 137,
  delegateImmediately: false,
});

if (!authorization) {
  // Already delegated, proceed without the authorization parameter
}

// 2) Create and name a transaction on the SAME chain as authorization.chainId
kit
  .transaction({
    to: '0x000000000000000000000000000000000000dEaD',
    value: '100000000000000',
    chainId: authorization?.chainId ?? 137,
  })
  .name({ transactionName: 'txWithAuth' });

// 3) Estimate or send by passing the authorization (delegation will be executed within the UserOp)
const named = kit.name({ transactionName: 'txWithAuth' });
const estimate = await named.estimate({ authorization });
const result = await named.send({ authorization });

Batch Example

// 1) Get a signed authorization without executing the installation
const { authorization } = await kit.delegateSmartAccountToEoa({
  chainId: 137,
  delegateImmediately: false,
});

if (!authorization) {
  // Already delegated, proceed without the authorization parameter
}

// 2) Create transactions on the SAME chain as authorization.chainId
kit
  .transaction({
    to: '0x000000000000000000000000000000000000dEaD',
    value: '100000000000000',
    chainId: authorization?.chainId ?? 137,
  })
  .name({ transactionName: 'batch-tx1' })
  .addToBatch({ batchName: 'auth-batch' });

kit
  .transaction({
    to: '0x000000000000000000000000000000000000beef',
    value: '200000000000000',
    chainId: authorization?.chainId ?? 137,
  })
  .name({ transactionName: 'batch-tx2' })
  .addToBatch({ batchName: 'auth-batch' });

// 3) Estimate or send batches by passing the authorization (delegation will be executed within the UserOp)
const estimate = await kit.estimateBatches({ authorization });
const result = await kit.sendBatches({ authorization });

Notes:

• The authorization must match the transaction chainId and Kernel v3.3 implementation.
• For multi-chain batches, the authorization will only be applied to chain groups matching the authorization's chainId.
• authorization is only supported in delegatedEoa mode; using it in modular mode will cause validation errors.
• If the EOA is already delegated, authorization is not required.

Multi-Chain Batch Operations

Enhanced batch operations with chain-based grouping:

// Create transactions across multiple chains
const multiChainBatches = async () => {
  // Ethereum transaction
  kit
    .transaction({
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
      value: '1000000000000000000', // 1 ETH
      chainId: 1, // Ethereum
    })
    .name({ transactionName: 'eth-tx' })
    .addToBatch({ batchName: 'multi-chain-batch' });

  // Polygon transaction
  kit
    .transaction({
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6',
      value: '500000000000000000', // 0.5 ETH
      chainId: 137, // Polygon
    })
    .name({ transactionName: 'poly-tx' })
    .addToBatch({ batchName: 'multi-chain-batch' });

  // Estimate costs across all chains
  const estimates = await kit.estimateBatches();
  console.log('Multi-chain estimates:', estimates);

  // Send batches (automatically grouped by chain)
  const result = await kit.sendBatches();

  if (result.isSentSuccessfully) {
    console.log('🎉 Multi-chain batch sent successfully!');
    Object.entries(result.batches).forEach(([batchName, batchResult]) => {
      console.log(`Batch "${batchName}":`, batchResult.userOpHash);
    });
  }
};

🔧 Configuration Options

TransactionKit supports two wallet modes to suit different use cases:

Modular Mode (Default)

Smart account functionality with Etherspot's Modular SDK:

```typescript const kit = TransactionKit({ provider: yourWalletProvider, // Required: Your wallet provider chainId: 137, // Required: Default chain ID bundlerApiKey: 'your-api-key', // Optional: For better performance bundlerUrl: 'https://your-bundler-url.com', // Optional: Custom bundler URL bundlerApiKeyFormat: '?api-key=', // Optional: API key format (default: '?api-key=') debugMode: false, //