gnoman 0.1.0

package/modules/sandbox/abiLoader.ts

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { Interface, FunctionFragment, ParamType, type InterfaceAbi } from 'ethers';
+import type { AbiFunctionDescription, AbiFunctionInput, AbiLoadRequest, AbiMetadata } from './types';
+
+const SAFE_ABI_CANDIDATES = [
+  path.join(__dirname, 'safe.abi.json'),
+  path.join(process.cwd(), 'modules/sandbox/safe.abi.json')
+];
+
+const resolveSafeAbiPath = () => {
+  for (const candidate of SAFE_ABI_CANDIDATES) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return SAFE_ABI_CANDIDATES[0];
+};
+
+export const loadSafeAbi = (): AbiMetadata => {
+  const abiSource = readFileSync(resolveSafeAbiPath(), 'utf8');
+  return parseAbi({ abi: abiSource, name: 'Safe' });
+};
+
+export const parseAbi = ({ abi, name }: AbiLoadRequest): AbiMetadata => {
+  const abiJson: InterfaceAbi = typeof abi === 'string' ? JSON.parse(abi) : abi;
+  const iface = new Interface(abiJson);
+  const functionFragments = iface.fragments.filter((fragment): fragment is FunctionFragment => fragment.type === 'function');
+  const functions: AbiFunctionDescription[] = functionFragments.map((fn) => ({
+    name: fn.name,
+    stateMutability: fn.stateMutability,
+    inputs: fn.inputs.map(mapParam),
+    outputs: fn.outputs?.map(mapParam) ?? [],
+    payable: fn.payable,
+    constant: fn.constant ?? false
+  }));
+
+  return {
+    name: name ?? functionFragments[0]?.name ?? 'Contract',
+    abi: abiJson,
+    functions
+  };
+};
+
+const mapParam = (fragment: ParamType): AbiFunctionInput => ({
+  name: fragment.name,
+  type: fragment.type,
+  internalType: (fragment as { internalType?: string }).internalType,
+  indexed:
+    (fragment as { indexed?: boolean | null }).indexed === null
+      ? undefined
+      : (fragment as { indexed?: boolean | null }).indexed ?? undefined
+});
+
+export const loadAbiFromFile = (filePath: string, name?: string): AbiMetadata => {
+  if (!existsSync(filePath)) {
+    throw new Error(`ABI file not found at ${filePath}`);
+  }
+  const raw = readFileSync(filePath, 'utf8');
+  return parseAbi({ abi: raw, name: name ?? path.basename(filePath) });
+};
+
+export const validateFunctionExists = (metadata: AbiMetadata, functionName: string) => {
+  const exists = metadata.functions.some((fn) => fn.name === functionName);
+  if (!exists) {
+    throw new Error(`Function ${functionName} not found in ABI ${metadata.name}`);
+  }
+};
+
+export const requireSafeAbi = (): AbiMetadata => {
+  const safePath = resolveSafeAbiPath();
+  if (!existsSync(safePath)) {
+    throw new Error('Safe ABI definition missing');
+  }
+  const abiSource = readFileSync(safePath, 'utf8');
+  return parseAbi({ abi: abiSource, name: 'Safe' });
+};
+

package/modules/sandbox/contractSimulator.ts

