gnoman 0.1.0

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

@@ -0,0 +1,57 @@
+import type { Request, Response } from 'express';
+
+jest.mock('../backend/services/walletService', () => ({
+  importWalletFromMnemonic: jest.fn(async (payload: unknown) => payload)
+}));
+
+import { importWalletFromMnemonic } from '../backend/services/walletService';
+import { importMnemonic } from '../backend/controllers/walletController';
+
+const mockedImportWalletFromMnemonic = importWalletFromMnemonic as jest.MockedFunction<
+  typeof importWalletFromMnemonic
+>;
+
+describe('walletController importMnemonic', () => {
+  afterEach(() => {
+    mockedImportWalletFromMnemonic.mockClear();
+  });
+
+  it('accepts derivationPath field from request body', async () => {
+    const req = {
+      body: {
+        mnemonic: 'test test test test test test test test test test test junk',
+        alias: 'alpha',
+        password: 'pw',
+        derivationPath: "m/44'/60'/0'/0/7",
+        hidden: true
+      }
+    } as Request;
+    const json = jest.fn();
+    const res = { json } as unknown as Response;
+
+    await importMnemonic(req, res, jest.fn());
+
+    expect(mockedImportWalletFromMnemonic).toHaveBeenCalledWith(
+      expect.objectContaining({ derivationPath: "m/44'/60'/0'/0/7" })
+    );
+    expect(json).toHaveBeenCalled();
+  });
+
+  it('falls back to legacy path field when derivationPath is not provided', async () => {
+    const req = {
+      body: {
+        mnemonic: 'test test test test test test test test test test test junk',
+        path: "m/44'/60'/0'/0/3"
+      }
+    } as Request;
+    const json = jest.fn();
+    const res = { json } as unknown as Response;
+
+    await importMnemonic(req, res, jest.fn());
+
+    expect(mockedImportWalletFromMnemonic).toHaveBeenCalledWith(
+      expect.objectContaining({ derivationPath: "m/44'/60'/0'/0/3" })
+    );
+    expect(json).toHaveBeenCalled();
+  });
+});

package/gnoman2.0/tsconfig.backend.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/backend"
+  },
+  "include": ["backend/**/*.ts", "backend/types/**/*.d.ts", "modules/**/*.ts", "src/**/*.ts", "cli/**/*.ts"]
+}

package/gnoman2.0/tsconfig.cli.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/cli"
+  },
+  "include": ["cli/**/*.ts", "src/**/*.ts"]
+}

package/gnoman2.0/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020", "DOM"],
+    "strict": true,
+    "moduleResolution": "Node",
+    "esModuleInterop": true,
+    "types": ["node", "cors", "better-sqlite3", "jest"],
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "sourceMap": true,
+    "outDir": "dist"
+  },
+  "exclude": ["renderer", "node_modules", "dist"]
+}

package/gnoman2.0/tsconfig.main.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/main"
+  },
+  "include": ["main/**/*.ts", "src/**/*.ts"]
+}

package/gnomon/api/etherscan_tracker.py

