@agentlayer.tech/wallet 0.1.21 → 0.1.23

package/.openclaw/extensions/agent-wallet/README.md

@@ -39,10 +39,10 @@ Recommended config:
         "config": {
           "userId": "openclaw-local-user",
           "backend": "solana_local",
-          "network": "devnet",
+          "network": "mainnet",
           "rpcUrls": [
             "https://your-primary-rpc.example",
-            "https://api.devnet.solana.com"
+            "https://api.mainnet-beta.solana.com"
           ],
           "signOnly": false,
           "encryptUserWallets": true,
@@ -77,7 +77,7 @@ The ClawHub plugin package only installs the native OpenClaw plugin. It expects
 
 If that runtime is not present, set `plugins.entries.agent-wallet.config.packageRoot` explicitly.
 
-That installs the Python backend, Node dependencies for the local BTC/EVM runtimes, and patches the OpenClaw plugin config. Solana stays ready immediately; EVM readiness can now be auto-healed during normal wallet switching when the runtime has sealed local vault credentials.
+That installs the Python backend, Node dependencies for the local BTC/EVM runtimes, patches the OpenClaw plugin config, and provisions the first encrypted per-user Solana mainnet wallet when no explicit signer is already configured. EVM readiness can still be auto-healed during normal wallet switching when the runtime has sealed local vault credentials.
 
 For self-hosted installs, prefer `SOLANA_RPC_URL` / `SOLANA_RPC_URLS` in local env and treat the plugin `rpcUrl` / `rpcUrls` fields as fallback only. If the local runtime exposes `ALCHEMY_API_KEY` or `HELIUS_API_KEY`, the wallet can derive the Solana RPC URL automatically for `mainnet` or `devnet`. Local env always takes precedence over `openclaw.json`.
 

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## v0.1.23 - 2026-05-23
+
+- Made the default Solana install flow mainnet-first for fresh local
+  onboarding.
+- Added host-side Solana wallet provisioning to the installer so
+  `wallet install --yes` creates an encrypted per-user mainnet wallet when no
+  explicit signer is already configured.
+- Kept wallet secrets local by running runtime onboarding without
+  provisioning-only secret environment variables and returning only public
+  wallet metadata in installer output.
+- Updated installer smoke coverage to verify encrypted wallet creation,
+  mainnet config, address pinning, and absence of boot/master/approval secrets
+  in stdout.
+
 ## v0.1.18 - 2026-05-19
 
 - Started the native x402 buyer integration inside `agent-wallet` instead of

package/README.md

@@ -9,7 +9,9 @@
 ```bash
 npx @agentlayer.tech/wallet install --yes
 ```
-For install to Hermes use
+
+For Hermes:
+
 ```bash
 npx @agentlayer.tech/wallet install --yes && npx @agentlayer.tech/wallet hermes install --yes
 ```
@@ -46,35 +48,35 @@ System prerequisites:
 - `node`
 - `npm`
 
-Install through npm:
+Install the local runtime:
 
 ```bash
 npx @agentlayer.tech/wallet install --yes
 ```
 
-Install the native OpenClaw plugins from ClawHub:
+Install the native OpenClaw plugin from ClawHub:
 
 ```bash
 openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin
 ```
 
-Those ClawHub packages do not replace the npm installer. Keep `npx @agentlayer.tech/wallet install --yes` for laying down the local wallet runtime, Python backend, and helper services. The ClawHub packages only install the OpenClaw plugin surfaces that point at that runtime.
+The ClawHub package does not replace the npm installer. `npx @agentlayer.tech/wallet install --yes` installs the local runtime, Python backend, and helper services. ClawHub only installs the OpenClaw plugin surface that points at that runtime.
 
-Or install the CLI globally first:
+Or install the CLI globally:
 
 ```bash
 npm install -g @agentlayer.tech/wallet
 wallet install --yes
 ```
 
-The npm CLI runs the same bundled installer, but uses a versioned runtime layout:
+The CLI uses a versioned runtime layout:
 
 ```bash
 ~/.openclaw/agent-wallet-runtime/releases/<version>
 ~/.openclaw/agent-wallet-runtime/current
 ```
 
-`--yes` generates local runtime secrets when this is the first install. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; only the boot key needed to unlock that sealed bundle is written to the installed runtime `.env`.
+On first install, `--yes` generates local runtime secrets. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; only the boot key needed to unlock that sealed bundle is written to the runtime `.env`.
 
 Useful npm CLI commands:
 
@@ -87,12 +89,11 @@ wallet update --yes --dry-run
 wallet rollback
 ```
 
-`wallet update --yes` now delegates to the latest published npm package and reuses shared Python and Node dependency snapshots when they have not changed, so frequent upgrades do not need to rebuild every runtime dependency from scratch.
-Use `wallet update --yes --dry-run` to inspect the target runtime version and whether Python/Node dependency snapshots will be reused or rebuilt before switching `current`.
+`wallet update --yes` delegates to the latest published npm package and reuses shared Python and Node dependency snapshots when possible. Use `wallet update --yes --dry-run` to inspect the target version and dependency plan before switching `current`.
 
 ## Native OpenClaw plugin installs
 
-Use ClawHub when you want the plugin itself to be installed through OpenClaw:
+Use ClawHub when you want the plugin installed through OpenClaw:
 
 ```bash
 openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin
@@ -104,7 +105,7 @@ Recommended order:
 2. Install the plugin package from ClawHub with `openclaw plugins install clawhub:...`.
 3. Restart the OpenClaw gateway and enable/configure the plugin entry in `openclaw.json`.
 
-The `agent-wallet` ClawHub plugin auto-checks the standard runtime path at:
+The `agent-wallet` ClawHub plugin checks the standard runtime path at:
 
 ```bash
 ~/.openclaw/agent-wallet-runtime/current/agent-wallet
@@ -118,7 +119,30 @@ Install from a local clone:
 sh ./setup.sh
 ```
 
-If you want the installer to finish the OpenClaw plugin wiring in the same pass, provide the runtime secrets before running it:
+## Updating
+
+If your installed CLI is `0.1.22` or newer, use:
+
+```bash
+wallet update --yes --dry-run
+wallet update --yes
+```
+
+If your installed CLI is older than `0.1.22`, or `wallet` is missing, use:
+
+```bash
+npx --yes @agentlayer.tech/wallet@latest update --yes --dry-run
+npx --yes @agentlayer.tech/wallet@latest update --yes
+```
+
+After updating, verify the active runtime:
+
+```bash
+npx --yes @agentlayer.tech/wallet@latest status --verbose
+```
+
+This flow keeps wallet files and `sealed_keys.json` in place, upgrades the runtime under `~/.openclaw/agent-wallet-runtime/releases/<version>`, and reuses shared Python and Node dependency snapshots when possible.
+
 
 ## Wallet capabilities through external services
 
@@ -225,6 +249,8 @@ Lido:
 
 Across these service-backed flows, read operations remain directly callable, while write operations stay behind preview, explicit intent, and host-issued approval tokens before execution.
 
+If you want the installer to finish the OpenClaw plugin wiring in the same pass, provide the runtime secrets first:
+
 Solana:
 
 ```bash
@@ -258,7 +284,7 @@ Run it three times and assign the outputs to:
 - `AGENT_WALLET_MASTER_KEY`
 - `AGENT_WALLET_APPROVAL_SECRET`
 
-Without those secrets, the installer still lays down the runtime and installs dependencies, but it stops short of the final hardened OpenClaw config step and prints the exact `next_configure_command` you should run after secrets are available.
+Without those secrets, the installer still lays down the runtime and installs dependencies, but stops before the final hardened OpenClaw config step and prints the exact `next_configure_command` to run later.
 
 ## Connect the MCP server
 
@@ -280,7 +306,7 @@ OpenClaw remains the primary local environment, but the repo also ships an optio
 hermes/plugins/agent_wallet
 ```
 
-It exposes a thin bridge, not a port of wallet logic:
+It exposes a thin bridge, not a separate wallet implementation:
 
 - `agent_wallet_tools`
 - `agent_wallet_invoke`
@@ -294,7 +320,7 @@ Install it by symlinking the plugin directory into Hermes:
 npx @agentlayer.tech/wallet hermes install --yes
 ```
 
-That command installs the Hermes plugin, runs `hermes plugins enable agent-wallet`, writes non-secret runtime paths into `~/.hermes/.env`, and points Hermes at a local boot-key file. Secrets stay in the existing protected OpenClaw runtime paths, especially `~/.openclaw/sealed_keys.json`; do not put wallet secrets into Hermes tool config.
+That command installs the Hermes plugin, runs `hermes plugins enable agent-wallet`, writes non-secret runtime paths into `~/.hermes/.env`, and points Hermes at a local boot-key file. Secrets stay in the protected OpenClaw runtime paths, especially `~/.openclaw/sealed_keys.json`; do not put wallet secrets into Hermes tool config.
 
 ## What you get after install
 
@@ -304,11 +330,11 @@ If you install through npm, the runtime is extracted under:
 ~/.openclaw/agent-wallet-runtime/current
 ```
 
-The installer then does the following:
+The installer then:
 
 - creates `agent-wallet/.env` from `agent-wallet/.env.example` if it does not exist
-- creates `agent-wallet/.venv` and installs the Python backend with `pip install -e`
-- installs Node dependencies for `wdk-btc-wallet` and `wdk-evm-wallet`
+- creates `agent-wallet/.runtime-venv` and installs the Python backend
+- installs Node dependencies for `wdk-btc-wallet`, `wdk-evm-wallet`, and `flash-sdk-bridge`
 - creates a minimal `~/.openclaw/openclaw.json` if one does not exist
 - if the required secrets are already present, writes or updates `~/.openclaw/sealed_keys.json`
 - if the required secrets are already present, patches `~/.openclaw/openclaw.json` to load the `agent-wallet` extension and point it at the installed runtime
@@ -317,7 +343,12 @@ The installer then does the following:
 When the installer reaches the final config step, the default plugin config is:
 
 - `backend=solana_local`
-- `network=devnet`
+- `network=mainnet`
+
+For a fresh Solana install, `wallet install --yes` also provisions the first local mainnet
+wallet for the configured local `userId`. The wallet secret stays encrypted under
+`~/.openclaw/users/.../wallets/`; the agent-facing surface only receives the public
+address and guarded wallet tools.
 
 ## What is not done automatically
 
@@ -332,10 +363,11 @@ The installer does not:
 - expose seed phrases to the agent
 - install `python3`, `node`, or `npm` for you
 
-For Solana specifically, install alone does not make signed transactions available. You still need a readable wallet identity:
+For existing Solana installs, the runtime keeps the current identity precedence:
 
 - read-only mode: `SOLANA_AGENT_PUBLIC_KEY`
 - signing mode: a sealed `private_key` or `SOLANA_AGENT_KEYPAIR_PATH`
+- otherwise: the encrypted per-user local wallet created by onboarding
 
 Optional private Solana payout routing is also available through Houdini. To enable it, add the Houdini partner credentials to the wallet runtime:
 
@@ -445,7 +477,8 @@ You only need to bring your own RPC if you want to override the default route. S
 - `ALCHEMY_API_KEY`
 - `HELIUS_API_KEY`
 
-Automatic local Solana wallet creation exists, but it is off by default:
+The legacy global keypair auto-create flag still exists for compatibility, but normal
+OpenClaw onboarding should use the encrypted per-user wallet path created by the installer:
 
 ```bash
 SOLANA_AUTO_CREATE_WALLET=false

package/agent-wallet/README.md

@@ -284,12 +284,12 @@ and still append the official Solana endpoint as fallback.
 
 For OpenClaw self-hosting, this means users can keep their own Alchemy/Helius key locally in `.env` or shell env. Nothing needs to be proxied or hosted by us.
 
-For OpenClaw install/runtime, the intended creation flow is:
+For OpenClaw install/runtime, the default creation flow is:
 
 1. OpenClaw plugin config sets `backend=solana_local`
-2. Optional: set `network=devnet`
-3. Optional: set `autoCreateWallet=true`
-4. On first startup, if no keypair exists and auto-create is enabled, the plugin creates a local wallet file under `~/.openclaw/wallets/`
+2. The installer configures `network=mainnet` unless you pass `--network`
+3. The installer calls host-side onboarding once the sealed runtime secrets exist
+4. If no explicit sealed signer or `SOLANA_AGENT_KEYPAIR_PATH` exists, onboarding creates an encrypted per-user Solana wallet under `~/.openclaw/users/.../wallets/`
 
 For multi-user OpenClaw integration, use `agent_wallet.user_wallets.create_wallet_backend_for_user(user_id)`.
 That provisions a wallet per user under:

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.21"
+version = "0.1.23"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/agent-wallet/scripts/install_agent_wallet.py

@@ -186,7 +186,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--plugin-id", default="agent-wallet")
     parser.add_argument("--user-id", default=_default_user_id())
     parser.add_argument("--backend", default="solana_local")
-    parser.add_argument("--network", default="devnet")
+    parser.add_argument("--network", default="mainnet")
     parser.add_argument("--rpc-url", default="")
     parser.add_argument("--rpc-urls", default="")
     parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=False)
@@ -667,6 +667,79 @@ def _build_next_steps(
     return command
 
 
+def _is_solana_backend(backend: str) -> bool:
+    return backend.strip().lower() in {"solana", "solana_local", "solana-local"}
+
+
+def _build_solana_onboard_config(args: argparse.Namespace) -> dict[str, object]:
+    config: dict[str, object] = {
+        "backend": args.backend,
+        "network": args.network,
+        "signOnly": bool(args.sign_only),
+        "encryptUserWallets": True,
+        "migratePlaintextUserWallets": True,
+        "refuseMainnetWalletRecreation": True,
+    }
+    if args.rpc_url.strip():
+        config["rpcUrl"] = args.rpc_url.strip()
+    if args.rpc_urls.strip():
+        config["rpcUrls"] = [item.strip() for item in args.rpc_urls.split(",") if item.strip()]
+    return config
+
+
+def _runtime_env_for_onboard(package_root: Path) -> dict[str, str]:
+    env = dict(os.environ)
+    python_path = env.get("PYTHONPATH", "").strip()
+    env["PYTHONPATH"] = (
+        f"{package_root}{os.pathsep}{python_path}" if python_path else str(package_root)
+    )
+    for var_name in (
+        "AGENT_WALLET_MASTER_KEY",
+        "AGENT_WALLET_APPROVAL_SECRET",
+        "SOLANA_AGENT_PRIVATE_KEY",
+    ):
+        env.pop(var_name, None)
+    return env
+
+
+def _bootstrap_solana_wallet(
+    python_bin: Path,
+    package_root: Path,
+    args: argparse.Namespace,
+) -> dict[str, object] | None:
+    if not _is_solana_backend(args.backend):
+        return None
+    result = subprocess.run(
+        [
+            str(python_bin),
+            "-m",
+            "agent_wallet.openclaw_cli",
+            "onboard",
+            "--user-id",
+            args.user_id,
+            "--config-json",
+            json.dumps(_build_solana_onboard_config(args)),
+        ],
+        cwd=package_root,
+        capture_output=True,
+        text=True,
+        check=True,
+        env=_runtime_env_for_onboard(package_root),
+    )
+    payload = json.loads(result.stdout)
+    session = dict(payload.get("session") or {})
+    return {
+        "ok": True,
+        "user_id": session.get("user_id") or args.user_id,
+        "address": session.get("address"),
+        "network": session.get("network") or args.network,
+        "wallet_path": session.get("wallet_path"),
+        "storage_format": session.get("storage_format"),
+        "created_now": bool(session.get("created_now")),
+        "backend": session.get("backend"),
+    }
+
+
 def main() -> None:
     args = build_parser().parse_args()
     source_package_root = Path(args.package_root).expanduser().resolve()
@@ -798,6 +871,7 @@ def main() -> None:
     pending_env = _pending_env_names() if backend_enabled else []
     configured = False
     configure_stdout = ""
+    solana_onboard_result: dict[str, object] | None = None
     if backend_enabled and not pending_env and not args.dry_run:
         result = subprocess.run(
             _build_next_steps(
@@ -813,6 +887,11 @@ def main() -> None:
         )
         configured = True
         configure_stdout = result.stdout
+        solana_onboard_result = _bootstrap_solana_wallet(
+            python_bin,
+            package_root,
+            args,
+        )
 
     print(
         json.dumps(
@@ -837,6 +916,7 @@ def main() -> None:
                 "runtime_sync": runtime_sync,
                 "configured": configured,
                 "pending_env": pending_env,
+                "solana_wallet": solana_onboard_result,
                 "next_configure_command": _build_next_steps(
                     python_bin,
                     install_config_script,

package/bin/openclaw-agent-wallet.mjs

@@ -226,6 +226,62 @@ function activeVersion(env = process.env) {
   return path.basename(path.resolve(path.dirname(current), link));
 }
 
+function detectRuntimeVersion(runtimeRoot) {
+  try {
+    const packageJsonText = fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8");
+    const pkg = JSON.parse(packageJsonText);
+    return String(pkg.version || "").trim() || null;
+  } catch {
+    // ignored
+  }
+  try {
+    const pyprojectText = fs.readFileSync(path.join(runtimeRoot, "agent-wallet", "pyproject.toml"), "utf8");
+    const match = pyprojectText.match(/^version = "([^"]+)"/m);
+    return match?.[1] || null;
+  } catch {
+    return null;
+  }
+}
+
+function uniquePathWithSuffix(targetPath) {
+  if (!fs.existsSync(targetPath)) return targetPath;
+  let counter = 2;
+  while (true) {
+    const candidate = `${targetPath}-${counter}`;
+    if (!fs.existsSync(candidate)) return candidate;
+    counter += 1;
+  }
+}
+
+function migrateDirectoryRuntimePointer(linkPath) {
+  const stat = fs.lstatSync(linkPath);
+  if (!stat.isDirectory()) return null;
+  const runtimeBase = path.dirname(linkPath);
+  const releasesDir = path.join(runtimeBase, "releases");
+  fs.mkdirSync(releasesDir, { recursive: true });
+  const detectedVersion = detectRuntimeVersion(linkPath);
+  const baseName = detectedVersion ? `${detectedVersion}-migrated` : `legacy-current-${Date.now()}`;
+  const destination = uniquePathWithSuffix(path.join(releasesDir, baseName));
+  fs.renameSync(linkPath, destination);
+  return destination;
+}
+
+function existingRuntimePointerTarget(linkPath) {
+  const link = readLinkOrNull(linkPath);
+  if (link) {
+    return path.resolve(path.dirname(linkPath), link);
+  }
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (stat.isDirectory()) {
+      return migrateDirectoryRuntimePointer(linkPath);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return null;
+}
+
 function listDirectories(rootPath) {
   try {
     return fs
@@ -665,6 +721,7 @@ function runInstall(args, { commandName = "install" } = {}) {
   const currentPath = currentRuntimePath();
   const previousPath = previousRuntimePath();
   const installerArgs = withoutCliOnlyArgs(args);
+  const dryRun = hasFlag(args, "--dry-run");
 
   if (!hasFlag(installerArgs, "--runtime-root")) {
     installerArgs.push("--runtime-root", releaseRoot);
@@ -695,9 +752,13 @@ function runInstall(args, { commandName = "install" } = {}) {
     return result.status ?? 1;
   }
 
-  const currentTarget = readLinkOrNull(currentPath);
+  if (dryRun) {
+    return 0;
+  }
+
+  const currentTarget = existingRuntimePointerTarget(currentPath);
   if (currentTarget) {
-    switchSymlink(previousPath, path.resolve(path.dirname(currentPath), currentTarget));
+    switchSymlink(previousPath, currentTarget);
   }
   switchSymlink(currentPath, releaseRoot);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {