EVM Address Generator

Generate deterministic EVM deposit addresses offline. Zero private key exposure.

Packages

Package	Description
@evm-address/sdk	Core SDK for address generation
@evm-address/cli	Command-line interface

Features

• Offline Generation: Generate addresses without RPC calls
• Zero Private Key Exposure: Works with public keys (xpub) or contract addresses only
• Two Strategies: BIP-44 HD derivation (EOA) or CREATE2 with EIP-1167 proxies
• Mathematically Verified: Foundry tests prove TypeScript matches on-chain logic

Quick Start

CLI

# Install globally
npm install -g @evm-address/cli

# Generate addresses using XPUB
export XPUB="xpub..."
evm-address 0-100

# Generate using factory mode
export FACTORY_ADDRESS="0x..."
export IMPLEMENTATION_ADDRESS="0x..."
evm-address 0-100 --mode factory

# Output as JSON
evm-address 0-10 --format json

SDK

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

// XPUB-based generation (EOA/EIP-7702/Permit)
const xpubGen = createXpubGenerator({ xpub: "xpub..." });
const address = xpubGen.generate(0);
const batch = xpubGen.generateBatch(parseRange("0-100"));

// Factory-based generation (CREATE2/EIP-1167)
const factoryGen = createFactoryGenerator({
  factory: "0x...",
  implementation: "0x...",
});
const addresses = factoryGen.generateBatch([0, 1, 2, 3, 4]);

Strategies

#	Method	Use Case
1	CREATE2 Factory	Counterfactual contract wallets with just-in-time deployment
2	EIP-7702 Delegation	Modern delegated EOA accounts
3	ERC-2612 Permit	Gasless sweeps with permit signatures
4	ERC-3009 Auth	USDC-style transferWithAuthorization

Smart Contracts

Located in src/:

• WalletFactory.sol: CREATE2 factory with EIP-1167 minimal proxies
• SweeperDelegate.sol: EIP-7702 delegation target
• PermitSweeper.sol: ERC-2612/ERC-3009 batch sweeper

Deployment

Prerequisites

1. Set your deployer private key:

export PRIVATE_KEY=0x...

2. Set your RPC URL:

export RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

Deploy All Contracts

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

Deploy Individual Contracts

# Strategy 1: WalletFactory only
forge script script/Deploy.s.sol:DeployFactory --broadcast --rpc-url $RPC_URL

# Strategy 2: EIP-7702 contracts
forge script script/Deploy.s.sol:DeployEIP7702 --broadcast --rpc-url $RPC_URL

# Strategy 3 & 4: PermitSweeper
forge script script/Deploy.s.sol:DeployPermitSweeper --broadcast --rpc-url $RPC_URL

Verify Contracts

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

Post-Deployment

After deployment, copy the output addresses to your .env:

FACTORY_ADDRESS=0x...
IMPLEMENTATION_ADDRESS=0x...

Development

Prerequisites

• Bun v1.0+
• Foundry

Setup

# Install dependencies
bun install
forge install

# Build
bun run build
forge build

# Test
bun run test
forge test -vvv

# Type check
bun run typecheck

Project Structure

├── packages/
│   ├── sdk/          # @evm-address/sdk
│   └── cli/          # @evm-address/cli
├── src/              # Smart contracts
│   ├── WalletFactory.sol
│   ├── SweeperDelegate.sol
│   └── PermitSweeper.sol
├── script/           # Deployment scripts
│   └── Deploy.s.sol
├── test/             # Foundry tests
└── lib/              # Solidity dependencies

Security

• This tool never requires private keys or xpriv
• Safe to run on public servers
• XPUB can link addresses - keep it private if needed

License

MIT