@@ -0,0 +1,72 @@
+"""
+Etherscan Tracker Integration for GNOMAN
+Tracks Safe transactions and performs lookup queries.
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+
+import requests
+from keyring import get_password
+
+SAFE_STATE_PATH = Path("state/gnosis_safe_state.json")
+LOG_PATH = Path("logs/safe_tx_log.json")
+ETHERSCAN_BASE_URL = "https://api.etherscan.io/api"
+POLL_INTERVAL = 30  # seconds
+
+
+def get_etherscan_api_key() -> str:
+    service = os.getenv("GNOMAN_KEYRING_SERVICE", "gnoman")
+    api_key = get_password(service, "ETHERSCAN_API_KEY")
+    if not api_key:
+        raise RuntimeError("ETHERSCAN_API_KEY is not configured in the keyring.")
+    return api_key
+
+
+def get_safe_address() -> str:
+    with open(SAFE_STATE_PATH, encoding="utf-8") as handle:
+        data = json.load(handle)
+    return data["address"]
+
+
+def load_safe_state() -> dict:
+    if not SAFE_STATE_PATH.exists():
+        raise RuntimeError("Safe state missing — persistence failure detected.")
+    with open(SAFE_STATE_PATH, encoding="utf-8") as handle:
+        state = json.load(handle)
+    if not state.get("owners") or len(state["owners"]) < 3:
+        raise ValueError("Safe loaded without correct owner list (3 required).")
+    return state
+
+
+def fetch_transactions(address: str, api_key: str | None = None):
+    api_key = api_key or get_etherscan_api_key()
+    url = (
+        f"{ETHERSCAN_BASE_URL}?module=account&action=txlist&address={address}"
+        f"&apikey={api_key}"
+    )
+    response = requests.get(url, timeout=20)
+    response.raise_for_status()
+    data = response.json()
+    if data["status"] != "1":
+        raise ValueError(f"Etherscan error: {data['message']}")
+    return data["result"]
+
+
+def track_safe_transactions():
+    safe = load_safe_state()
+    api_key = get_etherscan_api_key()
+    LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    print(f"[EtherscanTracker] Tracking transactions for Safe: {safe['address']}")
+    while True:
+        txs = fetch_transactions(safe["address"], api_key)
+        with open(LOG_PATH, "w", encoding="utf-8") as handle:
+            json.dump(txs, handle, indent=2)
+        print(f"[EtherscanTracker] {len(txs)} transactions logged.")
+        time.sleep(POLL_INTERVAL)
+
+
+if __name__ == "__main__":
+    track_safe_transactions()

package/gnomon/core/safe_manager.py

@@ -0,0 +1,111 @@
+"""Safe manager utilities for persisting and reloading Safe state."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, Optional
+
+SAFE_STATE_PATH = Path("state/gnosis_safe_state.json")
+
+
+def _normalize_owners(raw_owners: Any) -> list[str]:
+    if raw_owners is None:
+        return []
+    if callable(raw_owners):
+        raw_owners = raw_owners()
+    if isinstance(raw_owners, dict):
+        raw_owners = list(raw_owners.values())
+    if isinstance(raw_owners, str):
+        return [raw_owners]
+    if isinstance(raw_owners, Iterable):
+        return [str(owner) for owner in raw_owners]
+    return []
+
+
+def _extract_threshold(safe_instance: Any) -> int:
+    threshold = None
+    if hasattr(safe_instance, "getThreshold"):
+        threshold = safe_instance.getThreshold()
+    elif hasattr(safe_instance, "threshold"):
+        attr = safe_instance.threshold
+        threshold = attr() if callable(attr) else attr
+    if threshold is None:
+        raise ValueError("Safe instance does not expose a threshold value")
+    return int(threshold)
+
+
+def persist_safe_state(safe_instance: Any) -> Dict[str, Any]:
+    """Persist the current Safe metadata to disk.
+
+    Parameters
+    ----------
+    safe_instance: Any
+        Object exposing ``address``, ``owners`` (method or iterable) and
+        ``getThreshold`` or ``threshold``.
+    """
+
+    if safe_instance is None:
+        raise ValueError("Safe instance is required to persist state")
+
+    address = getattr(safe_instance, "address", None)
+    if callable(address):  # defensive: handle SDKs exposing callables
+        address = address()
+    if not address:
+        raise ValueError("Safe instance is missing an address")
+
+    owners = _normalize_owners(getattr(safe_instance, "owners", None))
+    if len(owners) < 3:
+        raise ValueError("Safe must have at least three owners before persisting")
+
+    threshold = _extract_threshold(safe_instance)
+
+    SAFE_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data = {"address": str(address), "owners": owners, "threshold": threshold}
+    with open(SAFE_STATE_PATH, "w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+    print("[SafeManager] Safe state persisted successfully.")
+    return data
+
+
+def load_persisted_safe() -> Dict[str, Any]:
+    if not SAFE_STATE_PATH.exists():
+        raise RuntimeError("Safe state file missing.")
+    with open(SAFE_STATE_PATH, "r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    owners = data.get("owners") or []
+    if len(owners) < 3:
+        raise ValueError("Invalid Safe state — missing or incomplete owners.")
+    print(f"[SafeManager] Loaded Safe with owners: {owners}")
+    return data
+
+
+class SafeManager:
+    """Utility orchestrating Safe persistence and retrieval."""
+
+    def __init__(self, safe_factory: Callable[..., Any]):
+        self._safe_factory = safe_factory
+        self._safe_instance: Optional[Any] = None
+
+    @property
+    def safe(self) -> Any:
+        if self._safe_instance is None:
+            raise RuntimeError("Safe has not been initialised. Call `load_safe`." )
+        return self._safe_instance
+
+    def load_safe(self, *factory_args: Any, **factory_kwargs: Any) -> Any:
+        """Instantiate a Safe instance and persist its state immediately."""
+        safe_instance = self._safe_factory(*factory_args, **factory_kwargs)
+        self._safe_instance = safe_instance
+        persist_safe_state(safe_instance)
+        return safe_instance
+
+    def refresh_state(self) -> Dict[str, Any]:
+        """Persist the currently tracked Safe instance again and return the cache."""
+        if self._safe_instance is None:
+            raise RuntimeError("Safe has not been initialised.")
+        return persist_safe_state(self._safe_instance)
+
+    def get_cached_state(self) -> Dict[str, Any]:
+        """Load Safe metadata from the persisted cache on disk."""
+        return load_persisted_safe()

package/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/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/gnomon/utils/__init__.py

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