@@ -0,0 +1,241 @@
+import { JsonRpcProvider, Wallet, Interface, getAddress, isHexString, ZeroAddress, type InterfaceAbi } from 'ethers';
+import type {
+  ContractSimulationRequest,
+  ContractSimulationResult,
+  SimulationParameterMap,
+  AbiMetadata
+} from './types';
+import { randomUUID } from 'crypto';
+
+const TRACE_METHOD = 'debug_traceCall';
+
+const toHexValue = (value?: string) => {
+  if (!value) return undefined;
+  return isHexString(value) ? value : `0x${BigInt(value).toString(16)}`;
+};
+
+export interface SimulationContext {
+  metadata: AbiMetadata;
+  request: ContractSimulationRequest;
+  abiInterface: Interface;
+}
+
+export const buildProvider = async (rpcUrl: string) => {
+  const provider = new JsonRpcProvider(rpcUrl);
+  await provider.getNetwork();
+  return provider;
+};
+
+export const encodeParameters = (abiInterface: Interface, functionName: string, parameters: SimulationParameterMap) => {
+  const fragment = abiInterface.getFunction(functionName);
+  if (!fragment) {
+    throw new Error(`Function ${functionName} not found in ABI`);
+  }
+  const orderedArgs = fragment.inputs.map((input, index) => {
+    if (input.name && input.name in parameters) {
+      return parameters[input.name];
+    }
+    const fallbackKey = `arg_${index}`;
+    if (fallbackKey in parameters) {
+      return parameters[fallbackKey];
+    }
+    throw new Error(`Missing parameter ${input.name || fallbackKey}`);
+  });
+  return abiInterface.encodeFunctionData(functionName, orderedArgs);
+};
+
+const decodeReturn = (abiInterface: Interface, functionName: string, data: string | null | undefined) => {
+  if (!data) return null;
+  try {
+    return abiInterface.decodeFunctionResult(functionName, data);
+  } catch (error) {
+    return { error: (error as Error).message };
+  }
+};
+
+const captureTrace = async (
+  provider: JsonRpcProvider,
+  request: ContractSimulationRequest,
+  callData: string,
+  from: string
+) => {
+  try {
+    const trace = await provider.send(TRACE_METHOD, [
+      {
+        from,
+        to: request.contractAddress,
+        data: callData,
+        gas: request.gasLimit,
+        value: request.value ? toHexValue(request.value) : undefined
+      },
+      'latest',
+      {
+        enableMemory: true,
+        enableReturnData: true,
+        disableStack: false
+      }
+    ]);
+    return trace;
+  } catch (error) {
+    return { error: (error as Error).message };
+  }
+};
+
+const runStaticCall = async (
+  provider: JsonRpcProvider,
+  abiInterface: Interface,
+  request: ContractSimulationRequest,
+  callData: string,
+  from: string
+) => {
+  try {
+    const result = await provider.call({
+      to: request.contractAddress,
+      data: callData,
+      from,
+      value: request.value ? toHexValue(request.value) : undefined
+    });
+    return { success: true as const, result };
+  } catch (error) {
+    return { success: false as const, error: error as Error };
+  }
+};
+
+const estimateGas = async (
+  provider: JsonRpcProvider,
+  request: ContractSimulationRequest,
+  callData: string,
+  from: string
+) => {
+  try {
+    const estimate = await provider.estimateGas({
+      to: request.contractAddress,
+      data: callData,
+      from,
+      value: request.value ? toHexValue(request.value) : undefined,
+      gasLimit: request.gasLimit ? BigInt(request.gasLimit) : undefined
+    });
+    return estimate.toString();
+  } catch (error) {
+    return undefined;
+  }
+};
+
+export const simulateContractCall = async (
+  metadata: AbiMetadata,
+  request: ContractSimulationRequest
+): Promise<ContractSimulationResult> => {
+  const provider = await buildProvider(request.rpcUrl);
+  const network = await provider.getNetwork();
+  const abiInterface = new Interface(metadata.abi as InterfaceAbi);
+  const contractAddress = getAddress(request.contractAddress);
+  const fromAddress = request.from ? getAddress(request.from) : ZeroAddress;
+  const callData = encodeParameters(abiInterface, request.functionName, request.parameters);
+  const gasEstimate = await estimateGas(provider, { ...request, contractAddress }, callData, fromAddress);
+  const staticResult = await runStaticCall(provider, abiInterface, { ...request, contractAddress }, callData, fromAddress);
+
+  let decoded: unknown = null;
+  let revertReason: string | undefined;
+
+  if (staticResult.success) {
+    decoded = decodeReturn(abiInterface, request.functionName, staticResult.result);
+  } else {
+    const error = staticResult.error;
+    revertReason = error.message;
+  }
+
+  const trace = await captureTrace(provider, { ...request, contractAddress }, callData, fromAddress);
+
+  const record: ContractSimulationResult = {
+    id: randomUUID(),
+    timestamp: new Date().toISOString(),
+    success: staticResult.success,
+    network: {
+      chainId: Number(network.chainId.toString()),
+      name: network.name
+    },
+    gasEstimate,
+    gasLimit: request.gasLimit,
+    returnData: staticResult.success ? staticResult.result : undefined,
+    decodedReturnData: decoded ?? undefined,
+    error: staticResult.success ? undefined : staticResult.error?.message,
+    revertReason,
+    trace,
+    callData,
+    functionName: request.functionName,
+    contractAddress,
+    parameters: request.parameters,
+    forkMode: Boolean(request.fork),
+    rpcUrl: request.rpcUrl,
+    value: request.value
+  };
+
+  return record;
+};
+
+export const simulateOnFork = async (
+  metadata: AbiMetadata,
+  request: ContractSimulationRequest,
+  forkRpcUrl: string
+): Promise<ContractSimulationResult> => {
+  const provider = await buildProvider(forkRpcUrl);
+  const abiInterface = new Interface(metadata.abi as InterfaceAbi);
+  const contractAddress = getAddress(request.contractAddress);
+  const callData = encodeParameters(abiInterface, request.functionName, request.parameters);
+  const fromWallet = Wallet.createRandom().connect(provider);
+  const gasEstimate = await provider.estimateGas({
+    to: contractAddress,
+    data: callData,
+    value: request.value ? toHexValue(request.value) : undefined,
+    gasLimit: request.gasLimit ? BigInt(request.gasLimit) : undefined,
+    from: await fromWallet.getAddress()
+  });
+
+  try {
+    const response = await provider.call({
+      to: contractAddress,
+      data: callData,
+      from: await fromWallet.getAddress(),
+      value: request.value ? toHexValue(request.value) : undefined
+    });
+
+    return {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      success: true,
+      network: {
+        chainId: Number((await provider.getNetwork()).chainId.toString()),
+        name: (await provider.getNetwork()).name
+      },
+      gasEstimate: gasEstimate.toString(),
+      returnData: response,
+      decodedReturnData: decodeReturn(abiInterface, request.functionName, response) ?? undefined,
+      callData,
+      functionName: request.functionName,
+      contractAddress,
+      parameters: request.parameters,
+      forkMode: true,
+      rpcUrl: forkRpcUrl,
+      value: request.value
+    };
+  } catch (error) {
+    return {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      success: false,
+      network: {
+        chainId: Number((await provider.getNetwork()).chainId.toString()),
+        name: (await provider.getNetwork()).name
+      },
+      gasEstimate: gasEstimate.toString(),
+      error: (error as Error).message,
+      callData,
+      functionName: request.functionName,
+      contractAddress,
+      parameters: request.parameters,
+      forkMode: true,
+      rpcUrl: forkRpcUrl,
+      value: request.value
+    };
+  }
+};

