Empire Builder 技能

Empires（帝国） 是社区金库（部署于 Base 8453 和 Arbitrum 42161 的 ERC-4337 SmartVaults），并绑定一个身份标识（Empire ID）。Agent 通过编排 HTTP API 调用与钱包签名交易（如用于发放奖励的 executeBatch）来完成操作。

基础 URL： https://empirebuilder.world —— 仅限主网（mainnet）。 本文档中未提供测试网（testnet）或 sandbox 环境的 API。

依赖包（固定版本）： npm install clanker-sdk@4.2.16 viem@2.48.0 —— 版本号需严格匹配 YAML 前置元数据中的声明；自动化流程中应使用 lockfile；请勿使用 @latest，以确保可复现性。

技能副本校验： 若你从 homepage 同步该技能文件，请在脚本中实际使用前，先将其与可信代码检出版本进行 diff 校验。

有意为之的产品行为（非文档缺陷）

该集成接口的设计目标是直接对接 生产环境链，且所有写操作均需具备金库合约中 owner() 的链上权限。“安全加固”（hardening）应由 产品代码、基础设施及运维工具链 承担——本技能文档仅描述 API 与合约的接口形态。

• 所有写操作均为实时生效，除非你仅执行只读请求（reads），否则在 Base 8453 / Arbitrum 42161 上的操作将立即影响链上状态。
• distribute-prepare + owner 主动广播 executeBatch 是官方定义的标准 API 流程；SmartVault 合约要求调用方必须为链上 owner()（参见 references/contracts.md）。
• POST /api/store-distribution 的输入必须基于已上链确认的 transactionHashes（即 receipt 可验证的交易哈希）：所记录的发放行为严格对应 链上实际执行结果，而非仅依据 prepare 阶段提交的 JSON。你仍须正确传入 empireAddress、baseToken（即 Empire ID）以及排行榜相关字段，以确保数据行归属到正确的 Empire（详见 http-api.md）。
• 注册表/扫描器中关于“agent + wallet + mainnet”的警告，正是对上述 有意设计 的反映，并非本文件遗漏重要注意事项。

Agent 应如何使用此技能

模型通常仅优先加载 SKILL.md。请将本文件视为 路由指引与约束说明。在编写 HTTP 请求体、签名流程或多步骤交互逻辑前，务必打开下方列出的参考文档——否则极易遗漏关键字段（例如 signer 与 signerAddress 的区别、leaderboardType 的合法取值、booster 的 payload 结构等）。对于 单条端到端流水线场景（尤其是发放奖励），请严格遵循 references/workflows.md 中的步骤顺序执行。

不应使用此技能的情形

若出现以下任一情况，请立即中止并选用其他方案：

• 在 Empire 网页应用内实现终端用户的钱包交互体验。 官方网站采用 赞助型 ERC‑4337 UserOperations（由 paymaster 提供 Gas，经 EntryPoint 调用 executeBatch）实现共签者（co-signer）签名——这与本技能所述的 “prepare → owner 广播 → store” 流程完全不同。请使用网页应用内置流程（或其专用前端客户端代码），而非这些 HTTP 接口。
• 共签者（co-signer）或“授权签名者”（authorized signer）的自动化场景。 共签者 无法 直接调用金库合约的 execute/executeBatch 方法（会因 Unauthorized 错误回滚），也 无法 触发 POST /api/distribute-prepare —— 该接口明确要求调用方为 owner()。如果你是共签者，请选择：(a) 通过网页应用触发 UserOp，或 (b) 升级权限至金库 owner。
• 通用型 ERC-4337 / paymaster / bundler 教程场景。 本技能不涉及 sponsor、bundler 或 EntryPoint 集成的教学。请勿将类似 /alchemy-sponsor-userop 的辅助函数，或旧版 distribute-v3 接口嫁接到当前流程中。
• 非 Empire 场景下的代币部署。 纯 Clanker SDK 的无 Empire 部署不在本技能覆盖范围内——请直接查阅 Clanker 官方文档。本技能仅涵盖 Clanker SDK 到 deploy-empire 的对接逻辑。
• 测试网（testnets）或本地开发（local dev）。 当前不存在 sandbox 端点。如需预演（dry-run），只读 GET 请求是安全的；请勿自行构造 /sepolia/...、chainId: 84532 或 staging 域名等非官方路径。
• 大量随机 EOA 地址之间的用户间转账。 请直接使用标准 ERC-20 的 transfer 方法从持有钱包发起——金库角色、prepare/store 流程及 distribution 接口均不适用。

