@agentlayer.tech/wallet 0.1.0

package/agent-wallet/scripts/security_utils.py

@@ -0,0 +1,37 @@
+"""Helpers for avoiding secret leakage in config patch scripts."""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+
+SENSITIVE_PLUGIN_KEYS = {"masterKey", "privateKey", "approvalSecret"}
+
+
+def scrub_plugin_secrets(data: dict[str, Any]) -> dict[str, Any]:
+    clone = copy.deepcopy(data)
+    plugins = clone.get("plugins")
+    if not isinstance(plugins, dict):
+        return clone
+    entries = plugins.get("entries")
+    if not isinstance(entries, dict):
+        return clone
+    for entry in entries.values():
+        if not isinstance(entry, dict):
+            continue
+        config = entry.get("config")
+        if not isinstance(config, dict):
+            continue
+        for key in SENSITIVE_PLUGIN_KEYS:
+            if key in config:
+                config[key] = "[REDACTED]"
+    return clone
+
+
+def write_redacted_backup(path: Path, data: dict[str, Any]) -> None:
+    atomic_write_text(path, json.dumps(scrub_plugin_secrets(data), indent=2) + "\n", mode=0o600)
+    chmod_if_exists(path, 0o600)

package/agent-wallet/scripts/setup_btc_wallet.sh

@@ -0,0 +1,146 @@
+#!/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|mainnet|bitcoin)
+      printf "mainnet"
+      ;;
+    2|testnet)
+      printf "testnet"
+      ;;
+    3|regtest)
+      printf "regtest"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+prompt_network_choice() {
+  default_value=$1
+  if ! [ -t 0 ]; then
+    printf "%s" "$default_value"
+    return 0
+  fi
+
+  case "$default_value" in
+    mainnet|bitcoin) default_hint="1" ;;
+    testnet) default_hint="2" ;;
+    regtest) default_hint="3" ;;
+    *) default_hint="1" ;;
+  esac
+
+  while true; do
+    printf "BTC network:\n" >&2
+    printf "  1) mainnet\n" >&2
+    printf "  2) testnet\n" >&2
+    printf "  3) regtest\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, mainnet, testnet, or regtest.\n" >&2
+  done
+}
+
+DEFAULT_USER_ID=${OPENCLAW_BTC_USER_ID:-${USER:-openclaw-user}-local}
+DEFAULT_NETWORK=${OPENCLAW_BTC_NETWORK:-mainnet}
+DEFAULT_SERVICE_URL=${OPENCLAW_BTC_SERVICE_URL:-http://127.0.0.1:8080}
+
+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_BTC_CONFIG_PATH:-}" ]; then
+  set -- "$@" --config-path "$OPENCLAW_BTC_CONFIG_PATH"
+fi
+
+if ! has_flag --wdk-wallet-root "$@" && [ -n "${OPENCLAW_BTC_WDK_WALLET_ROOT:-}" ]; then
+  set -- "$@" --wdk-wallet-root "$OPENCLAW_BTC_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_btc.py" "$@"

package/agent-wallet/scripts/switch_openclaw_wallet_network.py

