@agentlayer.tech/wallet 0.1.11 → 0.1.13

package/agent-wallet/scripts/manage_openclaw_evm_wallet.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Host-side helper for managing a local OpenClaw EVM wallet binding."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from getpass import getpass
+from pathlib import Path
+from urllib.error import URLError
+from urllib.request import urlopen
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+from agent_wallet.config import settings  # noqa: E402
+from agent_wallet.evm_user_wallets import (  # noqa: E402
+    bind_user_evm_wallet,
+    create_user_evm_wallet,
+    get_user_evm_wallet_binding,
+    import_user_evm_wallet,
+    list_user_evm_wallet_bindings,
+    lock_user_evm_wallet,
+    unlock_user_evm_wallet,
+)
+from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient  # noqa: E402
+
+
+def _normalize_network(value: str) -> 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 _paired_network(network: str) -> str | None:
+    mapping = {
+        "ethereum": "base",
+        "base": "ethereum",
+        "sepolia": "base-sepolia",
+        "base-sepolia": "sepolia",
+    }
+    return mapping.get(_normalize_network(network))
+
+
+def _read_secret(
+    *,
+    prompt: str,
+    confirm_prompt: str | None = None,
+    stdin_mode: bool = False,
+) -> str:
+    if stdin_mode:
+        value = sys.stdin.read().strip()
+        if not value:
+            raise SystemExit(f"{prompt.rstrip(':')} is required on stdin.")
+        return value
+    value = getpass(prompt)
+    if confirm_prompt is not None:
+        confirmed = getpass(confirm_prompt)
+        if value != confirmed:
+            raise SystemExit("Secrets did not match.")
+    if not value.strip():
+        raise SystemExit(f"{prompt.rstrip(':')} is required.")
+    return value.strip()
+
+
+def _read_password_and_seed_from_stdin() -> tuple[str, str]:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        raise SystemExit("Password and seed phrase payload is required on stdin.")
+    lines = raw.splitlines()
+    if len(lines) < 2:
+        raise SystemExit(
+            "For import via stdin, provide password on the first line and the seed phrase on the remaining lines."
+        )
+    password = lines[0].strip()
+    seed_phrase = " ".join(line.strip() for line in lines[1:] if line.strip())
+    if not password or not seed_phrase:
+        raise SystemExit("Both password and seed phrase are required.")
+    return password, seed_phrase
+
+
+def _service_health(service_url: str | None) -> dict[str, object]:
+    target = str(service_url or "").strip()
+    if not target:
+        return {"service_url": None, "healthy": False, "error": "service_url is not configured"}
+    health_url = f"{target.rstrip('/')}/health"
+    try:
+        with urlopen(health_url, timeout=1.5) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+            return {
+                "service_url": target,
+                "healthy": int(getattr(response, "status", 0) or 0) == 200,
+                "health": payload,
+            }
+    except (URLError, TimeoutError, OSError, ValueError) as exc:
+        return {"service_url": target, "healthy": False, "error": str(exc)}
+
+
+def _status_payload(user_id: str | None, network: str | None, service_url: str | None) -> dict[str, object]:
+    target_service_url = str(service_url or settings.wdk_evm_service_url).strip() or None
+    payload: dict[str, object] = {
+        "ok": True,
+        "network": _normalize_network(network or "ethereum"),
+        "service": _service_health(target_service_url),
+    }
+    target_network = _normalize_network(network or "ethereum")
+    if target_service_url:
+        try:
+            payload["network_info"] = WdkEvmLocalClient(target_service_url).get_sync("/v1/evm/network")
+        except Exception as exc:  # pragma: no cover - defensive
+            payload["network_info_error"] = str(exc)
+    if user_id:
+        payload["bindings"] = list_user_evm_wallet_bindings(user_id)
+        try:
+            payload["binding"] = get_user_evm_wallet_binding(user_id, network=target_network)
+        except Exception as exc:
+            payload["binding_error"] = str(exc)
+    return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Manage a local OpenClaw EVM wallet binding")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    common_parent = argparse.ArgumentParser(add_help=False)
+    common_parent.add_argument("--network", default="ethereum")
+    common_parent.add_argument("--service-url")
+
+    get_parser = subparsers.add_parser("get", parents=[common_parent])
+    get_parser.add_argument("--user-id", required=True)
+
+    list_parser = subparsers.add_parser("list", parents=[common_parent])
+    list_parser.add_argument("--user-id", required=True)
+
+    status_parser = subparsers.add_parser("status", parents=[common_parent])
+    status_parser.add_argument("--user-id", default="")
+
+    setup_parser = subparsers.add_parser("setup", parents=[common_parent])
+    setup_parser.add_argument("--user-id", required=True)
+    setup_parser.add_argument("--label")
+    setup_parser.add_argument("--account-index", type=int)
+    setup_parser.add_argument("--password-stdin", action="store_true")
+    setup_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    create_parser = subparsers.add_parser("create", parents=[common_parent])
+    create_parser.add_argument("--user-id", required=True)
+    create_parser.add_argument("--label")
+    create_parser.add_argument("--account-index", type=int)
+    create_parser.add_argument("--reveal-seed", action="store_true")
+    create_parser.add_argument("--password-stdin", action="store_true")
+    create_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    import_parser = subparsers.add_parser("import", parents=[common_parent])
+    import_parser.add_argument("--user-id", required=True)
+    import_parser.add_argument("--label")
+    import_parser.add_argument("--account-index", type=int)
+    import_parser.add_argument("--password-stdin", action="store_true")
+    import_parser.add_argument("--seed-stdin", action="store_true")
+    import_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    unlock_parser = subparsers.add_parser("unlock", parents=[common_parent])
+    unlock_parser.add_argument("--user-id", required=True)
+    unlock_parser.add_argument("--password-stdin", action="store_true")
+    unlock_parser.add_argument("--wallet-id", default="")
+    unlock_parser.add_argument("--account-index", type=int)
+    unlock_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    lock_parser = subparsers.add_parser("lock", parents=[common_parent])
+    lock_parser.add_argument("--user-id", required=True)
+    lock_parser.add_argument("--wallet-id", default="")
+    lock_parser.add_argument("--account-index", type=int)
+
+    args = parser.parse_args()
+    effective_network = _normalize_network(args.network)
+
+    def _config_hint(wallet: dict[str, object]) -> dict[str, object]:
+        return {
+            "backend": "wdk_evm_local",
+            "network": effective_network,
+            "wdkEvmServiceUrl": args.service_url,
+            "wdkEvmWalletId": wallet.get("wallet_id"),
+            "wdkEvmAccountIndex": wallet.get("account_index"),
+        }
+
+    def _bind_pair(wallet: dict[str, object]) -> dict[str, object] | None:
+        if not getattr(args, "bind_network_pair", False):
+            return None
+        paired = _paired_network(effective_network)
+        if not paired:
+            return None
+        return bind_user_evm_wallet(
+            args.user_id,
+            wallet_id=str(wallet.get("wallet_id") or ""),
+            network=paired,
+            service_url=args.service_url,
+            account_index=wallet.get("account_index"),
+            tolerate_locked=True,
+            fallback_address=str(wallet.get("address") or "").strip() or None,
+        )
+
+    if args.command == "status":
+        payload = _status_payload(args.user_id or None, effective_network, args.service_url)
+    elif args.command == "list":
+        payload = {"ok": True, "wallets": list_user_evm_wallet_bindings(args.user_id)}
+    elif args.command == "get":
+        wallet = get_user_evm_wallet_binding(args.user_id, network=effective_network)
+        payload = {"ok": True, "wallet": wallet, "openclaw_config_hint": _config_hint(wallet)}
+    elif args.command == "setup":
+        password = _read_secret(
+            prompt="EVM wallet password: ",
+            confirm_prompt=None,
+            stdin_mode=bool(args.password_stdin),
+        )
+        try:
+            existing = get_user_evm_wallet_binding(args.user_id, network=effective_network)
+        except Exception:
+            existing = None
+
+        if existing is None:
+            wallet = create_user_evm_wallet(
+                args.user_id,
+                password=password,
+                label=args.label,
+                network=effective_network,
+                service_url=args.service_url,
+                account_index=args.account_index,
+            )
+            paired_binding = _bind_pair(wallet)
+            payload = {
+                "ok": True,
+                "action": "created",
+                "wallet": wallet,
+                "paired_binding": paired_binding,
+                "openclaw_config_hint": _config_hint(wallet),
+            }
+        else:
+            wallet = unlock_user_evm_wallet(
+                args.user_id,
+                password=password,
+                network=effective_network,
+                service_url=args.service_url,
+                account_index=args.account_index,
+            )
+            paired_binding = _bind_pair(wallet)
+            payload = {
+                "ok": True,
+                "action": "unlocked",
+                "wallet": wallet,
+                "paired_binding": paired_binding,
+                "openclaw_config_hint": _config_hint(wallet),
+            }
+    elif args.command == "create":
+        wallet = create_user_evm_wallet(
+            args.user_id,
+            password=_read_secret(
+                prompt="EVM wallet password: ",
+                confirm_prompt="Confirm EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            ),
+            label=args.label,
+            network=effective_network,
+            service_url=args.service_url,
+            reveal_seed_phrase=bool(args.reveal_seed),
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    elif args.command == "import":
+        if args.password_stdin and args.seed_stdin:
+            password, seed_phrase = _read_password_and_seed_from_stdin()
+        else:
+            password = _read_secret(
+                prompt="EVM wallet password: ",
+                confirm_prompt="Confirm EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            )
+            seed_phrase = _read_secret(
+                prompt="EVM seed phrase: ",
+                stdin_mode=bool(args.seed_stdin),
+            )
+        wallet = import_user_evm_wallet(
+            args.user_id,
+            password=password,
+            seed_phrase=seed_phrase,
+            label=args.label,
+            network=effective_network,
+            service_url=args.service_url,
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    elif args.command == "unlock":
+        wallet = unlock_user_evm_wallet(
+            args.user_id,
+            password=_read_secret(
+                prompt="EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            ),
+            network=effective_network,
+            service_url=args.service_url,
+            wallet_id=args.wallet_id or None,
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    else:
+        payload = {
+            "ok": True,
+            "wallet": lock_user_evm_wallet(
+                args.user_id,
+                network=effective_network,
+                service_url=args.service_url,
+                wallet_id=args.wallet_id or None,
+                account_index=args.account_index,
+            ),
+        }
+
+    print(json.dumps(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agent-wallet/scripts/setup_evm_wallet.sh

@@ -0,0 +1,151 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+PACKAGE_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+
+resolve_python_bin() {
+  if [ -n "${OPENCLAW_AGENT_WALLET_PYTHON:-}" ] && [ -x "${OPENCLAW_AGENT_WALLET_PYTHON}" ]; then
+    printf "%s" "${OPENCLAW_AGENT_WALLET_PYTHON}"
+    return 0
+  fi
+
+  if [ -x "/tmp/agent-wallet-venv/bin/python" ]; then
+    printf "%s" "/tmp/agent-wallet-venv/bin/python"
+    return 0
+  fi
+
+  if [ -x "$PACKAGE_ROOT/.venv/bin/python" ]; then
+    printf "%s" "$PACKAGE_ROOT/.venv/bin/python"
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3
+    return 0
+  fi
+
+  command -v python
+}
+
+PYTHON_BIN=$(resolve_python_bin)
+export OPENCLAW_AGENT_WALLET_PYTHON="$PYTHON_BIN"
+
+has_flag() {
+  flag=$1
+  shift
+  for arg in "$@"; do
+    case "$arg" in
+      "$flag"|"$flag"=*)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+prompt_with_default() {
+  label=$1
+  default_value=$2
+  if [ -t 0 ]; then
+    printf "%s [%s]: " "$label" "$default_value" >&2
+    read -r value
+    if [ -z "${value:-}" ]; then
+      printf "%s" "$default_value"
+    else
+      printf "%s" "$value"
+    fi
+    return 0
+  fi
+  printf "%s" "$default_value"
+}
+
+normalize_network_value() {
+  case $(printf "%s" "$1" | tr '[:upper:]' '[:lower:]') in
+    1|ethereum|eth|mainnet)
+      printf "ethereum"
+      ;;
+    2|base)
+      printf "base"
+      ;;
+    3|sepolia)
+      printf "sepolia"
+      ;;
+    4|base-sepolia|base_sepolia)
+      printf "base-sepolia"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+prompt_network_choice() {
+  default_value=$1
+  if ! [ -t 0 ]; then
+    printf "%s" "$default_value"
+    return 0
+  fi
+
+  case "$default_value" in
+    ethereum) default_hint="1" ;;
+    base) default_hint="2" ;;
+    sepolia) default_hint="3" ;;
+    base-sepolia) default_hint="4" ;;
+    *) default_hint="2" ;;
+  esac
+
+  while true; do
+    printf "EVM network:\n" >&2
+    printf "  1) ethereum\n" >&2
+    printf "  2) base\n" >&2
+    printf "  3) sepolia\n" >&2
+    printf "  4) base-sepolia\n" >&2
+    printf "Choose network [%s]: " "$default_hint" >&2
+    read -r choice
+    if [ -z "${choice:-}" ]; then
+      choice=$default_hint
+    fi
+    if network=$(normalize_network_value "$choice"); then
+      printf "%s" "$network"
+      return 0
+    fi
+    printf "Invalid choice. Enter 1, 2, 3, 4, ethereum, base, sepolia, or base-sepolia.\n" >&2
+  done
+}
+
+DEFAULT_USER_ID=${OPENCLAW_EVM_USER_ID:-${USER:-openclaw-user}-local}
+DEFAULT_NETWORK=${OPENCLAW_EVM_NETWORK:-base}
+DEFAULT_SERVICE_URL=${OPENCLAW_EVM_SERVICE_URL:-http://127.0.0.1:8081}
+
+if ! has_flag --user-id "$@"; then
+  USER_ID=$(prompt_with_default "OpenClaw user id" "$DEFAULT_USER_ID")
+  set -- "$@" --user-id "$USER_ID"
+fi
+
+if ! has_flag --network "$@"; then
+  NETWORK=$(prompt_network_choice "$DEFAULT_NETWORK")
+  set -- "$@" --network "$NETWORK"
+fi
+
+if ! has_flag --service-url "$@"; then
+  set -- "$@" --service-url "$DEFAULT_SERVICE_URL"
+fi
+
+if ! has_flag --config-path "$@" && [ -n "${OPENCLAW_EVM_CONFIG_PATH:-}" ]; then
+  set -- "$@" --config-path "$OPENCLAW_EVM_CONFIG_PATH"
+fi
+
+if ! has_flag --wdk-wallet-root "$@" && [ -n "${OPENCLAW_EVM_WDK_WALLET_ROOT:-}" ]; then
+  set -- "$@" --wdk-wallet-root "$OPENCLAW_EVM_WDK_WALLET_ROOT"
+fi
+
+if ! has_flag --python-bin "$@"; then
+  set -- "$@" --python-bin "$PYTHON_BIN"
+fi
+
+if ! has_flag --package-root "$@"; then
+  set -- "$@" --package-root "$PACKAGE_ROOT"
+fi
+
+exec "$PYTHON_BIN" "$SCRIPT_DIR/bootstrap_openclaw_evm.py" "$@"

package/hermes/plugins/agent_wallet/__init__.py

@@ -1,7 +1,19 @@
 """Hermes Agent plugin bridge for AgentLayer wallet tools."""
 
-from .schemas import AGENT_WALLET_APPROVE, AGENT_WALLET_INVOKE, AGENT_WALLET_TOOLS
-from .tools import agent_wallet_approve, agent_wallet_invoke, agent_wallet_tools
+from .schemas import (
+    AGENT_WALLET_APPROVE,
+    AGENT_WALLET_EVM_SETUP,
+    AGENT_WALLET_EVM_STATUS,
+    AGENT_WALLET_INVOKE,
+    AGENT_WALLET_TOOLS,
+)
+from .tools import (
+    agent_wallet_approve,
+    agent_wallet_evm_setup,
+    agent_wallet_evm_status,
+    agent_wallet_invoke,
+    agent_wallet_tools,
+)
 
 
 def register(ctx):
@@ -27,3 +39,17 @@ def register(ctx):
         handler=agent_wallet_approve,
         description=AGENT_WALLET_APPROVE["description"],
     )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_STATUS["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_STATUS,
+        handler=agent_wallet_evm_status,
+        description=AGENT_WALLET_EVM_STATUS["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_SETUP["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_SETUP,
+        handler=agent_wallet_evm_setup,
+        description=AGENT_WALLET_EVM_SETUP["description"],
+    )

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -5,3 +5,5 @@ provides_tools:
   - agent_wallet_tools
   - agent_wallet_invoke
   - agent_wallet_approve
+  - agent_wallet_evm_status
+  - agent_wallet_evm_setup

package/hermes/plugins/agent_wallet/schemas.py

@@ -132,3 +132,75 @@ AGENT_WALLET_APPROVE = {
         "additionalProperties": False,
     },
 }
