gnoman 0.1.0

package/gnoman2.0/src/core/backends/memoryBackend.ts

@@ -0,0 +1,27 @@
+import { KeyringBackend } from './types';
+
+export class MemoryBackend implements KeyringBackend {
+  private store = new Map<string, string>();
+
+  async initialize(): Promise<void> {
+    this.store = new Map<string, string>();
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.store.get(key) ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async list(): Promise<Record<string, string>> {
+    return Object.fromEntries(this.store.entries());
+  }
+}
+
+export default MemoryBackend;

package/gnoman2.0/src/core/backends/systemBackend.ts

@@ -0,0 +1,66 @@
+import { BackendUnavailableError, KeyringBackend } from './types';
+
+export class SystemBackend implements KeyringBackend {
+  private readonly serviceName: string;
+
+  private keytarModule?: Promise<typeof import('keytar')>;
+
+  constructor(serviceName = process.env.GNOMAN_KEYRING_SERVICE ?? 'gnoman') {
+    this.serviceName = serviceName;
+  }
+
+  private loadKeytar() {
+    if (!this.keytarModule) {
+      this.keytarModule = import('keytar').catch((error) => {
+        throw new BackendUnavailableError(
+          `System keyring unavailable: ${(error as Error)?.message ?? String(error)}`,
+          'system'
+        );
+      });
+    }
+    return this.keytarModule;
+  }
+
+  private async withKeytar<T>(handler: (keytar: typeof import('keytar')) => Promise<T>) {
+    const keytar = await this.loadKeytar();
+    try {
+      return await handler(keytar);
+    } catch (error) {
+      throw new BackendUnavailableError(
+        `System keyring operation failed: ${(error as Error)?.message ?? String(error)}`,
+        'system'
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {
+    await this.withKeytar(async (keytar) => {
+      await keytar.findCredentials(this.serviceName);
+    });
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.withKeytar((keytar) => keytar.getPassword(this.serviceName, key));
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await this.withKeytar((keytar) => keytar.setPassword(this.serviceName, key, value));
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.withKeytar((keytar) => keytar.deletePassword(this.serviceName, key));
+  }
+
+  async list(): Promise<Record<string, string>> {
+    return this.withKeytar(async (keytar) => {
+      const credentials = await keytar.findCredentials(this.serviceName);
+      const result: Record<string, string> = {};
+      for (const credential of credentials) {
+        result[credential.account] = credential.password;
+      }
+      return result;
+    });
+  }
+}
+
+export default SystemBackend;

package/gnoman2.0/src/core/backends/types.ts

@@ -0,0 +1,17 @@
+export type KeyringBackendName = 'system' | 'file' | 'memory';
+
+export interface KeyringBackend {
+  initialize(): Promise<void>;
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(): Promise<Record<string, string>>;
+  shutdown?(): Promise<void>;
+}
+
+export class BackendUnavailableError extends Error {
+  constructor(message: string, public readonly backend: KeyringBackendName) {
+    super(message);
+    this.name = 'BackendUnavailableError';
+  }
+}

package/gnoman2.0/src/core/keyringManager.ts

@@ -0,0 +1,208 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { BackendUnavailableError, KeyringBackend, KeyringBackendName } from './backends/types';
+import { FileBackend } from './backends/fileBackend';
+import { SystemBackend } from './backends/systemBackend';
+import { MemoryBackend } from './backends/memoryBackend';
+
+export type KeyringManagerOptions = {
+  auditLogPath?: string;
+  backendFactories?: Partial<Record<KeyringBackendName, () => KeyringBackend>>;
+};
+
+type OperationName = 'get' | 'set' | 'delete' | 'list' | 'switch';
+
+const FALLBACK_ORDER: KeyringBackendName[] = ['system', 'file', 'memory'];
+
+const maskKey = (key?: string | null) => {
+  if (!key) {
+    return '...';
+  }
+  const sanitized = key.replace(/[^A-Za-z0-9]/g, '');
+  if (!sanitized) {
+    return '...';
+  }
+  const prefix = sanitized
+    .slice(0, 3)
+    .toUpperCase()
+    .split('')
+    .join('_');
+  return `${prefix}${prefix ? '_' : ''}...`;
+};
+
+const defaultAuditLogPath = () => {
+  const base = process.env.GNOMAN_AUDIT_DIR ?? path.join(process.cwd(), 'logs');
+  return path.join(base, 'keyring_audit.log');
+};
+
+export class KeyringManager {
+  private readonly factories: Record<KeyringBackendName, () => KeyringBackend>;
+
+  private readonly auditLogPath: string;
+
+  private activeBackendName?: KeyringBackendName;
+
+  private activeBackend?: KeyringBackend;
+
+  private cache = new Map<string, string>();
+
+  constructor(options?: KeyringManagerOptions) {
+    this.factories = {
+      system: options?.backendFactories?.system ?? (() => new SystemBackend()),
+      file: options?.backendFactories?.file ?? (() => new FileBackend()),
+      memory: options?.backendFactories?.memory ?? (() => new MemoryBackend())
+    } as Record<KeyringBackendName, () => KeyringBackend>;
+    this.auditLogPath = options?.auditLogPath ?? defaultAuditLogPath();
+  }
+
+  currentBackend() {
+    return this.activeBackendName ?? 'memory';
+  }
+
+  private async ensureAuditLogDirectory() {
+    const directory = path.dirname(this.auditLogPath);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  }
+
+  private async record(operation: OperationName, key?: string | null, backend = this.currentBackend()) {
+    try {
+      await this.ensureAuditLogDirectory();
+      const timestamp = new Date().toISOString();
+      const entry = `${timestamp}\t${backend}\t${operation}\t${maskKey(key)}\n`;
+      await fs.appendFile(this.auditLogPath, entry, { encoding: 'utf8' });
+    } catch (error) {
+      console.warn('Unable to record keyring audit entry.', error);
+    }
+  }
+
+  private async setActiveBackend(name: KeyringBackendName, backend: KeyringBackend) {
+    this.activeBackendName = name;
+    this.activeBackend = backend;
+    this.cache = new Map();
+    const state = await backend.list();
+    this.cache = new Map(Object.entries(state));
+  }
+
+  private computeFallbackOrder(requested: KeyringBackendName) {
+    const index = FALLBACK_ORDER.indexOf(requested);
+    if (index === -1) {
+      return [...FALLBACK_ORDER];
+    }
+    return FALLBACK_ORDER.slice(index);
+  }
+
+  private createBackend(name: KeyringBackendName) {
+    const factory = this.factories[name];
+    if (!factory) {
+      throw new Error(`Unsupported keyring backend: ${name}`);
+    }
+    return factory();
+  }
+
+  async switchBackend(requested: KeyringBackendName): Promise<void> {
+    const attempts = this.computeFallbackOrder(requested);
+    for (const candidate of attempts) {
+      const backend = this.createBackend(candidate);
+      try {
+        await backend.initialize();
+        if (this.activeBackend?.shutdown) {
+          await this.activeBackend.shutdown();
+        }
+        await this.setActiveBackend(candidate, backend);
+        await this.record('switch', null, candidate);
+        return;
+      } catch (error) {
+        if (error instanceof BackendUnavailableError) {
+          console.warn(`Keyring backend '${candidate}' unavailable.`, error.message);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error('No available keyring backend.');
+  }
+
+  private async ensureBackend(): Promise<KeyringBackend> {
+    if (!this.activeBackend) {
+      await this.switchBackend('system');
+    }
+    if (!this.activeBackend) {
+      throw new Error('No available keyring backend.');
+    }
+    return this.activeBackend;
+  }
+
+  private nextFallback(current: KeyringBackendName) {
+    const index = FALLBACK_ORDER.indexOf(current);
+    if (index === -1 || index === FALLBACK_ORDER.length - 1) {
+      return undefined;
+    }
+    return FALLBACK_ORDER[index + 1];
+  }
+
+  private async execute<T>(
+    operation: (backend: KeyringBackend) => Promise<T>,
+    name: OperationName,
+    key?: string | null
+  ): Promise<T> {
+    const backend = await this.ensureBackend();
+    try {
+      const result = await operation(backend);
+      await this.record(name, key);
+      return result;
+    } catch (error) {
+      if (error instanceof BackendUnavailableError) {
+        const fallback = this.nextFallback(this.currentBackend());
+        if (!fallback) {
+          throw new Error('All keyring backends are unavailable.');
+        }
+        console.warn(
+          `Keyring backend '${this.currentBackend()}' failed (${error.message}). Falling back to '${fallback}'.`
+        );
+        await this.switchBackend(fallback);
+        return this.execute(operation, name, key);
+      }
+      throw error;
+    }
+  }
+
+  async get(key: string): Promise<string | null> {
+    const value = await this.execute(async (backend) => {
+      const result = await backend.get(key);
+      if (result === null) {
+        this.cache.delete(key);
+      } else {
+        this.cache.set(key, result);
+      }
+      return result;
+    }, 'get', key);
+    return value;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await this.execute(async (backend) => {
+      await backend.set(key, value);
+      this.cache.set(key, value);
+    }, 'set', key);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.execute(async (backend) => {
+      await backend.delete(key);
+      this.cache.delete(key);
+    }, 'delete', key);
+  }
+
+  async list(): Promise<Record<string, string>> {
+    const state = await this.execute(async (backend) => {
+      const snapshot = await backend.list();
+      this.cache = new Map(Object.entries(snapshot));
+      return snapshot;
+    }, 'list', 'ALL');
+    return state;
+  }
+}
+
+export const keyringManager = new KeyringManager();
+
+export default keyringManager;

package/gnoman2.0/src/utils/abiResolver.ts

@@ -0,0 +1,200 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { getAddress, isAddress } from 'ethers';
+import { http } from '../../backend/utils/http';
+import { resolveSecret } from './secretsResolver';
+import { runtimeObservability } from './runtimeObservability';
+
+export type AbiResolveResult = {
+  abi: unknown[];
+  contractName: string | null;
+  source: 'cache' | 'sourcify' | 'etherscan' | 'manual';
+  fetchedAt: string;
+  cachePath: string;
+  verified: boolean;
+};
+
+const CACHE_ROOT = path.join(process.cwd(), 'abi-cache');
+
+const normalizeAddress = (address: string) => {
+  if (!isAddress(address)) {
+    throw new Error(`Invalid address ${address}`);
+  }
+  return getAddress(address).toLowerCase();
+};
+
+const cachePath = (chainId: number, address: string) => path.join(CACHE_ROOT, String(chainId), `${address}.json`);
+const indexPath = (chainId: number) => path.join(CACHE_ROOT, String(chainId), 'index.json');
+
+type IndexEntry = { contractName: string | null; source: string; abiHash: string; address: string };
+
+const readIndex = (chainId: number): Record<string, IndexEntry> => {
+  const file = indexPath(chainId);
+  if (!fs.existsSync(file)) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, IndexEntry>;
+};
+
+const writeIndex = (chainId: number, index: Record<string, IndexEntry>) => {
+  const file = indexPath(chainId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(index, null, 2), 'utf8');
+};
+
+const writeCache = (chainId: number, address: string, payload: AbiResolveResult) => {
+  const file = cachePath(chainId, address);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2), 'utf8');
+  const index = readIndex(chainId);
+  index[address] = {
+    contractName: payload.contractName,
+    source: payload.source,
+    abiHash: crypto.createHash('sha256').update(JSON.stringify(payload.abi)).digest('hex'),
+    address
+  };
+  writeIndex(chainId, index);
+  return file;
+};
+
+const parseJsonIfNeeded = (abi: unknown): unknown[] => {
+  if (Array.isArray(abi)) {
+    return abi;
+  }
+  if (typeof abi === 'string') {
+    const parsed = JSON.parse(abi) as unknown;
+    if (Array.isArray(parsed)) {
+      return parsed;
+    }
+  }
+  throw new Error('ABI fragments are required.');
+};
+
+const resolveFromSourcify = async (chainId: number, address: string) => {
+  const url = `https://repo.sourcify.dev/contracts/full_match/${chainId}/${address}/metadata.json`;
+  try {
+    const response = await http.get(url);
+    const output = (response.data as { output?: { abi?: unknown[] }; settings?: { compilationTarget?: Record<string, string> } }) ?? {};
+    const abi = output.output?.abi;
+    if (!Array.isArray(abi) || abi.length === 0) {
+      return null;
+    }
+    const contractName = Object.values(output.settings?.compilationTarget ?? {})[0] ?? null;
+    return { abi, contractName: typeof contractName === 'string' ? contractName : null, source: 'sourcify' as const, verified: true };
+  } catch (_error) {
+    return null;
+  }
+};
+
+const resolveFromEtherscan = async (chainId: number, address: string) => {
+  const { value: apiKey } = await resolveSecret('ETHERSCAN_API_KEY', true);
+  const sourceResponse = await http.get('', {
+    params: {
+      module: 'contract',
+      action: 'getsourcecode',
+      chainid: chainId,
+      address,
+      apikey: apiKey
+    }
+  });
+  const source = sourceResponse.data as { result?: Array<{ ContractName?: string; Implementation?: string }> };
+  const impl = source.result?.[0]?.Implementation?.trim();
+  const abiAddress = impl && /^0x[a-fA-F0-9]{40}$/.test(impl) && impl !== '0x0000000000000000000000000000000000000000' ? normalizeAddress(impl) : address;
+
+  const abiResponse = await http.get('', {
+    params: {
+      module: 'contract',
+      action: 'getabi',
+      chainid: chainId,
+      address: abiAddress,
+      apikey: apiKey
+    }
+  });
+  const abiData = abiResponse.data as { status?: string; result?: string };
+  if (abiData.status !== '1' || !abiData.result) {
+    throw new Error(`Failed to fetch ABI from Etherscan for ${address}: ${abiData.result}`);
+  }
+  const abi = parseJsonIfNeeded(abiData.result);
+  return {
+    abi,
+    contractName: source.result?.[0]?.ContractName?.trim() || null,
+    source: 'etherscan' as const,
+    verified: true
+  };
+};
+
+const resolveFromManualRegistry = (chainId: number, address: string) => {
+  const registryPath = process.env.ABI_MANUAL_REGISTRY_PATH?.trim();
+  if (!registryPath) {
+    return null;
+  }
+  const payload = JSON.parse(fs.readFileSync(registryPath, 'utf8')) as Record<string, Record<string, { abi: unknown[]; contractName?: string }>>;
+  const chain = payload[String(chainId)] ?? {};
+  const hit = chain[address];
+  if (!hit) {
+    return null;
+  }
+  return {
+    abi: hit.abi,
+    contractName: hit.contractName ?? null,
+    source: 'manual' as const,
+    verified: false
+  };
+};
+
+export class AbiResolver {
+  async resolve(chainId: number, inputAddress: string): Promise<AbiResolveResult> {
+    const address = normalizeAddress(inputAddress);
+    const fromCachePath = cachePath(chainId, address);
+    if (fs.existsSync(fromCachePath)) {
+      const cached = JSON.parse(fs.readFileSync(fromCachePath, 'utf8')) as AbiResolveResult;
+      console.info(JSON.stringify({ event: 'ABI_RESOLVED', chainId, address, contractName: cached.contractName, source: 'cache', cached: true, functionsCount: cached.abi.length }));
+      runtimeObservability.pushAbiResolved({ chainId, address, contractName: cached.contractName, source: 'cache', cached: true, functionsCount: cached.abi.length, fetchedAt: cached.fetchedAt, cachePath: fromCachePath, verified: cached.verified });
+      return cached;
+    }
+
+
+    const legacyPath = path.join(process.cwd(), 'abi', 'address', String(chainId), `${address}.json`);
+    if (fs.existsSync(legacyPath)) {
+      const parsed = JSON.parse(fs.readFileSync(legacyPath, 'utf8')) as { abi?: unknown[] } | unknown[];
+      const abi = Array.isArray(parsed) ? parsed : parsed.abi ?? [];
+      const payload: AbiResolveResult = {
+        abi,
+        contractName: readIndex(chainId)[address]?.contractName ?? null,
+        source: 'cache',
+        fetchedAt: new Date().toISOString(),
+        cachePath: fromCachePath,
+        verified: false
+      };
+      writeCache(chainId, address, payload);
+      console.info(JSON.stringify({ event: 'ABI_RESOLVED', chainId, address, contractName: payload.contractName, source: 'cache', cached: true, functionsCount: payload.abi.length }));
+      runtimeObservability.pushAbiResolved({ chainId, address, contractName: payload.contractName, source: 'cache', cached: true, functionsCount: payload.abi.length, fetchedAt: payload.fetchedAt, cachePath: fromCachePath, verified: payload.verified });
+      return payload;
+    }
+
+    const sourcify = await resolveFromSourcify(chainId, address);
+    const etherscan = sourcify ? null : await resolveFromEtherscan(chainId, address);
+    const manual = sourcify || etherscan ? null : resolveFromManualRegistry(chainId, address);
+    const resolved = sourcify ?? etherscan ?? manual;
+    if (!resolved) {
+      throw new Error(`Unable to resolve ABI for ${address} on chain ${chainId}`);
+    }
+
+    const payload: AbiResolveResult = {
+      abi: resolved.abi,
+      contractName: resolved.contractName,
+      source: resolved.source,
+      fetchedAt: new Date().toISOString(),
+      cachePath: fromCachePath,
+      verified: resolved.verified
+    };
+    writeCache(chainId, address, payload);
+
+    console.info(JSON.stringify({ event: 'ABI_RESOLVED', chainId, address, contractName: payload.contractName, source: payload.source, cached: false, functionsCount: payload.abi.length }));
+    runtimeObservability.pushAbiResolved({ chainId, address, contractName: payload.contractName, source: payload.source, cached: false, functionsCount: payload.abi.length, fetchedAt: payload.fetchedAt, cachePath: fromCachePath, verified: payload.verified });
+    return payload;
+  }
+}
+
+export const abiResolver = new AbiResolver();

package/gnoman2.0/src/utils/runtimeObservability.ts

@@ -0,0 +1,110 @@
+import fs from 'fs';
+import path from 'path';
+
+export type SecretAuditRecord = {
+  key: string;
+  required: boolean;
+  present: boolean;
+  source: 'env' | 'dotenv' | 'file' | 'keyring' | 'missing';
+  redacted: string;
+  checkedSources: string[];
+};
+
+export type AbiResolveEvent = {
+  chainId: number;
+  address: string;
+  contractName: string | null;
+  source: string;
+  cached: boolean;
+  functionsCount: number;
+  fetchedAt: string;
+  cachePath: string;
+  verified: boolean;
+};
+
+export type RobinhoodRequestEvent = {
+  endpoint: string;
+  statusCode: number;
+  latencyMs: number;
+  at: string;
+};
+
+export type RobinhoodOrderEvent = {
+  action: 'created' | 'canceled' | 'filled';
+  orderId: string;
+  at: string;
+};
+
+const MAX_EVENTS = 20;
+const debugPath = path.join(process.cwd(), '.gnoman', 'run-debug.jsonl');
+
+const state = {
+  secrets: [] as SecretAuditRecord[],
+  abiResolves: [] as AbiResolveEvent[],
+  robinhoodEnabled: false,
+  robinhoodAuth: { ok: false, reason: 'Not attempted' },
+  robinhoodRequests: [] as RobinhoodRequestEvent[],
+  robinhoodOrders: [] as RobinhoodOrderEvent[],
+  noBroadcastReason: null as Record<string, unknown> | null,
+  safeExecutionTrace: null as Record<string, unknown> | null
+};
+
+const pushBounded = <T>(arr: T[], value: T) => {
+  arr.unshift(value);
+  if (arr.length > MAX_EVENTS) {
+    arr.splice(MAX_EVENTS);
+  }
+};
+
+const appendArtifact = (type: string, payload: unknown) => {
+  fs.mkdirSync(path.dirname(debugPath), { recursive: true });
+  fs.appendFileSync(debugPath, `${JSON.stringify({ type, at: new Date().toISOString(), payload })}\n`, 'utf8');
+};
+
+export const runtimeObservability = {
+  setSecretAudit(records: SecretAuditRecord[]) {
+    state.secrets = records;
+    appendArtifact('SECRET_AUDIT', records);
+  },
+  pushAbiResolved(event: AbiResolveEvent) {
+    pushBounded(state.abiResolves, event);
+    appendArtifact('ABI_RESOLVED', event);
+  },
+  setRobinhoodEnabled(enabled: boolean) {
+    state.robinhoodEnabled = enabled;
+  },
+  setRobinhoodAuth(ok: boolean, reason: string) {
+    state.robinhoodAuth = { ok, reason };
+    appendArtifact('ROBINHOOD_AUTH', state.robinhoodAuth);
+  },
+  pushRobinhoodRequest(event: RobinhoodRequestEvent) {
+    pushBounded(state.robinhoodRequests, event);
+    appendArtifact('ROBINHOOD_REQUEST', event);
+  },
+  pushRobinhoodOrder(event: RobinhoodOrderEvent) {
+    pushBounded(state.robinhoodOrders, event);
+    appendArtifact('ROBINHOOD_ORDER', event);
+  },
+  setNoBroadcastReason(reason: Record<string, unknown>) {
+    state.noBroadcastReason = reason;
+    appendArtifact('NO_BROADCAST_REASON', reason);
+  },
+  setSafeExecutionTrace(trace: Record<string, unknown>) {
+    state.safeExecutionTrace = trace;
+    appendArtifact('SAFE_EXECUTION_TRACE', trace);
+  },
+  snapshot() {
+    return {
+      secrets: state.secrets,
+      abiResolves: state.abiResolves,
+      robinhood: {
+        enabled: state.robinhoodEnabled,
+        auth: state.robinhoodAuth,
+        requests: state.robinhoodRequests,
+        orders: state.robinhoodOrders
+      },
+      noBroadcastReason: state.noBroadcastReason,
+      safeExecutionTrace: state.safeExecutionTrace
+    };
+  }
+};