Contractor

A powerful CLI tool that converts Ethereum smart contract ABIs into Python code using Web3.py library with native Python string templating.

Features

• Single File Processing: Convert individual ABI JSON files to Web3.py contract wrappers
• Batch Processing: Process entire folders containing multiple ABI files
• Automatic Class Naming: Intelligently extracts class names from filenames (e.g., ERC20.json → ERC20)
• Type-Safe Code Generation: Generates fully typed Python code with proper type hints
• Comprehensive Error Handling: Robust error handling and logging throughout
• Web3.py Integration: Generated code works seamlessly with Web3.py

Installation

Using uv (recommended)

# Install from local directory
uv pip install .

# Or install in development mode
uv pip install -e .

Using pip

pip install .

Usage

Process a single ABI file

contractor --abi contract.json --output generated_contract.py --class-name MyContract

Process from ABI string

contractor --abi-string '{"abi": [...]}' --class-name MyContract --output contract.py

Process from URL

contractor --abi-url https://api.etherscan.io/api?module=contract&action=getabi&address=0x... --class-name MyContract

Process entire folder of ABI files

# Process all JSON files in ./abis folder, output to current directory
contractor --folder ./abis

# Process all JSON files in ./abis folder, output to specific directory
contractor --folder ./abis --output ./generated

Options

• --abi: Path to ABI JSON file
• --abi-string: ABI as JSON string
• --abi-url: URL to fetch ABI from (e.g., Etherscan API)
• --folder: Path to folder containing ABI JSON files
• --output: Output Python file path (default: generated_contract.py for single files, . for folders)
• --class-name: Generated class name (default: ContractWrapper, auto-generated from filename for folders)
• --verbose: Enable verbose logging

Generated Code Features

The generated Python code includes:

• Type-safe function calls with proper parameter and return types
• Automatic gas estimation for transactions
• Transaction receipt handling with status checking
• Event filtering and retrieval with flexible block ranges
• Comprehensive error handling and logging
• Factory functions for easy instantiation

Example Generated Usage

from web3 import Web3
from generated_contract import create_erc20

# Initialize Web3
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/your-key'))

# Create contract instance
contract = create_erc20(
    web3=w3,
    contract_address="0x...",
)

# Call view functions
balance = contract.balance_of("0x...")
total_supply = contract.total_supply()

# Send transactions
tx_hash = contract.transfer(
    to="0x...",
    amount=1000,
    tx_params={'from': '0x...'}
)

# Wait for confirmation
receipt = contract.wait_for_transaction_receipt(tx_hash)

Requirements

• Python 3.8+
• web3>=6.0.0
• eth_typing>=3.0.0

License

MIT License