GEN0X

GEN0X — Contract Address Generator

A smart-contract address generator that analyses an existing on-chain contract, derives a new deterministic address using the EVM CREATE2 opcode, and optionally deploys a same-structure clone through the MotherContract (the index-0 factory / “mother” deployer).

Creator / Owner: kushmanmb

What It Does

Step	Description
1	Accept a source contract address as input
2	Fetch and analyse the contract’s deployed bytecode via eth_getCode
3	Compute a new deterministic CREATE2 address: keccak256(0xff ++ motherAddress ++ salt ++ keccak256(bytecode))[12:]
4	Optionally deploy through the MotherContract factory, recording the new child address on-chain

This enables complete remap-facing — you keep the original contract logic while obtaining a fresh, fully controllable on-chain address. The MotherContract acts as the “mother” (index 0) of all deployments, giving you centralised oversight and control.

---

Architecture

MotherContract (mother / index 0)
│
├─ deploy(bytecode, salt) ──► CREATE2 ──► child contract @ deterministic address  [owner only]
└─ computeAddress(bytecode, salt) ──► view (no gas, no state change)

MotherContract.sol

A minimal Solidity factory that exposes:

• CREATOR — public constant returning "kushmanmb", the on-chain creator / ownership badge for verification.
• owner — the current owner / manager of the mother contract (set to the deployer; transferable via transferOwnership).
• deploy(bytes memory bytecode, bytes32 salt) → address — deploys bytecode to a new address derived from salt. Restricted to the owner. Reverts if salt has been used before.
• transferOwnership(address newOwner) — transfers ownership/management of the mother contract to newOwner. Restricted to the owner.
• computeAddress(bytes calldata bytecode, bytes32 salt) → address — pure view that predicts the address without spending gas on deployment.
• getDeployment(bytes32 salt) → address — returns the address deployed for a given salt (or address(0) if not yet deployed).

---

Quick Start

1. Install dependencies

npm install

2. Compile the contracts

npm run compile

3. Run tests

npm test

4. Build the TypeScript CLI

npm run build

---

CLI Usage

gen0x [options]

Required:
  -a, --address <address>   Source contract address to analyse
  -r, --rpc <url>           JSON-RPC endpoint  (env: RPC_URL)
  -m, --mother <address>    Address of the deployed MotherContract factory

Optional:
  -s, --salt <hex>          32-byte hex salt (random if omitted)
  -b, --bytecode <hex>      Creation bytecode to use instead of the source's deployed bytecode
  --deploy                  Actually deploy the contract through the MotherContract
  --private-key <key>       Signer private key for deployment (env: PRIVATE_KEY)
  -h, --help                Display help
  -V, --version             Display version

Examples

Predict a new address (no deployment):

node dist/cli.js \
  --address 0xYourSourceContract \
  --rpc https://mainnet.infura.io/v3/YOUR_KEY \
  --mother 0xYourMotherContract

Use a fixed salt:

node dist/cli.js \
  --address 0xYourSourceContract \
  --rpc https://mainnet.infura.io/v3/YOUR_KEY \
  --mother 0xYourMotherContract \
  --salt 0x0000000000000000000000000000000000000000000000000000000000000001

Deploy via MotherContract (owner only):

node dist/cli.js \
  --address 0xYourSourceContract \
  --rpc https://mainnet.infura.io/v3/YOUR_KEY \
  --mother 0xYourMotherContract \
  --private-key 0xYourPrivateKey \
  --deploy

Sample output:

═══════════════════════════════════════════
  GEN0X — Contract Address Generator
═══════════════════════════════════════════
  Source address  : 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
  Chain ID        : 1
  Bytecode hash   : 0x7a2c...
  Salt            : 0xc3a4...
  ─────────────────────────────────────────
  New address     : 0x9F4B...
  (Prediction only — pass --deploy to deploy)
  Logs URL        : https://genox.com/logs/0x9F4B...
═══════════════════════════════════════════

---

Programmatic API

import { run, generateAddress, fetchBuildData } from 'gen0x';

// Compute a new address off-chain (no RPC needed)
const { address, salt } = generateAddress(
  '0xMotherContractAddress',
  '0x608060...', // creation bytecode
  '0xMySalt'    // optional; random if omitted
);

// Full pipeline (fetch bytecode from chain, compute address, optionally deploy)
const result = await run({
  sourceAddress: '0xExistingContract',
  rpcUrl: 'https://mainnet.infura.io/v3/KEY',
  motherContractAddress: '0xMotherContract',
  deploy: false,
});

console.log(result.newAddress);   // new deterministic address
console.log(result.salt);         // salt used
console.log(result.bytecodeHash); // keccak256 of the bytecode
console.log(result.logsUrl);      // URL to download logs: https://genox.com/logs/<address>

---

Environment Variables

Variable	Description
RPC_URL	JSON-RPC endpoint (used as default for --rpc)
PRIVATE_KEY	Signer private key for deployment (used as default for --private-key)

Create a .env file in the project root:

RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
PRIVATE_KEY=0xYourPrivateKey

---

Security Notes

• The PRIVATE_KEY variable should never be committed to source control. Add .env to .gitignore.
• MotherContract restricts deploy to the owner via the onlyOwner modifier, preventing unauthorised deployments.
• Ownership can be transferred to a new address via transferOwnership(address newOwner).
• Salts are single-use: re-using a salt reverts. Choose salts carefully in production.

---

Project Structure

GEN0X/
├── contracts/
│   └── MotherContract.sol   # CREATE2 factory (the "mother" contract)
├── src/
│   ├── cli.ts               # CLI entry point
│   ├── generator.ts         # Core address-generation and deployment logic
│   ├── types.ts             # TypeScript types
│   └── index.ts             # Public API exports
├── test/
│   ├── MotherContract.test.ts  # Solidity contract tests (Hardhat/Mocha)
│   └── generator.test.ts       # Off-chain generator unit tests
├── hardhat.config.ts
├── tsconfig.json
└── package.json