Batch Transactions

Execute multiple operations in a single transaction to reduce costs and improve efficiency.

Overview

Batch transactions combine multiple operations into one on-chain transaction. This amortizes fixed costs (base fee, nonce management) across all operations, reducing total gas consumption by 40-60% compared to individual transactions.

Benefits

Cost reduction: Single base fee instead of N separate fees Atomic execution: All operations succeed or all fail together Nonce efficiency: One nonce for multiple operations Faster confirmation: One transaction to track instead of N Simpler state management: Single confirmation event

Basic batching

Multiple transfers

Send tokens to multiple recipients in one transaction:

const batch = await client.executeBatch([
  { instruction: "Transfer 10 USDC to 0xaaaa..." },
  { instruction: "Transfer 15 USDC to 0xbbbb..." },
  { instruction: "Transfer 20 USDC to 0xcccc..." }
])

console.log(`Batch transaction: ${batch.txHash}`)
console.log(`Total gas: ${batch.gasEstimate}`)
console.log(`Operations: ${batch.operations.length}`)

Cost comparison:

Method	Base Fee	Gas per Transfer	Total Gas	USD Cost
Individual (3x)	3 × 45 gwei	3 × 21,000	135 gwei	$9.45
Batch (1x)	1 × 45 gwei	60,000	105 gwei	$7.35

Savings: $2.10 (22% reduction)

Structured batch

Use structured format for precise control:

const batch = await client.executeBatch([
  {
    action: "transfer",
    asset: "USDC",
    amount: "10",
    recipient: "0xaaaa..."
  },
  {
    action: "transfer",
    asset: "USDC",
    amount: "15",
    recipient: "0xbbbb..."
  },
  {
    action: "transfer",
    asset: "USDC",
    amount: "20",
    recipient: "0xcccc..."
  }
], {
  urgency: "fast",
  simulate: true
})

Advanced batching

Mixed operations

Combine different transaction types:

const batch = await client.executeBatch([
  // Approve token spending
  {
    action: "approve",
    asset: "USDC",
    spender: "0x1234...",  // Uniswap router
    amount: "1000"
  },
  // Swap tokens
  {
    action: "swap",
    inputAsset: "USDC",
    inputAmount: "1000",
    outputAsset: "WETH",
    minOutputAmount: "0.28"
  },
  // Transfer result to vault
  {
    action: "transfer",
    asset: "WETH",
    amount: "0.28",
    recipient: "0x5678..."  // Vault address
  }
])

Conditional batching

Execute operations based on conditions:

// Check balance first
const balance = await client.getBalance('USDC')

if (parseFloat(balance.formatted) >= 1000) {
  // Execute batch only if sufficient balance
  const batch = await client.executeBatch([
    { instruction: "Swap 500 USDC for WETH" },
    { instruction: "Swap 500 USDC for DAI" }
  ])
}

Dependent operations

Chain operations where later steps depend on earlier results:

const batch = await client.executeBatch([
  // Step 1: Borrow flash loan
  {
    action: "flashloan",
    protocol: "aave",
    asset: "USDC",
    amount: "100000"
  },
  // Step 2: Swap on DEX A
  {
    action: "swap",
    protocol: "uniswap",
    inputAsset: "USDC",
    inputAmount: "100000",
    outputAsset: "WETH"
  },
  // Step 3: Swap on DEX B
  {
    action: "swap",
    protocol: "sushiswap",
    inputAsset: "WETH",
    inputAmount: "${step2.output}",  // Use output from step 2
    outputAsset: "USDC"
  },
  // Step 4: Repay flash loan
  {
    action: "repay",
    protocol: "aave",
    asset: "USDC",
    amount: "100000"
  }
])

Batch strategies

Airdrop distribution

Distribute tokens to thousands of addresses:

import { readFileSync } from 'fs'

// Load recipients from CSV
const recipients = readFileSync('airdrop.csv', 'utf-8')
  .split('\n')
  .map(line => {
    const [address, amount] = line.split(',')
    return { address, amount }
  })

// Batch in chunks of 100 (gas limit considerations)
const chunkSize = 100
for (let i = 0; i < recipients.length; i += chunkSize) {
  const chunk = recipients.slice(i, i + chunkSize)

  const batch = await client.executeBatch(
    chunk.map(r => ({
      action: "transfer",
      asset: "TOKEN",
      amount: r.amount,
      recipient: r.address
    })),
    {
      urgency: "economy",  // Non-urgent, save costs
      simulate: true
    }
  )

  console.log(`Batch ${i / chunkSize + 1}: ${batch.txHash}`)
}

Cost analysis:

• 1000 recipients

• Individual transactions: ~$3 × 1000 = $3,000

