gnoman 0.1.0

package/backend/services/licenseService.ts

@@ -0,0 +1,163 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+export interface LicenseStatus {
+  active: boolean;
+  identifier?: string;
+  product?: string;
+  version?: string;
+  expiry?: string;
+  token?: string;
+}
+
+interface StoredLicense {
+  identifier: string;
+  product: string;
+  version: string;
+  expiry: number;
+  token: string;
+}
+
+class LicenseService {
+  private readonly storageDir = path.join(process.cwd(), '.gnoman');
+  private readonly licensePath = path.join(this.storageDir, 'license.json');
+  private readonly publicKeyPath = path.join(__dirname, '../licenses/license_public.pem');
+
+  constructor() {
+    if (!fs.existsSync(this.storageDir)) {
+      fs.mkdirSync(this.storageDir, { recursive: true });
+    }
+  }
+
+  getStatus(): LicenseStatus {
+    if (!fs.existsSync(this.licensePath)) {
+      return { active: false };
+    }
+
+    try {
+      const contents = fs.readFileSync(this.licensePath, 'utf8');
+      const parsed = JSON.parse(contents) as StoredLicense;
+      return {
+        active: true,
+        identifier: parsed.identifier,
+        product: parsed.product,
+        version: parsed.version,
+        expiry: new Date(parsed.expiry * 1000).toISOString(),
+        token: parsed.token
+      };
+    } catch (error) {
+      console.error('Unable to read license.json', error);
+      return { active: false };
+    }
+  }
+
+  applyLicense(input: string): LicenseStatus {
+    const rawToken = this.normalizeToken(input);
+    const { payload, signature } = this.splitToken(rawToken);
+    const payloadBuffer = this.decodeBase64Url(payload);
+    const signatureBuffer = this.decodeBase64Url(signature);
+
+    this.ensurePublicKey();
+    const publicKey = crypto.createPublicKey(fs.readFileSync(this.publicKeyPath));
+    const isValid = crypto.verify(null, payloadBuffer, publicKey, signatureBuffer);
+
+    if (!isValid) {
+      throw new Error('Invalid license signature.');
+    }
+
+    const decoded = payloadBuffer.toString('utf8');
+    const [identifier, product, version, expiry] = decoded.split('|');
+
+    if (!identifier || !product || !version || !expiry) {
+      throw new Error('License payload is malformed.');
+    }
+
+    const expiryNumber = Number.parseInt(expiry, 10);
+    if (Number.isNaN(expiryNumber)) {
+      throw new Error('License expiry is invalid.');
+    }
+
+    if (expiryNumber < Math.floor(Date.now() / 1000)) {
+      throw new Error('License token has expired.');
+    }
+
+    const record: StoredLicense = {
+      identifier,
+      product,
+      version,
+      expiry: expiryNumber,
+      token: rawToken
+    };
+
+    fs.writeFileSync(this.licensePath, JSON.stringify(record, null, 2));
+
+    return {
+      active: true,
+      identifier,
+      product,
+      version,
+      expiry: new Date(expiryNumber * 1000).toISOString(),
+      token: rawToken
+    };
+  }
+
+  private normalizeToken(input: string): string {
+    const trimmed = input.trim();
+    if (trimmed.includes('.')) {
+      return trimmed;
+    }
+
+    const cleaned = trimmed.replace(/[-\s]/g, '').toUpperCase();
+    const buffer = this.decodeBase32(cleaned);
+    const token = buffer.toString('utf8');
+    if (!token.includes('.')) {
+      throw new Error('Decoded license token is malformed.');
+    }
+    return token;
+  }
+
+  private splitToken(token: string) {
+    const parts = token.split('.');
+    if (parts.length !== 2) {
+      throw new Error('License token must contain a payload and signature.');
+    }
+    return { payload: parts[0], signature: parts[1] };
+  }
+
+  private decodeBase64Url(value: string): Buffer {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padLength = (4 - (padded.length % 4)) % 4;
+    const normalized = padded + '='.repeat(padLength);
+    return Buffer.from(normalized, 'base64');
+  }
+
+  private decodeBase32(value: string): Buffer {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+    let bits = '';
+
+    for (const char of value) {
+      const index = alphabet.indexOf(char);
+      if (index === -1) {
+        throw new Error('License token contains invalid base32 characters.');
+      }
+      bits += index.toString(2).padStart(5, '0');
+    }
+
+    const bytes: number[] = [];
+    for (let i = 0; i + 8 <= bits.length; i += 8) {
+      const chunk = bits.slice(i, i + 8);
+      bytes.push(Number.parseInt(chunk, 2));
+    }
+
+    return Buffer.from(bytes);
+  }
+
+  private ensurePublicKey() {
+    if (!fs.existsSync(this.publicKeyPath)) {
+      throw new Error('Missing license_public.pem. Place the public key in backend/licenses/.');
+    }
+  }
+}
+
+export const licenseService = new LicenseService();