Empire ID 与 SmartVault 地址（请先阅读本节）

三种输入格式均可解析为 同一个 Empire，但它们 均不等于 SmartVault 合约地址：

• Empire ID 是身份标识，常以 tokenAddress、baseToken、empire_id 形式出现，或作为路径段出现在 /api/empires/[empire_id] 中。
• SmartVault 地址 是链上金库合约地址，字段名为 empire_address / empireAddress / treasuryAddress。可通过 GET /api/empires/[empire_id] 接口解析获得。
• 二者 绝不可互换，除非某接口明确同时接受两者。切勿在需要合约地址的位置传入 fid… 类 Empire ID，也不可在要求 Empire ID 的位置（例如 store-distribution 接口，它同时需要两者且字段名不同）传入 SmartVault 地址。

详见 references/http-api.md → Empire ID 小节中的完整类型对照表。

本技能的组织结构

Agent 所需的一切内容均严格限定在 skill/ 目录内——不依赖其他任何目录。

Agent 约束条件（强制要求）

1. 目录保真度（Catalog fidelity）。 仅可使用 references/http-api.md 中明确定义的接口路径与语义。禁止自行构造路径或拼接未经文档说明的复合 URL。

2. 认证机制。 在 references/http-api.md 明确要求处，必须发送 x-api-key 请求头。写操作通常还需提供符合 EIP-191 标准的 signature、message，以及 signer 或 signerAddress 字段——请严格按各接口文档指定的字段名传递。

3. 金库发放（Treasury payouts）。 标准集成流程为：POST /api/distribute-prepare → 金库 owner() 钱包提交 executeBatch 交易（你承担 Gas 费用）→ POST /api/store-distribution。除非完全在官方网页应用内工作（走的是另一套 pipeline），否则不得用任意 sponsor/UserOp 教程替代此流程。

4. POST /api/distribute-prepare 的签名者必须与金库合约的 owner() 地址完全一致——不支持 共签者（co-signers）或 SmartVault “授权签名者”（authorized signers）。这些地址虽可在网页应用中授权 UserOperations（通过 EntryPoint 调用赞助型 executeBatch），但 无法 使用本 API 路径，也 无法 以普通 EOA 交易调用金库的 execute 或 executeBatch 方法（合约将返回 Unauthorized 错误）。详见 references/contracts.md。在 其他 接口中，“恢复出的 signer” 可能根据后端规则被校验是否属于 owner 或 co_emperors —— 请勿假设其校验逻辑与 distribute-prepare 完全相同。

5. Empire ID 与 SmartVault 地址区分。 如前所述，tokenAddress / baseToken / empire_id 表示 身份（ERC‑20 地址、fid… 或 slug）；empireAddress / treasuryAddress 表示 链上金库合约。混淆二者是最常见的技能误用原因——在发送任何写请求前，请务必核对字段名与 references/http-api.md 是否一致。

6. 销毁（Burns）。 销毁行为需从销毁交易的 receipt 中解码：对 Empire 基础代币（或 tokenless 情况下所绑定的基础代币）向 0x000…0000 或 0x000…dEaD 发起 ERC‑20 Transfer，随后调用 POST /api/store-burn。若代币位于 SmartVault 内部，则仅 owner() 可发起直接的金库 execute / executeBatch；共签者需通过 网页应用 发起赞助型 executeBatch UserOps（Base / Arbitrum）完成金库内代币销毁。若代币位于 其他任意钱包 中，则由该钱包直接调用 transfer 至销毁地址——无需金库角色参与。

快速概览：集成接口面

示例提示词（Prompts）

• 结合 references/workflows.md，逐步演示使用排行榜 main 及两个 ERC‑20 代币完成发放准备的全过程。
• 基于已上链的交易哈希，构建 store-distribution 接口的 curl 请求骨架。
• 解释为何存储类 payload 中的 baseToken 与 empireAddress 含义不同。

错误处理

详细章节 —— 请同步打开参考文档

• 接口路径与请求体（Routes & payloads）： references/http-api.md
• 分步流程（Step-by-step flows）： references/workflows.md
• 链上基础原语（On-chain primitives）： references/contracts.md