sol-classer 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# Classer: ABI to TypeScript/JavaScript Class Generator
+
+Classer is a CLI tool that automatically generates strongly-typed TypeScript or vanilla JavaScript classes from Ethereum ABI JSON/JS/TS files. It streamlines contract interaction by providing:
+
+- **Strict Typing**: TypeScript types for all function inputs and outputs (optional).
+- **Read/Write Separation**: Clear distinction between view functions and state-modifying transactions.
+- **Provider Flexibility**: Support for both RPC (server-side) and `window.ethereum` (browser).
+- **ERC20 Helpers**: Automatic injection of `getBalance` and `transferTokens` helpers for ERC20 contracts.
+- **Robustness**: Automatic contract initialization, `setSigner` helpers, and error handling wrapping.
+- **Ethers.js v6 Integration**: Built on top of the latest Ethers.js for robust interaction.
+
+## Installation
+
+To use it, you can install it globally or use `npx`:
+
+```bash
+npm install -g sol-classer
+# OR
+npx sol-classer [options]
+```
+
+## Usage
+
+Basic usage:
+
+```bash
+sol-classer \
+  --abi <path_to_abi> \
+  --name <ClassName> \
+  --address <ContractAddress> \
+  [options]
+```
+
+### Options
+
+- `-a, --abi <path>`: **Required**. Path to the ABI file (`.json`, `.js`, `.ts`).
+- `-n, --name <name>`: **Required**. Name of the class to generate.
+- `-x, --address <address>`: **Required**. The default contract address.
+- `-o, --output <path>`: Optional. Output file path. Defaults to `<ClassName>.[ts|js]`.
+- `--provider <type>`: Optional. `'rpc'` (default) or `'window'`.
+- `--lang <language>`: Optional. `'ts'` (default) or `'js'`.
+- `--rpc <variable>`: Optional. Env var for RPC URL (only for RPC provider). Defaults to `NEXT_PUBLIC_RPC`.
+
+### Examples
+
+**1. Standard TypeScript Class (RPC Provider)**
+```bash
+sol-classer \
+  --abi test/samples/ERC20.json \
+  --name MyToken \
+  --address 0x123... \
+  --provider rpc \
+  --lang ts
+```
+
+**2. Browser/Frontend Class (Window Provider)**
+This generates a class that connects to `window.ethereum` and handles wallet connection.
+```bash
+sol-classer \
+  --abi ABI/ABI.js \
+  --name FrontendToken \
+  --address 0x456... \
+  --provider window
+```
+
+**Usage in Frontend:**
+```typescript
+const token = new FrontendToken();
+// Auto-initializes on first call, or call explicitly
+await token.setSigner(); 
+await token.transfer("0xUser", "10"); 
+```
+
+**3. JavaScript Class (No Types)**
+```bash
+sol-classer \
+  --abi test/samples/ERC20.json \
+  --name LegacyToken \
+  --address 0x789... \
+  --lang js
+```
+
+## Generated Code Features
+
+- **Automatic Initialization**: All methods call `initializeContract()` internally to ensure provider/signer availability.
+- **Error Handling**: All contract calls are wrapped in `try-catch` blocks with informative error logging.
+- **Extensible**: The generated class can be easily extended or modified.
+- **Isomorphic**: Works in Node.js (RPC) and Browser (Window) environments.
+- **Zero Config**: Just pass the ABI and you are good to go.

package/dist/generator.d.ts

@@ -0,0 +1,11 @@
+export type ProviderType = 'rpc' | 'window';
+export type Language = 'ts' | 'js';
+export declare function solidityTypeToTs(type: string): string;
+export declare function generateClass({ abi, className, contractAddress, rpcEnvVar, providerType, language }: {
+    abi: any[];
+    className: string;
+    contractAddress: string;
+    rpcEnvVar?: string;
+    providerType?: ProviderType;
+    language?: Language;
+}): string;

