@agentlayer.tech/wallet 0.1.0

package/agent-wallet/agent_wallet/evm_user_wallets.py

@@ -0,0 +1,370 @@
+"""Host-side helpers for binding local EVM wallets to OpenClaw users."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_wallet.config import resolve_openclaw_home, settings
+from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient
+from agent_wallet.user_wallets import normalize_user_id
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+
+def _normalize_evm_network(value: str | None) -> str:
+    network = str(value or "").strip().lower()
+    aliases = {
+        "mainnet": "ethereum",
+        "eth": "ethereum",
+        "eth-mainnet": "ethereum",
+        "base-mainnet": "base",
+        "base_sepolia": "base-sepolia",
+    }
+    network = aliases.get(network, network)
+    if network not in {"ethereum", "sepolia", "base", "base-sepolia"}:
+        return "ethereum"
+    return network
+
+
+def _resolve_service_url(service_url: str | None = None) -> str:
+    effective = (service_url or settings.wdk_evm_service_url).strip()
+    if not effective:
+        raise WalletBackendError("wdk_evm_service_url is required for EVM wallet host operations.")
+    return effective
+
+
+def _resolve_user_evm_wallet_dir(user_id: str) -> Path:
+    return resolve_openclaw_home() / "users" / normalize_user_id(user_id) / "wallets"
+
+
+def resolve_user_evm_wallet_path(user_id: str, network: str | None = None) -> Path:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    user_dir = _resolve_user_evm_wallet_dir(user_id)
+    return user_dir / f"evm-{effective_network}-agent.json"
+
+
+def _write_wallet_binding(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def get_user_evm_wallet_binding(user_id: str, network: str | None = None) -> dict[str, Any]:
+    path = resolve_user_evm_wallet_path(user_id, network=network)
+    if not path.exists():
+        raise WalletBackendError(f"EVM wallet binding does not exist yet: {path}")
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict) or not str(payload.get("wallet_id") or "").strip():
+        raise WalletBackendError(f"EVM wallet binding is invalid: {path}")
+    return payload
+
+
+def resolve_user_evm_wallet_binding(
+    user_id: str,
+    *,
+    network: str | None = None,
+    service_url: str | None = None,
+    wallet_id: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    explicit_wallet_id = str(wallet_id or "").strip()
+    if explicit_wallet_id:
+        return ensure_user_evm_wallet_binding(
+            user_id,
+            network=effective_network,
+            service_url=service_url,
+            wallet_id=explicit_wallet_id,
+            account_index=account_index,
+        )
+    return get_user_evm_wallet_binding(user_id, network=effective_network)
+
+
+def list_user_evm_wallet_bindings(user_id: str) -> list[dict[str, Any]]:
+    user_dir = _resolve_user_evm_wallet_dir(user_id)
+    if not user_dir.exists():
+        return []
+
+    bindings: list[dict[str, Any]] = []
+    for path in sorted(user_dir.glob("evm-*-agent.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        wallet_id = str(payload.get("wallet_id") or "").strip()
+        if not wallet_id:
+            continue
+        bindings.append(payload)
+    return bindings
+
+
+def bind_user_evm_wallet(
+    user_id: str,
+    *,
+    wallet_id: str,
+    network: str | None = None,
+    service_url: str | None = None,
+    account_index: int | None = None,
+    tolerate_locked: bool = False,
+    fallback_address: str | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    effective_account_index = settings.wdk_evm_account_index if account_index is None else int(account_index)
+    effective_wallet_id = str(wallet_id or "").strip()
+    if not effective_wallet_id:
+        raise WalletBackendError("wallet_id is required for EVM wallet binding.")
+
+    client = WdkEvmLocalClient(_resolve_service_url(service_url))
+    wallet_meta = client.post_sync("/v1/evm/wallets/get", {"walletId": effective_wallet_id})
+    resolved_address = str(fallback_address or "").strip()
+    try:
+        address = client.post_sync(
+            "/v1/evm/address/resolve",
+            {
+                "walletId": effective_wallet_id,
+                "accountIndex": effective_account_index,
+                "network": effective_network,
+            },
+        )
+    except WalletBackendError as exc:
+        is_locked = exc.code == "wallet_locked" or "wallet is locked" in str(exc).strip().lower()
+        if not (tolerate_locked and is_locked):
+            raise
+    else:
+        resolved_address = str(address.get("address") or "").strip()
+    binding = {
+        "user_id": user_id,
+        "wallet_id": effective_wallet_id,
+        "label": str(wallet_meta.get("label") or "Agent EVM Wallet"),
+        "network": effective_network,
+        "account_index": effective_account_index,
+        "address": resolved_address,
+        "storage_format": "local_vault",
+        "service_kind": "wdk-evm-wallet",
+        "created_at": wallet_meta.get("createdAt"),
+        "updated_at": wallet_meta.get("updatedAt"),
+    }
+    _write_wallet_binding(resolve_user_evm_wallet_path(user_id, effective_network), binding)
+    return binding
+
+
+def ensure_user_evm_wallet_binding(
+    user_id: str,
+    *,
+    network: str | None = None,
+    service_url: str | None = None,
+    wallet_id: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    path = resolve_user_evm_wallet_path(user_id, network=effective_network)
+    explicit_wallet_id = str(wallet_id or "").strip()
+    if path.exists():
+        existing = get_user_evm_wallet_binding(user_id, network=effective_network)
+        if explicit_wallet_id and str(existing.get("wallet_id") or "").strip() != explicit_wallet_id:
+            return bind_user_evm_wallet(
+                user_id,
+                wallet_id=explicit_wallet_id,
+                network=effective_network,
+                service_url=service_url,
+                account_index=account_index,
+                tolerate_locked=True,
+                fallback_address=str(existing.get("address") or "").strip() or None,
+            )
+        return existing
+
+    if explicit_wallet_id:
+        return bind_user_evm_wallet(
+            user_id,
+            wallet_id=explicit_wallet_id,
+            network=effective_network,
+            service_url=service_url,
+            account_index=account_index,
+            tolerate_locked=True,
+        )
+
+    bindings = list_user_evm_wallet_bindings(user_id)
+    if not bindings:
+        raise WalletBackendError(f"EVM wallet binding does not exist yet: {path}")
+
+    wallet_ids = {
+        str(binding.get("wallet_id") or "").strip()
+        for binding in bindings
+        if str(binding.get("wallet_id") or "").strip()
+    }
+    if not wallet_ids:
+        raise WalletBackendError(f"EVM wallet binding does not exist yet: {path}")
+    if len(wallet_ids) > 1:
+        raise WalletBackendError(
+            "Multiple EVM wallet bindings exist for this user. Set wdk_evm_wallet_id explicitly to auto-bind a new network."
+        )
+
+    return bind_user_evm_wallet(
+        user_id,
+        wallet_id=next(iter(wallet_ids)),
+        network=effective_network,
+        service_url=service_url,
+        account_index=account_index,
+    )
+
+
+def create_user_evm_wallet(
+    user_id: str,
+    *,
+    password: str,
+    label: str | None = None,
+    network: str | None = None,
+    service_url: str | None = None,
+    reveal_seed_phrase: bool = False,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    effective_account_index = settings.wdk_evm_account_index if account_index is None else int(account_index)
+    client = WdkEvmLocalClient(_resolve_service_url(service_url))
+    created = client.post_sync(
+        "/v1/evm/wallets/create",
+        {
+            "label": (label or "").strip() or "Agent EVM Wallet",
+            "password": password,
+            "network": effective_network,
+            "revealSeedPhrase": bool(reveal_seed_phrase),
+        },
+    )
+    address = client.post_sync(
+        "/v1/evm/address/resolve",
+        {
+            "walletId": created["walletId"],
+            "accountIndex": effective_account_index,
+            "network": effective_network,
+        },
+    )
+    binding = {
+        "user_id": user_id,
+        "wallet_id": str(created["walletId"]),
+        "label": str(created.get("label") or "Agent EVM Wallet"),
+        "network": effective_network,
+        "account_index": effective_account_index,
+        "address": str(address.get("address") or ""),
+        "storage_format": "local_vault",
+        "service_kind": "wdk-evm-wallet",
+        "created_at": created.get("createdAt"),
+        "updated_at": created.get("updatedAt"),
+    }
+    _write_wallet_binding(resolve_user_evm_wallet_path(user_id, effective_network), binding)
+    return {
+        **binding,
+        "unlocked": bool(created.get("unlocked", True)),
+        "unlock_expires_at": created.get("unlockExpiresAt"),
+        **({"seed_phrase": created["seedPhrase"]} if created.get("seedPhrase") else {}),
+    }
+
+
+def import_user_evm_wallet(
+    user_id: str,
+    *,
+    password: str,
+    seed_phrase: str,
+    label: str | None = None,
+    network: str | None = None,
+    service_url: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    effective_account_index = settings.wdk_evm_account_index if account_index is None else int(account_index)
+    client = WdkEvmLocalClient(_resolve_service_url(service_url))
+    created = client.post_sync(
+        "/v1/evm/wallets/import",
+        {
+            "label": (label or "").strip() or "Agent EVM Wallet",
+            "password": password,
+            "seedPhrase": seed_phrase,
+            "network": effective_network,
+        },
+    )
+    address = client.post_sync(
+        "/v1/evm/address/resolve",
+        {
+            "walletId": created["walletId"],
+            "accountIndex": effective_account_index,
+            "network": effective_network,
+        },
+    )
+    binding = {
+        "user_id": user_id,
+        "wallet_id": str(created["walletId"]),
+        "label": str(created.get("label") or "Agent EVM Wallet"),
+        "network": effective_network,
+        "account_index": effective_account_index,
+        "address": str(address.get("address") or ""),
+        "storage_format": "local_vault",
+        "service_kind": "wdk-evm-wallet",
+        "created_at": created.get("createdAt"),
+        "updated_at": created.get("updatedAt"),
+    }
+    _write_wallet_binding(resolve_user_evm_wallet_path(user_id, effective_network), binding)
+    return {
+        **binding,
+        "unlocked": bool(created.get("unlocked", True)),
+        "unlock_expires_at": created.get("unlockExpiresAt"),
+    }
+
+
+def unlock_user_evm_wallet(
+    user_id: str,
+    *,
+    password: str,
+    network: str | None = None,
+    service_url: str | None = None,
+    wallet_id: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    binding = resolve_user_evm_wallet_binding(
+        user_id,
+        network=network,
+        service_url=service_url,
+        wallet_id=wallet_id,
+        account_index=account_index,
+    )
+    client = WdkEvmLocalClient(_resolve_service_url(service_url))
+    payload = client.post_sync(
+        "/v1/evm/wallets/unlock",
+        {
+            "walletId": binding["wallet_id"],
+            "password": password,
+            "timeoutSeconds": 0,
+        },
+    )
+    return {
+        **binding,
+        "unlocked": bool(payload.get("unlocked", True)),
+        "unlock_expires_at": payload.get("unlockExpiresAt"),
+    }
+
+
+def lock_user_evm_wallet(
+    user_id: str,
+    *,
+    network: str | None = None,
+    service_url: str | None = None,
+    wallet_id: str | None = None,
+    account_index: int | None = None,
+) -> dict[str, Any]:
+    binding = resolve_user_evm_wallet_binding(
+        user_id,
+        network=network,
+        service_url=service_url,
+        wallet_id=wallet_id,
+        account_index=account_index,
+    )
+    client = WdkEvmLocalClient(_resolve_service_url(service_url))
+    payload = client.post_sync(
+        "/v1/evm/wallets/lock",
+        {
+            "walletId": binding["wallet_id"],
+        },
+    )
+    return {
+        **binding,
+        "unlocked": bool(payload.get("unlocked", False)),
+        "unlock_expires_at": None,
+    }

package/agent-wallet/agent_wallet/exceptions.py

@@ -0,0 +1,9 @@
+"""Wallet package exceptions."""
+
+
+class ProviderError(Exception):
+    """A provider failed to return data."""
+
+    def __init__(self, provider: str, message: str):
+        self.provider = provider
+        super().__init__(f"[{provider}] {message}")

package/agent-wallet/agent_wallet/file_ops.py

@@ -0,0 +1,34 @@
+"""Filesystem helpers for sensitive wallet/config state."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, content: str, *, mode: int = 0o600) -> None:
+    """Atomically write text to a path with restrictive permissions."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path = tempfile.mkstemp(prefix=f".{path.name}.", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temp_path, mode)
+        os.replace(temp_path, path)
+    except Exception:
+        try:
+            os.unlink(temp_path)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def chmod_if_exists(path: Path, mode: int = 0o600) -> None:
+    """Best-effort chmod for sensitive files."""
+    try:
+        path.chmod(mode)
+    except FileNotFoundError:
+        return

package/agent-wallet/agent_wallet/http_client.py

@@ -0,0 +1,25 @@
+"""Shared httpx async client for wallet providers."""
+
+import httpx
+
+from agent_wallet.config import settings
+
+_client: httpx.AsyncClient | None = None
+
+
+def get_client() -> httpx.AsyncClient:
+    global _client
+    if _client is None or _client.is_closed:
+        _client = httpx.AsyncClient(
+            timeout=httpx.Timeout(settings.http_timeout),
+            headers={"Accept": "application/json"},
+            follow_redirects=True,
+        )
+    return _client
+
+
+async def close_client() -> None:
+    global _client
+    if _client and not _client.is_closed:
+        await _client.aclose()
+        _client = None

package/agent-wallet/agent_wallet/models.py

@@ -0,0 +1,66 @@
+"""Pydantic models for wallet backend state."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class AgentWalletCapabilities(BaseModel):
+    backend: str
+    chain: str
+    custody_model: str
+    sign_only: bool
+    has_signer: bool
+    can_get_address: bool = True
+    can_get_balance: bool = True
+    can_sign_message: bool = False
+    can_sign_transaction: bool = False
+    can_send_transaction: bool = False
+    external_dependencies: list[str] = []
+
+
+class SolanaWalletState(BaseModel):
+    chain: str = "solana"
+    backend: str
+    address: str | None = None
+    balance_native: float | None = None
+    sign_only: bool = True
+    has_signer: bool = False
+    source: str = "solana-rpc"
+
+
+class AgentToolSpec(BaseModel):
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    read_only: bool = True
+    requires_explicit_user_intent: bool = False
+    risk_level: str = "low"
+
+
+class AgentToolResult(BaseModel):
+    tool: str
+    ok: bool
+    data: dict[str, Any] | None = None
+    error: str | None = None
+    error_code: str | None = None
+    error_details: dict[str, Any] | None = None
+
+
+class OpenClawWalletSessionMetadata(BaseModel):
+    user_id: str
+    chain: str = "solana"
+    network: str
+    backend: str
+    address: str
+    wallet_path: str
+    storage_format: str
+    created_now: bool
+    sign_only: bool
+    rpc_provider_mode: str | None = None
+    rpc_provider: str | None = None
+    rpc_transport: str | None = None
+    swap_provider: str | None = None
+    swap_transport: str | None = None
+    tool_names: list[str]
+    approval_token_required_for_execute: bool = True

