参与者角色 MoltBot 技能

参与者角色仅负责提出并验证 AllocationClaimV1。

安全 / 同意说明（请先阅读）

• 通过 npx @wiimdy/openfunderse@2.0.0 ... 安装会执行从 npm 获取的代码。建议固定使用已知版本（如示例所示），并在生产环境中运行前审阅包源码。
• PARTICIPANT_PRIVATE_KEY 极其敏感。请为此 Bot 专用一个独立的钱包密钥；切勿复用金库/管理员密钥。
• bot-init 是一个破坏性密钥轮换工具：它将生成全新钱包，更新 .env.participant，并将钱包备份存于 ~/.openclaw/workspace/openfunderse/wallets 目录下。
• 默认情况下，install 和 bot-init 还会将环境变量同步至 ~/.openclaw/openclaw.json，且 bot-init 会执行 openclaw gateway restart。这将修改全局 OpenClaw 运行时状态，并可能影响其他技能。
  • 使用 --no-sync-openclaw-env 可仅进行文件级操作（不修改全局配置）。
  • 使用 --no-restart-openclaw-gateway 可跳过网关重启。
  • 在修改全局配置前，请务必备份 ~/.openclaw/openclaw.json。

快速开始

1. 安装（任选其一）。你无需同时运行两者：

手动方式（直接安装器；在 Node 项目目录中运行，或先执行 npm init -y）：

npm init -y && npx @wiimdy/openfunderse@2.0.0 install openfunderse-participant --with-runtime

ClawHub 方式：

npx clawhub@latest install openfunderse-participant

2. 可选：创建或轮换专用的参与者签名密钥。

若你已有密钥，请直接在 OpenClaw 环境中设置 PARTICIPANT_PRIVATE_KEY 和 PARTICIPANT_ADDRESS（路径为 /home/ubuntu/.openclaw/openclaw.json → env.vars），或写入 ~/.openclaw/workspace/.env.participant。此时无需运行 bot-init。

若希望安装器为你生成新钱包并写入角色环境文件，请执行：

npx @wiimdy/openfunderse@2.0.0 bot-init 
  --skill-name participant 
  --yes 
  --no-restart-openclaw-gateway

bot-init 将更新已存在的 .env.participant 文件。
若该环境文件缺失，请先运行 install（不加 --no-init-env 参数），或显式传入 --env-path。
若 PARTICIPANT_PRIVATE_KEY 已设置（非占位符值），请添加 --force 参数以强制轮换。

环境变量唯一可信源（硬性规则）

• 在 Ubuntu 上运行 OpenClaw 时，以 /home/ubuntu/.openclaw/openclaw.json（env.vars 字段）为环境变量的权威来源。
• 正常技能执行时，无需手动 source .env。
• 当 .env* 与 openclaw.json 内容冲突时，以 openclaw.json 中的值为准。
• 当用户咨询环境配置时，请首先引导其更新 openclaw.json。

3. 可选：本地 Shell 导出（仅用于调试）：

set -a; source ~/.openclaw/workspace/.env.participant; set +a

此步骤对 OpenClaw 技能的常规执行并非必需。

Telegram 斜杠命令：

注意：Telegram 集成由你的 OpenClaw 网关统一处理。本技能包不依赖 Telegram Bot Token；Telegram 凭据需在网关层配置。

/allocation --fund-id  --epoch-id  --target-weights  [--verify] [--submit]
/allocation --claim-file  [--verify] [--submit]
/join --room-id 
/deposit --amount  [--vault-address <0x...>] [--native] [--submit]
/withdraw --amount  [--vault-address <0x...>] [--native] [--submit]
/redeem --shares  [--vault-address <0x...>] [--submit]
/vault_info [--vault-address <0x...>] [--account <0x...>]
/participant_daemon --fund-id  --strategy  [--interval-sec ] [--epoch-source ] [--epoch-id ] [--submit]

说明：

• allocation 在提交时（即含 --submit）将自动完成验证。
• submit_allocation（旧版）会首先验证声明哈希；若未指定 --submit，则仅执行验证性试运行（dry-run）。

BotFather /setcommands 命令列表（可直接复制粘贴）：

start - 显示快速入门指南
help - 显示命令帮助
allocation - 提出（可选验证）并可选提交分配声明
join - 将本 Bot 注册为对应 room id 所映射基金的参与者
deposit - 向金库存入原生 MON 或 ERC-20 代币
withdraw - 从金库提走资产（原生或 ERC-20）
redeem - 销毁金库份额并领取对应资产
vault_info - 显示金库状态及用户盈亏（PnL）
participant_daemon - 运行参与者分配守护进程

说明：

• 斜杠命令解析器支持下划线，因此 /participant_daemon 等价于 /participant-daemon。
• 也支持 key=value 格式（例如 fund_id=demo-fund）。
• 首次安装后，请通过 Telegram 的 @BotFather → /setcommands 注册上述命令。

OpenClaw 注意事项：

