@agentlayer.tech/wallet 0.1.0

package/agent-wallet/agent_wallet/openclaw_runtime.py

@@ -0,0 +1,272 @@
+"""Host-side onboarding helpers for wiring agent-wallet into OpenClaw."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agent_wallet.approval import issue_approval_token
+from agent_wallet.btc_user_wallets import get_user_btc_wallet_binding
+from agent_wallet.config import settings
+from agent_wallet.evm_user_wallets import ensure_user_evm_wallet_binding, get_user_evm_wallet_binding
+from agent_wallet.models import OpenClawWalletSessionMetadata
+from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
+from agent_wallet.plugin_bundle import build_openclaw_plugin_bundle
+from agent_wallet.providers.wdk_btc_local import WdkBtcLocalClient
+from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient
+from agent_wallet.user_wallets import create_wallet_backend_for_user, ensure_user_solana_wallet, resolve_user_wallet_path
+from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendError
+from agent_wallet.wallet_layer.wdk_evm import WdkEvmLocalWalletBackend
+from agent_wallet.wallet_layer.wdk_btc import WdkBtcLocalWalletBackend
+
+
+@dataclass(slots=True)
+class OpenClawWalletRuntimeContext:
+    """Runtime-ready wallet context for a single OpenClaw user session."""
+
+    user_id: str
+    wallet_info: dict[str, str]
+    created_now: bool
+    backend: AgentWalletBackend
+    adapter: OpenClawWalletAdapter
+    plugin_bundle: dict[str, Any]
+
+    def issue_execute_approval(
+        self,
+        *,
+        tool_name: str,
+        confirmation_summary: dict[str, Any],
+        mainnet_confirmed: bool = False,
+        ttl_seconds: int | None = None,
+        issued_by: str = "host",
+    ) -> str:
+        """Issue a host approval token bound to an exact execute operation."""
+        return issue_approval_token(
+            tool_name=tool_name,
+            network=str(getattr(self.backend, "network", "mainnet")),
+            summary=confirmation_summary,
+            mainnet_confirmed=mainnet_confirmed,
+            ttl_seconds=ttl_seconds,
+            issued_by=issued_by,
+        )
+
+    def session_metadata(self) -> OpenClawWalletSessionMetadata:
+        """Return serializable metadata for host runtime/session storage."""
+        tool_names = [tool["name"] for tool in self.plugin_bundle["tools"]]
+        capabilities = self.backend.get_capabilities()
+        return OpenClawWalletSessionMetadata(
+            user_id=self.user_id,
+            chain=capabilities.chain,
+            network=str(getattr(self.backend, "network", "mainnet")),
+            backend=self.backend.name,
+            address=self.wallet_info["address"],
+            wallet_path=self.wallet_info["path"],
+            storage_format=self.wallet_info["storage_format"],
+            created_now=self.created_now,
+            sign_only=bool(getattr(self.backend, "sign_only", True)),
+            rpc_provider_mode=getattr(self.backend, "rpc_provider_mode", None),
+            rpc_provider=getattr(self.backend, "rpc_provider", None),
+            rpc_transport=getattr(self.backend, "rpc_transport", None),
+            swap_provider=getattr(self.backend, "swap_provider", None),
+            swap_transport=getattr(self.backend, "swap_transport", None),
+            tool_names=tool_names,
+        )
+
+    def serializable_bundle(self) -> dict[str, Any]:
+        """Return the plugin bundle without the invoke callable for JSON/session transport."""
+        return {
+            "manifest": self.plugin_bundle["manifest"],
+            "instructions": self.plugin_bundle["instructions"],
+            "tools": self.plugin_bundle["tools"],
+            "session": self.session_metadata().model_dump(),
+        }
+
+
+def onboard_openclaw_user_wallet(
+    user_id: str,
+    *,
+    backend: str | None = None,
+    sign_only: bool | None = None,
+    network: str | None = None,
+    rpc_url: str | None = None,
+    wdk_btc_service_url: str | None = None,
+    wdk_btc_wallet_id: str | None = None,
+    wdk_btc_account_index: int | None = None,
+    wdk_evm_service_url: str | None = None,
+    wdk_evm_wallet_id: str | None = None,
+    wdk_evm_account_index: int | None = None,
+) -> OpenClawWalletRuntimeContext:
+    """Provision and assemble a runtime-ready wallet context for one OpenClaw user."""
+    backend_name = str(backend or settings.agent_wallet_backend).strip().lower()
+    if backend_name in {"wdk_btc_local", "wdk-btc-local", "btc_local", "btc-local"}:
+        service_url = str(wdk_btc_service_url or settings.wdk_btc_service_url).strip()
+        account_index = (
+            settings.wdk_btc_account_index
+            if wdk_btc_account_index is None
+            else int(wdk_btc_account_index)
+        )
+        requested_network = (network or settings.solana_network).strip().lower() or "bitcoin"
+        effective_network = "bitcoin" if requested_network == "mainnet" else requested_network
+        binding: dict[str, Any] | None = None
+        wallet_id = str(wdk_btc_wallet_id or settings.wdk_btc_wallet_id).strip()
+        if not service_url:
+            raise WalletBackendError("wdk_btc_service_url is required for backend=wdk_btc_local.")
+        if not wallet_id:
+            binding = get_user_btc_wallet_binding(user_id, network=effective_network)
+            wallet_id = str(binding.get("wallet_id") or "").strip()
+        if not wallet_id:
+            raise WalletBackendError(
+                "wdk_btc_wallet_id is required for backend=wdk_btc_local, or create a bound user BTC wallet first."
+            )
+
+        client = WdkBtcLocalClient(service_url)
+        wallet_meta = client.post_sync("/v1/btc/wallets/get", {"walletId": wallet_id})
+        address_payload = client.post_sync(
+            "/v1/btc/address/resolve",
+            {
+                "walletId": wallet_id,
+                "accountIndex": account_index,
+                "network": effective_network,
+            },
+        )
+        backend = WdkBtcLocalWalletBackend(
+            service_url=service_url,
+            wallet_id=wallet_id,
+            network=effective_network,
+            account_index=account_index,
+            sign_only=settings.agent_wallet_sign_only if sign_only is None else sign_only,
+            address=str(address_payload.get("address") or "").strip() or None,
+        )
+        wallet_info = {
+            "user_id": user_id,
+            "address": str(address_payload.get("address") or (binding or {}).get("address") or ""),
+            "path": f"{service_url}#walletId={wallet_id}",
+            "storage_format": "local_vault",
+            "key_scope": "host-managed",
+            "wallet_id": wallet_id,
+            "label": str(wallet_meta.get("label") or (binding or {}).get("label") or "BTC Wallet"),
+        }
+        adapter = OpenClawWalletAdapter(backend)
+        plugin_bundle = build_openclaw_plugin_bundle(backend)
+        return OpenClawWalletRuntimeContext(
+            user_id=user_id,
+            wallet_info=wallet_info,
+            created_now=False,
+            backend=backend,
+            adapter=adapter,
+            plugin_bundle=plugin_bundle,
+        )
+
+    if backend_name in {"wdk_evm_local", "wdk-evm-local", "evm_local", "evm-local"}:
+        service_url = str(wdk_evm_service_url or settings.wdk_evm_service_url).strip()
+        account_index = (
+            settings.wdk_evm_account_index
+            if wdk_evm_account_index is None
+            else int(wdk_evm_account_index)
+        )
+        requested_network = (network or settings.solana_network).strip().lower() or "ethereum"
+        aliases = {
+            "mainnet": "ethereum",
+            "eth": "ethereum",
+            "eth-mainnet": "ethereum",
+            "base-mainnet": "base",
+            "base_sepolia": "base-sepolia",
+        }
+        effective_network = aliases.get(requested_network, requested_network)
+        binding: dict[str, Any] | None = None
+        wallet_id = str(wdk_evm_wallet_id or settings.wdk_evm_wallet_id).strip()
+        if not service_url:
+            raise WalletBackendError("wdk_evm_service_url is required for backend=wdk_evm_local.")
+        if wallet_id:
+            try:
+                binding = get_user_evm_wallet_binding(user_id, network=effective_network)
+            except WalletBackendError:
+                binding = ensure_user_evm_wallet_binding(
+                    user_id,
+                    network=effective_network,
+                    service_url=service_url,
+                    wallet_id=wallet_id,
+                    account_index=account_index,
+                )
+            else:
+                if str(binding.get("wallet_id") or "").strip() != wallet_id:
+                    binding = ensure_user_evm_wallet_binding(
+                        user_id,
+                        network=effective_network,
+                        service_url=service_url,
+                        wallet_id=wallet_id,
+                        account_index=account_index,
+                    )
+        else:
+            binding = ensure_user_evm_wallet_binding(
+                user_id,
+                network=effective_network,
+                service_url=service_url,
+                account_index=account_index,
+            )
+            wallet_id = str(binding.get("wallet_id") or "").strip()
+        if not wallet_id:
+            raise WalletBackendError(
+                "wdk_evm_wallet_id is required for backend=wdk_evm_local, or create a bound user EVM wallet first."
+            )
+
+        client = WdkEvmLocalClient(service_url)
+        wallet_meta = client.post_sync("/v1/evm/wallets/get", {"walletId": wallet_id})
+        resolved_address = str((binding or {}).get("address") or "").strip()
+        if not resolved_address:
+            address_payload = client.post_sync(
+                "/v1/evm/address/resolve",
+                {
+                    "walletId": wallet_id,
+                    "accountIndex": account_index,
+                    "network": effective_network,
+                },
+            )
+            resolved_address = str(address_payload.get("address") or "").strip()
+        backend = WdkEvmLocalWalletBackend(
+            service_url=service_url,
+            wallet_id=wallet_id,
+            network=effective_network,
+            account_index=account_index,
+            sign_only=settings.agent_wallet_sign_only if sign_only is None else sign_only,
+            address=resolved_address or None,
+        )
+        wallet_info = {
+            "user_id": user_id,
+            "address": resolved_address,
+            "path": f"{service_url}#walletId={wallet_id}",
+            "storage_format": "local_vault",
+            "key_scope": "host-managed",
+            "wallet_id": wallet_id,
+            "label": str(wallet_meta.get("label") or (binding or {}).get("label") or "EVM Wallet"),
+        }
+        adapter = OpenClawWalletAdapter(backend)
+        plugin_bundle = build_openclaw_plugin_bundle(backend)
+        return OpenClawWalletRuntimeContext(
+            user_id=user_id,
+            wallet_info=wallet_info,
+            created_now=False,
+            backend=backend,
+            adapter=adapter,
+            plugin_bundle=plugin_bundle,
+        )
+
+    wallet_path = resolve_user_wallet_path(user_id, network=network)
+    created_now = not wallet_path.exists()
+    wallet_info = ensure_user_solana_wallet(user_id, network=network)
+    backend = create_wallet_backend_for_user(
+        user_id,
+        sign_only=sign_only,
+        network=network,
+        rpc_url=rpc_url,
+    )
+    adapter = OpenClawWalletAdapter(backend)
+    plugin_bundle = build_openclaw_plugin_bundle(backend)
+    return OpenClawWalletRuntimeContext(
+        user_id=user_id,
+        wallet_info=wallet_info,
+        created_now=created_now,
+        backend=backend,
+        adapter=adapter,
+        plugin_bundle=plugin_bundle,
+    )

package/agent-wallet/agent_wallet/plugin_bundle.py

@@ -0,0 +1,42 @@
+"""Helpers for exposing agent-wallet as an OpenClaw-style plugin bundle."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
+from agent_wallet.wallet_layer.base import AgentWalletBackend
+
+
+def _package_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def get_plugin_manifest() -> dict[str, Any]:
+    """Load the OpenClaw plugin manifest from disk."""
+    manifest_path = _package_root() / "openclaw.plugin.json"
+    return json.loads(manifest_path.read_text(encoding="utf-8"))
+
+
+def get_skill_text() -> str:
+    """Load the wallet operator skill text."""
+    skill_path = _package_root() / "skills" / "wallet-operator" / "SKILL.md"
+    return skill_path.read_text(encoding="utf-8")
+
+
+def build_openclaw_plugin_bundle(backend: AgentWalletBackend) -> dict[str, Any]:
+    """Build a runtime-ready bundle for OpenClaw-style plugin registration."""
+    adapter = OpenClawWalletAdapter(backend)
+    return {
+        "manifest": get_plugin_manifest(),
+        "instructions": "\n\n".join(
+            [
+                adapter.get_runtime_instructions(),
+                get_skill_text(),
+            ]
+        ),
+        "tools": [tool.model_dump() for tool in adapter.list_tools()],
+        "invoke": adapter.invoke,
+    }

