gnoman 0.1.0

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

@@ -0,0 +1,144 @@
+import fs from 'fs';
+import path from 'path';
+import { FileBackend } from '../core/backends/fileBackend';
+import keyringAccessor from '../../backend/services/keyringAccessor';
+import { runtimeObservability, type SecretAuditRecord } from './runtimeObservability';
+
+export type SecretSource = 'env' | 'dotenv' | 'file' | 'keyring' | 'missing';
+
+const bootEnvKeys = new Set(Object.keys(process.env));
+let dotenvLoaded = false;
+let fileBackend: FileBackend | null = null;
+let fileSecrets = new Map<string, string>();
+
+const GUI_KEYRING_ALLOWED = Boolean(process.env.DISPLAY && process.env.DBUS_SESSION_BUS_ADDRESS);
+
+const redact = (value: string | undefined) => {
+  if (!value) {
+    return 'MISSING';
+  }
+  const trimmed = value.trim();
+  if (trimmed.length <= 4) {
+    return '****';
+  }
+  return `****${trimmed.slice(-4)}`;
+};
+
+const loadDotenvFile = () => {
+  const envPath = path.join(process.cwd(), '.env');
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+  const raw = fs.readFileSync(envPath, 'utf8');
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, '');
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+};
+
+const ensureDotenvLoaded = () => {
+  if (dotenvLoaded) {
+    return;
+  }
+  loadDotenvFile();
+  dotenvLoaded = true;
+};
+
+const ensureFileSecretsLoaded = async () => {
+  if (fileBackend) {
+    return;
+  }
+  const filePath = process.env.GNOMAN_KEYRING_FILE ?? path.join(process.cwd(), '.gnoman', 'secrets.enc');
+  fileBackend = new FileBackend(filePath);
+  try {
+    await fileBackend.initialize();
+    const listed = await fileBackend.list();
+    fileSecrets = new Map(Object.entries(listed));
+  } catch (error) {
+    console.error(JSON.stringify({ event: 'FILE_SECRET_BACKEND_ERROR', message: String(error) }));
+  }
+};
+
+const detectEnvSource = (key: string): SecretSource | null => {
+  const value = process.env[key];
+  if (!value?.trim()) {
+    return null;
+  }
+  return bootEnvKeys.has(key) ? 'env' : 'dotenv';
+};
+
+export const resolveSecret = async (key: string, required = false) => {
+  ensureDotenvLoaded();
+  await ensureFileSecretsLoaded();
+  const checkedSources = ['env', 'dotenv', 'file'];
+
+  const envSource = detectEnvSource(key);
+  if (envSource) {
+    return { value: process.env[key]!.trim(), source: envSource, checkedSources };
+  }
+
+  const fileValue = fileSecrets.get(key)?.trim();
+  if (fileValue) {
+    return { value: fileValue, source: 'file' as const, checkedSources };
+  }
+
+  if (GUI_KEYRING_ALLOWED) {
+    checkedSources.push('keyring');
+    try {
+      const keyringValue = await keyringAccessor.get(key);
+      if (keyringValue?.trim()) {
+        return { value: keyringValue.trim(), source: 'keyring' as const, checkedSources };
+      }
+    } catch (error) {
+      console.warn(`Unable to resolve ${key} from keyring`, error);
+    }
+  }
+
+  const missing = { event: 'MISSING_SECRET', key, checkedSources };
+  console.error(JSON.stringify(missing));
+  if (required) {
+    throw new Error(`${key} is required for this run mode.`);
+  }
+  return { value: undefined, source: 'missing' as const, checkedSources };
+};
+
+export const auditSecretsAtBoot = async (keys: Array<{ key: string; required: boolean }>) => {
+  ensureDotenvLoaded();
+  await ensureFileSecretsLoaded();
+  const records: SecretAuditRecord[] = [];
+  for (const { key, required } of keys) {
+    const resolved = await resolveSecret(key, false);
+    records.push({
+      key,
+      required,
+      present: Boolean(resolved.value),
+      source: resolved.source,
+      redacted: redact(resolved.value),
+      checkedSources: resolved.checkedSources
+    });
+  }
+  runtimeObservability.setSecretAudit(records);
+  console.info(
+    JSON.stringify({
+      event: 'SECRETS_AUDIT',
+      secrets: records.map((r) => ({
+        key: r.key,
+        required: r.required,
+        present: r.present,
+        source: r.source,
+        value: r.redacted
+      }))
+    })
+  );
+};