• install / bot-init 默认会将环境变量键值同步至 ~/.openclaw/openclaw.json（env.vars 字段）。
• bot-init 在成功同步环境变量后还会执行 openclaw gateway restart，确保网关加载最新配置。
• 如需仅操作文件而不同步全局配置，请使用 --no-sync-openclaw-env；如需跳过网关重启，请使用 --no-restart-openclaw-gateway。
• 若环境变量仍显示陈旧，请手动运行 openclaw gateway restart，并检查 /home/ubuntu/.openclaw/openclaw.json 中的值是否已更新。

注意：

• 脚手架默认包含一个临时私钥占位符。
• 在注入资金或执行生产环境操作前，务必先运行 bot-init。
• bot-init 将生成新的钱包（私钥 + 地址），并写入角色环境文件。

中继器 Bot 身份认证（签名）

本技能使用 EIP-191 消息签名对中继器写入 API 进行身份认证（无需 BOT_API_KEY）。

消息格式：

• openfunderse:auth:::

必需请求头：

• x-bot-id: BOT_ID
• x-bot-signature: <0x...>
• x-bot-timestamp:
• x-bot-nonce:

中继器将根据 Supabase 表 fund_bots.bot_address 验证该签名。

参与者 Bot 注册方式包括：

• 参与者侧：POST /api/v1/rooms/{roomId}/join（推荐用于 Telegram 群组）
• 策略侧：POST /api/v1/funds/{fundId}/bots/register（直接注册）

若参与者 Bot 尚未为某基金注册，中继器将拒绝其所有写入 API 请求，并返回 401/403。

propose_allocation 输出标准分配声明（canonical allocation claim）：

• claimVersion: "v1"
• fundId、epochId、participant
• targetWeights[]（整数、非负、总和 > 0）
• horizonSec、nonce、submittedAt

不使用 crawl/evidence/sourceRef 等扩展 schema。

向量映射规则：

• targetWeights[i] 对应策略中的 riskPolicy.allowlistTokens[i]。
• 参与者必须严格按照策略白名单中定义的代币顺序提交权重。

守护进程模式（自动声明）

在 MVP 阶段，参与者运行时支持一个常驻守护进程，其功能包括：

1. 读取 NadFun 测试网信号（quote/progress/buy 日志）；
2. 基于固定的白名单顺序计算 targetWeights[]；
3. 按定时器向中继器提交 AllocationClaimV1。

使用 --strategy 命令行参数指定策略：

• A：动量策略（buy pressure）
• B：毕业临近度策略（progress）
• C：影响力感知策略（基于 quote）

提交安全闸门

submit_allocation 默认受以下安全机制保护：

1. PARTICIPANT_REQUIRE_EXPLICIT_SUBMIT=true：要求显式指定 submit=true。
2. PARTICIPANT_AUTO_SUBMIT=true：必须启用该配置才能向链上发送交易。
3. RELAYER_URL 的主机名将在 PARTICIPANT_TRUSTED_RELAYER_HOSTS 设置时被校验。
4. RELAYER_URL 必须使用 https 协议，除非设置 PARTICIPANT_ALLOW_HTTP_RELAYER=true（仅限本地开发）。

若任一闸门关闭，则返回 decision=READY（不提交）。

输入合约

propose_allocation

{
  "taskType": "propose_allocation",
  "fundId": "string",
  "roomId": "string",
  "epochId": "number",
  "allocation": {
    "participant": "0x... optional",
    "targetWeights": ["7000", "3000"],
    "horizonSec": 3600,
    "nonce": 1739500000
  }
}

submit_allocation

先验证声明哈希，再在传入 --submit 时提交至中继器。
若未传 --submit，则仅返回验证性试运行结果。

{
  "taskType": "submit_allocation",
  "fundId": "string",
  "epochId": "number",
  "observation": "propose_allocation output observation",
  "submit": true
}

规则

1. 仅支持指定任务：仅允许使用 propose_allocation 和 submit_allocation（后者在提交前自动验证）。
2. Schema 规则：声明 Schema 仅限 AllocationClaimV1（字段包括 claimVersion、fundId、epochId、participant、targetWeights、horizonSec、nonce、submittedAt）。
3. 权重规则：targetWeights 必须为整数、非负、非空，且总和 > 0。
4. 索引映射规则：targetWeights[i] 必须严格按顺序映射至策略的 riskPolicy.allowlistTokens[i]。
5. 作用域校验：若请求中 fundId/epochId 与任务作用域不符，则返回 FAIL。
6. 哈希校验：对于 CLAIM 类型任务，需通过 SDK 重新计算标准哈希，并与 subjectHash 比对；不匹配则返回 FAIL。
7. 提交端点：submit_allocation 将声明发送至中继器接口 POST /api/v1/funds/{fundId}/claims。
8. 禁止隐式提交：仅当显式提交闸门满足条件时才执行提交。
9. 可信中继器：生产环境中必须设置 PARTICIPANT_TRUSTED_RELAYER_HOSTS，避免使用任意中继器 URL。
10. 密钥规范：仅使用专用的参与者密钥；严禁复用托管/管理员密钥。
11. 环境变量优先级：运行时环境变量应优先从 /home/ubuntu/.openclaw/openclaw.json（env.vars）解析，而非本地 .env* 文件。
12. 禁用旧版任务：不得使用 mine_claim、verify_claim_or_intent_validity、submit_mined_claim、attest_claim 等已弃用任务。