@portkey/eoa-agent-skills 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @portkey/eoa-agent-skills
 
+[中文版](./README.zh-CN.md) | English
+
 AI Agent Skills for Portkey EOA Wallet on [aelf blockchain](https://aelf.com). Provides MCP, CLI, and SDK interfaces for wallet management, token transfers, asset queries, and smart contract interactions.
 
 ## Features
@@ -62,7 +64,7 @@ cp .env.example .env
 | `PORTKEY_NETWORK` | `mainnet` | `mainnet` |
 | `PORTKEY_API_URL` | Override API base URL | Auto from network |
 | `PORTKEY_PRIVATE_KEY` | Plaintext private key (optional) | — |
-| `PORTKEY_WALLET_DIR` | Custom wallet storage directory | `~/.portkey-agent/wallets/` |
+| `PORTKEY_WALLET_DIR` | Custom wallet storage directory | `~/.portkey/eoa/wallets/` |
 | `PORTKEY_WALLET_PASSWORD` | Password for local wallet encryption | — |
 
 ### MCP Server
@@ -136,14 +138,15 @@ const result = await transfer(config, {
 console.log('TX:', result.transactionId);
 ```
 
-## MCP Tools (20 total)
+## MCP Tools (21 total)
 
-### Wallet Management (5)
+### Wallet Management (6)
 - `portkey_create_wallet` — Create new wallet with encrypted local storage
 - `portkey_import_wallet` — Import from mnemonic or private key
 - `portkey_get_wallet_info` — View wallet public info
 - `portkey_list_wallets` — List all local wallets
 - `portkey_backup_wallet` — Export wallet credentials
+- `portkey_delete_wallet` — Delete a local wallet (requires password)
 
 ### Asset Queries (7)
 - `portkey_get_token_list` — Token portfolio with balances
@@ -186,6 +189,10 @@ bun test tests/unit/        # Unit tests
 bun run tests/e2e/mcp-verify.ts  # MCP verification
 ```
 
+## Known Issues
+
+- **elliptic <= 6.6.1**: `aelf-sdk` has a transitive dependency on `elliptic` with a known low-severity vulnerability. This is an upstream issue — tracked for resolution when `aelf-sdk` updates its dependency.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # @portkey/eoa-agent-skills
 
+[English](./README.md) | 中文
+
 [aelf 区块链](https://aelf.com) 上 Portkey EOA 钱包的 AI Agent Skills。提供 MCP、CLI 和 SDK 三种接口，覆盖钱包管理、Token 转账、资产查询和智能合约交互。
 
 ## 功能
@@ -62,7 +64,7 @@ cp .env.example .env
 | `PORTKEY_NETWORK` | `mainnet` | `mainnet` |
 | `PORTKEY_API_URL` | 覆盖 API 基础 URL | 根据网络自动选择 |
 | `PORTKEY_PRIVATE_KEY` | 明文私钥（可选） | — |
-| `PORTKEY_WALLET_DIR` | 自定义钱包存储目录 | `~/.portkey-agent/wallets/` |
+| `PORTKEY_WALLET_DIR` | 自定义钱包存储目录 | `~/.portkey/eoa/wallets/` |
 | `PORTKEY_WALLET_PASSWORD` | 本地钱包加密密码 | — |
 
 ### MCP Server
@@ -136,14 +138,15 @@ const result = await transfer(config, {
 console.log('交易ID:', result.transactionId);
 ```
 
-## MCP Tools（共 20 个）
+## MCP Tools（共 21 个）
 
-### 钱包管理（5）
+### 钱包管理（6）
 - `portkey_create_wallet` — 创建新钱包并加密存储
 - `portkey_import_wallet` — 导入钱包（助记词/私钥）
 - `portkey_get_wallet_info` — 查看钱包公开信息
 - `portkey_list_wallets` — 列出所有本地钱包
 - `portkey_backup_wallet` — 导出钱包凭证
+- `portkey_delete_wallet` — 删除本地钱包（需密码验证）
 
 ### 资产查询（7）
 - `portkey_get_token_list` — Token 列表和余额
@@ -186,6 +189,10 @@ bun test tests/unit/        # 单元测试
 bun run tests/e2e/mcp-verify.ts  # MCP 验证
 ```
 
+## Known Issues
+
+- **elliptic <= 6.6.1**：`aelf-sdk` 的传递依赖 `elliptic` 存在一个 low 级别漏洞，属上游问题，等待 `aelf-sdk` 更新修复。
+
 ## License
 
 MIT

package/index.ts

@@ -7,7 +7,9 @@ export {
   getWalletInfo,
   listWallets,
   backupWallet,
+  deleteWalletByAddress,
   resolvePrivateKey,
+  createSignerFromWallet,
 } from './src/core/wallet.js';
 
 // Core: Queries
@@ -44,12 +46,24 @@ export {
 // Config
 export { getConfig } from './lib/config.js';
 
+// Crypto utilities
+export { generateStrongPassword } from './lib/crypto.js';
+
+// --- AelfSigner integration (for use with awaken/eforest DApp skills) ---
+export type { AelfSigner } from '@portkey/aelf-signer';
+export {
+  createEoaSigner,
+  createSignerFromEnv,
+  EoaSigner,
+} from '@portkey/aelf-signer';
+
 // Types
 export type {
   PortkeyConfig,
   NetworkType,
   ChainInfo,
   StoredWallet,
+  WalletPublicInfo,
   CreateWalletParams,
   CreateWalletResult,
   ImportWalletParams,

package/lib/aelf.ts

@@ -32,16 +32,23 @@ interface SendOptions {
 // Wallet helpers
 // ============================================================
 
-/** A common read-only private key used for view-only contract calls. */
-const COMMON_PRIVATE =
+/**
+ * Default read-only private key for view-only contract calls.
+ * Override via PORTKEY_READONLY_PRIVATE_KEY env variable.
+ */
+const DEFAULT_READONLY_PRIVATE_KEY =
   'f6e512a3c259e5f9af981d7f99d245aa5bc52fe448495e0b0dd56e8406be6f71';
 
+function getReadonlyPrivateKey(): string {
+  return process.env.PORTKEY_READONLY_PRIVATE_KEY || DEFAULT_READONLY_PRIVATE_KEY;
+}
+
 /**
  * Create an aelf wallet object from a private key.
- * If no key is provided, uses a common read-only key (for view calls).
+ * If no key is provided, uses a read-only key (for view calls).
  */
 export function getWallet(privateKey?: string): AElfWallet {
-  return AElf.wallet.getWalletByPrivateKey(privateKey || COMMON_PRIVATE);
+  return AElf.wallet.getWalletByPrivateKey(privateKey || getReadonlyPrivateKey());
 }
 
 /**

package/lib/api.ts

@@ -1,4 +1,5 @@
 import type { PortkeyConfig, AddressInfo } from './types.js';
+import { getAelfAddress, getChainIdFromAddress } from './aelf.js';
 
 const DEFAULT_TIMEOUT = 30000;
 
@@ -62,11 +63,15 @@ async function request<T>(
 // ============================================================
 
 function buildAddressInfos(
-  address: string,
+  rawAddress: string,
   chainId?: string,
 ): AddressInfo[] {
-  if (chainId) {
-    return [{ chainId, address }];
+  // Strip ELF_xxx_ChainId format → raw address, and extract chainId if embedded
+  const address = getAelfAddress(rawAddress);
+  const resolvedChainId = chainId || getChainIdFromAddress(rawAddress);
+
+  if (resolvedChainId) {
+    return [{ chainId: resolvedChainId, address }];
   }
   // If no specific chainId, include common aelf chains
   return [

package/lib/crypto.ts

@@ -1,4 +1,22 @@
 import AElf from 'aelf-sdk';
+import { randomBytes } from 'crypto';
+
+const PASSWORD_LENGTH = 24;
+const PASSWORD_CHARSET =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*_+-=';
+
+/**
+ * Generate a cryptographically strong random password.
+ * 24 chars from a 74-char alphabet ≈ 148 bits of entropy.
+ */
+export function generateStrongPassword(): string {
+  const bytes = randomBytes(PASSWORD_LENGTH);
+  let password = '';
+  for (let i = 0; i < PASSWORD_LENGTH; i++) {
+    password += PASSWORD_CHARSET[bytes[i] % PASSWORD_CHARSET.length];
+  }
+  return password;
+}
 
 /**
  * AES encrypt a string using aelf-sdk's built-in AES.

package/lib/storage.ts

@@ -3,47 +3,123 @@ import * as path from 'path';
 import * as os from 'os';
 import type { StoredWallet } from './types.js';
 
-const DEFAULT_WALLET_DIR = path.join(os.homedir(), '.portkey-agent', 'wallets');
+const DEFAULT_WALLET_DIR = path.join(os.homedir(), '.portkey', 'eoa', 'wallets');
+
+// Legacy directories from previous versions (newest first)
+const LEGACY_WALLET_DIRS = [
+  path.join(os.homedir(), '.portkey-eoa', 'wallets'),
+  path.join(os.homedir(), '.portkey-agent', 'wallets'),
+];
+
+// aelf addresses are Base58-encoded (1-9, A-Z, a-z excluding 0, O, I, l)
+const AELF_ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{30,60}$/;
+
+let migrationChecked = false;
+
+/** Reset migration flag (for testing only). */
+export function _resetMigrationFlag(): void {
+  migrationChecked = false;
+}
 
 /**
  * Get the wallet storage directory.
- * Priority: PORTKEY_WALLET_DIR env > default ~/.portkey-agent/wallets/
+ * Priority: PORTKEY_WALLET_DIR env > default ~/.portkey/eoa/wallets/
  */
 export function getWalletDir(): string {
   return process.env.PORTKEY_WALLET_DIR || DEFAULT_WALLET_DIR;
 }
 
 /**
- * Ensure the wallet directory exists.
+ * Validate an address string and return a safe absolute file path.
+ * Prevents path traversal attacks by:
+ *  1. Checking the address matches the Base58 character set
+ *  2. Verifying the resolved path stays inside the wallet directory
  */
-function ensureDir(): void {
-  const dir = getWalletDir();
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+function safeWalletPath(address: string): string {
+  if (!address || !AELF_ADDRESS_RE.test(address)) {
+    throw new Error(`Invalid address format: ${address}`);
   }
+  const dir = path.resolve(getWalletDir());
+  const resolved = path.resolve(dir, `${address}.json`);
+  if (!resolved.startsWith(dir + path.sep) && resolved !== dir) {
+    throw new Error('Path traversal detected');
+  }
+  return resolved;
 }
 
 /**
- * Get the file path for a wallet by address.
+ * Auto-migrate wallet files from legacy directories to the current directory.
+ * Only runs once per process. Copies (does not delete) files from old locations.
+ * Skips files that already exist in the new directory (no overwrite).
  */
-function walletPath(address: string): string {
-  return path.join(getWalletDir(), `${address}.json`);
+function migrateFromLegacy(): void {
+  if (migrationChecked) return;
+  migrationChecked = true;
+
+  // Skip migration if user overrode the directory via env
+  if (process.env.PORTKEY_WALLET_DIR) return;
+
+  const targetDir = getWalletDir();
+
+  for (const legacyDir of LEGACY_WALLET_DIRS) {
+    if (!fs.existsSync(legacyDir)) continue;
+
+    const files = fs.readdirSync(legacyDir).filter((f) => f.endsWith('.json'));
+    if (files.length === 0) continue;
+
+    // Ensure target exists before copying
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    }
+
+    let migrated = 0;
+    for (const file of files) {
+      const dest = path.join(targetDir, file);
+      if (fs.existsSync(dest)) continue; // don't overwrite
+      const src = path.join(legacyDir, file);
+      fs.copyFileSync(src, dest);
+      fs.chmodSync(dest, 0o600);
+      migrated++;
+    }
+
+    if (migrated > 0) {
+      console.error(
+        `[portkey] Migrated ${migrated} wallet(s) from ${legacyDir} → ${targetDir}`,
+      );
+    }
+  }
+}
+
+/**
+ * Ensure the wallet directory exists with restricted permissions (0700).
+ * On first call, also checks for legacy directories and auto-migrates.
+ */
+function ensureDir(): void {
+  const dir = getWalletDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  migrateFromLegacy();
 }
 
 /**
- * Save a wallet to local storage (encrypted JSON file).
+ * Save a wallet to local storage (encrypted JSON file, mode 0600).
  */
 export function saveWallet(wallet: StoredWallet): void {
   ensureDir();
-  const filePath = walletPath(wallet.address);
-  fs.writeFileSync(filePath, JSON.stringify(wallet, null, 2) + '\n', 'utf-8');
+  const filePath = safeWalletPath(wallet.address);
+  fs.writeFileSync(filePath, JSON.stringify(wallet, null, 2) + '\n', {
+    encoding: 'utf-8',
+    mode: 0o600,
+  });
 }
 
 /**
  * Load a wallet from local storage by address.
  */
 export function loadWallet(address: string): StoredWallet {
-  const filePath = walletPath(address);
+  ensureDir();
+  const filePath = safeWalletPath(address);
   if (!fs.existsSync(filePath)) {
     throw new Error(`Wallet not found: ${address}`);
   }
@@ -52,7 +128,9 @@ export function loadWallet(address: string): StoredWallet {
 }
 
 /**
- * List all locally stored wallets (public info only).
+ * List all locally stored wallets.
+ * Returns full StoredWallet objects (internal use).
+ * Use core/wallet.ts listWallets() for public-facing sanitized output.
  */
 export function listWallets(): StoredWallet[] {
   ensureDir();
@@ -68,7 +146,8 @@ export function listWallets(): StoredWallet[] {
  * Delete a wallet file by address.
  */
 export function deleteWallet(address: string): void {
-  const filePath = walletPath(address);
+  ensureDir();
+  const filePath = safeWalletPath(address);
   if (fs.existsSync(filePath)) {
     fs.unlinkSync(filePath);
   }
@@ -78,5 +157,6 @@ export function deleteWallet(address: string): void {
  * Check if a wallet exists locally.
  */
 export function walletExists(address: string): boolean {
-  return fs.existsSync(walletPath(address));
+  ensureDir();
+  return fs.existsSync(safeWalletPath(address));
 }

package/lib/types.ts

@@ -38,18 +38,34 @@ export interface StoredWallet {
   network: string;
 }
 
+/**
+ * Public-facing wallet info (no secrets).
+ * Used by listWallets and getWalletInfo to avoid leaking encrypted credentials.
+ */
+export interface WalletPublicInfo {
+  address: string;
+  publicKey: { x: string; y: string };
+  name: string;
+  network: string;
+  createdAt: string;
+}
+
 export interface CreateWalletParams {
   name?: string;
-  password: string;
+  password?: string; // optional — auto-generated if omitted
+  redactMnemonic?: boolean; // if true, mnemonic is NOT returned (already encrypted in wallet file, recoverable via wallet backup)
 }
 
 export interface CreateWalletResult {
   address: string;
-  mnemonic: string;
+  mnemonic?: string; // omitted when redactMnemonic is true
+  mnemonicHint?: string; // recovery guidance when mnemonic is redacted
+  passwordGenerated?: boolean; // true if password was auto-generated
+  password?: string; // included only when auto-generated
 }
 
 export interface ImportWalletParams {
-  password: string;
+  password?: string; // optional — auto-generated if omitted
   mnemonic?: string;
   privateKey?: string;
   name?: string;
@@ -57,6 +73,8 @@ export interface ImportWalletParams {
 
 export interface ImportWalletResult {
   address: string;
+  passwordGenerated?: boolean; // true if password was auto-generated
+  password?: string; // included only when auto-generated
 }
 
 export interface GetWalletInfoParams {

package/openclaw.json

@@ -1,17 +1,52 @@
 {
   "name": "portkey-eoa-agent-skills",
-  "description": "AI Agent Skills for Portkey EOA Wallet on aelf blockchain",
+  "description": "AI Agent Skills for Portkey EOA Wallet on aelf blockchain. SECURITY: Never output mnemonic phrases or private keys in channel messages. Auto-generated passwords SHOULD be returned to the user (they need it to unlock the wallet later). Use --redact-mnemonic for wallet creation. Mnemonic is encrypted in the wallet file and recoverable via wallet backup command with the correct password.",
   "tools": [
     {
       "name": "portkey-eoa-wallet-create",
-      "description": "Create a new EOA wallet",
+      "description": "Create a new EOA wallet. Password is auto-generated if omitted. Mnemonic is redacted by default (encrypted in wallet file, recoverable via portkey-eoa-wallet-backup). IMPORTANT: Do NOT output the mnemonic in the channel. The auto-generated password MUST be shown to the user so they can save it — without it the wallet cannot be unlocked.",
       "command": "bun",
-      "args": ["run", "portkey_eoa_skill.ts", "wallet", "create"],
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "create", "--redact-mnemonic"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-wallet-import",
+      "description": "Import a wallet from a private key or mnemonic. Password is auto-generated if omitted. IMPORTANT: Do NOT echo the private key or mnemonic back in the channel. The auto-generated password MUST be shown to the user.",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "import"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-wallet-list",
+      "description": "List all locally stored wallets (public info only: address, name, network)",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "list"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-wallet-info",
+      "description": "Get public info for a specific wallet",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "info"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-wallet-backup",
+      "description": "Export mnemonic and private key (requires password). IMPORTANT: NEVER output mnemonic or private key in a channel message. Instruct the user to run this command on their local machine instead.",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "backup"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-wallet-delete",
+      "description": "Delete a locally stored wallet (requires password verification)",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "wallet", "delete"],
       "cwd": "."
     },
     {
       "name": "portkey-eoa-query-tokens",
-      "description": "Get token list with balances",
+      "description": "Get token list with balances for a wallet address",
       "command": "bun",
       "args": ["run", "portkey_eoa_skill.ts", "query", "tokens"],
       "cwd": "."
@@ -23,26 +58,96 @@
       "args": ["run", "portkey_eoa_skill.ts", "query", "balance"],
       "cwd": "."
     },
+    {
+      "name": "portkey-eoa-query-price",
+      "description": "Get token prices in USD",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "query", "price"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-query-nft-collections",
+      "description": "Get NFT collections for a wallet",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "query", "nft-collections"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-query-nft-items",
+      "description": "Get NFT items in a collection",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "query", "nft-items"],
+      "cwd": "."
+    },
     {
       "name": "portkey-eoa-query-history",
-      "description": "Get transaction history",
+      "description": "Get transaction history for a wallet",
       "command": "bun",
       "args": ["run", "portkey_eoa_skill.ts", "query", "history"],
       "cwd": "."
     },
+    {
+      "name": "portkey-eoa-query-tx",
+      "description": "Get transaction detail by ID",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "query", "tx"],
+      "cwd": "."
+    },
     {
       "name": "portkey-eoa-transfer",
-      "description": "Send a token transfer",
+      "description": "Send a same-chain token transfer",
       "command": "bun",
       "args": ["run", "portkey_eoa_skill.ts", "transfer"],
       "cwd": "."
     },
+    {
+      "name": "portkey-eoa-cross-chain-transfer",
+      "description": "Send a cross-chain token transfer between aelf chains",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "transfer", "--cross-chain"],
+      "cwd": "."
+    },
     {
       "name": "portkey-eoa-contract-view",
       "description": "Call a read-only contract method",
       "command": "bun",
       "args": ["run", "portkey_eoa_skill.ts", "contract", "view"],
       "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-contract-send",
+      "description": "Call a state-changing contract method (requires wallet)",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "contract", "send"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-contract-approve",
+      "description": "Approve token spending allowance",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "contract", "approve"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-contract-estimate-fee",
+      "description": "Estimate transaction fee before sending",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "contract", "estimate-fee"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-ebridge-transfer",
+      "description": "Cross-chain transfer via eBridge (aelf <-> EVM)",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "ebridge", "transfer"],
+      "cwd": "."
+    },
+    {
+      "name": "portkey-eoa-ebridge-limit",
+      "description": "Query eBridge transfer limits",
+      "command": "bun",
+      "args": ["run", "portkey_eoa_skill.ts", "ebridge", "limit"],
+      "cwd": "."
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portkey/eoa-agent-skills",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "AI Agent Skills for Portkey EOA Wallet — MCP, CLI, and SDK interfaces for wallet management, token transfers, asset queries, and contract interactions on aelf blockchain.",
   "type": "module",
   "main": "index.ts",
@@ -39,8 +39,9 @@
     "test:e2e": "bun test tests/e2e/"
   },
   "dependencies": {
-    "aelf-sdk": "^3.5.1-beta.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@portkey/aelf-signer": "^1.0.0",
+    "aelf-sdk": "^3.5.1-beta.0",
     "commander": "^12.1.0",
     "zod": "^3.24.0"
   },

package/portkey_eoa_skill.ts

@@ -9,6 +9,7 @@ import {
   getWalletInfo,
   listWallets,
   backupWallet,
+  deleteWalletByAddress,
 } from './src/core/wallet.js';
 import {
   getChainInfo,
@@ -45,14 +46,16 @@ const wallet = program.command('wallet').description('Wallet management');
 wallet
   .command('create')
   .description('Create a new wallet')
-  .requiredOption('--password <password>', 'Encryption password')
+  .option('--password <password>', 'Encryption password (auto-generated if omitted)')
   .option('--name <name>', 'Wallet name')
+  .option('--redact-mnemonic', 'Save mnemonic to local file instead of printing')
   .action(async (opts) => {
     try {
       const config = getConfig(program.opts().network);
       const result = await createWallet(config, {
         password: opts.password,
         name: opts.name,
+        redactMnemonic: opts.redactMnemonic,
       });
       outputSuccess(result);
     } catch (err: any) {
@@ -63,7 +66,7 @@ wallet
 wallet
   .command('import')
   .description('Import a wallet from mnemonic or private key')
-  .requiredOption('--password <password>', 'Encryption password')
+  .option('--password <password>', 'Encryption password (auto-generated if omitted)')
   .option('--mnemonic <mnemonic>', '12-word mnemonic phrase')
   .option('--private-key <key>', '64-char hex private key')
   .option('--name <name>', 'Wallet name')
@@ -127,6 +130,24 @@ wallet
     }
   });
 
+wallet
+  .command('delete')
+  .description('Delete a locally stored wallet (requires password verification)')
+  .requiredOption('--address <address>', 'Wallet address to delete')
+  .requiredOption('--password <password>', 'Wallet password (for verification)')
+  .action(async (opts) => {
+    try {
+      const config = getConfig(program.opts().network);
+      const result = await deleteWalletByAddress(config, {
+        address: opts.address,
+        password: opts.password,
+      });
+      outputSuccess(result);
+    } catch (err: any) {
+      outputError(err.message);
+    }
+  });
+
 // ============================================================
 // Query commands
 // ============================================================

package/src/core/bridge.ts

@@ -45,6 +45,12 @@ export async function eBridgeTransfer(
     spender: params.bridgeContractAddress,
   });
 
+  if (allowanceResult.error) {
+    throw new Error(
+      `GetAllowance failed: ${allowanceResult.error.message || 'Unknown error'}`,
+    );
+  }
+
   const currentAllowance = BigInt(
     allowanceResult.data?.allowance || allowanceResult.data?.Allowance || '0',
   );

package/src/core/contract.ts

@@ -152,17 +152,30 @@ export async function estimateTransactionFee(
     );
   }
 
-  // Calculate fee via RPC
-  const res = await fetch(
-    `${rpcUrl}/api/blockChain/calculateTransactionFee`,
-    {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ RawTransaction: rawResult.data }),
-    },
-  );
-
-  const txFee = await res.json();
+  // Calculate fee via RPC (with timeout and status check)
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 30000);
+  let txFee: any;
+  try {
+    const res = await fetch(
+      `${rpcUrl}/api/blockChain/calculateTransactionFee`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ RawTransaction: rawResult.data }),
+        signal: controller.signal,
+      },
+    );
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(
+        `RPC error ${res.status}: ${text || res.statusText}`,
+      );
+    }
+    txFee = await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
   if (!txFee?.Success) {
     throw new Error('Failed to calculate transaction fee');
   }

package/src/core/wallet.ts

@@ -9,13 +9,15 @@ import type {
   BackupWalletParams,
   BackupWalletResult,
   StoredWallet,
+  WalletPublicInfo,
 } from '../../lib/types.js';
-import { encrypt, decrypt } from '../../lib/crypto.js';
+import { encrypt, decrypt, generateStrongPassword } from '../../lib/crypto.js';
 import {
   saveWallet,
   loadWallet,
   listWallets as listStoredWallets,
   walletExists,
+  deleteWallet as deleteStoredWallet,
 } from '../../lib/storage.js';
 import {
   createNewWallet,
@@ -31,8 +33,9 @@ export async function createWallet(
   config: PortkeyConfig,
   params: CreateWalletParams,
 ): Promise<CreateWalletResult> {
-  const { password, name } = params;
-  if (!password) throw new Error('password is required');
+  const { name, redactMnemonic } = params;
+  const passwordGenerated = !params.password;
+  const password = params.password || generateStrongPassword();
 
   const walletInfo = createNewWallet();
 
@@ -50,10 +53,30 @@ export async function createWallet(
 
   saveWallet(stored);
 
-  return {
+  const result: CreateWalletResult = {
     address: walletInfo.address,
-    mnemonic: walletInfo.mnemonic || '',
   };
+
+  // Mnemonic handling: redact or return
+  // When redacted, mnemonic is NOT returned — it's already AES-encrypted in the wallet file
+  // and can be recovered via `wallet backup --address <addr> --password <pwd>`
+  if (redactMnemonic) {
+    result.mnemonicHint =
+      'Mnemonic is encrypted and stored in your wallet file. ' +
+      'To recover it, run: wallet backup --address ' +
+      walletInfo.address +
+      ' --password <your_password>';
+  } else {
+    result.mnemonic = walletInfo.mnemonic || '';
+  }
+
+  // Password: include in result only when auto-generated
+  if (passwordGenerated) {
+    result.passwordGenerated = true;
+    result.password = password;
+  }
+
+  return result;
 }
 
 // ============================================================
@@ -64,8 +87,10 @@ export async function importWallet(
   config: PortkeyConfig,
   params: ImportWalletParams,
 ): Promise<ImportWalletResult> {
-  const { password, mnemonic, privateKey, name } = params;
-  if (!password) throw new Error('password is required');
+  const { mnemonic, privateKey, name } = params;
+  const passwordGenerated = !params.password;
+  const password = params.password || generateStrongPassword();
+
   if (!mnemonic && !privateKey) {
     throw new Error('Either mnemonic or privateKey is required');
   }
@@ -101,7 +126,12 @@ export async function importWallet(
 
   saveWallet(stored);
 
-  return { address: walletInfo.address };
+  const result: ImportWalletResult = { address: walletInfo.address };
+  if (passwordGenerated) {
+    result.passwordGenerated = true;
+    result.password = password;
+  }
+  return result;
 }
 
 // ============================================================
@@ -123,13 +153,38 @@ export async function getWalletInfo(
 }
 
 // ============================================================
-// listWallets — List all local wallets (public info only)
+// listWallets — List all local wallets (public info only, sanitized)
 // ============================================================
 
 export async function listWallets(
   _config: PortkeyConfig,
-): Promise<StoredWallet[]> {
-  return listStoredWallets();
+): Promise<WalletPublicInfo[]> {
+  return listStoredWallets().map((w) => ({
+    address: w.address,
+    publicKey: w.publicKey,
+    name: w.name,
+    network: w.network,
+    createdAt: w.createdAt,
+  }));
+}
+
+// ============================================================
+// deleteWallet — Remove a locally stored wallet
+// ============================================================
+
+export async function deleteWalletByAddress(
+  _config: PortkeyConfig,
+  params: { address: string; password: string },
+): Promise<{ address: string; deleted: boolean }> {
+  const { address, password } = params;
+  if (!password) throw new Error('password is required');
+
+  // Verify password is correct before deleting
+  const stored = loadWallet(address);
+  decrypt(stored.AESEncryptPrivateKey, password);
+
+  deleteStoredWallet(address);
+  return { address, deleted: true };
 }
 
 // ============================================================
@@ -198,3 +253,28 @@ function extractPublicKey(walletInfo: any): { x: string; y: string } {
     return { x: '', y: '' };
   }
 }
+
+// ============================================================
+// AelfSigner bridge — create signer from resolved wallet
+// ============================================================
+
+import { createEoaSigner, type AelfSigner } from '@portkey/aelf-signer';
+
+/**
+ * Create an AelfSigner (EoaSigner) from the resolved private key.
+ * Uses the same resolution logic as eoa-agent-skills:
+ *   1. Direct privateKey param
+ *   2. PORTKEY_PRIVATE_KEY env var
+ *   3. Local wallet file (address + password)
+ *
+ * The returned signer can be used with awaken-agent-skills / eforest-agent-skills.
+ */
+export function createSignerFromWallet(params: {
+  privateKey?: string;
+  address?: string;
+  password?: string;
+}): AelfSigner {
+  const pk = resolvePrivateKey(params);
+  return createEoaSigner(pk);
+}
+

package/src/mcp/server.ts

@@ -11,6 +11,7 @@ import {
   getWalletInfo,
   listWallets,
   backupWallet,
+  deleteWalletByAddress,
 } from '../core/wallet.js';
 import {
   getChainInfo,
@@ -65,29 +66,41 @@ function fail(err: any) {
 }
 
 // ============================================================
-// Wallet Management Tools (5)
+// Wallet Management Tools (6)
 // ============================================================
 
 server.registerTool(
   'portkey_create_wallet',
   {
     description:
-      'Create a new EOA wallet on aelf blockchain. Generates a mnemonic and private key, encrypts them with the provided password, and stores the wallet locally. Use when a user needs a fresh wallet. Returns address and mnemonic (save the mnemonic — it cannot be recovered).',
+      'Create a new EOA wallet on aelf blockchain. Generates a mnemonic and private key, encrypts them with a password, and stores the wallet locally.\n\nPassword behavior: If password is omitted, a strong password is auto-generated and returned in the response. After creation, ask the user if they want to persist the password by setting PORTKEY_WALLET_PASSWORD in their environment config. If they decline, remind them to save the password securely — it cannot be recovered.\n\nMnemonic safety: For channel-based environments (Slack, Discord, OpenClaw channels), set redactMnemonic=true so the mnemonic is NOT returned in the response. The mnemonic is already AES-encrypted in the wallet file and can be recovered later via wallet backup with the correct password. For local AI tools (Claude Desktop, Cursor), returning the mnemonic directly is acceptable.',
     inputSchema: {
       name: z.string().optional().describe('Human-readable wallet name'),
       password: z
         .string()
-        .describe('Password to encrypt the wallet private key and mnemonic'),
+        .optional()
+        .describe(
+          'Password to encrypt the wallet. If omitted, a strong password is auto-generated.',
+        ),
+      redactMnemonic: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe(
+          'If true, mnemonic is NOT returned in the response (it is already AES-encrypted in the wallet file, recoverable via wallet backup). Use for channel-based environments (Slack, Discord, OpenClaw) to prevent mnemonic leakage.',
+        ),
       network: z
         .enum(['mainnet'])
         .default('mainnet')
         .describe('Network (mainnet)'),
     },
   },
-  async ({ name, password, network }) => {
+  async ({ name, password, redactMnemonic, network }) => {
     try {
       const config = getConfig(network);
-      return ok(await createWallet(config, { name, password }));
+      return ok(
+        await createWallet(config, { name, password, redactMnemonic }),
+      );
     } catch (err) {
       return fail(err);
     }
@@ -98,7 +111,7 @@ server.registerTool(
   'portkey_import_wallet',
   {
     description:
-      'Import an existing wallet using a 12-word mnemonic phrase or a 64-character hex private key. Encrypts and stores the wallet locally. Use when a user wants to use an existing wallet.',
+      'Import an existing wallet using a 12-word mnemonic phrase or a 64-character hex private key. Encrypts and stores the wallet locally.\n\nPassword behavior: If password is omitted, a strong password is auto-generated and returned. After import, ask the user if they want to persist the password by setting PORTKEY_WALLET_PASSWORD in their environment. If they decline, remind them to save it securely.\n\nSecurity: Never echo the user\'s mnemonic or private key back in channel-based conversations (Slack, Discord, OpenClaw).',
     inputSchema: {
       mnemonic: z
         .string()
@@ -110,7 +123,10 @@ server.registerTool(
         .describe('64-character hex private key (with or without 0x prefix)'),
       password: z
         .string()
-        .describe('Password to encrypt the wallet'),
+        .optional()
+        .describe(
+          'Password to encrypt the wallet. If omitted, a strong password is auto-generated.',
+        ),
       name: z.string().optional().describe('Human-readable wallet name'),
       network: z
         .enum(['mainnet'])
@@ -199,6 +215,34 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  'portkey_delete_wallet',
+  {
+    description:
+      'Delete a locally stored wallet file. Requires the wallet password for verification — the password must be correct before the wallet is removed. Use when a user explicitly wants to remove a wallet from local storage.',
+    inputSchema: {
+      address: z.string().describe('Wallet address to delete'),
+      password: z
+        .string()
+        .describe('Wallet password (must be correct to authorize deletion)'),
+      network: z
+        .enum(['mainnet'])
+        .default('mainnet')
+        .describe('Network (mainnet)'),
+    },
+  },
+  async ({ address, password, network }) => {
+    try {
+      const config = getConfig(network);
+      return ok(
+        await deleteWalletByAddress(config, { address, password }),
+      );
+    } catch (err) {
+      return fail(err);
+    }
+  },
+);
+
 // ============================================================
 // Asset Query Tools (7)
 // ============================================================