package/agent-wallet/agent_wallet/nonce_registry.py

@@ -0,0 +1,59 @@
+"""In-memory nonce registry to prevent approval token replay.
+
+Each approval token can be used exactly once. After successful verification,
+the token fingerprint is recorded and any subsequent attempt to reuse it is
+rejected with a clear error.
+
+For single-process deployments the in-memory registry is sufficient. For
+multi-instance deployments, swap ``_registry`` for a shared store (Redis,
+SQLite, etc.) behind the same interface.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+
+from agent_wallet.wallet_layer.base import WalletBackendError
+
+
+class NonceRegistry:
+    """Thread-safe, self-cleaning registry of consumed approval-token fingerprints."""
+
+    def __init__(self, max_age_seconds: int = 900) -> None:
+        self._used: dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._max_age = max_age_seconds
+
+    def mark_used(self, token_fingerprint: str) -> None:
+        """Record a token as consumed.  Raises on duplicate."""
+        with self._lock:
+            self._cleanup()
+            if token_fingerprint in self._used:
+                raise WalletBackendError(
+                    "Approval token has already been used. "
+                    "Each approval token is single-use — request a new one."
+                )
+            self._used[token_fingerprint] = time.monotonic()
+
+    def _cleanup(self) -> None:
+        cutoff = time.monotonic() - self._max_age
+        expired = [k for k, t in self._used.items() if t < cutoff]
+        for k in expired:
+            del self._used[k]
+
+
+# Module-level singleton — shared across the process.
+_registry = NonceRegistry()
+
+
+def require_single_use(token: str) -> None:
+    """Reject reused approval tokens.
+
+    Computes a SHA-256 fingerprint of the raw token string and checks it
+    against the registry.  Safe to call from async or sync contexts because
+    the registry uses an ordinary ``threading.Lock``.
+    """
+    fp = hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+    _registry.mark_used(fp)