package/gnoman2.0/tests/chainlinkService.test.ts

@@ -0,0 +1,32 @@
+import { getChainlinkRuntimeConfig } from '../backend/services/chainlinkService';
+
+describe('chainlinkService config validation', () => {
+  const env = { ...process.env };
+
+  afterEach(() => {
+    process.env = { ...env };
+  });
+
+  it('validates required chainlink runtime config', () => {
+    process.env.CHAINLINK_NODE_URL = 'https://node.example';
+    process.env.CHAINLINK_JOB_ID = 'job-123';
+    process.env.CHAINLINK_OPERATOR_ADDRESS = '0x1111111111111111111111111111111111111111';
+    process.env.CHAINLINK_LINK_TOKEN = '0x2222222222222222222222222222222222222222';
+
+    const config = getChainlinkRuntimeConfig();
+
+    expect(config.nodeUrl).toBe('https://node.example');
+    expect(config.jobId).toBe('job-123');
+    expect(config.operatorAddress).toBe('0x1111111111111111111111111111111111111111');
+    expect(config.linkToken).toBe('0x2222222222222222222222222222222222222222');
+  });
+
+  it('throws on invalid operator address', () => {
+    process.env.CHAINLINK_NODE_URL = 'https://node.example';
+    process.env.CHAINLINK_JOB_ID = 'job-123';
+    process.env.CHAINLINK_OPERATOR_ADDRESS = 'not-an-address';
+    process.env.CHAINLINK_LINK_TOKEN = '0x2222222222222222222222222222222222222222';
+
+    expect(() => getChainlinkRuntimeConfig()).toThrow('CHAINLINK_OPERATOR_ADDRESS is not a valid Ethereum address');
+  });
+});

package/gnoman2.0/tests/diagnosticsService.test.ts