@@ -0,0 +1,106 @@
+"""Switch the configured OpenClaw agent-wallet network safely."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+from security_utils import write_redacted_backup
+
+
+def _default_config_path() -> Path:
+    return Path(os.path.expanduser("~/.openclaw/openclaw.json"))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config-path", default=str(_default_config_path()))
+    parser.add_argument("--plugin-id", default="agent-wallet")
+    parser.add_argument("--network", required=True, choices=["mainnet", "devnet", "testnet"])
+    parser.add_argument("--rpc-url", default="")
+    parser.add_argument("--rpc-urls", default="")
+    parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=None)
+    parser.add_argument("--show-only", action=argparse.BooleanOptionalAction, default=False)
+    return parser
+
+
+def _normalize_user_id(user_id: str) -> str:
+    import hashlib
+    import re
+
+    cleaned = re.sub(r"[^a-zA-Z0-9._-]+", "-", user_id.strip())
+    cleaned = cleaned.strip("-._")
+    if not cleaned:
+        cleaned = "user"
+    digest = hashlib.sha256(user_id.encode("utf-8")).hexdigest()[:12]
+    return f"{cleaned[:48]}-{digest}"
+
+
+def _resolve_wallet_path(openclaw_home: Path, user_id: str, network: str) -> Path:
+    return openclaw_home / "users" / _normalize_user_id(user_id) / "wallets" / f"solana-{network}-agent.json"
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    config_path = Path(args.config_path).expanduser()
+    data = json.loads(config_path.read_text(encoding="utf-8"))
+
+    plugin_entry = data["plugins"]["entries"][args.plugin_id]
+    plugin_config = plugin_entry.setdefault("config", {})
+    user_id = str(plugin_config.get("userId") or os.getenv("USER") or "openclaw-main").strip()
+    openclaw_home = Path(
+        str(plugin_config.get("openclawHome") or os.getenv("OPENCLAW_HOME") or "~/.openclaw")
+    ).expanduser()
+
+    wallet_path = _resolve_wallet_path(openclaw_home, user_id, args.network)
+    pin_path = wallet_path.with_suffix(f"{wallet_path.suffix}.pin.json")
+
+    result = {
+        "ok": True,
+        "config_path": str(config_path),
+        "plugin_id": args.plugin_id,
+        "user_id": user_id,
+        "selected_network": args.network,
+        "wallet_path": str(wallet_path),
+        "wallet_exists": wallet_path.exists(),
+        "wallet_pin_exists": pin_path.exists(),
+        "rpc_url": args.rpc_url.strip() or str(plugin_config.get("rpcUrl") or ""),
+        "rpc_urls": plugin_config.get("rpcUrls") or [],
+        "sign_only": plugin_config.get("signOnly"),
+        "show_only": args.show_only,
+    }
+
+    if args.show_only:
+        print(json.dumps(result, indent=2))
+        return
+
+    backup_path = config_path.with_name(
+        f"{config_path.name}.bak.agent-wallet-switch.{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}"
+    )
+    write_redacted_backup(backup_path, data)
+
+    plugin_config["network"] = args.network
+    if args.rpc_url.strip():
+        plugin_config["rpcUrl"] = args.rpc_url.strip()
+    else:
+        plugin_config.pop("rpcUrl", None)
+    if args.rpc_urls.strip():
+        plugin_config["rpcUrls"] = [item.strip() for item in args.rpc_urls.split(",") if item.strip()]
+    if args.sign_only is not None:
+        plugin_config["signOnly"] = args.sign_only
+
+    atomic_write_text(config_path, json.dumps(data, indent=2) + "\n", mode=0o600)
+    chmod_if_exists(config_path, 0o600)
+
+    result["backup_path"] = str(backup_path)
+    result["sign_only"] = plugin_config.get("signOnly")
+    result["rpc_urls"] = plugin_config.get("rpcUrls") or []
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/agent-wallet/skills/wallet-operator/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: wallet-operator
+description: Use when operating OpenClaw wallet tools: balances, transfers, swaps, LI.FI cross-chain swaps, Jupiter swaps, Velora EVM swaps, BTC transfers, staking, Jupiter Earn, Kamino lending, Bags claims/launches, and wallet execution safety.
+---
+
+# Wallet Operator
+
+Use this skill before calling OpenClaw wallet tools. It is the routing guide for wallet commands, providers, units, and approval flow.
+
+## Core Rules
+
+1. Start with `get_wallet_capabilities` when the active chain, signing support, or available tools are unclear.
+2. Use `get_wallet_address` before asking for deposits or confirming a recipient/source wallet.
+3. Use `get_wallet_balance` before spending, swapping, bridging, staking, lending, or claiming.
+4. Use `preview` first for every write action. Use `prepare` only after explicit user intent. Use `execute` only with a host-issued `approval_token`.
+5. `prepare` returns an execution plan only; it must not return signed transaction bytes.
+6. On mainnet, `execute` requires approval that includes explicit mainnet confirmation.
+7. If backend is `sign_only`, do not execute; use `prepare` and state that nothing was broadcast.
+8. Never claim a transfer, swap, bridge, stake, claim, deposit, borrow, repay, or withdrawal happened unless the tool result says it was broadcast/confirmed.
+9. Do not use Mayan. Direct Mayan paths were removed. Cross-chain swaps must go through LI.FI with Mayan denied.
+
+## Provider Map
+
+- Solana same-chain swap: `swap_solana_tokens` via Jupiter.
+- EVM same-chain swap: `swap_evm_tokens` via Velora, ERC-20 to ERC-20 on `ethereum` or `base`.
+- Cross-chain Solana -> EVM: `swap_solana_lifi_cross_chain_tokens` via LI.FI.
+- Cross-chain EVM -> EVM/Solana: `swap_evm_lifi_cross_chain_tokens` via LI.FI.
+- SOL/SPL transfers: `transfer_sol`, `transfer_spl_token`.
+- EVM transfers: `transfer_evm_native`, `transfer_evm_token`.
+- BTC transfer: `transfer_btc`.
+- Solana staking: `stake_sol_native`, `deactivate_solana_stake`, `withdraw_solana_stake`.
+- Jupiter Earn: `jupiter_earn_deposit`, `jupiter_earn_withdraw`.
+- Kamino: `kamino_lend_deposit`, `kamino_lend_withdraw`, `kamino_lend_borrow`, `kamino_lend_repay`.
+- Bags: `claim_bags_fees`, `launch_bags_token`.
+
+## Common Token IDs
+
+- Native SOL for LI.FI: `sol`, `native`, or `11111111111111111111111111111111`.
+- Native SOL mint for Jupiter swaps: `So11111111111111111111111111111111111111112`.
+- Native ETH for LI.FI EVM destinations/sources: `eth`, `native`, or `0x0000000000000000000000000000000000000000`.
+- EVM token addresses should be lowercase when possible. Checksummed addresses are accepted in current code and normalized for LI.FI.
+- Solana USDC mint: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`.
+- Base USDC: `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`.
+- LI.FI chain IDs: Ethereum `1`, Base `8453`, Solana `1151111081099710`.
+
+## Read Commands
+
+- `get_wallet_capabilities`: available chain, backend, send/sign support.
+- `get_wallet_address`: active wallet address.
+- `get_wallet_balance`: primary balance/portfolio summary. For EVM USD total, use `total_value_usd` from this result.
+- `get_wallet_portfolio`: Solana portfolio holdings.
+- `get_solana_token_prices`: prices by Solana mint.
+- `get_lifi_supported_chains`: supported LI.FI subset.
+- `get_lifi_quote`: read-only LI.FI quote/status surface; use when user asks for indicative cross-chain quote outside the write flow.
+- `get_lifi_transfer_status`: check LI.FI bridge status after a cross-chain source transaction.
+- `get_evm_network`: active EVM network and supported EVM swap networks.
+- `get_evm_token_balance`: ERC-20 balance by `token_address`, optional `network`.
+- `get_evm_token_metadata`: ERC-20 metadata by `token_address`, optional `network`.
+- `get_evm_fee_rates`: EVM fee suggestions.
+- `get_evm_transaction_receipt`: EVM receipt by `tx_hash`.
+- `get_btc_transfer_history`, `get_btc_fee_rates`, `get_btc_max_spendable`: BTC read helpers.
+
+## Transfer Commands
+
+- SOL transfer: `transfer_sol`
+  - Params: `recipient`, `amount` in SOL UI units, `mode`, `purpose`, optional `user_intent`, `approval_token`.
+- SPL transfer: `transfer_spl_token`
+  - Params: `recipient`, `mint`, `amount` in UI units, optional `decimals`, `mode`, `purpose`.
+- EVM native transfer: `transfer_evm_native`
+  - Params: `recipient`, `amount_wei` raw wei string, `mode`, `purpose`, optional `network`.
+- EVM ERC-20 transfer: `transfer_evm_token`
+  - Params: `token_address`, `recipient`, `amount_raw` base-unit string, `mode`, `purpose`, optional `network`.
+- BTC transfer: `transfer_btc`
+  - Params: `recipient`, `amount_sats`, optional `fee_rate`, `confirmation_target`, `mode`, `purpose`.
+
+## Swap Commands
+
+- Solana same-chain Jupiter swap: `swap_solana_tokens`
+  - Params: `input_mint`, `output_mint`, `amount` in UI units, optional `slippage_bps`, `mode`, `purpose`.
+  - Use for SOL<->SPL or SPL<->SPL on Solana. Do not use LI.FI for Solana-only swaps.
+- EVM same-chain Velora swap: `swap_evm_tokens`
+  - Params: `token_in`, `token_out`, `amount_in_raw` base-unit string, `mode`, `purpose`, optional `network`.
+  - Current intended path is ERC-20 to ERC-20 on `ethereum` or `base`.
+- EVM swap quote only: `get_evm_swap_quote`
+  - Params: `token_in`, `token_out`, `amount_in_raw`, optional `network`.
+
+## Cross-Chain Commands
+
+- Solana -> Ethereum/Base: `swap_solana_lifi_cross_chain_tokens`
+  - Source must be Solana mainnet.
+  - Params: `input_token`, `destination_chain` (`ethereum`, `base`, `1`, `8453`), `output_token`, `destination_address`, `amount_in_raw`, optional `slippage`, bridge lists, `mode`, `purpose`.
+  - Example SOL -> Base native ETH: `input_token=sol`, `destination_chain=base`, `output_token=native`, `amount_in_raw` in lamports.
+  - Execute confirms the Solana source tx. Use `get_lifi_transfer_status` to track final destination-chain completion.
+- Ethereum/Base -> Ethereum/Base/Solana: `swap_evm_lifi_cross_chain_tokens`
+  - Source network is selected by active EVM network or optional `network`.
+  - Params: `token_in`, `destination_chain` (`ethereum`, `base`, `solana`, `1`, `8453`, `1151111081099710`), `output_token`, `destination_address`, `amount_in_raw`, optional `slippage`, bridge lists, `mode`, `purpose`, optional `network`.
+  - Native EVM input can be `native`, `eth`, or zero address.
+  - Solana output token should be a Solana mint such as USDC mint.
+
+## Staking And DeFi Commands
+
+- `stake_sol_native`: `vote_account`, `amount` in SOL, `mode`, `purpose`.
+- `deactivate_solana_stake`: `stake_account`, `mode`, `purpose`.
+- `withdraw_solana_stake`: `stake_account`, `amount` in SOL, optional `recipient`, `mode`, `purpose`.
+- Before Jupiter Earn writes, use `get_jupiter_earn_tokens`, `get_jupiter_earn_positions`, and `get_jupiter_earn_earnings`.
+- `jupiter_earn_deposit`: `asset` mint, `amount_raw`, `mode`, `purpose`.
+- `jupiter_earn_withdraw`: `asset` mint, `amount_raw`, `mode`, `purpose`.
+- Before Kamino writes, use `get_kamino_lend_markets`, `get_kamino_lend_market_reserves`, `get_kamino_lend_user_obligations`, and `get_kamino_lend_user_rewards`.
+- Kamino write params: `market`, `reserve`, `amount_ui` decimal string, `mode`, `purpose`.
+- Bags reads: `get_bags_claimable_positions`, `get_bags_fee_analytics`.
+- `claim_bags_fees`: `token_mint`, `mode`, `purpose`.
+- `launch_bags_token`: `name`, `symbol`, `description`, `base_mint`, `claimers`, `basis_points`, `initial_buy_sol`, `mode`, `purpose`; optional socials/image/config type.
+- `close_empty_token_accounts`: `limit`, `mode` (`preview` or `execute`), `purpose`.
+- `request_devnet_airdrop`: `amount`; only outside mainnet.
+
+## Approval Flow Template
+
+1. Call the write tool with `mode=preview` and a concrete `purpose`.
+2. Show the user the important fields: chain, token, amount, destination, provider, estimated output/minimum output, fees, and route/tool when present.
+3. For `prepare`, call same tool with `mode=prepare`, same params, `user_intent=true`.
+4. For `execute`, use the same semantic params and pass the `approval_token`. Do not mutate amount, token, destination, network, slippage, or minimum output between preview and execute.
+5. For cross-chain swaps, after execute, offer `get_lifi_transfer_status` using the source tx hash and bridge/tool if returned.
+
+## Disabled Or Avoided Paths
+
+- Do not call Jupiter Portfolio tools if they are not listed by `get_wallet_capabilities`; they may be temporarily disabled.
+- Do not invent generic calldata, arbitrary contract calls, token approvals, or non-listed bridge providers.
+- If a requested tool is absent from `list_tools` or capabilities, say the wallet runtime does not expose it.