Evm Address

EVM Address Generator

Overview

The evm-address toolkit allows for the offline, deterministic generation of EVM deposit addresses. It supports two primary modes:

1. XPUB (BIP-44): Generates EOA addresses using an extended public key. 2. Factory (CREATE2): Generates contract addresses for EIP-1167 minimal proxies.

Installation

SDK

npm install @evm-address/sdk

CLI

npm install -g @evm-address/cli

Quick Start (SDK)

import { createXpubGenerator } from "@evm-address/sdk";

const generator = createXpubGenerator({ xpub: "xpub..." });
const address = generator.generate(0);

Detailed Documentation

• [SDK Guide](references/sdk.md): Full API for programatic address generation.
• [CLI Guide](references/cli.md): Usage patterns for the command-line tool.
• [Smart Contract Deployment](references/deployment.md): How to deploy and verify the required contracts.
• [Contract Source Code](references/contracts.md): Solidity source code for Factory, Delegate, and Permit contracts.

Strategies Support

Security Note

This tool is designed for offline use and never requires your private keys. It only uses public information (XPUB or contract addresses) to derive deterministic deposit locations.

EVM Address Skills

This skill provides guidance and implementation patterns for generating deterministic EVM deposit addresses using the @evm-address toolkit. It covers both SDK integration and CLI usage.

Features

• Offline Generation: No RPC required for address derivation.
• Zero Private Key Exposure: Uses XPUB or CREATE2 constants.
• Dual Mode: Support for EOAs and Smart Contract Proxies.
• Batch Processing: Tools for generating thousands of addresses efficiently.

Installation

To add this skill to your project, run:

npx skills add melonask/evm-address-skills

Contents

• `SKILL.md`: Main guide with strategies and quick start.
• `references/sdk.md`: API reference for the TypeScript SDK.
• `references/cli.md`: Command-line interface documentation.
• `references/deployment.md`: Contract deployment guides.
• `references/contracts.md`: Solidity source code for contracts.

Usage

Trigger this skill by asking:

• "How do I generate addresses from an XPUB?"
• "Set up the WalletFactory for CREATE2 addresses."
• "Show me how to use the @evm-address/sdk in my project."
• "Generate a batch of 100 deposit addresses using the CLI."

EVM Address CLI Reference

Command-line tool to generate deterministic EVM deposit addresses.

Installation

npm install -g @evm-address/cli

Usage

evm-address <range> [options]

Environment Variables

• XPUB: For xpub mode (default).
• FACTORY_ADDRESS: For factory mode.
• IMPLEMENTATION_ADDRESS: For factory mode.

Examples

XPUB Mode

export XPUB="xpub..."
evm-address 0-10

Factory Mode

export FACTORY_ADDRESS="0x..."
export IMPLEMENTATION_ADDRESS="0x..."
evm-address 0-10 --mode factory

Formats

• --format csv (default)
• --format json
• --format plain

Complex Ranges

evm-address "0-5,100,500-505"

EVM Address Smart Contracts

Source code for the core smart contracts used in the evm-address system.

1. WalletFactory.sol

Implements Strategy 1 (CREATE2) with EIP-1167 minimal proxies.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";

error OnlyFactory();
error NothingToFlush();
error EthTransferFailed();

contract WalletImplementation {
  using SafeERC20 for IERC20;
  address public immutable FACTORY;

  constructor(address _factory) {
    FACTORY = _factory;
  }

  function flush(address token, address recipient) external {
    if (msg.sender != FACTORY) revert OnlyFactory();
    IERC20 tokenContract = IERC20(token);
    uint256 balance = tokenContract.balanceOf(address(this));
    if (balance != 0) tokenContract.safeTransfer(recipient, balance);
  }

  function flushEth(address payable destination) external {
    if (msg.sender != FACTORY) revert OnlyFactory();
    uint256 balance = address(this).balance;
    if (balance == 0) revert NothingToFlush();
    (bool success, ) = destination.call{value: balance}("");
    if (!success) revert EthTransferFailed();
  }

  receive() external payable {}
}

contract WalletFactory is Ownable {
  address public immutable IMPLEMENTATION;

  constructor() Ownable(msg.sender) {
    IMPLEMENTATION = address(new WalletImplementation(address(this)));
  }

  function predictAddress(bytes32 salt) external view returns (address) {
    return Clones.predictDeterministicAddress(IMPLEMENTATION, salt, address(this));
  }

  function batchSweep(bytes32[] calldata salts, address token, address recipient) external onlyOwner {
    address impl = IMPLEMENTATION;
    for (uint256 i; i < salts.length; ) {
      bytes32 salt = salts[i];
      address proxy = Clones.predictDeterministicAddress(impl, salt, address(this));
      if (proxy.code.length == 0) Clones.cloneDeterministic(impl, salt);
      WalletImplementation(payable(proxy)).flush(token, recipient);
      unchecked { ++i; }
    }
  }

  function batchSweepEth(bytes32[] calldata salts, address payable recipient) external onlyOwner {
    address impl = IMPLEMENTATION;
    for (uint256 i; i < salts.length; ) {
      bytes32 salt = salts[i];
      address proxy = Clones.predictDeterministicAddress(impl, salt, address(this));
      if (proxy.code.length == 0) Clones.cloneDeterministic(impl, salt);
      WalletImplementation(payable(proxy)).flushEth(recipient);
      unchecked { ++i; }
    }
  }
}