@@ -0,0 +1,68 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { runSystemDiagnostics } from '../backend/services/diagnosticsService';
+
+describe('runSystemDiagnostics', () => {
+  const logsPath = path.join(process.cwd(), 'logs');
+  const safevaultPath = path.join(process.cwd(), '.safevault');
+  let removeLogs = false;
+  let removeSafevault = false;
+
+  beforeAll(async () => {
+    removeLogs = await fs
+      .access(logsPath)
+      .then(() => false)
+      .catch(() => true);
+    removeSafevault = await fs
+      .access(safevaultPath)
+      .then(() => false)
+      .catch(() => true);
+    if (removeLogs) {
+      await fs.rm(logsPath, { recursive: true, force: true });
+    }
+    if (removeSafevault) {
+      await fs.rm(safevaultPath, { recursive: true, force: true });
+    }
+  });
+
+  afterAll(async () => {
+    if (removeLogs) {
+      await fs.rm(logsPath, { recursive: true, force: true });
+    }
+    if (removeSafevault) {
+      await fs.rm(safevaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('produces a consistent report snapshot', async () => {
+    const report = await runSystemDiagnostics({ skipGpg: true });
+    expect(report.generatedAt).toEqual(expect.any(String));
+    expect(report.environment.cwd).toBe(process.cwd());
+    expect(report.summary.total).toBe(report.checks.length);
+
+    const nodeCheck = report.checks.find((check) => check.id === 'node-version');
+    expect(nodeCheck).toBeDefined();
+    expect(nodeCheck?.metadata).toEqual(
+      expect.objectContaining({ current: process.version })
+    );
+
+    const walletCheck = report.checks.find((check) => check.id === 'wallet-inventory');
+    expect(walletCheck).toBeDefined();
+    expect(walletCheck?.metadata).toEqual(
+      expect.objectContaining({ count: expect.any(Number) })
+    );
+
+    const keyringChecks = report.checks.filter((check) => check.id.startsWith('keyring-'));
+    expect(keyringChecks.map((check) => check.id)).toEqual(
+      expect.arrayContaining(['keyring-system', 'keyring-file', 'keyring-memory'])
+    );
+  });
+
+  it('auto-fix mode creates the logs directory', async () => {
+    await fs.rm(logsPath, { recursive: true, force: true });
+    const report = await runSystemDiagnostics({ autoFix: true, skipGpg: true });
+    const logsCheck = report.checks.find((check) => check.id === 'logs-dir');
+    expect(logsCheck?.status).toBe('ok');
+    await expect(fs.stat(logsPath)).resolves.toBeDefined();
+  });
+});

package/gnoman2.0/tests/etherscanController.test.ts

@@ -0,0 +1,99 @@
+import type { Request, Response } from 'express';
+
+jest.mock('../backend/services/etherscanService', () => ({
+  resolveAbiByAddress: jest.fn(async () => [{ type: 'function', name: 'transfer' }]),
+  resolveAbiFileForAddress: jest.fn(async () => '/tmp/abi/address/1/0xabc.json'),
+  getTxHistory: jest.fn(async () => ({ status: '1', result: [{ hash: '0x1' }] })),
+  getGasOracle: jest.fn(async () => ({ status: '1', result: { SafeGasPrice: '10' } }))
+}));
+
+import {
+  getAddressTxHistory,
+  getCurrentGasOracle,
+  resolveContractAbi,
+  resolveContractAbiFile
+} from '../backend/controllers/etherscanController';
+import {
+  getGasOracle,
+  getTxHistory,
+  resolveAbiByAddress,
+  resolveAbiFileForAddress
+} from '../backend/services/etherscanService';
+
+const mockedResolveAbiByAddress = resolveAbiByAddress as jest.MockedFunction<typeof resolveAbiByAddress>;
+const mockedResolveAbiFileForAddress =
+  resolveAbiFileForAddress as jest.MockedFunction<typeof resolveAbiFileForAddress>;
+const mockedGetTxHistory = getTxHistory as jest.MockedFunction<typeof getTxHistory>;
+const mockedGetGasOracle = getGasOracle as jest.MockedFunction<typeof getGasOracle>;
+
+describe('etherscanController', () => {
+  afterEach(() => {
+    mockedResolveAbiByAddress.mockClear();
+    mockedResolveAbiFileForAddress.mockClear();
+    mockedGetTxHistory.mockClear();
+    mockedGetGasOracle.mockClear();
+  });
+
+  it('resolves contract ABI from body params', async () => {
+    const req = {
+      body: { address: '0x1111111111111111111111111111111111111111', chainId: '8453', abiNameHint: 'ERC20' }
+    } as Request;
+    const json = jest.fn();
+    const status = jest.fn(() => ({ json }));
+    const res = { json, status } as unknown as Response;
+
+    await resolveContractAbi(req, res, jest.fn());
+
+    expect(mockedResolveAbiByAddress).toHaveBeenCalledWith(
+      8453,
+      '0x1111111111111111111111111111111111111111',
+      'ERC20'
+    );
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({ itemCount: 1, chainId: 8453 }));
+  });
+
+  it('returns 400 when ABI resolve request has no address', async () => {
+    const req = { body: {} } as Request;
+    const json = jest.fn();
+    const status = jest.fn(() => ({ json }));
+    const res = { json, status } as unknown as Response;
+
+    await resolveContractAbi(req, res, jest.fn());
+
+    expect(status).toHaveBeenCalledWith(400);
+    expect(mockedResolveAbiByAddress).not.toHaveBeenCalled();
+  });
+
+  it('resolves ABI file path via query params', async () => {
+    const req = {
+      params: { address: '0x1111111111111111111111111111111111111111' },
+      query: { chainId: '10', abiNameHint: 'Proxy' }
+    } as unknown as Request;
+    const json = jest.fn();
+    const res = { json } as unknown as Response;
+
+    await resolveContractAbiFile(req, res, jest.fn());
+
+    expect(mockedResolveAbiFileForAddress).toHaveBeenCalledWith(
+      10,
+      '0x1111111111111111111111111111111111111111',
+      'Proxy'
+    );
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({ chainId: 10 }));
+  });
+
+  it('proxies tx history and gas oracle calls', async () => {
+    const txReq = { params: { address: '0x1111111111111111111111111111111111111111' }, query: { chainId: '1' } } as unknown as Request;
+    const gasReq = { query: { chainId: '137' } } as unknown as Request;
+    const txJson = jest.fn();
+    const gasJson = jest.fn();
+
+    await getAddressTxHistory(txReq, { json: txJson } as unknown as Response, jest.fn());
+    await getCurrentGasOracle(gasReq, { json: gasJson } as unknown as Response, jest.fn());
+
+    expect(mockedGetTxHistory).toHaveBeenCalledWith('0x1111111111111111111111111111111111111111', 1);
+    expect(mockedGetGasOracle).toHaveBeenCalledWith(137);
+    expect(txJson).toHaveBeenCalled();
+    expect(gasJson).toHaveBeenCalled();
+  });
+});

package/gnoman2.0/tests/etherscanService.test.ts

@@ -0,0 +1,116 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { http } from '../backend/utils/http';
+import {
+  resolveAbiByAddress,
+  resolveAbiFileForAddress,
+  _internal as etherscanInternal
+} from '../backend/services/etherscanService';
+
+describe('etherscanService ABI resolver', () => {
+  const originalCwd = process.cwd();
+  let workspace: string;
+
+  beforeEach(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'gnoman-abi-'));
+    process.chdir(workspace);
+    delete process.env.ETHERSCAN_API_KEY;
+    delete process.env.ETHERSCAN_CHAIN_ID;
+    etherscanInternal.clearCaches();
+    jest.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it('returns cached ABI without network call', async () => {
+    const address = '0x1111111111111111111111111111111111111111';
+    const cachePath = path.join(workspace, 'abi', 'address', '1', `${address}.json`);
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify({ abi: [{ type: 'function', name: 'transfer' }] }));
+
+    const requestSpy = jest.spyOn(http, 'get');
+
+    const abi = await resolveAbiByAddress(1, address);
+
+    expect(requestSpy).not.toHaveBeenCalled();
+    expect(abi[0]).toEqual(expect.objectContaining({ name: 'transfer' }));
+  });
+
+  it('detects proxy implementation and caches under original address', async () => {
+    process.env.ETHERSCAN_API_KEY = 'test-key';
+    const original = '0x2222222222222222222222222222222222222222';
+    const implementation = '0x3333333333333333333333333333333333333333';
+
+    const requestSpy = jest.spyOn(http, 'get').mockImplementation(async (_url, config) => {
+      const action = (config?.params as { action?: string }).action;
+      if (action === 'getsourcecode') {
+        return {
+          data: { status: '1', message: 'OK', result: [{ Implementation: implementation }] }
+        } as never;
+      }
+      if (action === 'getabi') {
+        expect((config?.params as { address?: string }).address).toBe(implementation.toLowerCase());
+        return {
+          data: {
+            status: '1',
+            message: 'OK',
+            result: JSON.stringify([{ type: 'function', name: 'balanceOf' }])
+          }
+        } as never;
+      }
+      throw new Error(`Unexpected action: ${String(action)}`);
+    });
+
+    const resolvedPath = await resolveAbiFileForAddress(1, original, 'ERC20');
+
+    expect(requestSpy).toHaveBeenCalledTimes(2);
+    expect(resolvedPath).toContain(path.join('abi', 'address', '1', `${original.toLowerCase()}.json`));
+    const metaPath = resolvedPath.replace(/\.json$/, '.meta.json');
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) as Record<string, unknown>;
+    expect(meta).toEqual(
+      expect.objectContaining({
+        chainId: 1,
+        address: original.toLowerCase(),
+        abiTargetAddress: implementation.toLowerCase(),
+        isProxy: true,
+        abiNameHint: 'ERC20',
+        source: 'etherscan'
+      })
+    );
+  });
+
+
+  it('rate limits to <= 3 calls/sec under repeated resolves', async () => {
+    process.env.ETHERSCAN_API_KEY = 'test-key';
+    const calls: number[] = [];
+
+    jest.spyOn(http, 'get').mockImplementation(async (_url, config) => {
+      calls.push(Date.now());
+      const action = (config?.params as { action?: string }).action;
+      if (action === 'getsourcecode') {
+        return { data: { status: '1', message: 'OK', result: [{ Implementation: '' }] } } as never;
+      }
+      return {
+        data: { status: '1', message: 'OK', result: JSON.stringify([{ type: 'function', name: 'foo' }]) }
+      } as never;
+    });
+
+    const start = Date.now();
+    await resolveAbiByAddress(1, '0x5555555555555555555555555555555555555555');
+    await resolveAbiByAddress(1, '0x6666666666666666666666666666666666666666');
+    const elapsed = Date.now() - start;
+
+    expect(calls.length).toBe(4);
+    expect(elapsed).toBeGreaterThanOrEqual(900);
+  });
+
+  it('fails clearly when API key is missing and no local ABI exists', async () => {
+    await expect(resolveAbiByAddress(1, '0x4444444444444444444444444444444444444444')).rejects.toThrow(
+      'Missing ABI and no ETHERSCAN_API_KEY configured'
+    );
+  });
+});

