xrpl-hermes

# ☤ xrpl-hermes 开源的XRPL工具包，适用于AI代理和Python用户。它结合了包含65个文件的XRPL知识库和72个CLI命令 — 以及一个MCP服务器，暴露了其中代理安全子集和整个知识库，供任何MCP客户端使用 — 用于实时账本查询、签名准备交易JSON、修正检查、代币情报和XRPL L1、发行代币、NFT、AMM、MPT、Xaman、Xahau、Flare、Axelar、Arweave和XRPL EVM侧链的生态系统工作流。 **托管边界：** 所有72个命令都在本地运行。通过MCP，代理可以访问其中67个 — 只读查询和未签名构建器。涉及密钥材料、广播或创建外部签名请求的五个命令（`wallet-generate`、`wallet-from-seed`、`submit`、`submit-multisigned`、`xaman-payload`）被MCP拒绝，并保留在本地CLI中。参见 [MCP代理边界](#mcp-agent-boundary)。 **保持最新：** xrpl-hermes 配备了markdown知识，但代理被指示在提出声明之前验证实时账本状态和当前官方文档（`knowledge/65-agent-freshness-and-source-policy.md`）。知识库中的过时事实会在出现时标记日期。 [](https://github.com/CarpXRPL/xrpl-hermes) [](LICENSE)  [](https://github.com/CarpXRPL/xrpl-hermes/actions/workflows/ci.yml) ## 这是什么 xrpl-hermes 是一个实用的构建工具包。代理/MCP流程永远不会接受钱包种子或广播交易，并且不会假装草稿功能是活跃的。密钥和广播实用程序保持在本地CLI中，仅限本地CLI使用。正常流程是： 1. 读取相关的知识文件， 2. 在功能依赖于某个功能时检查实时网络/修正状态， 3. 构建签名准备好的JSON， 4. 让用户使用自己的钱包或签名堆栈签名。 它还包括**产品构建模式**，适用于产品高度工作：当用户想要一个应用、仪表板、启动台、付费API、资金管理工具、代币情报产品或自托管的XRPL代理栈时，技能会通过以下步骤：接入 → 架构 → XRPL原始映射 → MVP → 测试网演示 → 主网安全启动门户，然后发出交易JSON。规范流程：[`skills/build-xrpl-product-flow.md`](skills/build-xrpl-product-flow.md)；人工中心：[`docs/PRODUCT-BUILDER.md`](docs/PRODUCT-BUILDER.md)。 ## 适用对象 — 以及这不是什么 **适用于：** 希望使用AI辅助研究、未签名交易构建、代币情报和支付/x402流程的XRPL和代理构建者 — 使用Python（`xrpl-py`）或JavaScript/TypeScript（`xrpl.js`）。**不适用于：** 钱包或种子托管服务、自动签名者（自动移动资金）或“自我进化”的演示。代理准备、验证、解释和监控；您的钱包/签名堆栈签名。密钥保留给您。 **三种使用方式：** 作为**MCP工具**（在任何MCP客户端中 [`docs/MCP-CLIENTS.md`](docs/MCP-CLIENTS.md)），作为**Python** CLI/库（`xrpl-py`），或与您的**JavaScript/TypeScript** 应用程序代码一起（`xrpl.js`）— 参见下面的*选择您的堆栈*。 ## 选择您的堆栈 — Python *或* TypeScript/JavaScript XRPL-Hermes **CLI和MCP服务器运行在Python（`xrpl-py`）** — 这是发出签名准备好的JSON、检查实时修正和运行代币情报的引擎。您的**代码**可以是任意语言；两者都是首选： | 堆栈 | SDK | 安装 | 首选用于 | 深入文件 | | --- | --- | --- | --- | --- | | **Python** | `xrpl-py` | `pip install xrpl-py` | FastAPI服务、脚本、数据作业、服务器端机器人、Hermes CLI本身 | [`knowledge/30-xrpl-xrplpy.md`](knowledge/30-xrpl-xrplpy.md) | | **TypeScript / JavaScript** | `xrpl.js` | `npm install xrpl` | Web应用、仪表板、钱包UX、浏览器dApps、Node机器人、x402服务、AI代理CLI | [`knowledge/31-xrpl-xrpljs.md`](knowledge/31-xrpl-xrpljs.md) · [`examples/js/`](examples/js/) | 构建者发出相同的签名准备好的JSON — 选择与您的代码库匹配的SDK，**不要引入第二种语言**，只需使用此工具包。两个堆栈的可运行、仅限构建的支付示例位于 [`examples/`](examples/) （Python）和 [`examples/js/`](examples/js/) （xrpl.js）。签名分离模型在两者中相同：[`references/agentic-payments.md`](references/agentic-payments.md)。 ## 运行您自己的XRPL代理 今天，XRPL原生代理 — 在账本上预训练，能够启动代币、部署网站和运行机器人 — 以托管平台的形式存在。 xrpl-hermes 不是针对任何这些平台的宣传。 它为希望自己运行此类代理的人员提供开源路径： - **自带运行时。** 作为Hermes代理技能或OpenClaw、Claude Code、Cursor等任何支持MCP的平台。 - **自带基础设施。** 您的机器、VPS或自己的rippled/Clio节点 — 公共端点开箱即用。 - **密钥保留给您。** 构建者和MCP工具在不接受或存储种子情况下发出签名准备好的JSON。 可选的本地钱包实用程序从不暴露给代理。 - **MIT许可。** 使用它、fork它、在您的产品中发布。 如果托管平台更适合您，请使用它 — 该存储库存在，以便自托管成为一个真正的选项，而不是妥协。 ## 使用AI代理在XRPL上构建任何内容 您可以构建的**实用地图**，带有**诚实标签**，说明XRPL-Hermes为您提供了什么：**CLI** = 已发货命令；**实时工具** = 进行实时网络读取；**参考** = 参考卡 + 知识文件；**模式** = 集成模式/可运行示例；**路线图** = 已文档设计， 不是已发货功能。 | 构建 | XRPL-Hermes为您提供的内容 | 标签 | | --- | --- | --- | | 发行代币启动 | 发行人标志、信任线、域名、转账率、冻结/回收、供应流程 (`build-account-set`、`build-trustset`、`build-clawback`) + `skills/token-launch-flow.md` | CLI + 流程 | | NFT市场 | 铸造、创建/接受/取消报价、发现报价、销毁（7个`nft`/`build-nft-*`命令） | CLI + 实时工具 | | AMM / DEX | 创建池、存入/提取、投票费用、拍卖槽竞标、实时池 + 订单簿读取 (`build-amm-*`、`amm-info`、`book-offers`、`path-find`) | CLI + 实时工具 | | 支付（XRP） | 带有`SourceTag`/`DestinationTag`/`Memos`的签名准备好的`Payment` JSON，储备感知（`build-payment`）— Python + xrpl.js 示例 | CLI | | RLUSD / 发行货币 | 带有160位货币代码和信任线及合规指南的美元计价支付（`references/rlusd.md`，`knowledge/58`） | CLI + 参考 | | x402 / HTTP-402付费API | 结算402收费的XRPL支付 + t54促进者流程 | 参考 + 路线图 | | 机器人和监控 | 金库/AMM监控剧本、Telegram/Discord示例、WebSocket `subscribe` | CLI + 模式 | | 钱包和身份验证 | Xaman/Joey/Privy/MetaMask登录 + 签名者交接 (`xaman-payload`，`knowledge/53`) | 实时工具 + 参考 | | MPT操作 | 带有实时修正检查的MPT发行/授权载荷 (`build-mpt-*`) | CLI | | 金库和托管 | 多重签名、票据、检查、托管、支付通道 (`build-*`，`submit-multisigned`) | CLI | | EVM侧链 | 余额、合约部署JSON、桥接状态 (`evm-balance`、`evm-contract`、`evm-bridge`) | 实时工具 + 参考 | | Xahau Hooks | HookOn位掩码计算器 + hooks查找 (`hooks-bitmask`、`hooks-info`) | CLI + 实时工具 | | Flare价格上下文 | 链上FTSOv2预言机读取 + 公共价格备用 (`flare-ftso`、`flare-price`) | 实时工具 | | Axelar桥 | 路由/注册状态和传输跟踪 (`bridge-status`、`bridge-tx`) | 实时工具 | | Arweave存储 | 永久存储成本估算，从不上传 (`arweave-cost`) | 实时工具 | | 代币情报 | 具有风险标志 + 缺失数据诚实的单次实时代币报告 (`token-intel`) | 实时工具 | | 注意桥 / 社交卡 | “吸引注意力到XRPL” / 发现想法的产品框架 | 参考 | | 代理/技能收据 | 记录代理执行的操作，或技能如何改进（v1→v2），作为无签名的链上`NFTokenMint` — 来源，时间戳，公共可验证性；无种子，无自主签名 (`build-nft-mint` + `skills/agent-receipt-flow.md` + `examples/js/agent-receipt-nft.js`) | CLI + 模式 | 两个堆栈对于您在此基础上编写的代码都是首选的 — 参见上面的**选择堆栈**。 ## 快速开始 ```bash pip install -r requirements.txt python3 -m scripts.xrpl_tools ledger ``` 有用的第一个命令： ```bash python3 -m scripts.xrpl_tools server-info python3 -m scripts.xrpl_tools amendments python3 -m scripts.xrpl_tools amendment MPTokensV1 python3 -m scripts.xrpl_tools account rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe python3 -m scripts.xrpl_tools build-payment --from rSRC --to rDST --amount 10000000 ``` ## 文档 | 指南 | 适用于 | | --- | --- | | [`QUICKSTART.md`](QUICKSTART.md) | 5分钟内安装和第一个命令 | | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | XRPL和代理CLI新手 — 概念、安全、第一个会话 | | [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) | 生态系统工作流索引 — 命令、知识和每个生态系统的诚实覆盖标签 | | [`docs/PRODUCT-BUILDER.md`](docs/PRODUCT-BUILDER.md) | 产品构建模式 — 应用程序/平台/仪表板原型、5框架构和产品剧本链接 | | [`docs/MCP-CLIENTS.md`](docs/MCP-CLIENTS.md) | 将MCP服务器连接到Claude Code、Cursor、Codex、Hermes或任何MCP客户端 | | [`docs/DEVELOPERS.md`](docs/DEVELOPERS.md) | 架构、添加命令、MCP内部、测试、发布流程 | | [`docs/MAINTENANCE.md`](docs/MAINTENANCE.md) | 刷新节奏和保持存储库最新的确切验证命令 | | [`STANDALONE.md`](STANDALONE.md) | 常见命令的深入CLI用法（完整72命令列表：`SKILL.md`工具表） | | [`SECURITY.md`](SECURITY.md) · [`LIMITATIONS.md`](LIMITATIONS.md) | 安全模型和诚实范围 | | [`AUDIT-tool-matrix.md`](AUDIT-tool-matrix.md) | 生成的验证矩阵 — 安全命令执行，副作用命令显式跳过，零失败 | | [`docs/BUILD-BENCHMARK.md`](docs/BUILD-BENCHMARK.md) | 构建证明基准 — L1→L3 +对抗性安全任务，证明代理在XRPL上安全构建（补充工具矩阵） | | [`skills/agent-receipt-flow.md`](skills/agent-receipt-flow.md) · [`references/track-agent-behavior.md`](references/track-agent-behavior.md) | 代理来源：记录运行为无签名的链上收据，并将行为归因/监控（SourceTag · Memos · WebSocket） | ## 命令覆盖 72个命令分布在`scripts/tools/`中聚焦的Python模块中。所有72个命令都在本地运行；其中67个也可以通过MCP访问（参见 [MCP代理边界](#mcp-agent-boundary)）。 | 生态系统 | 计数 | 命令 | | --- | ---: | --- | | XRPL L1核心和操作 | 41 | `account`、`balance`、`account_objects`、`account-tx`、`trustlines`、`build-payment`、`build-trustset`、`build-offer`、`book-offers`、`path-find`、`ledger`、`ledger-entry`、`server-info`、`tx-info`、`decode`、`submit`、`submit-multisigned`、`build-account-set`、`build-account-delete`、`build-set-regular-key`、`build-deposit-preauth`、`build-signer-list-set`、`build-ticket-create`、`build-escrow-create`、`build-escrow-finish`、`build-escrow-cancel`、`build-check-create`、`build-check-cash`、`build-check-cancel`、`build-paychannel-create`、`build-paychannel-fund`、`build-paychannel-claim`、`build-clawback`、`build-cross-currency-payment`、`build-set-oracle`、`build-credential-create`、`build-credential-accept`、`build-credential-delete`、`build-mpt-issuance-create`、`build-mpt-authorize`、`subscribe` | | 修正状态 | 3 | `amendments`、`amendment`、`amendment-status` | | NFT市场 | 7 | `nft-info`、`nft-offers`、`build-nft-mint`、`build-nft-create-offer`、`build-nft-accept-offer`、`build-nft-cancel-offer`、`build-nft-burn` | | AMM流动性 | 6 | `amm-info`、`build-amm-create`、`build-amm-deposit`、`build-amm-withdraw`、`build-amm-vote`、`build-amm-bid` | | 代币情报 | 1 | `token-intel` | | EVM侧链 | 3 | `evm-balance`、`evm-contract`、`evm-bridge` | | Xahau Hooks | 2 | `hooks-bitmask`、`hooks-info` | | Flare / 价格上下文 | 2 | `flare-price`、`flare-ftso` | | Axelar / Arweave | 3 | `bridge-status`、`bridge-tx`、`arweave-cost` | | 钱包实用程序 | 3 | `wallet-generate`、`wallet-from-seed`、`validate-address` | | Xaman 平台 | 1 | `xaman-payload` | `build-batch` 已停用且未注册，因为 XLS-56 批次在 XRPL 主网上未启用。 MPT、凭证和预言机构造器在发出 JSON 之前检查实时修正状态。 ## 知识地图 | 范围 | 主题 | | --- | --- | | `01`-`15` | XRPL 账户、支付、信任线、DEX、AMM、NFT、clawback、MPT、托管、检查、通道、多重签名、票据、共识、交易格式 | | `16`-`25` | Clio、私有节点、速率限制、成本、数据API、代币模型、发行、NFT铸造、部署、安全 | | `26`-`35` | Xaman、钱包、Privy、MetaMask、xrpl-py、xrpl.js、Hooks、EVM、AMM机器人、互操作性 | | `36`-`45` | XLS标准、实时修正、铸造操作、NFT操作、监控、机器人模式、托管、高级Hooks/EVM、生态系统地图 | | `46`-`55` | Axelar、Arweave、TX生态系统、Flare、EVM侧链、Xahau、L1参考、钱包身份验证、Evernode、侧链互操作性 | | `56`-`63` | Telegram机器人、Discord机器人、RLUSD、RWA代币化、账户集标志、WebSocket流、NFT市场、Xaman平台 | | `64`-`65` | 代币情报报告、代理新鲜度和源策略 | ## Hermes 代理安装 ```bash git clone https://github.com/CarpXRPL/xrpl-hermes.git cd xrpl-hermes pip install -r requirements.txt # 安装为本地Hermes技能。 使用您的Hermes配置文件加载的路径。 mkdir -p ~/.hermes/skills cp -r . ~/.hermes/skills/xrpl-hermes ``` 用以下命令激活： ```text activate xrpl-hermes ``` ## MCP 服务器（Claude Code、OpenClaw、Cursor、任何MCP客户端） `scripts/mcp_server.py` 是一个无依赖的标准输入输出MCP服务器，暴露了四个工具：`xrpl_list_commands`、`xrpl_run`（67个代理安全命令）、`xrpl_knowledge_index` 和 `xrpl_knowledge`。 ```bash # Claude 代码 claude mcp add xrpl-hermes -- python3 /path/to/xrpl-hermes/scripts/mcp_server.py ``` 通用MCP客户端配置： ```json { "mcpServers": { "xrpl-hermes": { "command": "python3", "args": ["/path/to/xrpl-hermes/scripts/mcp_server.py"] } } } ``` 命令在带有90秒超时的子进程中运行；知识读取被沙箱化到 `knowledge/`、`references/` 和 `skills/`。 服务器从不请求或存储秘密密钥。 ## MCP 代理边界 `xrpl_run` 是一个 **具有默认拒绝的积极允许列表**。 72个本地CLI命令精确地分为67个代理可以运行的命令和5个不能运行的命令： | 界面 | 计数 | 涵盖内容 | | --- | ---: | --- | | **本地CLI** — `python3 -m scripts.xrpl_tools` | **72** | 所有已注册的命令 | | **MCP安全** — `xrpl_run` / `xrpl_list_commands` | **67** | 只读实时查询和未签名的签名准备构建器 | | **通过MCP拒绝** — 仅限本地CLI | **5** | `wallet-generate`、`wallet-from-seed`、`submit`、`submit-multisigned`、`xaman-payload` | 这五个是托管和广播界面：两个触及密钥材料（`wallet-generate` 发出种子，`wallet-from-seed` 消耗种子），两个广播到实时网络，一个创建真正的外部钱包签名请求。 当您本地运行时，它们仍然完全按照以前的方式工作 — 它们只是代理无法访问的。 - 拒绝的命令在 **任何子进程被生成之前被拒绝**，因此它永远不会执行，MCP响应也不会携带种子。 拒绝命令会指定要使用的本地CLI调用。 - `xrpl_list_commands` 仅列出代理安全的集合，因此客户端无法发现被拒绝的命令并尝试它。 - 允许列表是积极的：任何不在列表中的命令 — **包括在未来版本中添加的命令** — 在未经维护人员分类之前被拒绝。 新的密钥触摸命令默认是安全的，而不是通过意外暴露。 `tests/test_mcp_server.py` 将此作为不变式强制执行：允许列表和拒绝列表必须是不相交的，并且必须完全覆盖调度器，因此新命令不能在未经分类的情况下发货。 ## 安全模型 - 没有硬编码的钱包种子或私钥。 - 交易构建器输出JSON以供外部签名。 - 密钥管理、广播和Xaman签名请求命令仅限本地CLI使用，通过MCP拒绝。 - `submit` 仅适用于具有已签名blob的高级用户。 - 修正依赖构建器检查实时XRPL主网状态或发出仅限构建的警告。 - Flare价格输出由其来源标记：`flare-price`是公共价格备用，而`flare-ftso`执行实时读取的FTSOv2 `eth_call`查找。 ## 开发检查 ```bash python3 -m pytest -q python3 scripts/dev_test_matrix.py ``` 开发测试矩阵写入`AUDIT-tool-matrix.md`，在不发送真实交易的情况下练习安全注册命令，并显式记录跳过防止种子生成或外部签名请求的命令。 ## 贡献 在 `scripts/tools/` 中使用模块模式：每个模块公开一个 `COMMANDS` 字典并通过共享助手发出JSON。 在更改命令输出时添加或更新有针对性的pytest覆盖。 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`CHANGELOG.md`](CHANGELOG.md)。 ## 许可 MIT。 免费使用、fork和构建。