package/backend/services/onchain/abiRegistry.ts

@@ -0,0 +1,57 @@
+import { EtherscanClient } from './etherscanClient';
+import { OnchainClientError } from './errors';
+import { chainCacheKey, normalizeAddress } from './types';
+
+export type AbiResolver = {
+  getContractAbi(address: string): Promise<unknown[]>;
+};
+
+export type AbiRegistryConfig = {
+  etherscanClients: Record<number, AbiResolver>;
+};
+
+export class AbiRegistry {
+  private readonly cache = new Map<string, unknown[]>();
+
+  constructor(private readonly config: AbiRegistryConfig) {}
+
+  getCacheSize(): number {
+    return this.cache.size;
+  }
+
+  setAbi(address: string, chainId: number, abi: unknown[]): void {
+    this.cache.set(chainCacheKey(chainId, address), abi);
+  }
+
+  async getAbi(address: string, chainId: number): Promise<unknown[]> {
+    const normalized = normalizeAddress(address);
+    const key = chainCacheKey(chainId, normalized);
+    const cached = this.cache.get(key);
+    if (cached) {
+      return cached;
+    }
+
+    const etherscan = this.config.etherscanClients[chainId];
+    if (!etherscan) {
+      throw new OnchainClientError('No Etherscan client configured for chain.', 'ABI_RESOLUTION_FAILED', {
+        chainId,
+        address: normalized
+      });
+    }
+
+    const abi = await etherscan.getContractAbi(normalized);
+    this.cache.set(key, abi);
+    return abi;
+  }
+}
+
+export const createAbiRegistryFromEtherscanConfig = (
+  configs: Record<number, { apiKey: string; baseUrl?: string; chainId?: number }>
+) => {
+  const etherscanClients = Object.entries(configs).reduce<Record<number, EtherscanClient>>((acc, [chainId, cfg]) => {
+    const numericChainId = Number(chainId);
+    acc[numericChainId] = new EtherscanClient(cfg.apiKey, cfg.baseUrl, cfg.chainId ?? numericChainId);
+    return acc;
+  }, {});
+  return new AbiRegistry({ etherscanClients });
+};

package/backend/services/onchain/chainlinkClient.ts