package/modules/sandbox/formBuilder.ts

@@ -0,0 +1,16 @@
+import type { AbiFunctionDescription } from './types';
+
+export interface ParameterField {
+  name: string;
+  type: string;
+  placeholder: string;
+}
+
+export const buildParameterFields = (fn?: AbiFunctionDescription): ParameterField[] => {
+  if (!fn) return [];
+  return fn.inputs.map((input, index) => ({
+    name: input.name || `arg_${index}`,
+    type: input.type,
+    placeholder: input.type
+  }));
+};

package/modules/sandbox/index.ts

@@ -0,0 +1,6 @@
+import SandboxManager from './sandboxManager';
+
+const sandboxManager = new SandboxManager();
+
+export default sandboxManager;
+export * from './types';

package/modules/sandbox/localFork.ts

@@ -0,0 +1,129 @@
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
+import path from 'path';
+import { EventEmitter } from 'events';
+import fs from 'fs';
+
+export interface ForkOptions {
+  rpcUrl: string;
+  blockNumber?: number;
+  port?: number;
+  command?: string;
+  workspace?: string;
+}
+
+export interface ForkStatus {
+  active: boolean;
+  port?: number;
+  pid?: number;
+  startedAt?: string;
+  rpcUrl?: string;
+  blockNumber?: number;
+  command?: string;
+  error?: string;
+}
+
+export default class LocalFork extends EventEmitter {
+  private process: ChildProcessWithoutNullStreams | null = null;
+  private status: ForkStatus = { active: false };
+  private readonly allowedCommands: Set<string>;
+
+  constructor(private readonly logsDir: string) {
+    super();
+    const fromEnv = process.env.GNOMAN_FORK_ALLOWLIST?.split(',').map((value) => value.trim()).filter(Boolean);
+    const defaults = ['anvil'];
+    if (fromEnv && fromEnv.length > 0) {
+      this.allowedCommands = new Set(fromEnv.map((command) => command.toLowerCase()));
+      defaults.forEach((command) => this.allowedCommands.add(command));
+    } else {
+      this.allowedCommands = new Set(defaults.map((command) => command.toLowerCase()));
+    }
+  }
+
+  start(options: ForkOptions) {
+    if (this.process) {
+      throw new Error('Fork already running');
+    }
+
+    const port = options.port ?? 8545;
+    const command = this.sanitizeCommand(options.command);
+    const args = ['--fork-url', options.rpcUrl, '--port', String(port)];
+    if (options.blockNumber !== undefined) {
+      args.push('--fork-block-number', String(options.blockNumber));
+    }
+
+    const forkWorkspace = options.workspace ?? process.cwd();
+    const logFile = path.join(this.logsDir, `fork-${Date.now()}.log`);
+    const outStream = fs.createWriteStream(logFile, { flags: 'a' });
+
+    const child = spawn(command, args, {
+      cwd: forkWorkspace,
+      stdio: 'pipe'
+    });
+
+    child.on('error', (error) => {
+      outStream.write(String(error));
+      this.status = { active: false, error: (error as Error).message };
+      this.emit('error', (error as Error).message);
+    });
+
+    child.stdout.on('data', (data) => {
+      outStream.write(data);
+      this.emit('log', data.toString());
+    });
+
+    child.stderr.on('data', (data) => {
+      outStream.write(data);
+      this.emit('error', data.toString());
+    });
+
+    child.on('close', (code) => {
+      outStream.close();
+      this.process = null;
+      this.status = { active: false, error: code ? `Fork exited with code ${code}` : undefined };
+      this.emit('stop', this.status);
+    });
+
+    this.process = child;
+    this.status = {
+      active: true,
+      port,
+      pid: child.pid ?? undefined,
+      startedAt: new Date().toISOString(),
+      rpcUrl: `http://127.0.0.1:${port}`,
+      blockNumber: options.blockNumber,
+      command
+    };
+
+    this.emit('start', this.status);
+    return this.status;
+  }
+
+  stop() {
+    if (!this.process) {
+      return this.status;
+    }
+    this.process.kill('SIGTERM');
+    this.process = null;
+    this.status = { active: false };
+    this.emit('stop', this.status);
+    return this.status;
+  }
+
+  getStatus(): ForkStatus {
+    return this.status;
+  }
+
+  private sanitizeCommand(command?: string) {
+    const candidate = command?.trim() ?? 'anvil';
+    if (!/^[A-Za-z0-9._-]+$/.test(candidate)) {
+      throw new Error('Fork command contains unsupported characters');
+    }
+    if (candidate.includes('/') || candidate.includes('\\')) {
+      throw new Error('Fork command cannot include path separators');
+    }
+    if (!this.allowedCommands.has(candidate.toLowerCase())) {
+      throw new Error(`Fork command "${candidate}" is not permitted`);
+    }
+    return candidate;
+  }
+}