2. SweeperDelegate.sol

Implements Strategy 2 (EIP-7702) for delegation.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

error EthTransferFailed();

contract SweeperDelegate {
  using SafeERC20 for IERC20;

  function executeSweep(address token, address recipient) external {
    IERC20 tokenContract = IERC20(token);
    uint256 balance = tokenContract.balanceOf(address(this));
    if (balance != 0) tokenContract.safeTransfer(recipient, balance);
  }

  function executeSweepEth(address payable recipient) external {
    uint256 balance = address(this).balance;
    if (balance != 0) {
      (bool success, ) = recipient.call{value: balance}("");
      if (!success) revert EthTransferFailed();
    }
  }

  receive() external payable {}
}

contract BatchInvoker is Ownable {
  constructor() Ownable(msg.sender) {}

  function batchCall7702(address[] calldata users, address token, address recipient) external onlyOwner {
    for (uint256 i; i < users.length; ) {
      SweeperDelegate(payable(users[i])).executeSweep(token, recipient);
      unchecked { ++i; }
    }
  }

  function batchCall7702Eth(address[] calldata users, address payable recipient) external onlyOwner {
    for (uint256 i; i < users.length; ) {
      SweeperDelegate(payable(users[i])).executeSweepEth(recipient);
      unchecked { ++i; }
    }
  }
}

3. PermitSweeper.sol

Implements Strategy 3 (Permit) & 4 (Auth) for gasless sweeping.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

interface IERC20Permit {
  function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external;
}
interface IERC3009 {
  function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, uint8 v, bytes32 r, bytes32 s) external;
}

contract PermitSweeper is Ownable {
  using SafeERC20 for IERC20;
  constructor() Ownable(msg.sender) {}

  struct PermitBatch {
    address token;
    address owner;
    uint256 amount;
    uint256 deadline;
    uint8 v;
    bytes32 r;
    bytes32 s;
  }
  struct AuthBatch {
    address token;
    address from;
    address to;
    uint256 value;
    uint256 validAfter;
    uint256 validBefore;
    bytes32 nonce;
    uint8 v;
    bytes32 r;
    bytes32 s;
  }

  function executeBatchPermitSweep(PermitBatch[] calldata batches, address recipient) external onlyOwner {
    for (uint256 i; i < batches.length; ) {
      PermitBatch calldata b = batches[i];
      IERC20Permit(b.token).permit(b.owner, address(this), b.amount, b.deadline, b.v, b.r, b.s);
      IERC20(b.token).safeTransferFrom(b.owner, recipient, b.amount);
      unchecked { ++i; }
    }
  }

  function executeBatchAuthSweep(AuthBatch[] calldata batches) external onlyOwner {
    for (uint256 i; i < batches.length; ) {
      AuthBatch calldata b = batches[i];
      IERC3009(b.token).transferWithAuthorization(b.from, b.to, b.value, b.validAfter, b.validBefore, b.nonce, b.v, b.r, b.s);
      unchecked { ++i; }
    }
  }
}

Smart Contract Deployment Reference

The EVM Address system uses several smart contracts to enable deterministic sweeping.

Deployment with Foundry (Forge)

1. Set Environment

export PRIVATE_KEY=0x...
export RPC_URL=https://...

2. Deploy All

forge script script/Deploy.s.sol:DeployAll --broadcast --rpc-url $RPC_URL

3. Deploy Individual Strategies

• Strategy 1 (Factory): DeployFactory
• Strategy 2 (EIP-7702): DeployEIP7702
• Strategy 3 & 4 (Permit): DeployPermitSweeper

Deployed Addresses

After deployment, configure your tools with:

• FACTORY_ADDRESS: The WalletFactory.
• IMPLEMENTATION_ADDRESS: The logic contract for proxies.

Verification

forge verify-contract <ADDRESS> WalletFactory --chain-id 1

EVM Address SDK Reference

The @evm-address/sdk provides core logic for deterministic address generation.

1. XPUB-based Generation (BIP-44)

Used for generating EOA (Externally Owned Account) addresses from an extended public key.

import { createXpubGenerator, parseRange } from "@evm-address/sdk";

const generator = createXpubGenerator({
  xpub: "xpub...", // Account-level xpub (m/44'/60'/0'/0)
});

// Generate single
const address = generator.generate(0);

// Generate batch
const addresses = generator.generateBatch(parseRange("0-10,50,100-105"));

2. Factory-based Generation (CREATE2)

Used for counterfactual contract wallet addresses (EIP-1167 proxies).

import { createFactoryGenerator } from "@evm-address/sdk";

const generator = createFactoryGenerator({
  factory: "0x...", // WalletFactory address
  implementation: "0x...", // Implementation address
});

// Generate deterministic proxy address
const address = generator.generate(42);

// Generate batch
const addresses = generator.generateBatch([0, 1, 2, 3, 4]);

3. Utilities

• parseRange(input: string): Parses strings like "0-5,10" into [0,1,2,3,4,5,10].
• indexToSalt(index: number): Converts index to 32-byte hex salt.
• computeCreationCode(implementation: Address): Computes EIP-1167 minimal proxy creation code.

4. Types

interface GeneratedAddress {
  index: number;
  address: Address;
}

interface AddressGenerator {
  generate(index: number): Address;
  generateBatch(indices: number[]): GeneratedAddress[];
}