@@ -0,0 +1,56 @@
+import { Contract, JsonRpcProvider } from 'ethers';
+import { normalizeAddress } from './types';
+import { OnchainClientError } from './errors';
+
+const AGGREGATOR_V3_ABI = [
+  'function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)',
+  'function decimals() view returns (uint8)',
+  'function description() view returns (string)'
+] as const;
+
+export type ChainlinkLatestRoundData = {
+  roundId: bigint;
+  answer: bigint;
+  startedAt: bigint;
+  updatedAt: bigint;
+  answeredInRound: bigint;
+  decimals: number;
+  description: string;
+};
+
+export type ChainlinkClientConfig = {
+  rpcUrl: string;
+  chainId: number;
+};
+
+export class ChainlinkClient {
+  private readonly provider: JsonRpcProvider;
+
+  constructor(private readonly config: ChainlinkClientConfig) {
+    this.provider = new JsonRpcProvider(config.rpcUrl, config.chainId);
+  }
+
+  async getLatestFeedData(feedAddress: string): Promise<ChainlinkLatestRoundData> {
+    const normalized = normalizeAddress(feedAddress);
+    try {
+      const contract = new Contract(normalized, AGGREGATOR_V3_ABI, this.provider);
+      const [roundId, answer, startedAt, updatedAt, answeredInRound] = await contract.latestRoundData();
+      const [decimals, description] = await Promise.all([contract.decimals(), contract.description()]);
+      return {
+        roundId,
+        answer,
+        startedAt,
+        updatedAt,
+        answeredInRound,
+        decimals: Number(decimals),
+        description
+      };
+    } catch (error) {
+      throw new OnchainClientError('Unable to read Chainlink feed data.', 'CHAINLINK_FEED_ERROR', {
+        chainId: this.config.chainId,
+        feedAddress: normalized,
+        reason: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+}

package/backend/services/onchain/errors.ts

@@ -0,0 +1,16 @@
+export class OnchainClientError extends Error {
+  constructor(
+    message: string,
+    public readonly code:
+      | 'ETHERSCAN_API_ERROR'
+      | 'ETHERSCAN_ABI_NOT_VERIFIED'
+      | 'ETHERSCAN_RATE_LIMIT'
+      | 'ABI_RESOLUTION_FAILED'
+      | 'CHAINLINK_FEED_ERROR'
+      | 'TENDERLY_RPC_ERROR',
+    public readonly context?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'OnchainClientError';
+  }
+}

package/backend/services/onchain/etherscanClient.ts

@@ -0,0 +1,94 @@
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+import { normalizeAddress } from './types';
+import { OnchainClientError } from './errors';
+
+const DEFAULT_BASE_URL = 'https://api.etherscan.io/api';
+
+type EtherscanEnvelope<T> = {
+  status: string;
+  message: string;
+  result: T;
+};
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const shouldRetryRateLimit = (response: AxiosResponse<EtherscanEnvelope<unknown>> | undefined) => {
+  const msg = String(response?.data?.result ?? response?.data?.message ?? '').toLowerCase();
+  return msg.includes('rate limit') || msg.includes('max rate limit');
+};
+
+export class EtherscanClient {
+  private readonly client: AxiosInstance;
+
+  constructor(
+    private readonly apiKey: string,
+    private readonly baseUrl: string = DEFAULT_BASE_URL,
+    private readonly chainId: number = 1
+  ) {
+    if (!apiKey?.trim()) {
+      throw new OnchainClientError('Etherscan API key is required.', 'ETHERSCAN_API_ERROR');
+    }
+    this.client = axios.create({ baseURL: baseUrl, timeout: 15_000 });
+  }
+
+  private async request<T>(action: string, params: Record<string, string>, attempt = 0): Promise<EtherscanEnvelope<T>> {
+    const response = await this.client.get<EtherscanEnvelope<T>>('', {
+      params: {
+        module: 'contract',
+        action,
+        chainid: this.chainId,
+        apikey: this.apiKey,
+        ...params
+      }
+    });
+
+    if (response.data.status === '1') {
+      return response.data;
+    }
+
+    if (shouldRetryRateLimit(response) && attempt < 3) {
+      await sleep((attempt + 1) * 400);
+      return this.request<T>(action, params, attempt + 1);
+    }
+
+    if (shouldRetryRateLimit(response)) {
+      throw new OnchainClientError('Etherscan rate limit exceeded after retries.', 'ETHERSCAN_RATE_LIMIT', {
+        action,
+        chainId: this.chainId,
+        result: response.data.result
+      });
+    }
+
+    throw new OnchainClientError('Etherscan request failed.', 'ETHERSCAN_API_ERROR', {
+      action,
+      chainId: this.chainId,
+      result: response.data.result,
+      message: response.data.message
+    });
+  }
+
+  async getContractAbi(address: string): Promise<unknown[]> {
+    const normalized = normalizeAddress(address);
+    const response = await this.request<string>('getabi', { address: normalized });
+
+    try {
+      const parsed = JSON.parse(response.result) as unknown;
+      if (!Array.isArray(parsed)) {
+        throw new Error('ABI payload was not an array');
+      }
+      return parsed;
+    } catch (error) {
+      throw new OnchainClientError('Contract ABI is not verified or malformed on Etherscan.', 'ETHERSCAN_ABI_NOT_VERIFIED', {
+        address: normalized,
+        chainId: this.chainId,
+        reason: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  async getContractSource(address: string): Promise<unknown> {
+    const normalized = normalizeAddress(address);
+    const response = await this.request<unknown>('getsourcecode', { address: normalized });
+    return response.result;
+  }
+}

package/backend/services/onchain/index.ts

@@ -0,0 +1,76 @@
+import { AbiRegistry, createAbiRegistryFromEtherscanConfig } from './abiRegistry';
+import { ChainlinkClient } from './chainlinkClient';
+import { EtherscanClient } from './etherscanClient';
+import { TenderlyRpcClient } from './tenderlyRpcClient';
+import { OnchainServiceConfig } from './types';
+
+export * from './types';
+export * from './errors';
+export * from './etherscanClient';
+export * from './chainlinkClient';
+export * from './tenderlyRpcClient';
+export * from './abiRegistry';
+
+export type OnchainToolkit = {
+  getEtherscanClient(chainId?: number): EtherscanClient;
+  getChainlinkClient(chainId?: number): ChainlinkClient;
+  getTenderlyRpcClient(chainId?: number): TenderlyRpcClient;
+  abiRegistry: AbiRegistry;
+};
+
+export const createOnchainToolkit = (config: OnchainServiceConfig): OnchainToolkit => {
+  const defaultChainId = config.defaultChainId;
+
+  const etherscanConfig = Object.entries(config.networks).reduce<
+    Record<number, { apiKey: string; baseUrl?: string; chainId?: number }>
+  >((acc, [chainId, network]) => {
+    if (network.etherscan) {
+      acc[Number(chainId)] = {
+        apiKey: network.etherscan.apiKey,
+        baseUrl: network.etherscan.baseUrl,
+        chainId: network.chainId
+      };
+    }
+    return acc;
+  }, {});
+
+  const abiRegistry = createAbiRegistryFromEtherscanConfig(etherscanConfig);
+
+  const resolveChain = (chainId = defaultChainId) => {
+    const network = config.networks[chainId];
+    if (!network) {
+      throw new Error(`Network not configured for chainId=${chainId}`);
+    }
+    return network;
+  };
+
+  return {
+    abiRegistry,
+    getEtherscanClient: (chainId = defaultChainId) => {
+      const network = resolveChain(chainId);
+      if (!network.etherscan) {
+        throw new Error(`Etherscan config missing for chainId=${chainId}`);
+      }
+      return new EtherscanClient(network.etherscan.apiKey, network.etherscan.baseUrl, chainId);
+    },
+    getChainlinkClient: (chainId = defaultChainId) => {
+      const network = resolveChain(chainId);
+      if (!network.rpcUrl) {
+        throw new Error(`rpcUrl missing for chainId=${chainId}`);
+      }
+      return new ChainlinkClient({ rpcUrl: network.rpcUrl, chainId });
+    },
+    getTenderlyRpcClient: (chainId = defaultChainId) => {
+      const network = resolveChain(chainId);
+      const rpcUrl = network.tenderly?.rpcUrl ?? network.rpcUrl;
+      if (!rpcUrl) {
+        throw new Error(`Tenderly rpcUrl missing for chainId=${chainId}`);
+      }
+      return new TenderlyRpcClient({
+        rpcUrl,
+        accessKey: network.tenderly?.accessKey,
+        chainId
+      });
+    }
+  };
+};

package/backend/services/onchain/tenderlyRpcClient.ts

@@ -0,0 +1,74 @@
+import axios, { AxiosInstance } from 'axios';
+import { OnchainClientError } from './errors';
+
+export type TenderlyRpcClientConfig = {
+  rpcUrl: string;
+  accessKey?: string;
+  chainId: number;
+  timeoutMs?: number;
+};
+
+type JsonRpcResponse<T> = {
+  jsonrpc: '2.0';
+  id: number;
+  result?: T;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+};
+
+export class TenderlyRpcClient {
+  private readonly client: AxiosInstance;
+
+  constructor(private readonly config: TenderlyRpcClientConfig) {
+    this.client = axios.create({
+      baseURL: config.rpcUrl,
+      timeout: config.timeoutMs ?? 20_000,
+      headers: config.accessKey ? { 'X-Access-Key': config.accessKey } : undefined
+    });
+  }
+
+  async request<T>(method: string, params: unknown[] = []): Promise<T> {
+    try {
+      const response = await this.client.post<JsonRpcResponse<T>>('', {
+        jsonrpc: '2.0',
+        id: Date.now(),
+        method,
+        params
+      });
+      if (response.data.error) {
+        throw new OnchainClientError('Tenderly RPC returned an error.', 'TENDERLY_RPC_ERROR', {
+          method,
+          chainId: this.config.chainId,
+          error: response.data.error
+        });
+      }
+      if (typeof response.data.result === 'undefined') {
+        throw new OnchainClientError('Tenderly RPC response missing result.', 'TENDERLY_RPC_ERROR', {
+          method,
+          chainId: this.config.chainId
+        });
+      }
+      return response.data.result;
+    } catch (error) {
+      if (error instanceof OnchainClientError) {
+        throw error;
+      }
+      throw new OnchainClientError('Tenderly RPC call failed.', 'TENDERLY_RPC_ERROR', {
+        method,
+        chainId: this.config.chainId,
+        reason: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  getBlockNumber(): Promise<string> {
+    return this.request<string>('eth_blockNumber');
+  }
+
+  call(transaction: { to: string; data: string }, blockTag: string = 'latest'): Promise<string> {
+    return this.request<string>('eth_call', [transaction, blockTag]);
+  }
+}

package/backend/services/onchain/types.ts

@@ -0,0 +1,33 @@
+import { getAddress, isAddress } from 'ethers';
+
+export type OnchainNetworkConfig = {
+  chainId: number;
+  rpcUrl?: string;
+  etherscan?: {
+    apiKey: string;
+    baseUrl?: string;
+  };
+  tenderly?: {
+    accountSlug?: string;
+    projectSlug?: string;
+    accessKey?: string;
+    baseUrl?: string;
+    rpcUrl?: string;
+  };
+};
+
+export type OnchainServiceConfig = {
+  defaultChainId: number;
+  networks: Record<number, OnchainNetworkConfig>;
+};
+
+export type Address = `0x${string}`;
+
+export const normalizeAddress = (address: string): Address => {
+  if (!isAddress(address)) {
+    throw new Error(`Invalid Ethereum address: ${address}`);
+  }
+  return getAddress(address) as Address;
+};
+
+export const chainCacheKey = (chainId: number, address: string) => `${chainId}:${normalizeAddress(address).toLowerCase()}`;