package/modules/sandbox/safe.abi.json

@@ -0,0 +1,82 @@
+[
+  {
+    "inputs": [
+      { "internalType": "address", "name": "owner", "type": "address" }
+    ],
+    "name": "isOwner",
+    "outputs": [
+      { "internalType": "bool", "name": "", "type": "bool" }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      { "internalType": "address", "name": "owner", "type": "address" },
+      { "internalType": "uint256", "name": "_threshold", "type": "uint256" }
+    ],
+    "name": "addOwnerWithThreshold",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      { "internalType": "address", "name": "prevOwner", "type": "address" },
+      { "internalType": "address", "name": "owner", "type": "address" },
+      { "internalType": "uint256", "name": "_threshold", "type": "uint256" }
+    ],
+    "name": "removeOwner",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      { "internalType": "address", "name": "owner", "type": "address" },
+      { "internalType": "address", "name": "newOwner", "type": "address" }
+    ],
+    "name": "swapOwner",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      { "internalType": "address", "name": "to", "type": "address" },
+      { "internalType": "uint256", "name": "value", "type": "uint256" },
+      { "internalType": "bytes", "name": "data", "type": "bytes" },
+      { "internalType": "uint8", "name": "operation", "type": "uint8" },
+      { "internalType": "uint256", "name": "safeTxGas", "type": "uint256" },
+      { "internalType": "uint256", "name": "baseGas", "type": "uint256" },
+      { "internalType": "uint256", "name": "gasPrice", "type": "uint256" },
+      { "internalType": "address", "name": "gasToken", "type": "address" },
+      { "internalType": "address", "name": "refundReceiver", "type": "address" },
+      { "internalType": "bytes", "name": "signatures", "type": "bytes" }
+    ],
+    "name": "execTransaction",
+    "outputs": [
+      { "internalType": "bool", "name": "success", "type": "bool" }
+    ],
+    "stateMutability": "payable",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "getOwners",
+    "outputs": [
+      { "internalType": "address[]", "name": "", "type": "address[]" }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "nonce",
+    "outputs": [
+      { "internalType": "uint256", "name": "", "type": "uint256" }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  }
+]