clawchain-wallet 1.0.0

package/src/tools.ts

@@ -0,0 +1,623 @@
+/**
+ * ClawChain Agent Tools 定义
+ * 
+ * 使用 OpenClaw Plugin SDK 的类型和辅助函数
+ * 支持按 Agent 隔离钱包存储
+ */
+
+import path from "node:path";
+import { Type } from "@sinclair/typebox";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { jsonResult } from "openclaw/plugin-sdk";
+import type { ExecutorOptions, CommandArgs } from "./executor.js";
+import { executeCommand } from "./executor.js";
+
+/**
+ * Plugin 工具上下文类型
+ * 匹配 OpenClaw 的 OpenClawPluginToolContext
+ */
+export interface ToolContext {
+  workspaceDir?: string;
+  agentId?: string;
+  agentDir?: string;
+  sessionKey?: string;
+  messageChannel?: string;
+  sandboxed?: boolean;
+}
+
+/**
+ * Agent 工具类型定义
+ */
+export interface AgentToolDef {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute: (toolCallId: string, args: Record<string, unknown>) => Promise<AgentToolResult<unknown>>;
+}
+
+/**
+ * 工具工厂函数类型
+ * 匹配 OpenClaw 的 OpenClawPluginToolFactory
+ */
+export type ToolFactory = (ctx: ToolContext) => AgentToolDef | null;
+
+/**
+ * 根据上下文确定钱包存储目录
+ * 
+ * 优先级：
+ * 1. 显式配置的 walletsDir
+ * 2. Agent 工作区目录下的 .wallets
+ * 3. 默认目录（由 Python CLI 决定，通常是 ~/.clawchain/wallets）
+ */
+function resolveWalletsDir(baseOptions: ExecutorOptions, ctx: ToolContext): string | undefined {
+  // 如果显式配置了 walletsDir，优先使用
+  if (baseOptions.walletsDir) {
+    return baseOptions.walletsDir;
+  }
+  
+  // 否则使用 agent 工作区目录
+  if (ctx.workspaceDir) {
+    return path.join(ctx.workspaceDir, ".wallets");
+  }
+  
+  // 都没有则返回 undefined，让 Python CLI 使用默认值
+  return undefined;
+}
+
+/**
+ * 创建所有 ClawChain 工具工厂
+ * 
+ * 每个工厂函数会根据当前 agent 上下文确定钱包存储目录
+ */
+export function createClawChainToolFactories(baseOptions: ExecutorOptions): ToolFactory[] {
+  return [
+    createWalletCreateToolFactory(baseOptions),
+    createWalletImportToolFactory(baseOptions),
+    createWalletListToolFactory(baseOptions),
+    createWalletInfoToolFactory(baseOptions),
+    createWalletDeleteToolFactory(baseOptions),
+    createWalletRenameToolFactory(baseOptions),
+    createWalletExportToolFactory(baseOptions),
+    createBalanceQueryToolFactory(baseOptions),
+    createTransferToolFactory(baseOptions),
+    createTxInfoToolFactory(baseOptions),
+    createTxHistoryToolFactory(baseOptions),
+    createChainInfoToolFactory(baseOptions),
+    createBlockInfoToolFactory(baseOptions),
+    createClaimAirdropToolFactory(baseOptions),
+  ];
+}
+
+// ==================== 钱包创建工具 ====================
+
+function createWalletCreateToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_create",
+      label: "ClawChain Wallet Create",
+      description: `在 ClawChain 上创建新钱包。创建后会自动保存到本地，返回钱包地址和私钥。
+
+【重要】钱包命名规则：
+1. 强烈建议为每个钱包指定一个**唯一且有意义的名称**，方便后续管理和区分
+2. 名称必须是之前未使用过的，否则会报错
+3. 如果不指定名称，系统会自动生成名称（格式：wallet-01, wallet-02 等）
+4. 创建前可以先调用 clawchain_wallet_list 查看已有钱包名称，避免重复
+
+建议的命名方式：
+- 按用途命名：'主钱包'、'储蓄钱包'、'交易钱包'、'测试钱包'
+- 按编号命名：'钱包-1'、'钱包-2' 等`,
+      parameters: Type.Object({
+        name: Type.Optional(
+          Type.String({
+            description: "钱包名称（必须唯一）。强烈建议指定一个有意义且未使用过的名称。如不指定，系统会自动生成 wallet-XX 格式的名称",
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { name?: string };
+        const cmdArgs: CommandArgs = {};
+        if (params.name) {
+          cmdArgs.name = params.name;
+        }
+        const result = executeCommand(options, "wallet-create", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包导入工具 ====================
+
+function createWalletImportToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_import",
+      label: "ClawChain Wallet Import",
+      description: `通过私钥导入已有的钱包到 ClawChain。
+导入后钱包会保存到本地，可以像新创建的钱包一样使用。
+
+【重要】钱包命名规则：
+1. 强烈建议为导入的钱包指定一个**唯一且有意义的名称**
+2. 名称必须是之前未使用过的，否则会报错
+3. 如果不指定名称，系统会自动生成名称（格式：wallet-01, wallet-02 等）
+4. 导入前可以先调用 clawchain_wallet_list 查看已有钱包名称，避免重复`,
+      parameters: Type.Object({
+        private_key: Type.String({
+          description: "要导入的钱包私钥（支持带或不带 0x 前缀）",
+        }),
+        name: Type.Optional(
+          Type.String({
+            description: "钱包名称（必须唯一）。强烈建议指定一个有意义且未使用过的名称。如不指定，系统会自动生成 wallet-XX 格式的名称",
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { private_key: string; name?: string };
+        const cmdArgs: CommandArgs = {
+          private_key: params.private_key,
+        };
+        if (params.name) {
+          cmdArgs.name = params.name;
+        }
+        const result = executeCommand(options, "wallet-import", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包列表工具 ====================
+
+function createWalletListToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_list",
+      label: "ClawChain Wallet List",
+      description: `列出所有已创建或导入的 ClawChain 钱包。
+可以选择是否显示每个钱包的 CLAW 余额。
+返回钱包名称、地址、创建时间等信息。`,
+      parameters: Type.Object({
+        show_balance: Type.Optional(
+          Type.Boolean({
+            description: "是否显示每个钱包的 CLAW 余额（查询余额需要联网，可能稍慢）",
+            default: false,
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { show_balance?: boolean };
+        const cmdArgs: CommandArgs = {
+          show_balance: params.show_balance ?? false,
+        };
+        const result = executeCommand(options, "wallet-list", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包详情工具 ====================
+
+function createWalletInfoToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_info",
+      label: "ClawChain Wallet Info",
+      description: `获取指定钱包的详细信息，包括地址、余额、创建时间等。
+可以通过钱包名称或钱包 ID 来查询。
+默认不显示私钥，需要显示私钥时设置 show_private_key 为 true。`,
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "钱包名称或钱包 ID",
+        }),
+        show_private_key: Type.Optional(
+          Type.Boolean({
+            description: "是否显示私钥（敏感信息，谨慎使用）",
+            default: false,
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { identifier: string; show_private_key?: boolean };
+        const cmdArgs: CommandArgs = {
+          identifier: params.identifier,
+          show_private_key: params.show_private_key ?? false,
+        };
+        const result = executeCommand(options, "wallet-info", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包删除工具 ====================
+
+function createWalletDeleteToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_delete",
+      label: "ClawChain Wallet Delete",
+      description: `删除指定的钱包。删除前会自动备份到 deleted 目录。
+可以通过钱包名称或钱包 ID 来指定要删除的钱包。
+注意：删除后钱包将无法直接使用，但私钥备份仍保留。`,
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "要删除的钱包名称或钱包 ID",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { identifier: string };
+        const cmdArgs: CommandArgs = {
+          identifier: params.identifier,
+        };
+        const result = executeCommand(options, "wallet-delete", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包重命名工具 ====================
+
+function createWalletRenameToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_rename",
+      label: "ClawChain Wallet Rename",
+      description: `重命名指定的钱包。
+可以通过钱包名称或钱包 ID 来指定要重命名的钱包。`,
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "要重命名的钱包名称或钱包 ID",
+        }),
+        new_name: Type.String({
+          description: "新的钱包名称",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { identifier: string; new_name: string };
+        const cmdArgs: CommandArgs = {
+          identifier: params.identifier,
+          new_name: params.new_name,
+        };
+        const result = executeCommand(options, "wallet-rename", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 钱包导出工具 ====================
+
+function createWalletExportToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_wallet_export",
+      label: "ClawChain Wallet Export",
+      description: `导出钱包的私钥。用于备份或在其他地方导入钱包。
+警告：私钥是敏感信息，请勿泄露给他人！`,
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "要导出的钱包名称或钱包 ID",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { identifier: string };
+        const cmdArgs: CommandArgs = {
+          identifier: params.identifier,
+        };
+        const result = executeCommand(options, "wallet-export", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 余额查询工具 ====================
+
+function createBalanceQueryToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_balance",
+      label: "ClawChain Balance",
+      description: `查询 ClawChain 上指定地址或钱包的 CLAW 余额。
+可以输入钱包名称、钱包 ID 或直接输入地址（0x 开头）。
+返回余额（CLAW 和 Wei 两种单位）。`,
+      parameters: Type.Object({
+        address: Type.String({
+          description: "钱包地址（0x 开头）、钱包名称或钱包 ID",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { address: string };
+        const cmdArgs: CommandArgs = {
+          address: params.address,
+        };
+        const result = executeCommand(options, "balance", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 转账工具 ====================
+
+function createTransferToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_transfer",
+      label: "ClawChain Transfer",
+      description: `在 ClawChain 上进行 CLAW 转账。
+从指定钱包转账到目标地址或另一个钱包。
+发送方必须是本地已有的钱包（通过名称或 ID 指定）。
+接收方可以是地址、钱包名称或钱包 ID。`,
+      parameters: Type.Object({
+        from_wallet: Type.String({
+          description: "发送方钱包名称或钱包 ID（必须是本地钱包）",
+        }),
+        to: Type.String({
+          description: "接收方地址（0x 开头）、钱包名称或钱包 ID",
+        }),
+        amount: Type.Number({
+          description: "转账金额（单位：CLAW）",
+        }),
+        wait: Type.Optional(
+          Type.Boolean({
+            description: "是否等待交易确认（默认不等待，立即返回交易哈希）",
+            default: false,
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { from_wallet: string; to: string; amount: number; wait?: boolean };
+        const cmdArgs: CommandArgs = {
+          from_wallet: params.from_wallet,
+          to: params.to,
+          amount: params.amount,
+          wait: params.wait ?? false,
+        };
+        const execOptions = { ...options, timeout: 180000 };
+        const result = executeCommand(execOptions, "transfer", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 交易详情工具 ====================
+
+function createTxInfoToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_tx_info",
+      label: "ClawChain Transaction Info",
+      description: `查询 ClawChain 上指定交易的详细信息。
+输入交易哈希，返回发送方、接收方、金额、状态等信息。`,
+      parameters: Type.Object({
+        hash: Type.String({
+          description: "交易哈希（0x 开头）",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { hash: string };
+        const cmdArgs: CommandArgs = {
+          hash: params.hash,
+        };
+        const result = executeCommand(options, "tx-info", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 交易历史工具 ====================
+
+function createTxHistoryToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_tx_history",
+      label: "ClawChain Transaction History",
+      description: `查询指定地址或钱包的交易历史。
+扫描最近的区块，找出与该地址相关的所有交易。
+注意：扫描大量区块可能需要较长时间。`,
+      parameters: Type.Object({
+        address: Type.String({
+          description: "钱包地址、钱包名称或钱包 ID",
+        }),
+        blocks: Type.Optional(
+          Type.Number({
+            description: "扫描的区块数量（默认 1000）",
+            default: 1000,
+          })
+        ),
+        limit: Type.Optional(
+          Type.Number({
+            description: "返回的交易数量限制（默认 20）",
+            default: 20,
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { address: string; blocks?: number; limit?: number };
+        const cmdArgs: CommandArgs = {
+          address: params.address,
+          blocks: params.blocks ?? 1000,
+          limit: params.limit ?? 20,
+        };
+        const execOptions = { ...options, timeout: 120000 };
+        const result = executeCommand(execOptions, "tx-history", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 链信息工具 ====================
+
+function createChainInfoToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_info",
+      label: "ClawChain Info",
+      description: `获取 ClawChain 的基本信息，包括：
+- 链名称：ClawChain
+- 代币符号：CLAW
+- RPC 地址
+- Chain ID
+- 连接状态
+- 最新区块号
+- 当前 Gas 价格`,
+      parameters: Type.Object({}),
+      execute: async () => {
+        const result = executeCommand(options, "chain-info", {});
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 区块信息工具 ====================
+
+function createBlockInfoToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_block_info",
+      label: "ClawChain Block Info",
+      description: `查询 ClawChain 上指定区块的信息。
+可以输入区块号或 "latest" 获取最新区块。
+返回区块哈希、时间戳、交易数量等信息。`,
+      parameters: Type.Object({
+        number: Type.Optional(
+          Type.String({
+            description: "区块号或 'latest'（默认为 latest）",
+            default: "latest",
+          })
+        ),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { number?: string };
+        const cmdArgs: CommandArgs = {
+          number: params.number || "latest",
+        };
+        const result = executeCommand(options, "block-info", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}
+
+// ==================== 领取空投工具 ====================
+
+function createClaimAirdropToolFactory(baseOptions: ExecutorOptions): ToolFactory {
+  return (ctx: ToolContext) => {
+    const options: ExecutorOptions = {
+      ...baseOptions,
+      walletsDir: resolveWalletsDir(baseOptions, ctx),
+    };
+    
+    return {
+      name: "clawchain_claim_airdrop",
+      label: "ClawChain Claim Airdrop",
+      description: `通过 moltbook 发帖领取 CLAW 空投。
+
+【重要】领取空投的完整流程（必须按顺序执行）：
+
+第一步：确保有 ClawChain 钱包
+- 调用 clawchain_wallet_list 查看现有钱包
+- 如果没有钱包，调用 clawchain_wallet_create 创建一个
+- 记住钱包地址
+
+第二步：发布帖子
+- 在 moltbook 上发布一个帖子
+- 帖子内容必须包含你的钱包地址
+- 例如: "申请 CLAW 空投，我的钱包地址: 0x1234...abcd"
+- 获取帖子的完整 URL
+
+第三步：调用此工具领取空投
+- 将帖子的 URL 传入此工具
+
+【注意事项】
+- 帖子内容必须包含有效的钱包地址
+- URL 必须是 moltbook.com 的链接`,
+      parameters: Type.Object({
+        post_url: Type.String({
+          description: "moltbook 帖子或回复的完整 URL，例如: https://www.moltbook.com/post/xxx-xxx-xxx",
+        }),
+      }),
+      execute: async (_toolCallId: string, args: Record<string, unknown>) => {
+        const params = args as { post_url: string };
+        const cmdArgs: CommandArgs = {
+          post_url: params.post_url,
+        };
+        const result = executeCommand(options, "claim-airdrop", cmdArgs);
+        return jsonResult(result);
+      },
+    };
+  };
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+/**
+ * ClawChain Plugin 类型定义
+ */
+
+export interface ClawChainConfig {
+  walletsDir?: string;
+}
+
+export interface CommandResult {
+  success: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+export interface WalletInfo {
+  id: string;
+  name: string;
+  address: string;
+  created_at: string;
+  imported?: boolean;
+  balance?: string;
+  balance_wei?: string;
+}
+
+export interface TransactionInfo {
+  hash: string;
+  from: string;
+  to: string;
+  value: string;
+  gas?: number;
+  gas_price?: string;
+  nonce?: number;
+  block_number?: number;
+  status?: string;
+}
+
+export interface ChainInfo {
+  name: string;
+  token_symbol: string;
+  rpc_url: string;
+  chain_id: number;
+  connected: boolean;
+  latest_block?: number;
+  gas_price?: string;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["*.ts", "src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}