+
+AGENT_WALLET_EVM_STATUS = {
+    "name": "agent_wallet_evm_status",
+    "description": (
+        "Inspect the local EVM wallet runtime used by AgentLayer/OpenClaw. "
+        "Returns wdk-evm-wallet health, network info, and existing user wallet "
+        "bindings without changing wallet state."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id to inspect.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Optional EVM network hint, such as ethereum, base, sepolia, or base-sepolia.",
+            },
+            "service_url": {
+                "type": "string",
+                "description": "Optional localhost override for the wdk-evm-wallet service.",
+            },
+        },
+        "additionalProperties": False,
+    },
+}
+
+AGENT_WALLET_EVM_SETUP = {
+    "name": "agent_wallet_evm_setup",
+    "description": (
+        "Create or unlock the local EVM wallet binding used by AgentLayer/OpenClaw "
+        "for Hermes. This can auto-start the localhost-only wdk-evm-wallet service, "
+        "set up the selected network, and bind the same wallet to the paired EVM network "
+        "such as ethereum/base."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "password": {
+                "type": "string",
+                "description": "Local EVM wallet password used to create or unlock the vault wallet.",
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id. Defaults to AGENT_WALLET_USER_ID, USER, or hermes-local-user.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Selected EVM network, typically ethereum or base.",
+            },
+            "label": {
+                "type": "string",
+                "description": "Optional wallet label used when creating a new local EVM wallet.",
+            },
+            "service_url": {
+                "type": "string",
+                "description": "Optional localhost override for the wdk-evm-wallet service.",
+            },
+            "auto_start_service": {
+                "type": "boolean",
+                "description": "Whether to auto-start the local wdk-evm-wallet service when it is not healthy. Defaults to true.",
+            },
+            "bind_network_pair": {
+                "type": "boolean",
+                "description": "Whether to also bind the paired EVM network such as ethereum/base. Defaults to true.",
+            },
+        },
+        "required": ["password"],
+        "additionalProperties": False,
+    },
+}