• Batched (10 batches of 100): ~$150 × 10 = $1,500

• Savings: $1,500 (50%)

Recurring payments

Process monthly salaries or subscriptions:

const payments = [
  { recipient: "0xaaaa...", amount: "5000", memo: "Salary - Alice" },
  { recipient: "0xbbbb...", amount: "4500", memo: "Salary - Bob" },
  { recipient: "0xcccc...", amount: "6000", memo: "Salary - Carol" },
  // ... 50 more employees
]

const batch = await client.executeBatch(
  payments.map(p => ({
    action: "transfer",
    asset: "USDC",
    amount: p.amount,
    recipient: p.recipient,
    metadata: { memo: p.memo }
  })),
  {
    urgency: "standard",
    simulate: true,
    policies: "require_approval"  // Human approval for payroll
  }
)

console.log(`Payroll batch: ${batch.txHash}`)
console.log(`Total paid: $${payments.reduce((sum, p) => sum + parseFloat(p.amount), 0)}`)

Portfolio rebalancing

Rebalance multiple assets atomically:

// Target allocation: 60% stablecoins, 30% ETH, 10% governance tokens
const batch = await client.executeBatch([
  // Sell excess ETH
  {
    action: "swap",
    inputAsset: "WETH",
    inputAmount: "5",
    outputAsset: "USDC"
  },
  // Buy governance tokens
  {
    action: "swap",
    inputAsset: "USDC",
    inputAmount: "2000",
    outputAsset: "UNI"
  },
  // Split stablecoins
  {
    action: "swap",
    inputAsset: "USDC",
    inputAmount: "5000",
    outputAsset: "DAI"
  }
], {
  urgency: "fast",
  simulate: true,
  atomicity: "required"  // All-or-nothing execution
})

Gas optimization

Calldata compression

Molt402 automatically compresses calldata for batch transactions:

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  batchOptimization: {
    compressCalldata: true,  // Enable compression
    method: "zlib"  // or "lz4", "brotli"
  }
})

const batch = await client.executeBatch([
  /* many operations */
])

// Compression saves ~2000 gas per operation

Operation reordering

Optimize execution order for gas efficiency:

const batch = await client.executeBatch([
  { instruction: "Approve USDC for Uniswap" },
  { instruction: "Swap 100 USDC for WETH" },
  { instruction: "Approve WETH for SushiSwap" },
  { instruction: "Swap 0.05 WETH for DAI" }
], {
  optimizeOrder: true  // Reorder for minimal gas
})

// Molt402 reorders to minimize storage writes

Redundant operation elimination

Remove duplicate approvals automatically:

const batch = await client.executeBatch([
  { instruction: "Approve USDC for Uniswap" },
  { instruction: "Swap 50 USDC for WETH" },
  { instruction: "Approve USDC for Uniswap" },  // Duplicate
  { instruction: "Swap 50 USDC for DAI" }
], {
  eliminateDuplicates: true
})

// Second approval eliminated, saves ~45,000 gas

Error handling

Partial failure handling

By default, batch transactions are atomic (all succeed or all fail):

const batch = await client.executeBatch([
  { instruction: "Transfer 10 USDC to Alice" },
  { instruction: "Transfer 999999 USDC to Bob" },  // Will fail
  { instruction: "Transfer 10 USDC to Carol" }
], {
  atomicity: "required"  // Default: all-or-nothing
})

// Entire batch fails if any operation fails

Allow partial execution:

const batch = await client.executeBatch([
  { instruction: "Transfer 10 USDC to Alice" },
  { instruction: "Transfer 999999 USDC to Bob" },
  { instruction: "Transfer 10 USDC to Carol" }
], {
  atomicity: "optional",  // Continue on failures
  failureStrategy: "skip"  // or "revert", "retry"
})

// Results show which operations succeeded
console.log(batch.results)
/*
[
  { index: 0, success: true, txHash: "0xaaa..." },
  { index: 1, success: false, error: "Insufficient balance" },
  { index: 2, success: true, txHash: "0xccc..." }
]
*/

Retry failed operations

Automatically retry failed operations:

const batch = await client.executeBatch([
  /* operations */
], {
  retry: {
    enabled: true,
    maxAttempts: 3,
    failedOnly: true,  // Only retry failed operations
    backoff: "exponential"
  }
})

Monitoring and tracking

Batch status

Track batch execution progress:

const batch = await client.executeBatch([
  /* 100 operations */
])

// Monitor progress
const status = await client.getBatchStatus(batch.batchId)

console.log(`Total operations: ${status.total}`)
console.log(`Completed: ${status.completed}`)
console.log(`Failed: ${status.failed}`)
console.log(`Pending: ${status.pending}`)