package/dist/generator.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.solidityTypeToTs = solidityTypeToTs;
+exports.generateClass = generateClass;
+function solidityTypeToTs(type) {
+    if (type.startsWith("uint") || type.startsWith("int")) {
+        return "string | number | bigint";
+    }
+    if (type === "address")
+        return "string";
+    if (type === "bool")
+        return "boolean";
+    if (type === "string")
+        return "string";
+    if (type.startsWith("bytes"))
+        return "string";
+    if (type === "tuple")
+        return "any"; // TODO: Handle tuples better if needed
+    if (type.endsWith("[]"))
+        return "any[]"; // Arrays
+    return "any";
+}
+function isReadFunction(fn) {
+    return (fn.stateMutability === "view" ||
+        fn.stateMutability === "pure");
+}
+function isWriteFunction(fn) {
+    return (fn.stateMutability === "nonpayable" ||
+        fn.stateMutability === "payable");
+}
+function generateParams(inputs, language) {
+    if (!inputs || inputs.length === 0)
+        return "";
+    return inputs
+        .map((i, idx) => {
+        const name = i.name || `arg${idx}`;
+        return language === 'ts'
+            ? `${name}: ${solidityTypeToTs(i.type)}`
+            : name;
+    })
+        .join(", ");
+}
+function generateReadMethod(fn, language) {
+    const params = generateParams(fn.inputs, language);
+    const argNames = fn.inputs ? fn.inputs.map((i, idx) => i.name || `arg${idx}`).join(", ") : "";
+    const returnType = language === 'ts' ? ": Promise<any>" : "";
+    return `
+  async ${fn.name}(${params})${returnType} {
+      try {
+        await this.initializeContract();
+        return await this.contract.${fn.name}(${argNames});
+      } catch (error) {
+        console.error("Failed to read ${fn.name}:", error);
+        throw error;
+      }
+  }
+`;
+}
+function generateWriteMethod(fn, language) {
+    const params = generateParams(fn.inputs, language);
+    const argNames = fn.inputs ? fn.inputs.map((i, idx) => i.name || `arg${idx}`).join(", ") : "";
+    const returnType = language === 'ts' ? ": Promise<ethers.ContractTransactionResponse>" : "";
+    return `
+  async ${fn.name}(${params})${returnType} {
+      try {
+        await this.initializeContract();
+        if (!this.contract.runner) {
+             throw new Error("Signer required for ${fn.name}. Ensure you have connected a wallet.");
+        }
+        
+        const tx = await this.contract.${fn.name}(${argNames});
+        await tx.wait();
+        return tx;
+      } catch (error) {
+        console.error("Failed to execute ${fn.name}:", error);
+        throw error;
+      }
+  }
+`;
+}
+function isERC20(abi) {
+    const names = abi
+        .filter((x) => x.type === "function")
+        .map((x) => x.name);
+    return (names.includes("decimals") &&
+        names.includes("symbol") &&
+        names.includes("balanceOf") &&
+        names.includes("transfer"));
+}
+function generateClass({ abi, className, contractAddress, rpcEnvVar = "NEXT_PUBLIC_RPC", providerType = 'rpc', language = 'ts' }) {
+    const readFns = abi.filter((x) => x.type === "function" && isReadFunction(x));
+    const writeFns = abi.filter((x) => x.type === "function" && isWriteFunction(x));
+    const isErc20Token = isERC20(abi);
+    const isTs = language === 'ts';
+    let erc20Methods = "";
+    if (isErc20Token) {
+        const balanceReturnType = isTs ? ": Promise<string>" : "";
+        const txReturnType = isTs ? ": Promise<ethers.ContractTransactionResponse>" : "";
+        const addressType = isTs ? ": string" : "";
+        const amountType = isTs ? ": string" : "";
+        erc20Methods = `
+    // -------------------------
+    // ERC20 Helpers
+    // -------------------------
+    
+    async getBalance(address${addressType})${balanceReturnType} {
+        try {
+            await this.initializeContract();
+            const balance = await this.contract.balanceOf(address);
+            const decimals = await this.contract.decimals();
+            return ethers.formatUnits(balance, decimals);
+        } catch (error) {
+            console.error("Failed to get balance:", error);
+            throw error;
+        }
+    }
+    
+    async transferTokens(to${addressType}, amount${amountType})${txReturnType} {
+        try {
+             await this.initializeContract();
+             if (!this.contract.runner) {
+                throw new Error("Signer required for transferTokens");
+            }
+            const decimals = await this.contract.decimals();
+            const parsedAmount = ethers.parseUnits(amount, decimals);
+            const tx = await this.contract.transfer(to, parsedAmount);
+            await tx.wait();
+            return tx;
+        } catch (error) {
+            console.error("Failed to transfer tokens:", error);
+            throw error;
+        }
+    }
+    `;
+    }
+    // Type Definitions
+    const fieldTypes = isTs ? `
+    private provider: ethers.Provider | ethers.BrowserProvider | null; 
+    private signer: ethers.Signer | null;
+    private contract: ethers.Contract | null;
+    private contractAddress: string;
+  ` : "";
+    // Constructor logic
+    let constructorCode = "";
+    let methodsCode = "";
+    if (providerType === 'rpc') {
+        const ctorParams = isTs
+            ? `contractAddress: string = "${contractAddress}", privateKey?: string, rpcUrl?: string`
+            : `contractAddress = "${contractAddress}", privateKey, rpcUrl`;
+        constructorCode = `
+    constructor(${ctorParams}) {
+        this.contractAddress = contractAddress;
+        this.contract = null;
+        this.signer = null;
+        
+        const rpc = rpcUrl || process.env.${rpcEnvVar};
+        if (!rpc) {
+            throw new Error("RPC URL not found. Please provide it or set ${rpcEnvVar}");
+        }
+        this.provider = new ethers.JsonRpcProvider(rpc);
+        
+        if (privateKey) {
+            this.signer = new ethers.Wallet(privateKey, this.provider);
+        }
+    }
+      `;
+        methodsCode = `
+    async initializeContract()${isTs ? ": Promise<void>" : ""} {
+        if (this.contract) return;
+        
+        try {
+            // If we have a signer (private key), use it. Otherwise use provider (read-only)
+            const runner = this.signer || this.provider;
+            this.contract = new ethers.Contract(
+                this.contractAddress,
+                ABI,
+                runner
+            );
+        } catch (error) {
+             console.error("Failed to initialize contract:", error);
+             throw error;
+        }
+    }
+      `;
+    }
+    else {
+        // Window / Browser provider
+        const ctorParams = isTs
+            ? `contractAddress: string = "${contractAddress}"`
+            : `contractAddress = "${contractAddress}"`;
+        constructorCode = `
+    constructor(${ctorParams}) {
+        this.contractAddress = contractAddress;
+        this.provider = null;
+        this.signer = null;
+        this.contract = null;
+    }
+      `;
+        methodsCode = `
+    async init()${isTs ? ": Promise<void>" : ""} {
+        if (typeof window !== "undefined" && (window as any).ethereum) {
+            this.provider = new ethers.BrowserProvider((window as any).ethereum);
+        } else {
+            throw new Error("window.ethereum is not available");
+        }
+    }
+
+    async setSigner()${isTs ? ": Promise<void>" : ""} {
+         try {
+            if (!this.provider) await this.init();
+            
+            // @ts-ignore
+            this.signer = await this.provider.getSigner();
+        } catch (error) {
+            console.error("Failed to set signer:", error);
+            throw error;
+        }
+    }
+
+    async getSignerAddress()${isTs ? ": Promise<string>" : ""} {
+        try {
+            if (!this.signer) await this.setSigner();
+            // @ts-ignore
+            return await this.signer.getAddress();
+        } catch (error) {
+            console.error("Failed to get signer address:", error);
+            throw error;
+        }
+    }
+
+    async initializeContract()${isTs ? ": Promise<void>" : ""} {
+         try {
+            if (!this.provider) await this.init();
+            
+            if (!this.signer) {
+                // Try to get signer if possible, otherwise implementation might fail for usage requiring signer
+                // But we don't force it here to allow read-only if the user hasn't connected wallet yet?
+                // Actually, for consistency with 'setSigner', let's try to get it.
+                try {
+                    // @ts-ignore
+                    this.signer = await this.provider.getSigner();
+                } catch (e) {
+                    console.warn("Could not get signer, defaulting to read-only provider if possible");
+                }
+            }
+
+            if (!this.contract) {
+                const runner = this.signer || this.provider;
+                this.contract = new ethers.Contract(
+                    this.contractAddress,
+                    ABI,
+                    runner
+                );
+            }
+        } catch (error) {
+            console.error("Failed to initialize contract:", error);
+            throw error;
+        }
+    }
+      `;
+    }
+    return `
+import { ethers } from "ethers";
+
+const ABI = ${JSON.stringify(abi, null, 2)};
+
+export class ${className} {
+    ${fieldTypes}
+    ${constructorCode}
+    
+    ${methodsCode}
+
+    ${erc20Methods}
+
+    // -------------------------
+    // Write functions
+    // -------------------------
+    ${writeFns.map(fn => generateWriteMethod(fn, language)).join("\n")}
+
+    // -------------------------
+    // Read functions
+    // -------------------------
+    ${readFns.map(fn => generateReadMethod(fn, language)).join("\n")}
+}
+`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("./utils");
+const generator_1 = require("./generator");
+const program = new commander_1.Command();
+program
+    .version("1.0.0")
+    .description("Generate TypeScript class from ABI JSON")
+    .requiredOption("-a, --abi <path>", "Path to ABI JSON file")
+    .requiredOption("-n, --name <name>", "Name of the class to generate")
+    .requiredOption("-x, --address <address>", "Contract address")
+    .option("-o, --output <path>", "Output file path")
+    .option("--provider <type>", "Provider type: 'rpc' | 'window'", "rpc")
+    .option("--lang <language>", "Output language: 'ts' | 'js'", "ts")
+    .action(async (options) => {
+    try {
+        const abiPath = path_1.default.resolve(process.cwd(), options.abi);
+        const abi = await (0, utils_1.loadAbi)(abiPath);
+        // Validate options
+        if (!['rpc', 'window'].includes(options.provider)) {
+            throw new Error("Invalid provider type. Must be 'rpc' or 'window'.");
+        }
+        if (!['ts', 'js'].includes(options.lang)) {
+            throw new Error("Invalid language. Must be 'ts' or 'js'.");
+        }
+        const classCode = (0, generator_1.generateClass)({
+            abi,
+            className: options.name,
+            contractAddress: options.address,
+            rpcEnvVar: options.rpc,
+            providerType: options.provider,
+            language: options.lang
+        });
+        const extension = options.lang === 'js' ? 'js' : 'ts';
+        const outputPath = options.output
+            ? path_1.default.resolve(process.cwd(), options.output)
+            : path_1.default.join(process.cwd(), `${options.name}.${extension}`);
+        await (0, utils_1.writefile)(outputPath, classCode);
+        console.log(`Successfully generated ${options.name} at ${outputPath}`);
+    }
+    catch (error) {
+        console.error("Error generating class:", error);
+        process.exit(1);
+    }
+});
+program.parse(process.argv);

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function loadAbi(filePath: string): Promise<any>;
+export declare function writefile(filePath: string, content: string): Promise<void>;

package/dist/utils.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAbi = loadAbi;
+exports.writefile = writefile;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function loadAbi(filePath) {
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    if (ext === ".json") {
+        return await fs_extra_1.default.readJson(filePath);
+    }
+    else if (ext === ".js" || ext === ".ts") {
+        const absolutePath = path_1.default.resolve(filePath);
+        // Use jiti to handle both CJS and ESM, and TS files
+        const createJiti = require("jiti");
+        const jiti = createJiti(__filename);
+        const module = jiti(absolutePath);
+        // Try to find the ABI array
+        let candidate = module.default || module.ABI || module.abi || module.Abi;
+        // If default is an object containing ABI
+        if (module.default && !Array.isArray(module.default)) {
+            candidate = module.default.ABI || module.default.abi || module.default.Abi || candidate;
+        }
+        if (candidate && Array.isArray(candidate))
+            return candidate;
+        // If the module itself is the array (unlikely for named export but possible for default)
+        if (Array.isArray(module))
+            return module;
+        // Specific check for the 'ABI' key as seen in logs
+        if (Array.isArray(module.ABI))
+            return module.ABI;
+        throw new Error(`Could not find ABI array in ${filePath}. Loaded keys: ${Object.keys(module).join(", ")}`);
+    }
+    else {
+        throw new Error(`Unsupported file extension: ${ext}. Use .json, .js, or .ts`);
+    }
+}
+async function writefile(filePath, content) {
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(filePath));
+    await fs_extra_1.default.writeFile(filePath, content);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "sol-classer",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "bin": {
+    "sol-classer": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "larsalaxsanderson@gmail.com",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "ethers": "^6.16.0",
+    "fs-extra": "^11.3.3",
+    "jiti": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.2.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}