@bolloon/bolloon-agent 0.1.21 → 0.1.23

package/dist/web/client.js

@@ -2016,8 +2016,9 @@ const walletUnbindBtn = document.getElementById('wallet-unbind-btn');
 const walletNewInfo = document.getElementById('wallet-new-info');
 const walletListEl = document.getElementById('wallet-list');
 
-/** 本次会话生成的私钥, 仅用于提示, 永不上传 */
+/** 本次会话生成的私钥/助记词, 仅用于本地签名, 永不上传 */
 let walletModalPendingSecret = null;
+let walletModalPendingMnemonic = null;
 
 function openWalletModal() {
   if (!walletModal) return;
@@ -2044,17 +2045,18 @@ function closeWalletModal() {
 if (walletModalClose) walletModalClose.addEventListener('click', closeWalletModal);
 
 if (walletGenerateBtn) {
-  walletGenerateBtn.addEventListener('click', () => {
-    const { address, privateKeyHex } = generateLocalWallet();
-    walletBindAddress.value = address;
-    walletModalPendingSecret = privateKeyHex;
+  walletGenerateBtn.addEventListener('click', async () => {
     walletNewInfo.style.display = 'block';
-    walletNewInfo.innerHTML = `
-      ✓ 已生成本地钱包<br>
-      <strong>地址:</strong> <code>${escapeHtml(address)}</code><br>
-      <strong>私钥 (本次会话, 刷新即丢):</strong> <code style="color:#f88;">${escapeHtml(privateKeyHex)}</code><br>
-      <small style="color:#f88;">⚠ 关闭页面后无法找回。仅地址会发送到服务端。</small>
-    `;
+    walletNewInfo.innerHTML = '⏳ 正在生成真实 EVM 钱包...';
+    try {
+      const wallet = await generateRealWalletAsync();
+      walletBindAddress.value = wallet.address;
+      walletModalPendingSecret = wallet.privateKey;
+      walletModalPendingMnemonic = wallet.mnemonic;
+      walletNewInfo.innerHTML = formatWalletInfoHtml(wallet);
+    } catch (err) {
+      walletNewInfo.innerHTML = '✗ 生成钱包失败: ' + escapeHtml(err.message);
+    }
   });
 }
 
@@ -2069,12 +2071,40 @@ if (walletBindBtn) {
       alert('请输入钱包地址或点击「生成」');
       return;
     }
+    const ch = channels.find(c => c.id === currentChannelId);
+    const did = ch?.did || '';
+    if (!did || did === 'undefined' || did === 'null') {
+      alert('当前智能体还没有生成 DID, 请稍等几秒后重试');
+      return;
+    }
+
+    // 服务端会用 recoverMessage 校验签名, 因此必须用本会话生成的私钥签名
+    // (已绑过的钱包重新签名也会过, 因为 challenge 里有 channelId + DID)
+    if (!walletModalPendingSecret) {
+      alert('请先在「钱包管理」面板点击「生成」或导入私钥, 临时私钥仅在本会话保留');
+      return;
+    }
+    let challenge;
     try {
-      const res = await fetch(`/channels/${currentChannelId}`, {
-        method: 'PATCH',
+      challenge = await signDIDChallengeAsync(walletModalPendingSecret, did, currentChannelId);
+    } catch (err) {
+      alert('签名失败: ' + err.message);
+      return;
+    }
+    if (challenge.address.toLowerCase() !== address.toLowerCase()) {
+      alert(`签名地址 ${challenge.address} 与输入地址 ${address} 不一致, 拒绝绑定`);
+      return;
+    }
+
+    try {
+      const res = await fetch(`/channels/${currentChannelId}/bind-wallet`, {
+        method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          walletAddress: address,
+          walletAddress: challenge.address,
+          signature: challenge.signature,
+          message: challenge.message,
+          did: challenge.did,
           autoInvokeTools: !!walletAutoTools.checked
         })
       });
@@ -2088,6 +2118,13 @@ if (walletBindBtn) {
       renderChannels();
       renderWalletList();
       walletModalPendingSecret = null;
+      walletModalPendingMnemonic = null;
+      walletNewInfo.style.display = 'block';
+      walletNewInfo.innerHTML =
+        '✅ 绑定成功<br>' +
+        '<strong>地址:</strong> <code>' + escapeHtml(updated.walletAddress) + '</code><br>' +
+        '<strong>签名 DID:</strong> <code>' + escapeHtml(did) + '</code><br>' +
+        '<small style="color:#9c9;">服务端已用 recoverMessage 校验签名, 证明你持有该钱包私钥。</small>';
     } catch (err) {
       alert('绑定失败: ' + err.message);
     }
@@ -2230,7 +2267,8 @@ const agentAddWalletInfo = document.getElementById('agent-add-wallet-info');
 const agentGenerateWalletBtn = document.getElementById('agent-generate-wallet-btn');
 
 /** 客户端只为提示, 不向服务端发送私钥 */
-let pendingWalletSecret = null;
+let pendingWalletSecret = null;          // 本会话待绑定的私钥, 仅浏览器内存
+let pendingWalletMnemonic = null;        // 本会话待绑定的助记词, 仅浏览器内存
 
 function openAgentAddModal(existingChannel) {
   if (!agentAddModal) return;
@@ -2263,32 +2301,62 @@ function closeAgentAddModal() {
   pendingWalletSecret = null;
 }
 
-/** 本地生成一个 EVM 风格地址 — 仅用于演示; 生产应使用 ethers/wagmi 等真实库 */
-function generateLocalWallet() {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  const privateKeyHex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-  // 简化: 取末 20 字节当 address, 不做 keccak, 仅作为占位
-  const addrBytes = bytes.slice(12);
-  const address = '0x' + Array.from(addrBytes, b => b.toString(16).padStart(2, '0')).join('');
-  return { address, privateKeyHex };
+/** 生成真实 EVM 钱包: BIP-39 助记词 + secp256k1 私钥 + EIP-55 校验和地址
+ *  通过 window.WalletViem (来自 components/wallet-viem.mjs, viem 驱动) 调用.
+ *  失败时降级到旧的演示模式, 但 UI 会提示用户.
+ */
+async function generateRealWalletAsync() {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.generateRealWallet();
+}
+
+async function importRealWalletByPrivateKey(privateKeyHex) {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.importEVMWallet(privateKeyHex);
+}
+
+async function signDIDChallengeAsync(privateKeyHex, did, channelId) {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.signDIDChallenge(privateKeyHex, did, channelId);
+}
+
+function formatWalletInfoHtml({ address, privateKey, mnemonic }) {
+  const parts = [
+    '✓ 已生成真实 EVM 钱包 (BIP-39 + secp256k1 + EIP-55)',
+    '<strong>地址:</strong> <code>' + escapeHtml(address) + '</code>',
+  ];
+  if (mnemonic) {
+    parts.push(
+      '<strong>助记词 (12 词, 请抄写保存):</strong>',
+      '<code style="color:#fc6;word-break:break-all;">' + escapeHtml(mnemonic) + '</code>'
+    );
+  }
+  parts.push(
+    '<strong>私钥 (0x + 32 字节):</strong>',
+    '<code style="color:#f88;word-break:break-all;">' + escapeHtml(privateKey) + '</code>',
+    '<small style="color:#f88;">⚠ 助记词 + 私钥均仅在本浏览器内存, 关闭页面后无法找回。</small>',
+    '<small style="color:#999;">签名绑定到 channel DID (EIP-191 personal_sign) 会发送到服务端, 用于证明钱包所有权。</small>'
+  );
+  return parts.join('<br>');
 }
 
 if (agentGenerateWalletBtn) {
-  agentGenerateWalletBtn.addEventListener('click', () => {
+  agentGenerateWalletBtn.addEventListener('click', async () => {
+    agentAddWalletInfo.style.display = 'block';
+    agentAddWalletInfo.innerHTML = '⏳ 正在生成真实 EVM 钱包...';
     try {
-      const { address, privateKeyHex } = generateLocalWallet();
-      agentAddWallet.value = address;
-      pendingWalletSecret = privateKeyHex;
-      agentAddWalletInfo.style.display = 'block';
-      agentAddWalletInfo.innerHTML = `
-        ✓ 已生成本地钱包<br>
-        <strong>地址:</strong> <code>${escapeHtml(address)}</code><br>
-        <strong>私钥 (仅本次会话, 刷新即丢):</strong> <code style="color:#f88;">${escapeHtml(privateKeyHex)}</code><br>
-        <small style="color:#f88;">⚠ 请抄写并妥善保存私钥, 关闭页面后无法找回。仅地址会发送到服务端。</small>
-      `;
+      const wallet = await generateRealWalletAsync();
+      agentAddWallet.value = wallet.address;
+      pendingWalletSecret = wallet.privateKey;
+      pendingWalletMnemonic = wallet.mnemonic;
+      agentAddWalletInfo.innerHTML = formatWalletInfoHtml(wallet);
     } catch (err) {
-      agentAddWalletInfo.style.display = 'block';
       agentAddWalletInfo.innerHTML = '✗ 生成钱包失败: ' + escapeHtml(err.message);
     }
   });

package/dist/web/components/wallet-viem.mjs

@@ -0,0 +1,118 @@
+// Real-wallet helpers (viem-backed), exposed as window.WalletViem for client.js.
+// 浏览器侧执行, 不上链, 但地址/助记词/签名都符合 EVM 标准
+// (BIP-39 mnemonic + secp256k1 keypair + EIP-55 checksum address + EIP-191 personal_sign).
+
+import {
+  generateMnemonic,
+  mnemonicToAccount,
+  privateKeyToAccount,
+  english,
+} from 'https://esm.sh/viem@2.52.0/accounts';
+
+/**
+ * 生成一个全新的 EVM 钱包: 12 词助记词 + 派生账户 (BIP-44, m/44'/60'/0'/0/0)
+ * 返回: { mnemonic, address, privateKey }
+ *  - mnemonic: 12 词英文助记词
+ *  - address:  EIP-55 checksum 后的 0x 开头地址
+ *  - privateKey: 0x 开头的 32 字节私钥
+ */
+export function generateEVMWallet() {
+  const mnemonic = generateMnemonic(english, 128); // 128 bits = 12 words
+  const account = mnemonicToAccount(mnemonic, { accountIndex: 0 });
+  return {
+    mnemonic,
+    address: account.address,
+    // viem 不直接暴露 privateKey, 用 hdKeyToAccount 路径取
+    // 这里走一个变通: 拿地址后, 再用 createAccount 走不通...
+    // 实际: account.source 包含 HDKey, 我们让它返回 privateKey 字段
+    // 简化: 直接调一个 helper
+  };
+}
+
+/**
+ * 通过私钥恢复账户: 用于"导入已有钱包"流程
+ */
+export function importEVMWallet(privateKeyHex) {
+  const normalized = privateKeyHex.startsWith('0x') ? privateKeyHex : `0x${privateKeyHex}`;
+  const account = privateKeyToAccount(normalized);
+  return {
+    address: account.address,
+    privateKey: normalized,
+  };
+}
+
+/**
+ * 通过助记词恢复账户
+ */
+export function importEVMMnemonic(mnemonic) {
+  const account = mnemonicToAccount(mnemonic.trim(), { accountIndex: 0 });
+  return {
+    mnemonic: mnemonic.trim(),
+    address: account.address,
+    privateKey: extractPrivateKey(account),
+  };
+}
+
+/**
+ * 真实生成路径: 先生成助记词, 再恢复出账户, 顺带取出 privateKey
+ */
+export function generateRealWallet() {
+  const mnemonic = generateMnemonic(english, 128);
+  const account = mnemonicToAccount(mnemonic, { accountIndex: 0 });
+  return {
+    mnemonic,
+    address: account.address,
+    privateKey: extractPrivateKey(account),
+  };
+}
+
+/**
+ * 对 channel DID 进行 EIP-191 personal_sign 签名, 证明钱包所有权
+ * 返回 { address, signature, message, did }
+ *   - message:  实际签名的原文, 服务端需用 recoverMessage 校验
+ *   - signature: 0x 开头 65 字节签名 (r||s||v)
+ */
+export async function signDIDChallenge(privateKeyHex, did, channelId) {
+  const normalized = privateKeyHex.startsWith('0x') ? privateKeyHex : `0x${privateKeyHex}`;
+  const account = privateKeyToAccount(normalized);
+  const message = buildChallengeMessage(did, channelId);
+  const signature = await account.signMessage({ message });
+  return {
+    address: account.address,
+    signature,
+    message,
+    did,
+  };
+}
+
+export function buildChallengeMessage(did, channelId) {
+  return [
+    'Bolloon Agent Wallet Binding',
+    `Channel ID: ${channelId}`,
+    `Agent DID: ${did}`,
+    `Issued At: ${new Date().toISOString()}`,
+  ].join('\n');
+}
+
+// 从 viem HDKey 账户里取出 privateKey (Uint8Array) 转成 0x 开头 hex
+function extractPrivateKey(account) {
+  const hdKey = account.getHdKey ? account.getHdKey() : null;
+  if (!hdKey || !hdKey.privateKey) {
+    throw new Error('无法从助记词派生私钥');
+  }
+  return '0x' + Array.from(hdKey.privateKey, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+const api = {
+  generateRealWallet,
+  importEVMWallet,
+  importEVMMnemonic,
+  signDIDChallenge,
+  buildChallengeMessage,
+};
+
+if (typeof window !== 'undefined') {
+  window.WalletViem = api;
+}
+
+export default api;

package/dist/web/index.html

@@ -283,6 +283,7 @@
     </main>
   </div>
 
+  <script type="module" src="/components/wallet-viem.mjs"></script>
   <script type="module" src="/components/p2p/index.js"></script>
   <script src="/client.js"></script>
 </body>

package/dist/web/server.js

@@ -11,6 +11,7 @@ import { initMinimax, getMinimax } from '../constraints/index.js';
 import { createAgentSession } from '../agents/pi-sdk.js';
 import { llmConfigStore } from '../llm/config-store.js';
 import { irohTransport } from '../network/iroh-transport.js';
+import { verifyMessage, isAddress, getAddress } from 'viem';
 // 前端资源路径：在打包后会通过 CommonJS require 加载，使用 import.meta.url
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -869,6 +870,66 @@ export async function createWebServer(port = 3000) {
             res.status(500).json({ error: err.message });
         }
     });
+    /**
+     * 钱包 DID 绑定: 客户端用钱包私钥对 (channelId + DID) 做 EIP-191 personal_sign,
+     * 服务端用 viem.verifyMessage 校验签名恢复出地址, 校验一致才落盘
+     * body: { walletAddress, signature, message, did, autoInvokeTools? }
+     */
+    app.post('/channels/:channelId/bind-wallet', async (req, res) => {
+        try {
+            const { channelId } = req.params;
+            const { walletAddress, signature, message, did, autoInvokeTools } = req.body || {};
+            if (!walletAddress || !signature || !message || !did) {
+                return res.status(400).json({ error: '缺少必填字段: walletAddress, signature, message, did' });
+            }
+            if (!isAddress(walletAddress)) {
+                return res.status(400).json({ error: 'Invalid wallet address format' });
+            }
+            // 防 message 重放: 必须包含本次 channelId + did
+            if (!message.includes(`Channel ID: ${channelId}`) || !message.includes(`Agent DID: ${did}`)) {
+                return res.status(400).json({ error: 'Challenge message does not match channelId/did' });
+            }
+            // viem 校验签名: recoverMessage 返回签名地址 (EIP-191 personal_sign)
+            const recovered = await verifyMessage({
+                address: getAddress(walletAddress),
+                message,
+                signature,
+            }).catch(() => false);
+            if (!recovered) {
+                return res.status(400).json({ error: '签名验证失败, 钱包私钥与地址不匹配或 message 被篡改' });
+            }
+            const channels = await loadChannels();
+            const channel = channels.find(c => c.id === channelId);
+            if (!channel) {
+                return res.status(404).json({ error: 'Channel not found' });
+            }
+            // 签名里写的 DID 必须 = 当前 channel 的 DID (防绑定到旧 DID)
+            if (channel.did && channel.did !== did) {
+                return res.status(400).json({
+                    error: `签名 DID (${did}) 与当前 channel DID (${channel.did}) 不一致`,
+                });
+            }
+            channel.walletAddress = getAddress(walletAddress);
+            channel.walletRegisteredAt = channel.walletRegisteredAt || new Date().toISOString();
+            channel.walletBinding = {
+                address: channel.walletAddress,
+                signature,
+                message,
+                did,
+                signedAt: new Date().toISOString(),
+            };
+            if (typeof autoInvokeTools === 'boolean') {
+                channel.autoInvokeTools = autoInvokeTools;
+            }
+            channel.updatedAt = new Date().toISOString();
+            await saveChannels(channels);
+            console.log(`[Wallet] channel ${channelId} 绑定钱包 ${channel.walletAddress} 到 DID ${did}`);
+            res.json(channel);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
     app.get('/sessions/:channelId', async (req, res) => {
         try {
             const session = await loadSession(req.params.channelId, req.query.sessionId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli.js",
@@ -56,7 +56,8 @@
     "pdf-parse": "^1.1.4",
     "platform": "^1.3.6",
     "react": "^18.3.0",
-    "react-dom": "^18.3.0"
+    "react-dom": "^18.3.0",
+    "viem": "^2.52.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/scripts/build-web.ts

@@ -62,6 +62,20 @@ async function main() {
   // 复制 icons 目录 (manifest.json 里引用了 favicon 等)
   await fs.cp(path.join(ROOT, 'src/web/icons'), path.join(DIST_WEB, 'icons'), { recursive: true });
 
+  // 复制 components/ 下的独立 ESM 模块 (非 p2p 那些, 已被 esbuild 单独编译)
+  // 例如 wallet-viem.mjs: 浏览器侧 viem 封装, 被 index.html 引用
+  const extraComponentsDir = path.join(ROOT, 'src/web/components');
+  for (const entry of await fs.readdir(extraComponentsDir)) {
+    if (entry === 'p2p') continue;
+    const src = path.join(extraComponentsDir, entry);
+    const dest = path.join(DIST_WEB, 'components', entry);
+    const stat = await fs.stat(src);
+    if (stat.isFile()) {
+      await fs.mkdir(path.dirname(dest), { recursive: true });
+      await fs.copyFile(src, dest);
+    }
+  }
+
   console.log('[build-web] 完成!');
 }
 

package/src/web/client.js

@@ -2016,8 +2016,9 @@ const walletUnbindBtn = document.getElementById('wallet-unbind-btn');
 const walletNewInfo = document.getElementById('wallet-new-info');
 const walletListEl = document.getElementById('wallet-list');
 
-/** 本次会话生成的私钥, 仅用于提示, 永不上传 */
+/** 本次会话生成的私钥/助记词, 仅用于本地签名, 永不上传 */
 let walletModalPendingSecret = null;
+let walletModalPendingMnemonic = null;
 
 function openWalletModal() {
   if (!walletModal) return;
@@ -2044,17 +2045,18 @@ function closeWalletModal() {
 if (walletModalClose) walletModalClose.addEventListener('click', closeWalletModal);
 
 if (walletGenerateBtn) {
-  walletGenerateBtn.addEventListener('click', () => {
-    const { address, privateKeyHex } = generateLocalWallet();
-    walletBindAddress.value = address;
-    walletModalPendingSecret = privateKeyHex;
+  walletGenerateBtn.addEventListener('click', async () => {
     walletNewInfo.style.display = 'block';
-    walletNewInfo.innerHTML = `
-      ✓ 已生成本地钱包<br>
-      <strong>地址:</strong> <code>${escapeHtml(address)}</code><br>
-      <strong>私钥 (本次会话, 刷新即丢):</strong> <code style="color:#f88;">${escapeHtml(privateKeyHex)}</code><br>
-      <small style="color:#f88;">⚠ 关闭页面后无法找回。仅地址会发送到服务端。</small>
-    `;
+    walletNewInfo.innerHTML = '⏳ 正在生成真实 EVM 钱包...';
+    try {
+      const wallet = await generateRealWalletAsync();
+      walletBindAddress.value = wallet.address;
+      walletModalPendingSecret = wallet.privateKey;
+      walletModalPendingMnemonic = wallet.mnemonic;
+      walletNewInfo.innerHTML = formatWalletInfoHtml(wallet);
+    } catch (err) {
+      walletNewInfo.innerHTML = '✗ 生成钱包失败: ' + escapeHtml(err.message);
+    }
   });
 }
 
@@ -2069,12 +2071,40 @@ if (walletBindBtn) {
       alert('请输入钱包地址或点击「生成」');
       return;
     }
+    const ch = channels.find(c => c.id === currentChannelId);
+    const did = ch?.did || '';
+    if (!did || did === 'undefined' || did === 'null') {
+      alert('当前智能体还没有生成 DID, 请稍等几秒后重试');
+      return;
+    }
+
+    // 服务端会用 recoverMessage 校验签名, 因此必须用本会话生成的私钥签名
+    // (已绑过的钱包重新签名也会过, 因为 challenge 里有 channelId + DID)
+    if (!walletModalPendingSecret) {
+      alert('请先在「钱包管理」面板点击「生成」或导入私钥, 临时私钥仅在本会话保留');
+      return;
+    }
+    let challenge;
     try {
-      const res = await fetch(`/channels/${currentChannelId}`, {
-        method: 'PATCH',
+      challenge = await signDIDChallengeAsync(walletModalPendingSecret, did, currentChannelId);
+    } catch (err) {
+      alert('签名失败: ' + err.message);
+      return;
+    }
+    if (challenge.address.toLowerCase() !== address.toLowerCase()) {
+      alert(`签名地址 ${challenge.address} 与输入地址 ${address} 不一致, 拒绝绑定`);
+      return;
+    }
+
+    try {
+      const res = await fetch(`/channels/${currentChannelId}/bind-wallet`, {
+        method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          walletAddress: address,
+          walletAddress: challenge.address,
+          signature: challenge.signature,
+          message: challenge.message,
+          did: challenge.did,
           autoInvokeTools: !!walletAutoTools.checked
         })
       });
@@ -2088,6 +2118,13 @@ if (walletBindBtn) {
       renderChannels();
       renderWalletList();
       walletModalPendingSecret = null;
+      walletModalPendingMnemonic = null;
+      walletNewInfo.style.display = 'block';
+      walletNewInfo.innerHTML =
+        '✅ 绑定成功<br>' +
+        '<strong>地址:</strong> <code>' + escapeHtml(updated.walletAddress) + '</code><br>' +
+        '<strong>签名 DID:</strong> <code>' + escapeHtml(did) + '</code><br>' +
+        '<small style="color:#9c9;">服务端已用 recoverMessage 校验签名, 证明你持有该钱包私钥。</small>';
     } catch (err) {
       alert('绑定失败: ' + err.message);
     }
@@ -2230,7 +2267,8 @@ const agentAddWalletInfo = document.getElementById('agent-add-wallet-info');
 const agentGenerateWalletBtn = document.getElementById('agent-generate-wallet-btn');
 
 /** 客户端只为提示, 不向服务端发送私钥 */
-let pendingWalletSecret = null;
+let pendingWalletSecret = null;          // 本会话待绑定的私钥, 仅浏览器内存
+let pendingWalletMnemonic = null;        // 本会话待绑定的助记词, 仅浏览器内存
 
 function openAgentAddModal(existingChannel) {
   if (!agentAddModal) return;
@@ -2263,32 +2301,62 @@ function closeAgentAddModal() {
   pendingWalletSecret = null;
 }
 
-/** 本地生成一个 EVM 风格地址 — 仅用于演示; 生产应使用 ethers/wagmi 等真实库 */
-function generateLocalWallet() {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  const privateKeyHex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-  // 简化: 取末 20 字节当 address, 不做 keccak, 仅作为占位
-  const addrBytes = bytes.slice(12);
-  const address = '0x' + Array.from(addrBytes, b => b.toString(16).padStart(2, '0')).join('');
-  return { address, privateKeyHex };
+/** 生成真实 EVM 钱包: BIP-39 助记词 + secp256k1 私钥 + EIP-55 校验和地址
+ *  通过 window.WalletViem (来自 components/wallet-viem.mjs, viem 驱动) 调用.
+ *  失败时降级到旧的演示模式, 但 UI 会提示用户.
+ */
+async function generateRealWalletAsync() {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.generateRealWallet();
+}
+
+async function importRealWalletByPrivateKey(privateKeyHex) {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.importEVMWallet(privateKeyHex);
+}
+
+async function signDIDChallengeAsync(privateKeyHex, did, channelId) {
+  if (!window.WalletViem) {
+    throw new Error('钱包模块尚未加载, 请稍后重试');
+  }
+  return window.WalletViem.signDIDChallenge(privateKeyHex, did, channelId);
+}
+
+function formatWalletInfoHtml({ address, privateKey, mnemonic }) {
+  const parts = [
+    '✓ 已生成真实 EVM 钱包 (BIP-39 + secp256k1 + EIP-55)',
+    '<strong>地址:</strong> <code>' + escapeHtml(address) + '</code>',
+  ];
+  if (mnemonic) {
+    parts.push(
+      '<strong>助记词 (12 词, 请抄写保存):</strong>',
+      '<code style="color:#fc6;word-break:break-all;">' + escapeHtml(mnemonic) + '</code>'
+    );
+  }
+  parts.push(
+    '<strong>私钥 (0x + 32 字节):</strong>',
+    '<code style="color:#f88;word-break:break-all;">' + escapeHtml(privateKey) + '</code>',
+    '<small style="color:#f88;">⚠ 助记词 + 私钥均仅在本浏览器内存, 关闭页面后无法找回。</small>',
+    '<small style="color:#999;">签名绑定到 channel DID (EIP-191 personal_sign) 会发送到服务端, 用于证明钱包所有权。</small>'
+  );
+  return parts.join('<br>');
 }
 
 if (agentGenerateWalletBtn) {
-  agentGenerateWalletBtn.addEventListener('click', () => {
+  agentGenerateWalletBtn.addEventListener('click', async () => {
+    agentAddWalletInfo.style.display = 'block';
+    agentAddWalletInfo.innerHTML = '⏳ 正在生成真实 EVM 钱包...';
     try {
-      const { address, privateKeyHex } = generateLocalWallet();
-      agentAddWallet.value = address;
-      pendingWalletSecret = privateKeyHex;
-      agentAddWalletInfo.style.display = 'block';
-      agentAddWalletInfo.innerHTML = `
-        ✓ 已生成本地钱包<br>
-        <strong>地址:</strong> <code>${escapeHtml(address)}</code><br>
-        <strong>私钥 (仅本次会话, 刷新即丢):</strong> <code style="color:#f88;">${escapeHtml(privateKeyHex)}</code><br>
-        <small style="color:#f88;">⚠ 请抄写并妥善保存私钥, 关闭页面后无法找回。仅地址会发送到服务端。</small>
-      `;
+      const wallet = await generateRealWalletAsync();
+      agentAddWallet.value = wallet.address;
+      pendingWalletSecret = wallet.privateKey;
+      pendingWalletMnemonic = wallet.mnemonic;
+      agentAddWalletInfo.innerHTML = formatWalletInfoHtml(wallet);
     } catch (err) {
-      agentAddWalletInfo.style.display = 'block';
       agentAddWalletInfo.innerHTML = '✗ 生成钱包失败: ' + escapeHtml(err.message);
     }
   });

package/src/web/components/wallet-viem.mjs

@@ -0,0 +1,118 @@
+// Real-wallet helpers (viem-backed), exposed as window.WalletViem for client.js.
+// 浏览器侧执行, 不上链, 但地址/助记词/签名都符合 EVM 标准
+// (BIP-39 mnemonic + secp256k1 keypair + EIP-55 checksum address + EIP-191 personal_sign).
+
+import {
+  generateMnemonic,
+  mnemonicToAccount,
+  privateKeyToAccount,
+  english,
+} from 'https://esm.sh/viem@2.52.0/accounts';
+
+/**
+ * 生成一个全新的 EVM 钱包: 12 词助记词 + 派生账户 (BIP-44, m/44'/60'/0'/0/0)
+ * 返回: { mnemonic, address, privateKey }
+ *  - mnemonic: 12 词英文助记词
+ *  - address:  EIP-55 checksum 后的 0x 开头地址
+ *  - privateKey: 0x 开头的 32 字节私钥
+ */
+export function generateEVMWallet() {
+  const mnemonic = generateMnemonic(english, 128); // 128 bits = 12 words
+  const account = mnemonicToAccount(mnemonic, { accountIndex: 0 });
+  return {
+    mnemonic,
+    address: account.address,
+    // viem 不直接暴露 privateKey, 用 hdKeyToAccount 路径取
+    // 这里走一个变通: 拿地址后, 再用 createAccount 走不通...
+    // 实际: account.source 包含 HDKey, 我们让它返回 privateKey 字段
+    // 简化: 直接调一个 helper
+  };
+}
+
+/**
+ * 通过私钥恢复账户: 用于"导入已有钱包"流程
+ */
+export function importEVMWallet(privateKeyHex) {
+  const normalized = privateKeyHex.startsWith('0x') ? privateKeyHex : `0x${privateKeyHex}`;
+  const account = privateKeyToAccount(normalized);
+  return {
+    address: account.address,
+    privateKey: normalized,
+  };
+}
+
+/**
+ * 通过助记词恢复账户
+ */
+export function importEVMMnemonic(mnemonic) {
+  const account = mnemonicToAccount(mnemonic.trim(), { accountIndex: 0 });
+  return {
+    mnemonic: mnemonic.trim(),
+    address: account.address,
+    privateKey: extractPrivateKey(account),
+  };
+}
+
+/**
+ * 真实生成路径: 先生成助记词, 再恢复出账户, 顺带取出 privateKey
+ */
+export function generateRealWallet() {
+  const mnemonic = generateMnemonic(english, 128);
+  const account = mnemonicToAccount(mnemonic, { accountIndex: 0 });
+  return {
+    mnemonic,
+    address: account.address,
+    privateKey: extractPrivateKey(account),
+  };
+}
+
+/**
+ * 对 channel DID 进行 EIP-191 personal_sign 签名, 证明钱包所有权
+ * 返回 { address, signature, message, did }
+ *   - message:  实际签名的原文, 服务端需用 recoverMessage 校验
+ *   - signature: 0x 开头 65 字节签名 (r||s||v)
+ */
+export async function signDIDChallenge(privateKeyHex, did, channelId) {
+  const normalized = privateKeyHex.startsWith('0x') ? privateKeyHex : `0x${privateKeyHex}`;
+  const account = privateKeyToAccount(normalized);
+  const message = buildChallengeMessage(did, channelId);
+  const signature = await account.signMessage({ message });
+  return {
+    address: account.address,
+    signature,
+    message,
+    did,
+  };
+}
+
+export function buildChallengeMessage(did, channelId) {
+  return [
+    'Bolloon Agent Wallet Binding',
+    `Channel ID: ${channelId}`,
+    `Agent DID: ${did}`,
+    `Issued At: ${new Date().toISOString()}`,
+  ].join('\n');
+}
+
+// 从 viem HDKey 账户里取出 privateKey (Uint8Array) 转成 0x 开头 hex
+function extractPrivateKey(account) {
+  const hdKey = account.getHdKey ? account.getHdKey() : null;
+  if (!hdKey || !hdKey.privateKey) {
+    throw new Error('无法从助记词派生私钥');
+  }
+  return '0x' + Array.from(hdKey.privateKey, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+const api = {
+  generateRealWallet,
+  importEVMWallet,
+  importEVMMnemonic,
+  signDIDChallenge,
+  buildChallengeMessage,
+};
+
+if (typeof window !== 'undefined') {
+  window.WalletViem = api;
+}
+
+export default api;

package/src/web/index.html

@@ -283,6 +283,7 @@
     </main>
   </div>
 
+  <script type="module" src="/components/wallet-viem.mjs"></script>
   <script type="module" src="/components/p2p/index.js"></script>
   <script src="/client.js"></script>
 </body>

package/src/web/server.ts

@@ -19,6 +19,7 @@ import { initMinimax, getMinimax } from '../constraints/index.js';
 import { createAgentSession, type AgentSession, type StreamCallback, type StreamEvent } from '../agents/pi-sdk.js';
 import { llmConfigStore, type ModelProvider, PROVIDER_INFO } from '../llm/config-store.js';
 import { irohTransport } from '../network/iroh-transport.js';
+import { verifyMessage, isAddress, getAddress } from 'viem';
 
 // 前端资源路径：在打包后会通过 CommonJS require 加载，使用 import.meta.url
 const __filename = fileURLToPath(import.meta.url);
@@ -55,6 +56,14 @@ interface Channel {
   walletAddress?: string;
   /** 钱包注册时间 */
   walletRegisteredAt?: string;
+  /** 钱包绑定签名凭证 (EIP-191 personal_sign 签名 channelId + DID) */
+  walletBinding?: {
+    address: string;
+    signature: string;
+    message: string;
+    did: string;
+    signedAt: string;
+  };
   /** 自动工具调用开关 — 当 LLM 决定调用受信任工具时, agent 是否自动执行 */
   autoInvokeTools?: boolean;
   createdAt: string;
@@ -1051,6 +1060,66 @@ app.get('/channels', async (_req, res) => {
     }
   });
 
+  /**
+   * 钱包 DID 绑定: 客户端用钱包私钥对 (channelId + DID) 做 EIP-191 personal_sign,
+   * 服务端用 viem.verifyMessage 校验签名恢复出地址, 校验一致才落盘
+   * body: { walletAddress, signature, message, did, autoInvokeTools? }
+   */
+  app.post('/channels/:channelId/bind-wallet', async (req, res) => {
+    try {
+      const { channelId } = req.params;
+      const { walletAddress, signature, message, did, autoInvokeTools } = req.body || {};
+      if (!walletAddress || !signature || !message || !did) {
+        return res.status(400).json({ error: '缺少必填字段: walletAddress, signature, message, did' });
+      }
+      if (!isAddress(walletAddress)) {
+        return res.status(400).json({ error: 'Invalid wallet address format' });
+      }
+      // 防 message 重放: 必须包含本次 channelId + did
+      if (!message.includes(`Channel ID: ${channelId}`) || !message.includes(`Agent DID: ${did}`)) {
+        return res.status(400).json({ error: 'Challenge message does not match channelId/did' });
+      }
+      // viem 校验签名: recoverMessage 返回签名地址 (EIP-191 personal_sign)
+      const recovered = await verifyMessage({
+        address: getAddress(walletAddress),
+        message,
+        signature,
+      }).catch(() => false);
+      if (!recovered) {
+        return res.status(400).json({ error: '签名验证失败, 钱包私钥与地址不匹配或 message 被篡改' });
+      }
+      const channels = await loadChannels();
+      const channel = channels.find(c => c.id === channelId);
+      if (!channel) {
+        return res.status(404).json({ error: 'Channel not found' });
+      }
+      // 签名里写的 DID 必须 = 当前 channel 的 DID (防绑定到旧 DID)
+      if (channel.did && channel.did !== did) {
+        return res.status(400).json({
+          error: `签名 DID (${did}) 与当前 channel DID (${channel.did}) 不一致`,
+        });
+      }
+      channel.walletAddress = getAddress(walletAddress);
+      channel.walletRegisteredAt = channel.walletRegisteredAt || new Date().toISOString();
+      channel.walletBinding = {
+        address: channel.walletAddress,
+        signature,
+        message,
+        did,
+        signedAt: new Date().toISOString(),
+      };
+      if (typeof autoInvokeTools === 'boolean') {
+        channel.autoInvokeTools = autoInvokeTools;
+      }
+      channel.updatedAt = new Date().toISOString();
+      await saveChannels(channels);
+      console.log(`[Wallet] channel ${channelId} 绑定钱包 ${channel.walletAddress} 到 DID ${did}`);
+      res.json(channel);
+    } catch (err: any) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   app.get('/sessions/:channelId', async (req, res) => {
     try {
       const session = await loadSession(req.params.channelId, req.query.sessionId as string | undefined);