pcaversaccio / batch-distributor

Helper smart contract for batch sending both native and ERC-20 tokens.

Batch Distributor

Installation

It is recommended to install pnpm through the npm package manager, which comes bundled with Node.js when you install it on your system. It is recommended to use a Node.js version >= 20.0.0.

Once you have npm installed, you can run the following both to install and upgrade pnpm:

npm install -g pnpm

After having installed pnpm, simply run:

pnpm install

Unit Tests

You can run the unit tests with

pnpm test

Test Coverage

This repository implements a test coverage plugin. Simply run:

pnpm coverage

Implemented Functionalities

• ETH Batch Transaction: distributeEther(batch (tuple))
• ERC20 Batch Transaction: distributeToken(token (address), batch (tuple))

The parameter batch is a nested struct object that contains an array of tuples that contain each a recipient address & ETH/token amount. Please ensure that the amount for the ETH transactions is given in wei (1 wei = $10^{-18}$ ETH) and check the decimal digits for the ERC20 tokens.

{
  txns: [{ recipient: address, amount: amount }];
}

Caveats

1. Although the batch size is only theoretically limited to the size of uint256, sending too many transactions in a batch will cause the block gasLimit to be exceeded and therefore such a transaction will revert. A large number of transactions should be split into separate batches.
2. A low-level Solidity call will copy any amount of bytes to local memory. When bytes are copied from returndata to memory, the memory expansion cost is paid. This means that when using a standard Solidity call, the callee can "returnbomb" the caller, imposing an arbitrary gas cost. Because this gas is paid by the caller and in the caller's context, it can cause the caller to run out of gas and halt execution. It is possible to prevent this attack (see e.g. here), but this contract contains no measures against it. If you need this kind of security, please do not use this contract.

Test Deployments

The smart contract BatchDistributor.sol has been deployed to the following test networks:

• Goerli: 0xBFe76cA9bAbF3566A89e215782d97ADb87Fa55C6
• Sepolia: 0xBFe76cA9bAbF3566A89e215782d97ADb87Fa55C6

Examples

• Example 1: ETH distribution 0x88373d0c99927a70f81d474b444848dd83e04b0d7100a018152a38aa8fab0b8b
  • Input tuple data batch: [[["0x9F3f11d72d96910df008Cfe3aBA40F361D2EED03",1],["0x3854Ca47Abc62A3771fE06ab45622A42C4A438Cf",2]]]
• Example 2: ERC-20 token distribution 0x25bec5c3e0ae70acef4457ced251ab92c6414e2018a868fa4c6e5a1e44428395
  • Input token address: 0x11fE4B6AE13d2a6055C8D9cF65c55bac32B5d844
  • Input tuple data batch: [[["0x9F3f11d72d96910df008Cfe3aBA40F361D2EED03",50],["0x3854Ca47Abc62A3771fE06ab45622A42C4A438Cf",50]]]