package/agent-wallet/agent_wallet/providers/__init__.py

@@ -0,0 +1 @@
+"""Wallet providers."""

package/agent-wallet/agent_wallet/providers/bags.py

@@ -0,0 +1,259 @@
+"""Bags provider helpers routed through the shared provider gateway."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from agent_wallet.config import settings
+from agent_wallet.exceptions import ProviderError
+from agent_wallet.http_client import get_client
+
+
+def _gateway_base_url() -> str:
+    base_url = os.getenv("PROVIDER_GATEWAY_URL", settings.provider_gateway_url).strip()
+    if not base_url:
+        raise ProviderError(
+            "bags",
+            "Provider gateway URL is not configured for Bags integration.",
+        )
+    return base_url.rstrip("/")
+
+
+def _gateway_headers() -> dict[str, str]:
+    headers = {"Accept": "application/json"}
+    bearer = os.getenv(
+        "PROVIDER_GATEWAY_BEARER_TOKEN",
+        settings.provider_gateway_bearer_token,
+    ).strip()
+    if bearer:
+        headers["Authorization"] = f"Bearer {bearer}"
+    return headers
+
+
+def _unwrap_gateway_payload(
+    status_code: int,
+    payload: Any,
+    *,
+    operation: str,
+) -> Any:
+    if isinstance(payload, dict) and payload.get("ok") is False:
+        message = str(payload.get("error") or f"{operation} failed.")
+        raise ProviderError("bags", f"{operation} failed via provider gateway: {message}")
+
+    if status_code != 200:
+        message = payload
+        if isinstance(payload, dict):
+            message = payload.get("error") or payload
+        raise ProviderError("bags", f"{operation} failed via provider gateway: {message}")
+
+    return payload
+
+
+def _unwrap_bags_response(
+    payload: Any,
+    *,
+    operation: str,
+) -> Any:
+    if not isinstance(payload, dict):
+        raise ProviderError("bags", f"Unexpected {operation} response from provider gateway.")
+
+    if "success" not in payload:
+        return payload
+
+    if not payload.get("success"):
+        error = payload.get("error") or payload.get("message") or f"{operation} failed."
+        raise ProviderError("bags", f"{operation} failed: {error}")
+
+    return payload.get("response")
+
+
+async def _gateway_get_json(
+    path: str,
+    *,
+    params: dict[str, Any],
+    operation: str,
+) -> Any:
+    client = get_client()
+    response = await client.get(
+        f"{_gateway_base_url()}{path}",
+        params=params,
+        headers=_gateway_headers(),
+    )
+    payload = response.json() if response.content else {}
+    gateway_payload = _unwrap_gateway_payload(
+        response.status_code,
+        payload,
+        operation=operation,
+    )
+    return _unwrap_bags_response(gateway_payload, operation=operation)
+
+
+async def _gateway_post_json(
+    path: str,
+    *,
+    body: dict[str, Any],
+    operation: str,
+) -> Any:
+    client = get_client()
+    response = await client.post(
+        f"{_gateway_base_url()}{path}",
+        json=body,
+        headers={**_gateway_headers(), "Content-Type": "application/json"},
+    )
+    payload = response.json() if response.content else {}
+    gateway_payload = _unwrap_gateway_payload(
+        response.status_code,
+        payload,
+        operation=operation,
+    )
+    return _unwrap_bags_response(gateway_payload, operation=operation)
+
+
+async def fetch_trade_quote(
+    *,
+    input_mint: str,
+    output_mint: str,
+    amount_raw: int,
+    slippage_bps: int = 50,
+) -> dict[str, Any]:
+    """Fetch a Bags trade quote via the shared provider gateway."""
+    client = get_client()
+    response = await client.get(
+        f"{_gateway_base_url()}/v1/bags/trade/quote",
+        params={
+            "inputMint": input_mint,
+            "outputMint": output_mint,
+            "amount": str(amount_raw),
+            "slippageMode": "manual",
+            "slippageBps": str(slippage_bps),
+        },
+        headers=_gateway_headers(),
+    )
+    payload = response.json() if response.content else {}
+    gateway_payload = _unwrap_gateway_payload(
+        response.status_code,
+        payload,
+        operation="Bags trade quote",
+    )
+    quote = _unwrap_bags_response(gateway_payload, operation="Bags trade quote")
+    if not isinstance(quote, dict) or "outAmount" not in quote:
+        raise ProviderError("bags", "Unexpected trade quote response from Bags.")
+    return quote
+
+
+async def build_swap_transaction(
+    *,
+    user_public_key: str,
+    quote_response: dict[str, Any],
+) -> dict[str, Any]:
+    """Build a serialized Bags swap transaction via the shared provider gateway."""
+    client = get_client()
+    response = await client.post(
+        f"{_gateway_base_url()}/v1/bags/trade/swap",
+        json={
+            "quoteResponse": quote_response,
+            "userPublicKey": user_public_key,
+        },
+        headers={**_gateway_headers(), "Content-Type": "application/json"},
+    )
+    payload = response.json() if response.content else {}
+    gateway_payload = _unwrap_gateway_payload(
+        response.status_code,
+        payload,
+        operation="Bags swap transaction",
+    )
+    swap = _unwrap_bags_response(gateway_payload, operation="Bags swap transaction")
+    if not isinstance(swap, dict) or "swapTransaction" not in swap:
+        raise ProviderError("bags", "Unexpected swap transaction response from Bags.")
+    return swap
+
+
+async def create_token_info(payload: dict[str, Any]) -> dict[str, Any]:
+    response = await _gateway_post_json(
+        "/v1/bags/launch/token-info",
+        body=payload,
+        operation="Bags token info",
+    )
+    if not isinstance(response, dict):
+        raise ProviderError("bags", "Unexpected token info response from Bags.")
+    return response
+
+
+async def create_fee_share_config(payload: dict[str, Any]) -> dict[str, Any]:
+    response = await _gateway_post_json(
+        "/v1/bags/launch/fee-share-config",
+        body=payload,
+        operation="Bags fee share config",
+    )
+    if not isinstance(response, dict):
+        raise ProviderError("bags", "Unexpected fee share config response from Bags.")
+    return response
+
+
+async def create_launch_transaction(payload: dict[str, Any]) -> str:
+    response = await _gateway_post_json(
+        "/v1/bags/launch/transaction",
+        body=payload,
+        operation="Bags launch transaction",
+    )
+    if isinstance(response, str):
+        return response
+    raise ProviderError("bags", "Unexpected launch transaction response from Bags.")
+
+
+async def fetch_claimable_positions(wallet: str) -> Any:
+    return await _gateway_get_json(
+        "/v1/bags/claim/positions",
+        params={"wallet": wallet},
+        operation="Bags claimable positions",
+    )
+
+
+async def build_claim_transactions(payload: dict[str, Any]) -> Any:
+    return await _gateway_post_json(
+        "/v1/bags/claim/transactions",
+        body=payload,
+        operation="Bags claim transactions",
+    )
+
+
+async def fetch_lifetime_fees(token_mint: str) -> Any:
+    return await _gateway_get_json(
+        "/v1/bags/fees/lifetime",
+        params={"tokenMint": token_mint},
+        operation="Bags lifetime fees",
+    )
+
+
+async def fetch_claim_stats(token_mint: str) -> Any:
+    return await _gateway_get_json(
+        "/v1/bags/fees/claim-stats",
+        params={"tokenMint": token_mint},
+        operation="Bags claim stats",
+    )
+
+
+async def fetch_claim_events(
+    *,
+    token_mint: str,
+    mode: str = "offset",
+    limit: int | None = None,
+    offset: int | None = None,
+    from_ts: int | None = None,
+    to_ts: int | None = None,
+) -> Any:
+    params: dict[str, Any] = {"tokenMint": token_mint, "mode": mode}
+    if limit is not None:
+        params["limit"] = str(limit)
+    if offset is not None:
+        params["offset"] = str(offset)
+    if from_ts is not None:
+        params["from"] = str(from_ts)
+    if to_ts is not None:
+        params["to"] = str(to_ts)
+    return await _gateway_get_json(
+        "/v1/bags/fees/claim-events",
+        params=params,
+        operation="Bags claim events",
+    )