evm-selector-extractor 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# evm-selector-extractor
+
+[![npm version](https://img.shields.io/npm/v/evm-selector-extractor?style=flat-square)](https://www.npmjs.com/package/evm-selector-extractor)
+[![npm downloads](https://img.shields.io/npm/dm/evm-selector-extractor?style=flat-square)](https://www.npmjs.com/package/evm-selector-extractor)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=flat-square&logo=github)](https://github.com/snipe-dev/evm-selector-extractor)
+
+
+Lightweight Ethereum Virtual Machine (EVM) bytecode selector extractor.
+
+-   Zero dependencies
+-   Works in Node.js and Browser
+-   ESM + CommonJS compatible
+-   Extracts `PUSH4` function selectors directly from raw bytecode
+
+------------------------------------------------------------------------
+
+## Installation
+
+``` bash
+npm install evm-selector-extractor
+```
+
+------------------------------------------------------------------------
+
+## Usage (Node.js + ethers v6)
+
+This example:
+
+-   Creates a provider
+-   Fetches bytecode of PEPE (ERC-20)
+-   Extracts function selectors
+-   Prints them to console
+
+``` ts
+import { JsonRpcProvider } from "ethers";
+import { EVM } from "evm-selector-extractor";
+
+const provider = new JsonRpcProvider("https://ethereum-rpc.publicnode.com");
+
+const address = "0x6982508145454ce325ddbe47a25d4ec3d2311933"; // PEPE ERC-20
+
+async function main() {
+    const bytecode = await provider.getCode(address);
+
+    const evm = new EVM(bytecode);
+    const selectors = evm.getSelectors();
+
+    console.log("Extracted selectors:");
+    console.log(selectors);
+}
+
+main();
+```
+
+------------------------------------------------------------------------
+
+## Usage (CommonJS)
+
+``` js
+const { JsonRpcProvider } = require("ethers");
+const { EVM } = require("evm-selector-extractor");
+
+const provider = new JsonRpcProvider("https://ethereum-rpc.publicnode.com");
+
+async function main() {
+    const bytecode = await provider.getCode(
+        "0x6982508145454ce325ddbe47a25d4ec3d2311933"
+    );
+
+    const evm = new EVM(bytecode);
+    console.log(evm.getSelectors());
+}
+
+main();
+```
+
+------------------------------------------------------------------------
+
+## Browser Example
+
+``` ts
+import { EVM } from "evm-selector-extractor";
+
+const bytecode = "0x63a9059cbb...";
+const evm = new EVM(bytecode);
+
+console.log(evm.getSelectors());
+```
+
+No Node.js APIs are used internally. The library relies only on
+`Uint8Array`.
+
+------------------------------------------------------------------------
+
+## API
+
+### new EVM(bytecode: string)
+
+Creates an EVM bytecode parser instance.
+
+-   Accepts hex string with or without `0x`
+-   Throws if invalid hex
+
+------------------------------------------------------------------------
+
+### getOpcodes(): EvmOpcode\[\]
+
+Returns parsed opcode list.
+
+``` ts
+interface EvmOpcode {
+    name: string;
+    opcode: number;
+    pc: number;
+    pushData?: Uint8Array;
+}
+```
+
+------------------------------------------------------------------------
+
+### getSelectors(): string\[\]
+
+Extracts unique `PUSH4` selectors.
+
+Returns:
+
+``` ts
+string[] // e.g. ["0xa9059cbb", "0x095ea7b3"]
+```
+
+Hidden internal selectors are automatically filtered.
+
+------------------------------------------------------------------------
+
+## Why not use ethereum.js / ethers ABI parsing?
+
+This library:
+
+-   Does not require ABI
+-   Does not depend on heavy EVM stacks
+-   Works directly on raw bytecode
+-   Designed for lightweight analysis tools and browser environments
+
+------------------------------------------------------------------------
+
+## Build
+
+``` bash
+npm run build
+```
+
+------------------------------------------------------------------------
+
+## Repository
+
+https://github.com/snipe-dev/evm-selector-extractor

package/dist/cjs/index.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVM = void 0;
+/**
+ * Lightweight EVM bytecode parser for extracting opcodes and function selectors.
+ *
+ * Zero dependencies.
+ * Works in both Node.js and browser environments.
+ */
+class EVM {
+    /**
+     * Creates an EVM bytecode parser instance.
+     *
+     * @param bytecode - Raw EVM bytecode as a hex string (with or without '0x' prefix)
+     * @throws {Error} If bytecode is not a valid hex string
+     */
+    constructor(bytecode) {
+        this.opcodes = [];
+        const hexCode = bytecode.startsWith("0x")
+            ? bytecode.slice(2)
+            : bytecode;
+        if (!EVM.isValidHex(hexCode)) {
+            throw new Error("Invalid hex string provided as bytecode");
+        }
+        this.code = EVM.hexToBytes(hexCode);
+    }
+    /**
+     * Parses and returns all opcodes from the bytecode.
+     *
+     * @returns Array of parsed opcode objects with their metadata
+     */
+    getOpcodes() {
+        if (this.opcodes.length > 0) {
+            return this.opcodes;
+        }
+        for (let pc = 0; pc < this.code.length; pc++) {
+            const opcodeByte = this.code[pc];
+            const opcodeInfo = this.getOpcodeInfo(opcodeByte);
+            const currentOp = {
+                name: opcodeInfo.name,
+                opcode: opcodeByte,
+                pc: pc
+            };
+            if (opcodeInfo.name.startsWith("PUSH")) {
+                const pushSize = parseInt(opcodeInfo.name.replace("PUSH", ""), 10);
+                if (pc + pushSize < this.code.length) {
+                    currentOp.pushData = this.code.slice(pc + 1, pc + pushSize + 1);
+                    pc += pushSize;
+                }
+            }
+            this.opcodes.push(currentOp);
+        }
+        return this.opcodes;
+    }
+    /**
+     * Extracts unique 4-byte function selectors (PUSH4) from EVM bytecode.
+     *
+     * @returns Array of unique function selectors as hex strings with `0x` prefix
+     */
+    getSelectors() {
+        const hidden = new Set([
+            "0xffffffff",
+            "0x00000000",
+            "0x4e487b71",
+            "0xad5c4648"
+        ]);
+        const opcodes = this.getOpcodes();
+        const push4codes = opcodes
+            .filter(op => op.name === "PUSH4" && op.pushData)
+            .map(op => EVM.bytesToHex(op.pushData));
+        return Array.from(new Set(push4codes))
+            .sort()
+            .map(hex => "0x" + hex)
+            .filter(selector => !hidden.has(selector));
+    }
+    /**
+     * Maps opcode byte values to their human-readable names.
+     */
+    getOpcodeInfo(opcode) {
+        const opcodeMap = {
+            0x60: "PUSH1", 0x61: "PUSH2", 0x62: "PUSH3", 0x63: "PUSH4",
+            0x64: "PUSH5", 0x65: "PUSH6", 0x66: "PUSH7", 0x67: "PUSH8",
+            0x68: "PUSH9", 0x69: "PUSH10", 0x6A: "PUSH11", 0x6B: "PUSH12",
+            0x6C: "PUSH13", 0x6D: "PUSH14", 0x6E: "PUSH15", 0x6F: "PUSH16",
+            0x70: "PUSH17", 0x71: "PUSH18", 0x72: "PUSH19", 0x73: "PUSH20",
+            0x74: "PUSH21", 0x75: "PUSH22", 0x76: "PUSH23", 0x77: "PUSH24",
+            0x78: "PUSH25", 0x79: "PUSH26", 0x7A: "PUSH27", 0x7B: "PUSH28",
+            0x7C: "PUSH29", 0x7D: "PUSH30", 0x7E: "PUSH31", 0x7F: "PUSH32",
+            0x00: "STOP", 0x01: "ADD", 0x02: "MUL", 0x03: "SUB",
+            0x50: "POP", 0x51: "MLOAD", 0x52: "MSTORE", 0x53: "MSTORE8",
+            0x54: "SLOAD", 0x55: "SSTORE", 0x56: "JUMP", 0x57: "JUMPI",
+            0x58: "PC", 0x59: "MSIZE", 0x5A: "GAS", 0x5B: "JUMPDEST",
+            0xF0: "CREATE", 0xF1: "CALL", 0xF2: "CALLCODE", 0xF3: "RETURN",
+            0xF4: "DELEGATECALL", 0xFA: "STATICCALL",
+            0xFD: "REVERT", 0xFF: "SELFDESTRUCT"
+        };
+        return {
+            name: opcodeMap[opcode] ||
+                `0x${opcode.toString(16).toUpperCase().padStart(2, "0")}`
+        };
+    }
+    /**
+     * Validates hex string.
+     */
+    static isValidHex(hex) {
+        return hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(hex);
+    }
+    /**
+     * Converts hex string to Uint8Array.
+     */
+    static hexToBytes(hex) {
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    /**
+     * Converts Uint8Array to hex string (without 0x prefix).
+     */
+    static bytesToHex(bytes) {
+        return Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+}
+exports.EVM = EVM;

package/dist/esm/index.js

@@ -0,0 +1,123 @@
+/**
+ * Lightweight EVM bytecode parser for extracting opcodes and function selectors.
+ *
+ * Zero dependencies.
+ * Works in both Node.js and browser environments.
+ */
+export class EVM {
+    /**
+     * Creates an EVM bytecode parser instance.
+     *
+     * @param bytecode - Raw EVM bytecode as a hex string (with or without '0x' prefix)
+     * @throws {Error} If bytecode is not a valid hex string
+     */
+    constructor(bytecode) {
+        this.opcodes = [];
+        const hexCode = bytecode.startsWith("0x")
+            ? bytecode.slice(2)
+            : bytecode;
+        if (!EVM.isValidHex(hexCode)) {
+            throw new Error("Invalid hex string provided as bytecode");
+        }
+        this.code = EVM.hexToBytes(hexCode);
+    }
+    /**
+     * Parses and returns all opcodes from the bytecode.
+     *
+     * @returns Array of parsed opcode objects with their metadata
+     */
+    getOpcodes() {
+        if (this.opcodes.length > 0) {
+            return this.opcodes;
+        }
+        for (let pc = 0; pc < this.code.length; pc++) {
+            const opcodeByte = this.code[pc];
+            const opcodeInfo = this.getOpcodeInfo(opcodeByte);
+            const currentOp = {
+                name: opcodeInfo.name,
+                opcode: opcodeByte,
+                pc: pc
+            };
+            if (opcodeInfo.name.startsWith("PUSH")) {
+                const pushSize = parseInt(opcodeInfo.name.replace("PUSH", ""), 10);
+                if (pc + pushSize < this.code.length) {
+                    currentOp.pushData = this.code.slice(pc + 1, pc + pushSize + 1);
+                    pc += pushSize;
+                }
+            }
+            this.opcodes.push(currentOp);
+        }
+        return this.opcodes;
+    }
+    /**
+     * Extracts unique 4-byte function selectors (PUSH4) from EVM bytecode.
+     *
+     * @returns Array of unique function selectors as hex strings with `0x` prefix
+     */
+    getSelectors() {
+        const hidden = new Set([
+            "0xffffffff",
+            "0x00000000",
+            "0x4e487b71",
+            "0xad5c4648"
+        ]);
+        const opcodes = this.getOpcodes();
+        const push4codes = opcodes
+            .filter(op => op.name === "PUSH4" && op.pushData)
+            .map(op => EVM.bytesToHex(op.pushData));
+        return Array.from(new Set(push4codes))
+            .sort()
+            .map(hex => "0x" + hex)
+            .filter(selector => !hidden.has(selector));
+    }
+    /**
+     * Maps opcode byte values to their human-readable names.
+     */
+    getOpcodeInfo(opcode) {
+        const opcodeMap = {
+            0x60: "PUSH1", 0x61: "PUSH2", 0x62: "PUSH3", 0x63: "PUSH4",
+            0x64: "PUSH5", 0x65: "PUSH6", 0x66: "PUSH7", 0x67: "PUSH8",
+            0x68: "PUSH9", 0x69: "PUSH10", 0x6A: "PUSH11", 0x6B: "PUSH12",
+            0x6C: "PUSH13", 0x6D: "PUSH14", 0x6E: "PUSH15", 0x6F: "PUSH16",
+            0x70: "PUSH17", 0x71: "PUSH18", 0x72: "PUSH19", 0x73: "PUSH20",
+            0x74: "PUSH21", 0x75: "PUSH22", 0x76: "PUSH23", 0x77: "PUSH24",
+            0x78: "PUSH25", 0x79: "PUSH26", 0x7A: "PUSH27", 0x7B: "PUSH28",
+            0x7C: "PUSH29", 0x7D: "PUSH30", 0x7E: "PUSH31", 0x7F: "PUSH32",
+            0x00: "STOP", 0x01: "ADD", 0x02: "MUL", 0x03: "SUB",
+            0x50: "POP", 0x51: "MLOAD", 0x52: "MSTORE", 0x53: "MSTORE8",
+            0x54: "SLOAD", 0x55: "SSTORE", 0x56: "JUMP", 0x57: "JUMPI",
+            0x58: "PC", 0x59: "MSIZE", 0x5A: "GAS", 0x5B: "JUMPDEST",
+            0xF0: "CREATE", 0xF1: "CALL", 0xF2: "CALLCODE", 0xF3: "RETURN",
+            0xF4: "DELEGATECALL", 0xFA: "STATICCALL",
+            0xFD: "REVERT", 0xFF: "SELFDESTRUCT"
+        };
+        return {
+            name: opcodeMap[opcode] ||
+                `0x${opcode.toString(16).toUpperCase().padStart(2, "0")}`
+        };
+    }
+    /**
+     * Validates hex string.
+     */
+    static isValidHex(hex) {
+        return hex.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(hex);
+    }
+    /**
+     * Converts hex string to Uint8Array.
+     */
+    static hexToBytes(hex) {
+        const bytes = new Uint8Array(hex.length / 2);
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+        }
+        return bytes;
+    }
+    /**
+     * Converts Uint8Array to hex string (without 0x prefix).
+     */
+    static bytesToHex(bytes) {
+        return Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, "0"))
+            .join("");
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Interface representing an EVM opcode with its metadata
+ */
+export interface EvmOpcode {
+    name: string;
+    opcode: number;
+    pc: number;
+    pushData?: Uint8Array;
+}
+/**
+ * Lightweight EVM bytecode parser for extracting opcodes and function selectors.
+ *
+ * Zero dependencies.
+ * Works in both Node.js and browser environments.
+ */
+export declare class EVM {
+    private readonly code;
+    private opcodes;
+    /**
+     * Creates an EVM bytecode parser instance.
+     *
+     * @param bytecode - Raw EVM bytecode as a hex string (with or without '0x' prefix)
+     * @throws {Error} If bytecode is not a valid hex string
+     */
+    constructor(bytecode: string);
+    /**
+     * Parses and returns all opcodes from the bytecode.
+     *
+     * @returns Array of parsed opcode objects with their metadata
+     */
+    getOpcodes(): EvmOpcode[];
+    /**
+     * Extracts unique 4-byte function selectors (PUSH4) from EVM bytecode.
+     *
+     * @returns Array of unique function selectors as hex strings with `0x` prefix
+     */
+    getSelectors(): string[];
+    /**
+     * Maps opcode byte values to their human-readable names.
+     */
+    private getOpcodeInfo;
+    /**
+     * Validates hex string.
+     */
+    private static isValidHex;
+    /**
+     * Converts hex string to Uint8Array.
+     */
+    private static hexToBytes;
+    /**
+     * Converts Uint8Array to hex string (without 0x prefix).
+     */
+    private static bytesToHex;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "evm-selector-extractor",
+  "version": "0.1.0",
+  "description": "Lightweight Ethereum Virtual Machine (EVM) bytecode selector extractor (Node + Browser, zero dependencies)",
+  "author": "snipe-dev",
+  "license": "MIT",
+
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snipe-dev/evm-selector-extractor.git"
+  },
+  "homepage": "https://github.com/snipe-dev/evm-selector-extractor#readme",
+  "bugs": {
+    "url": "https://github.com/snipe-dev/evm-selector-extractor/issues"
+  },
+
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+
+  "files": [
+    "dist"
+  ],
+
+  "scripts": {
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "prepublishOnly": "npm run build"
+  },
+
+  "keywords": [
+    "ethereum",
+    "evm",
+    "bytecode",
+    "selector",
+    "solidity",
+    "push4",
+    "typescript",
+    "decompiler"
+  ],
+
+  "engines": {
+    "node": ">=16"
+  },
+
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}