Individual operation tracking

Track each operation within batch:

const batch = await client.executeBatch([
  { instruction: "Operation 1" },
  { instruction: "Operation 2" },
  { instruction: "Operation 3" }
])

// Get detailed results
for (const result of batch.results) {
  console.log(`Operation ${result.index}: ${result.success ? 'Success' : 'Failed'}`)
  if (result.success) {
    console.log(`  Gas used: ${result.gasUsed}`)
  } else {
    console.log(`  Error: ${result.error}`)
  }
}

Size limits

Transaction size constraints

Each batch has gas and size limits:

Block gas limit: ~30M gas per block Transaction size: ~128KB calldata limit Practical limits:

• Simple transfers: ~1000 per batch

• Complex operations: ~50-100 per batch

Automatic chunking

Molt402 automatically splits large batches:

const operations = [] // 5000 operations

// Automatically chunks into multiple transactions
const batches = await client.executeBatch(operations, {
  autoChunk: true,
  maxGasPerBatch: "10000000",  // 10M gas max per batch
  maxOperationsPerBatch: 500
})

console.log(`Split into ${batches.length} batches`)

Testing batches

Simulation

Simulate entire batch before submission:

const simulation = await client.simulateBatch([
  { instruction: "Transfer 10 USDC to Alice" },
  { instruction: "Transfer 15 USDC to Bob" },
  { instruction: "Transfer 20 USDC to Carol" }
])

console.log(`Batch will succeed: ${simulation.success}`)
console.log(`Total gas: ${simulation.totalGas}`)
console.log(`Individual results:`)
simulation.operations.forEach((op, i) => {
  console.log(`  ${i}: ${op.success ? 'OK' : 'FAIL'} (${op.gasUsed} gas)`)
})

Dry run

Test batch without spending gas:

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: walletConfig,
  dryRun: true  // Simulate all transactions
})

const batch = await client.executeBatch([
  /* operations */
])

// Returns simulation results, no actual submission
console.log(batch.simulationResult)

Best practices

Batch similar operations: Group transfers together, swaps together, etc.

Set reasonable chunk sizes: 100-500 operations per batch depending on complexity

Always simulate: Enable simulation for batch transactions

Monitor gas costs: Track cumulative gas for cost analysis

Use atomicity appropriately: Atomic for critical operations, optional for best-effort

Handle failures gracefully: Implement retry logic for failed batches

Test thoroughly: Validate batches on testnet before mainnet

Set timeouts: Configure reasonable deadlines for batch execution

Example: Complete treasury distribution

import { Molt402Client } from '@molt402/sdk'
import { readFileSync } from 'fs'

async function distributeTokens() {
  const client = new Molt402Client({
    network: 'x402-mainnet',
    wallet: walletConfig
  })

  // Load recipients
  const recipients = JSON.parse(readFileSync('distribution.json', 'utf-8'))

  // Validate total amount
  const total = recipients.reduce((sum, r) => sum + parseFloat(r.amount), 0)
  const balance = await client.getBalance('TOKEN')

  if (parseFloat(balance.formatted) < total) {
    throw new Error(`Insufficient balance: need ${total}, have ${balance.formatted}`)
  }

  // Execute in chunks
  const chunkSize = 100
  const batches = []

  for (let i = 0; i < recipients.length; i += chunkSize) {
    const chunk = recipients.slice(i, i + chunkSize)

    console.log(`Processing batch ${i / chunkSize + 1}...`)

    const batch = await client.executeBatch(
      chunk.map(r => ({
        action: "transfer",
        asset: "TOKEN",
        amount: r.amount,
        recipient: r.address
      })),
      {
        urgency: "standard",
        simulate: true,
        atomicity: "required"
      }
    )

    console.log(`  Transaction: ${batch.txHash}`)
    console.log(`  Gas used: ${batch.gasUsed}`)

    batches.push(batch)

    // Wait for confirmation before next batch
    await client.waitForConfirmation(batch.txHash, {
      confirmations: 3
    })
  }

  console.log(`\nDistribution complete!`)
  console.log(`Total batches: ${batches.length}`)
  console.log(`Total recipients: ${recipients.length}`)
  console.log(`Total distributed: ${total} TOKEN`)
}

distributeTokens().catch(console.error)

Next steps

• Gas optimization: Reduce batch transaction costs

• Transaction simulation: Validate batches before submission

• Error handling: Handle batch failures

• Monitoring and alerts: Track batch execution

Support

Questions about batch transactions?

• Discord: discord.gg/molt402 (#batch-transactions channel)

• Examples: github.com/molt402-dev/examples/batch

• Email: [email protected]