package/gnoman2.0/tests/keyringManager.test.ts

@@ -0,0 +1,135 @@
+import fs from 'fs';
+import fsPromises from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { KeyringManager } from '../src/core/keyringManager';
+import { MemoryBackend } from '../src/core/backends/memoryBackend';
+import { FileBackend } from '../src/core/backends/fileBackend';
+import { BackendUnavailableError, KeyringBackend } from '../src/core/backends/types';
+
+class StubBackend implements KeyringBackend {
+  constructor(private state: Record<string, string>) {}
+
+  async initialize(): Promise<void> {
+    // no-op
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.state[key] ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.state[key] = value;
+  }
+
+  async delete(key: string): Promise<void> {
+    delete this.state[key];
+  }
+
+  async list(): Promise<Record<string, string>> {
+    return { ...this.state };
+  }
+}
+
+describe('KeyringManager', () => {
+  const createTempPath = (fileName: string) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gnoman-keyring-test-'));
+    return path.join(dir, fileName);
+  };
+
+  it('switchBackend reloads secrets from the requested backend', async () => {
+    const manager = new KeyringManager({
+      backendFactories: {
+        system: () => new StubBackend({ RPC_URL: 'https://system' }),
+        file: () => new StubBackend({ FILE_ONLY: 'present' }),
+        memory: () => new MemoryBackend()
+      },
+      auditLogPath: createTempPath('audit.log')
+    });
+
+    await manager.switchBackend('system');
+    expect(await manager.get('RPC_URL')).toBe('https://system');
+
+    await manager.switchBackend('file');
+    const snapshot = await manager.list();
+    expect(snapshot).toEqual({ FILE_ONLY: 'present' });
+    expect(await manager.get('FILE_ONLY')).toBe('present');
+  });
+
+  it('round-trips secrets between persistent backends', async () => {
+    const filePath = createTempPath('secrets.enc');
+    const manager = new KeyringManager({
+      backendFactories: {
+        system: () => new FileBackend(filePath),
+        file: () => new FileBackend(filePath),
+        memory: () => new MemoryBackend()
+      },
+      auditLogPath: createTempPath('audit.log')
+    });
+
+    await manager.switchBackend('system');
+    await manager.set('API_TOKEN', 'system-token');
+    expect(await manager.get('API_TOKEN')).toBe('system-token');
+
+    await manager.switchBackend('file');
+    expect(await manager.get('API_TOKEN')).toBe('system-token');
+
+    await manager.set('API_TOKEN', 'file-token');
+    expect(await manager.get('API_TOKEN')).toBe('file-token');
+
+    await manager.switchBackend('system');
+    expect(await manager.get('API_TOKEN')).toBe('file-token');
+  });
+
+  it('encrypts secrets on disk for the file backend', async () => {
+    const filePath = createTempPath('secrets.enc');
+    const manager = new KeyringManager({
+      backendFactories: {
+        system: () => new FileBackend(filePath),
+        file: () => new FileBackend(filePath),
+        memory: () => new MemoryBackend()
+      },
+      auditLogPath: createTempPath('audit.log')
+    });
+
+    await manager.switchBackend('file');
+    await manager.set('PRIVATE_KEY', 'super-secret-value');
+
+    const raw = await fsPromises.readFile(filePath, 'utf8');
+    expect(raw).not.toContain('super-secret-value');
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+  it('falls back when the system backend is unavailable', async () => {
+    class FailingBackend implements KeyringBackend {
+      async initialize(): Promise<void> {
+        throw new BackendUnavailableError('Unavailable', 'system');
+      }
+      async get(): Promise<string | null> {
+        throw new Error('unreachable');
+      }
+      async set(): Promise<void> {
+        throw new Error('unreachable');
+      }
+      async delete(): Promise<void> {
+        throw new Error('unreachable');
+      }
+      async list(): Promise<Record<string, string>> {
+        throw new Error('unreachable');
+      }
+    }
+
+    const manager = new KeyringManager({
+      backendFactories: {
+        system: () => new FailingBackend(),
+        file: () => new MemoryBackend(),
+        memory: () => new MemoryBackend()
+      },
+      auditLogPath: createTempPath('audit.log')
+    });
+
+    const secrets = await manager.list();
+    expect(secrets).toEqual({});
+    expect(['file', 'memory']).toContain(manager.currentBackend());
+  });
+});

package/gnoman2.0/tests/onchainToolkit.test.ts

@@ -0,0 +1,71 @@
+import { AbiRegistry } from '../backend/services/onchain/abiRegistry';
+import { EtherscanClient } from '../backend/services/onchain/etherscanClient';
+import { OnchainClientError } from '../backend/services/onchain/errors';
+import { createOnchainToolkit } from '../backend/services/onchain';
+
+describe('AbiRegistry', () => {
+  it('resolves ABI from etherscan client and caches by chainId + address', async () => {
+    const resolver = {
+      getContractAbi: jest.fn(async () => [{ type: 'function', name: 'balanceOf' }])
+    };
+
+    const registry = new AbiRegistry({ etherscanClients: { 1: resolver } });
+
+    const abi1 = await registry.getAbi('0x1111111111111111111111111111111111111111', 1);
+    const abi2 = await registry.getAbi('0x1111111111111111111111111111111111111111', 1);
+
+    expect(abi1).toEqual(abi2);
+    expect(resolver.getContractAbi).toHaveBeenCalledTimes(1);
+    expect(registry.getCacheSize()).toBe(1);
+  });
+
+  it('throws a typed error when chain is not configured', async () => {
+    const registry = new AbiRegistry({ etherscanClients: {} });
+    await expect(registry.getAbi('0x1111111111111111111111111111111111111111', 10)).rejects.toMatchObject({
+      code: 'ABI_RESOLUTION_FAILED'
+    } satisfies Partial<OnchainClientError>);
+  });
+});
+
+describe('EtherscanClient', () => {
+  it('retries rate limited responses and returns parsed ABI', async () => {
+    const client = new EtherscanClient('key');
+    const responses = [
+      { data: { status: '0', message: 'NOTOK', result: 'Max rate limit reached' } },
+      { data: { status: '1', message: 'OK', result: JSON.stringify([{ type: 'function', name: 'foo' }]) } }
+    ];
+
+    (client as unknown as { client: { get: jest.Mock } }).client = {
+      get: jest.fn(async () => responses.shift())
+    };
+
+    const abi = await client.getContractAbi('0x1111111111111111111111111111111111111111');
+
+    expect(Array.isArray(abi)).toBe(true);
+  });
+});
+
+describe('createOnchainToolkit', () => {
+  it('creates swappable per-network clients', () => {
+    const toolkit = createOnchainToolkit({
+      defaultChainId: 1,
+      networks: {
+        1: {
+          chainId: 1,
+          rpcUrl: 'https://rpc-mainnet.example',
+          etherscan: { apiKey: 'mainnet-key' },
+          tenderly: { rpcUrl: 'https://rpc.tenderly.co/fork/mainnet' }
+        },
+        11155111: {
+          chainId: 11155111,
+          rpcUrl: 'https://rpc-sepolia.example',
+          etherscan: { apiKey: 'sepolia-key', baseUrl: 'https://api-sepolia.etherscan.io/api' }
+        }
+      }
+    });
+
+    expect(toolkit.getEtherscanClient(11155111)).toBeInstanceOf(EtherscanClient);
+    expect(toolkit.getChainlinkClient(1)).toBeDefined();
+    expect(toolkit.getTenderlyRpcClient(1)).toBeDefined();
+  });
+});