gnoman 0.1.0

package/gnoman2.0/gnomon/tests/test_abi_resolver.py

@@ -0,0 +1,181 @@
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from gnomon.utils import abi_resolver
+
+
+@pytest.fixture(autouse=True)
+def _isolated_abi_root(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("ETHERSCAN_API_KEY", raising=False)
+    monkeypatch.delenv("ETHERSCAN_BASE_URL", raising=False)
+    monkeypatch.delenv("ETHERSCAN_CHAIN_ID", raising=False)
+    abi_resolver._ABI_CACHE.clear()
+    abi_resolver._FILE_CACHE.clear()
+    abi_resolver._FETCH_ONCE_CACHE.clear()
+    yield
+
+
+def test_resolver_returns_cached_file_without_network_call(monkeypatch):
+    chain_id = 1
+    address = "0x1111111111111111111111111111111111111111"
+    cache_file = Path("abi/address/1") / f"{address}.json"
+    cache_file.parent.mkdir(parents=True, exist_ok=True)
+    cache_file.write_text(json.dumps({"abi": [{"name": "transfer", "type": "function"}]}), encoding="utf-8")
+
+    called = False
+
+    def _fail_get(*args, **kwargs):
+        nonlocal called
+        called = True
+        raise AssertionError("network should not be called")
+
+    monkeypatch.setattr(abi_resolver.requests, "get", _fail_get)
+
+    payload = abi_resolver.resolveAbiByAddress(chain_id, address, None)
+
+    assert payload["abi"][0]["name"] == "transfer"
+    assert called is False
+
+
+def test_proxy_resolves_implementation_and_caches_under_original(monkeypatch):
+    os.environ["ETHERSCAN_API_KEY"] = "test-key"
+    chain_id = 1
+    original = "0x2222222222222222222222222222222222222222"
+    implementation = "0x3333333333333333333333333333333333333333"
+
+    class _Response:
+        def __init__(self, payload):
+            self._payload = payload
+
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return self._payload
+
+    called_actions = []
+
+    def _mock_get(url, params, timeout):
+        called_actions.append((params["action"], params["address"]))
+        if params["action"] == "getsourcecode":
+            return _Response(
+                {
+                    "status": "1",
+                    "message": "OK",
+                    "result": [{"Implementation": implementation}],
+                }
+            )
+        if params["action"] == "getabi":
+            assert params["address"] == implementation
+            return _Response(
+                {
+                    "status": "1",
+                    "message": "OK",
+                    "result": json.dumps([{"name": "balanceOf", "type": "function"}]),
+                }
+            )
+        raise AssertionError("unexpected action")
+
+    monkeypatch.setattr(abi_resolver.requests, "get", _mock_get)
+
+    payload = abi_resolver.resolveAbiByAddress(chain_id, original, "ERC20")
+
+    assert payload["abi"][0]["name"] == "balanceOf"
+    cache_path = Path("abi/address/1") / f"{original}.json"
+    assert cache_path.exists()
+    assert ("getsourcecode", original) in called_actions
+    assert ("getabi", implementation) in called_actions
+
+
+def test_rate_limiter_prevents_exceeding_limit_under_loop(monkeypatch):
+    os.environ["ETHERSCAN_API_KEY"] = "test-key"
+
+    class _Response:
+        def __init__(self, payload):
+            self._payload = payload
+
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return self._payload
+
+    def _mock_get(url, params, timeout):
+        if params["action"] == "getsourcecode":
+            return _Response({"status": "1", "message": "OK", "result": [{"Implementation": ""}]})
+        return _Response({"status": "1", "message": "OK", "result": json.dumps([{"type": "function"}])})
+
+    monkeypatch.setattr(abi_resolver.requests, "get", _mock_get)
+
+    addresses = [f"0x{i:040x}" for i in range(10, 12)]  # 2 resolves => 4 HTTP calls
+    start = time.perf_counter()
+    for address in addresses:
+        abi_resolver.resolveAbiByAddress(1, address, None)
+    elapsed = time.perf_counter() - start
+
+    assert elapsed >= 0.9
+
+
+def test_meta_file_written_with_required_fields(monkeypatch):
+    os.environ["ETHERSCAN_API_KEY"] = "test-key"
+    address = "0x4444444444444444444444444444444444444444"
+
+    class _Response:
+        def __init__(self, payload):
+            self._payload = payload
+
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return self._payload
+
+    def _mock_get(url, params, timeout):
+        if params["action"] == "getsourcecode":
+            return _Response({"status": "1", "message": "OK", "result": [{"Implementation": ""}]})
+        return _Response(
+            {
+                "status": "1",
+                "message": "OK",
+                "result": json.dumps([{"name": "approve", "type": "function"}]),
+            }
+        )
+
+    monkeypatch.setattr(abi_resolver.requests, "get", _mock_get)
+
+    abi_resolver.resolveAbiFileForAddress(1, address, "Token")
+
+    meta_file = Path("abi/address/1") / f"{address}.meta.json"
+    assert meta_file.exists()
+    meta = json.loads(meta_file.read_text(encoding="utf-8"))
+
+    for field in (
+        "chainId",
+        "address",
+        "abiTargetAddress",
+        "isProxy",
+        "implementation",
+        "abiNameHint",
+        "source",
+        "fetchedAt",
+        "abiSha256",
+    ):
+        assert field in meta
+    assert meta["address"] == address
+    assert meta["source"] == "etherscan"
+
+
+def test_missing_api_key_raises_clear_error():
+    address = "0x5555555555555555555555555555555555555555"
+    with pytest.raises(RuntimeError, match="Missing ABI and no ETHERSCAN_API_KEY configured"):
+        abi_resolver.resolveAbiByAddress(1, address, None)

package/gnoman2.0/gnomon/tests/test_safe_persistence_and_etherscan.py

@@ -0,0 +1,97 @@
+import json
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+if "keyring" not in sys.modules:
+    keyring_stub = types.ModuleType("keyring")
+    _store: dict[tuple[str, str], str] = {}
+
+    def get_password(service_name: str, username: str):
+        return _store.get((service_name, username))
+
+    def set_password(service_name: str, username: str, password: str):
+        _store[(service_name, username)] = password
+
+    def delete_password(service_name: str, username: str):
+        _store.pop((service_name, username), None)
+
+    keyring_stub.get_password = get_password
+    keyring_stub.set_password = set_password
+    keyring_stub.delete_password = delete_password
+    sys.modules["keyring"] = keyring_stub
+
+from keyring import delete_password, set_password
+
+# Configure the keyring stub before importing the tracker module.
+set_password("gnoman", "ETHERSCAN_API_KEY", "dummy-test-key")
+
+from gnomon.api import etherscan_tracker
+from gnomon.api.etherscan_tracker import (
+    fetch_transactions,
+    get_etherscan_api_key,
+    load_safe_state,
+    SAFE_STATE_PATH,
+)
+
+
+@pytest.fixture(autouse=True)
+def cleanup_state_file():
+    SAFE_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    yield
+    if SAFE_STATE_PATH.exists():
+        SAFE_STATE_PATH.unlink()
+    delete_password("gnoman", "ETHERSCAN_API_KEY")
+
+
+def _write_state_file(address: str = "0xSAFE", owners=None, threshold: int = 2):
+    owners = owners or ["0x1", "0x2", "0x3"]
+    SAFE_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(SAFE_STATE_PATH, "w", encoding="utf-8") as handle:
+        json.dump({"address": address, "owners": owners, "threshold": threshold}, handle, indent=2)
+
+
+def test_safe_persistence_and_tx_lookup(monkeypatch):
+    assert get_etherscan_api_key() == "dummy-test-key"
+
+    _write_state_file()
+
+    state = load_safe_state()
+    assert "owners" in state and len(state["owners"]) == 3
+
+    dummy_response = {
+        "status": "1",
+        "message": "OK",
+        "result": [
+            {"hash": "0xabc", "value": "0x0"},
+            {"hash": "0xdef", "value": "0x0"},
+        ],
+    }
+
+    class _StubResponse:
+        def __init__(self, payload):
+            self._payload = payload
+
+        def raise_for_status(self):
+            return None
+
+        def json(self):
+            return self._payload
+
+    def _mock_get(url, timeout):
+        assert state["address"] in url
+        assert get_etherscan_api_key() in url
+        return _StubResponse(dummy_response)
+
+    monkeypatch.setattr(etherscan_tracker.requests, "get", _mock_get)
+
+    txs = fetch_transactions(state["address"])
+    assert isinstance(txs, list)
+    assert all("hash" in tx for tx in txs)
+    print("[TEST] ✅ Safe persistence and Etherscan lookup verified.")

package/gnoman2.0/gnomon/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility helpers for GNOMAN."""
+
+from .abi_resolver import resolveAbiByAddress, resolveAbiFileForAddress
+
+__all__ = ["resolveAbiByAddress", "resolveAbiFileForAddress"]

package/gnoman2.0/gnomon/utils/abi_resolver.py

@@ -0,0 +1,255 @@
+"""ABI resolver with address-tethered caching and Etherscan proxy awareness."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+import time
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CHAIN_ID = 1
+DEFAULT_ETHERSCAN_BASE_URL = "https://api.etherscan.io/api"
+ABI_ROOT = Path("abi")
+ADDRESS_ABI_ROOT = ABI_ROOT / "address"
+ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+
+
+class _RateLimiter:
+    """Simple sleep-based limiter constrained to 3 calls per second."""
+
+    def __init__(self, max_calls: int = 3, period_seconds: float = 1.0):
+        self.max_calls = max_calls
+        self.period_seconds = period_seconds
+        self._calls: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        while True:
+            sleep_for = 0.0
+            with self._lock:
+                now = time.monotonic()
+                while self._calls and now - self._calls[0] >= self.period_seconds:
+                    self._calls.popleft()
+                if len(self._calls) < self.max_calls:
+                    self._calls.append(now)
+                    return
+                sleep_for = self.period_seconds - (now - self._calls[0])
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+
+
+_RATE_LIMITER = _RateLimiter()
+_ABI_CACHE: dict[tuple[int, str], dict[str, Any]] = {}
+_FILE_CACHE: dict[tuple[int, str], Path] = {}
+_FETCH_ONCE_CACHE: dict[tuple[int, str], bool] = {}
+
+
+def _normalize_address(address: str) -> str:
+    address = address.strip().lower()
+    if not address.startswith("0x"):
+        raise ValueError(f"Invalid address format: {address}")
+    return address
+
+
+def _address_abi_path(chain_id: int, address: str) -> Path:
+    return ADDRESS_ABI_ROOT / str(chain_id) / f"{_normalize_address(address)}.json"
+
+
+def _address_meta_path(chain_id: int, address: str) -> Path:
+    return ADDRESS_ABI_ROOT / str(chain_id) / f"{_normalize_address(address)}.meta.json"
+
+
+def _read_abi_file(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as handle:
+        parsed = json.load(handle)
+    if isinstance(parsed, list):
+        return {"abi": parsed}
+    if isinstance(parsed, dict) and "abi" in parsed:
+        return parsed
+    raise ValueError(f"Unexpected ABI payload in {path}")
+
+
+def _write_address_cache(
+    chain_id: int,
+    original_address: str,
+    abi_payload: dict[str, Any],
+    *,
+    abi_target_address: str,
+    is_proxy: bool,
+    implementation: str | None,
+    abi_name_hint: str | None,
+    source: str,
+) -> Path:
+    abi_path = _address_abi_path(chain_id, original_address)
+    meta_path = _address_meta_path(chain_id, original_address)
+    abi_path.parent.mkdir(parents=True, exist_ok=True)
+
+    abi_json_canonical = json.dumps(abi_payload, sort_keys=True, separators=(",", ":"))
+    with open(abi_path, "w", encoding="utf-8") as handle:
+        json.dump(abi_payload, handle, indent=2)
+
+    metadata = {
+        "chainId": chain_id,
+        "address": _normalize_address(original_address),
+        "abiTargetAddress": _normalize_address(abi_target_address),
+        "isProxy": bool(is_proxy),
+        "implementation": _normalize_address(implementation) if implementation else None,
+        "abiNameHint": abi_name_hint,
+        "source": source,
+        "fetchedAt": datetime.now(timezone.utc).isoformat(),
+        "abiSha256": hashlib.sha256(abi_json_canonical.encode("utf-8")).hexdigest(),
+    }
+
+    with open(meta_path, "w", encoding="utf-8") as handle:
+        json.dump(metadata, handle, indent=2)
+
+    return abi_path
+
+
+def _etherscan_request(action: str, *, chain_id: int, address: str, api_key: str) -> dict[str, Any]:
+    _RATE_LIMITER.acquire()
+    base_url = os.getenv("ETHERSCAN_BASE_URL", DEFAULT_ETHERSCAN_BASE_URL)
+    response = requests.get(
+        base_url,
+        params={
+            "module": "contract",
+            "action": action,
+            "address": _normalize_address(address),
+            "apikey": api_key,
+            "chainid": chain_id,
+        },
+        timeout=20,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def _resolve_via_etherscan(chain_id: int, original_address: str, abi_name_hint: str | None) -> Path:
+    key = (chain_id, _normalize_address(original_address))
+    if key in _FETCH_ONCE_CACHE:
+        raise RuntimeError(
+            f"ABI fetch already attempted for {original_address} on chain {chain_id} during this run"
+        )
+    _FETCH_ONCE_CACHE[key] = True
+
+    api_key = os.getenv("ETHERSCAN_API_KEY")
+    if not api_key:
+        raise RuntimeError("Missing ABI and no ETHERSCAN_API_KEY configured")
+
+    logger.info("ABI cache miss → fetching from Etherscan: %s chainId=%s", original_address, chain_id)
+
+    source_data = _etherscan_request("getsourcecode", chain_id=chain_id, address=original_address, api_key=api_key)
+    implementation = None
+    is_proxy = False
+    source_result = source_data.get("result")
+    if isinstance(source_result, list) and source_result:
+        implementation = (source_result[0].get("Implementation") or "").strip()
+        if implementation and implementation.lower() != ZERO_ADDRESS:
+            is_proxy = True
+
+    abi_target = implementation if is_proxy else original_address
+    if is_proxy:
+        logger.info(
+            "Proxy detected → implementation=%s (caching ABI for original address)",
+            _normalize_address(abi_target),
+        )
+
+    abi_data = _etherscan_request("getabi", chain_id=chain_id, address=abi_target, api_key=api_key)
+    status = str(abi_data.get("status", ""))
+    result = abi_data.get("result")
+    if status != "1" or not isinstance(result, str):
+        message = abi_data.get("result") or abi_data.get("message") or "Unknown Etherscan error"
+        raise RuntimeError(f"Failed to fetch ABI from Etherscan for {original_address}: {message}")
+
+    try:
+        abi = json.loads(result)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Invalid ABI payload returned by Etherscan for {original_address}") from exc
+
+    if not abi:
+        raise RuntimeError(f"Failed to fetch ABI from Etherscan for {original_address}: empty ABI response")
+
+    payload = {"abi": abi}
+    abi_path = _write_address_cache(
+        chain_id,
+        original_address,
+        payload,
+        abi_target_address=abi_target,
+        is_proxy=is_proxy,
+        implementation=implementation,
+        abi_name_hint=abi_name_hint,
+        source="etherscan",
+    )
+    return abi_path
+
+
+def resolve_abi_file_for_address(chain_id: int, address: str, abi_name_hint: str | None = None) -> Path:
+    normalized_address = _normalize_address(address)
+    key = (chain_id, normalized_address)
+
+    if key in _FILE_CACHE:
+        return _FILE_CACHE[key]
+
+    address_path = _address_abi_path(chain_id, normalized_address)
+    if address_path.exists():
+        logger.info("ABI cache hit: %s", address_path.as_posix())
+        _FILE_CACHE[key] = address_path
+        return address_path
+
+    if abi_name_hint:
+        for candidate in (ABI_ROOT / f"{abi_name_hint}.json", ABI_ROOT / f"_{abi_name_hint}.json"):
+            if candidate.exists():
+                payload = _read_abi_file(candidate)
+                cache_path = _write_address_cache(
+                    chain_id,
+                    normalized_address,
+                    payload,
+                    abi_target_address=normalized_address,
+                    is_proxy=False,
+                    implementation=None,
+                    abi_name_hint=abi_name_hint,
+                    source="name-cache",
+                )
+                _FILE_CACHE[key] = cache_path
+                _ABI_CACHE[key] = payload
+                return cache_path
+
+    abi_path = _resolve_via_etherscan(chain_id, normalized_address, abi_name_hint)
+    _FILE_CACHE[key] = abi_path
+    return abi_path
+
+
+def resolve_abi_by_address(chain_id: int, address: str, abi_name_hint: str | None = None) -> dict[str, Any]:
+    normalized_address = _normalize_address(address)
+    key = (chain_id, normalized_address)
+    if key in _ABI_CACHE:
+        return _ABI_CACHE[key]
+
+    abi_file = resolve_abi_file_for_address(chain_id, normalized_address, abi_name_hint)
+    payload = _read_abi_file(abi_file)
+    _ABI_CACHE[key] = payload
+    return payload
+
+
+# Public API aliases requested in the spec.
+def resolveAbiByAddress(chainId: int, address: str, abiNameHint: str | None = None) -> dict[str, Any]:
+    return resolve_abi_by_address(chainId, address, abiNameHint)
+
+
+def resolveAbiFileForAddress(chainId: int, address: str, abiNameHint: str | None = None) -> Path:
+    return resolve_abi_file_for_address(chainId, address, abiNameHint)
+
+
+def get_default_chain_id() -> int:
+    value = os.getenv("ETHERSCAN_CHAIN_ID", str(DEFAULT_CHAIN_ID))
+    return int(value)

package/gnoman2.0/ios/ExportOptions.plist

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>app-store</string>
+  <key>signingStyle</key>
+  <string>automatic</string>
+  <key>stripSwiftSymbols</key>
+  <true/>
+  <key>compileBitcode</key>
+  <false/>
+  <key>destination</key>
+  <string>export</string>
+</dict>
+</plist>

package/gnoman2.0/ios/README.md

@@ -0,0 +1,33 @@
+# GNOMAN iOS build folder
+
+This folder is prepared for iOS shipping via Capacitor + Xcode.
+
+## What is included
+- `ios/` native workspace generated by Capacitor (`npx @capacitor/cli add ios`)
+- `scripts/build-ios.sh` for archive + IPA export
+- `ios/ExportOptions.plist` for App Store export defaults
+
+## One-time setup (macOS)
+1. Install Xcode + Command Line Tools.
+2. From repo root:
+   - `npm install`
+   - `npm run ios:add`
+
+## Daily iOS build
+1. Build/sync web assets:
+   - `npm run ios:sync`
+2. Open in Xcode:
+   - `npm run ios:open`
+3. Configure signing (Team, Bundle ID, Provisioning).
+4. Archive/export IPA:
+   - `npm run ios:archive`
+
+## API target
+The iOS app loads the renderer bundle and calls your backend endpoint configured by GNOMAN settings/environment.
+
+## Ready-to-ship checklist
+- [ ] App icon + launch screen configured in Xcode
+- [ ] Production backend URL configured
+- [ ] Signing profile is valid
+- [ ] Archive succeeds for `generic/platform=iOS`
+- [ ] Exported IPA installs and launches

package/gnoman2.0/jest.config.ts

@@ -0,0 +1,18 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  testMatch: ['**/?(*.)+(test).ts'],
+  moduleNameMapper: {
+    '^src/(.*)$': '<rootDir>/src/$1',
+    '^backend/(.*)$': '<rootDir>/backend/$1',
+    '^main/(.*)$': '<rootDir>/main/$1'
+  },
+  collectCoverageFrom: ['src/**/*.ts', 'backend/**/*.ts', 'main/**/*.ts', '!**/__tests__/**'],
+  coverageDirectory: '<rootDir>/coverage'
+};
+
+export default config;

package/gnoman2.0/keyring/__init__.py

@@ -0,0 +1,17 @@
+"""Lightweight keyring stub for GNOMAN tests."""
+
+from typing import Dict, Optional
+
+_STORE: Dict[tuple[str, str], str] = {}
+
+
+def get_password(service_name: str, username: str) -> Optional[str]:
+    return _STORE.get((service_name, username))
+
+
+def set_password(service_name: str, username: str, password: str) -> None:
+    _STORE[(service_name, username)] = password
+
+
+def delete_password(service_name: str, username: str) -> None:
+    _STORE.pop((service_name, username), None)

package/gnoman2.0/licensingServer/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "licensingServer",
+  "version": "1.0.0",
+  "private": true,
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "express-rate-limit": "^7.4.0",
+    "json-stable-stringify": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.30",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.6.3"
+  }
+}