Xahau MCP

xahau-mcp

一个适用于 Xahau 网络的 Model Context Protocol 服务，有两项开创性功能：它可以在本地 VM 中运行 Hook 的真实 WebAssembly 字节码（无需 xahaud 节点），并对其运行 Hooks 专用的静态分析／安全规则引擎——两者都完全离线。围绕这一核心，它还提供只读账本访问、支持 Xahau 的二进制编解码器、指令计数费用估算、网络奖励计算、治理辅助工具和未签名交易构建器。

Xahau 是 XRPL 的一个分支，其旗舰功能是 Hooks——部署在链上的小型 WebAssembly 智能合约。此前既没有适用于 Xahau 的 MCP，也没有适用于 Hooks 的静态分析器；本项目两者兼具。

三位一体——安全的 Hooks，全流程覆盖

三款开源工具，一个工作流：编写 → 模拟一笔交易 → 证明所有输入。 xahau-mcp 负责模拟阶段。

阶段	工具	功能
编写	xahc	编写并编译安全的 Hook，生成干净且通过 lint 检查的 WASM
模拟一笔交易	xahau-mcp	针对一笔实时交易运行真实字节码
证明所有输入	xahc-prover	证明某个不变量对范围内的每个输入都成立，或返回反例

它的用途

让任何支持 MCP 的 Agent（Claude 等）连接到此服务，即可：

• 签名前预见结果 — simulate_transaction 是签名前的飞行模拟器：未签名交易会触发的每个 Hook 都会作为真实字节码，在实时账本状态下运行，并提供逐个 Hook 的接受／回滚结果、解码后的已发出交易、模拟的状态写入，以及带标签的静态引擎预检。它的姊妹工具 what_if 是一台时光机：在任意真实历史交易发生时的账本上重放该交易（包括你的修改）。经验证，它能精确复现一笔真实领取交易所发出的 GenesisMint 派发金额（72,251,963 drops），测试已锁定。
• 无需部署即可运行 Hook — execute_hook 会在本地 VM 中实例化真实的 CreateCode WASM，通过一笔模拟交易和账本状态提供 Hook API，并报告实际的 accept／rollback 决策、返回码／字符串、状态写入、已发出交易和调用跟踪。无需 xahaud 节点。
• 安装前审计 Hook — 粘贴 CreateCode WASM（或链上 Hook 哈希），即可获取 SARIF-lite 检查结果：缺少 accept／rollback 退出、未设保护的循环（_g）、未知的 env 导入、危险的 HookGrant、范围过宽的 HookOn 等。
• 双向解码晦涩的 HookOn 位图 — 这个 256 位、反转、低电平有效的掩码（以及高电平有效的 SetHook 位）很容易出错；此处的解码已验证并经过往返测试。
• 读取 Xahau 账本状态 — 账户、已安装的 Hook、Hook 定义、Hook 状态、交易（包含 HookExecutions 元数据）和账本。
• 回答散户最关心的问题 — reward_status 可告知任意账户是否已选择加入 Xahau 网络奖励（余额调整），已累积的 XAH 精确金额（根据创世奖励 Hook 自身的公式和实时参数计算，并经验证能精确复现真实链上派发金额），下次可领取的时间，以及领取是否已逾期（延迟领取会损失收益）。
• 诊断 Evernode 主机 — evernode_host_diagnostics 通过一次只读调用，自动执行 Xahau 最大运营商群体的官方故障排查清单：注册状态、心跳活跃情况（实际的链上活跃规则）、声誉、EVR 信任线、租约报价、规格和累计奖励。
• 解释失败的交易 — diagnose_failed_tx 将引擎结果和 Hook 返回字符串转换为通俗易懂的原因和具体修复方法。
• 实时关注治理情况 — governance_state 解码 Genesis Governance Game 的完整 Hook 状态：20 个席位由谁持有、每项未决投票及票数统计，以及某项变更（成员替换、奖励率变更）是否即将执行。没有区块浏览器能显示这些信息。
• 构建未签名交易（SetHook、ClaimReward、Payment），并自动进行安全预检 — 返回的交易未经签名，可离线签名。

为什么这是我们所知最先进的区块链 MCP

这个说法很有分量，因此我们提供可核查的证据（2026-06-11）。据我们所知，没有任何链——Ethereum、Solana、Bitcoin、XRPL 或其他链——的 MCP 同时具备其中哪怕两项；最接近的同类产品是云端模拟 MCP（例如 Tenderly 的产品，它在其托管基础设施上进行模拟）和独立分析器（例如 Slither，它仅支持 EVM，且不是 MCP）：

1. 在本地 VM 中执行真实的链上合约字节码——execute_hook 在没有节点、云服务或账户的情况下运行实际的 CreateCode WASM。它不是 ABI 封装器，也不是托管模拟器。
2. 公布与链上实际情况对比、经过测量且锁定回归的保真度分数——vm_fidelity_report 重放了 30 次真实的主网 Hook 执行：30/30 结果一致（100%），0 次降级，其中包括主导实际流量的跨状态读取 Hook。这 30 次全部是接受方向（实际的 Xahau 流量以心跳为主），该指标本身也会说明这一点——它会报告接受/回滚的组成，并警告说，仅含接受情况的语料库无法区分该 VM 与始终接受的存根。 tests/regression.test.ts 中的真实创世字节码（治理 Invoke → 回滚）则覆盖了回滚方向。语料库、方法和如实记录的历史（25% → 0% → 100%）见 docs/FIDELITY.md。据我们所知，没有其他区块链 MCP 尝试过这件事。
3. 协议内静态安全分析——针对 Hooks 的规则引擎（SARIF-lite 检测结果），以网络自身的创世 Hook 为基准进行校准。
4. 协议内差分模糊测试——fuzz_hook 可在本地 VM 中绘制合约的接受/拒绝决策边界。
5. 使用真实字节码对真实交易进行事后分析——hook_execution_postmortem 重放链上实际触发的内容并进行比对。
6. 精确复现链上经济机制——reward_status 重新实现创世奖励 Hook 的公式，并精确复现实际发放的款项，精确到 drop（已验证，并由测试锁定）。
7. 端到端解码实时治理信息——governance_state 实时显示治理游戏中的每个席位、投票、计票结果和门槛。
8. 运维诊断工具，解决生态系统中的实际痛点：失败交易诊断并提供原因和修复方法、Evernode 主机健康状况、逾期领取检测。

上述每项声明都可以通过此仓库复现：语料库已提交，测试会断言这些数字，代码中也引用了权威来源（xahaud 创世 Hook、evernode-js-client）。

安全态势

• 对网络只读。 此服务中没有任何 submit 或 sign。

• 不托管密钥。 构建工具绝不接受密钥/种子，并始终返回未签名的交易，以及离线签名说明（例如使用 xaman 或 xrpl-accountlib）。默认使用测试网。

• 忠实呈现实际情况。 execute_hook 会在模拟环境中运行真实字节码。VM 实现了 78 个函数 Hook API 中的大部分功能，包括几乎完整的 XFL 浮点数 API（已对照 float_one 验证；float_root/float_log 除外，它们会返回 NOT_IMPLEMENTED）、slot 表 + STObject 子字段提取（slot_subfield/sto_subfield，与真实交易逐字节一致）、state、otxn_*/hook_*、util_accid/util_raddr/util_verify/util_sha512h 等。现在还支持 STObject 修改（sto_emplace/erase/validate）、util_keylet（account + hook 已对照实时账本索引验证；offer/escrow/check/ticket/signers 使用规范形式并以安全方式失败）、slot_set + 外部 Hook state（state_foreign/state_foreign_set）异步预解析（execute_hook resolveKeylets:true 会获取 Hook 读取的账本对象和外部 state 条目——逐步迭代，因为已解析的一次读取可能会暴露下一次读取——然后重新运行）、slot_float/float_sto/float_sto_set（STAmount ⇄ XFL 双向转换——将原生或已发行/IOU Amount 解析为浮点数，并序列化回去；下文所述的已发行格式中，低于 bit 63 的部分就是 XFL 格式），以及 32 字节 state-key 填充（短键会像链上处理方式一样在左侧补零）。state_foreign_set 会记录写入，但不会模拟链上 HookGrant 要求；etxn_details 会返回已披露的合成占位符（列于 syntheticCalls 中，且不会改变 accept/rollback 决策）。无法忠实模拟的部分会如实记录：未经验证的 keylet 子类型、meta_slot 和其他未建模调用都会返回真实的 NOT_IMPLEMENTED 代码，列于 unsupportedCalls 中，并将运行标记为 degraded——绝不伪造。VM 会模拟 guard 预算（_g 会强制执行每个 guard 声明的 maxiter → GUARD_VIOLATION），并报告 stateApplied（state 写入仅在 accept 时提交，在 rollback 时丢弃）。它不是忠实于共识机制的 xahaud 副本——除 guard 外，它不进行费用/fuel 计量；XFL 数学运算会截断而非四舍五入到最接近值（因此 float_mulratio 的向上取整标志和最后有效位的结果可能不同）；仅在已测试的情况下验证数值层面的数学运算。包含循环但没有 _g guard 的 Hooks 会在执行前被拒绝（链上无效）；而有 guard 的运行受VM 预算限制（累计 1M 次 guard 调用 / 2s 墙钟时间——标记为本地 VM 上限，而非共识限制）；请务必在测试网上确认涉及资金/资源的 Hooks。hook_dry_run 为 STATIC_ONLY，compute_reward 为 DOCUMENTED_MODEL（旧版——优先使用 reward_status，其 REWARD_HOOK_FORMULA 会精确重新实现 reward.c，并复现真实链上向空投对象发放的 GenesisMint 奖励），estimate_hook_fee 为 ESTIMATE。

• 资源和提示词。 除工具外，此服务还提供 MCP 资源（xahau://rules、xahau://hook-api、xahau://tx-types）和引导式提示词（audit_hook、simulate_hook、explain_hook），方便 Agent 获取参考数据并直接运行常见工作流。

工具

Hook 智能分析（离线——核心功能）

工具	用途
execute_hook	在本地 VM 中运行真实 Hook 字节码，针对模拟的交易/状态 → 实际接受/回滚、返回码、状态写入、发出内容、跟踪（LOCAL_VM）。
simulate_transaction	签名前模拟器——预测未签名交易的结果：发起方 + 利益相关方 Hook 链（顺序以 xahaud Transactor.cpp/applyHook.cpp 中的规范顺序为准）将以真实字节码针对实时状态运行；提供逐个 Hook 的判定、解码后的发出内容、状态写入、静态引擎预检和诈骗评分。命名 Hook：只有交易携带相同 HookName 时，安装了 HookName 的 Hook 才会运行（否则报告为 not fired: hook requires HookName …）。EscrowFinish/EscrowCancel：托管所有者（Owner + OfferSequence）作为强利益相关方运行；目标地址会被标记，但不会猜测。
what_if	时光机——获取真实的历史交易，应用你的覆盖值，并在其原始账本上重新模拟。可重现真实奖励领取中的 GenesisMint 到空投过程（测试锁定）。
fuzz_hook	差分模糊测试：通过 VM 扫描大量生成的交易，以绘制 Hook 的接受/回滚决策边界（它接受与拒绝哪些交易类型/金额）。
annotate_hook_trace	按字节宽度将 execute_hook 的 trace[] 解码为易读值：规范 XFL 浮点数（definite）、int64/原生滴（两种字节序）、UInt32 + Ripple 纪元日期、候选账户 ID → r 地址（possible）、32 字节哈希。始终保留原始十六进制；离线运行。
hook_report	一次调用生成完整报告：结构 + 通俗易懂的分类 + 安全发现 + 费用。
hook_execution_postmortem	对真实链上交易的 Hook 进行事后分析：获取交易及其 meta.HookExecutions 和引擎结果，然后通过 VM 运行每个已触发 Hook 的真实字节码，并将 VM 的接受/回滚结果与链上记录进行比较。链上判定具有权威性；VM 运行标记为 LOCAL_VM；在降级/不确定时，agree 为 null（而非 false）。串行 RPC：每个唯一 HookHash 使用 1 次 tx + 1 次 ledger_entry。
vm_fidelity_report	如实报告保真度指标：通过 VM 重放已提交的真实主网 HookExecutions 语料库，仅报告**可比较（未降级）**运行的符合率；离线运行。
classify_hook	用通俗易懂的语言推断 Hook 的作用（防火墙/发出器/有状态/金融类/……）。
hook_diff	比较两个 Hook 版本——API/HookOn/大小差异 + 新增的敏感功能。
scaffold_hook	根据意图生成 C 语言的 Hook 入门模板（防火墙/支付限额/状态计数器/……），然后使用 analyze/execute 进行验证。
analyze_hook	对 Hook 运行静态分析规则引擎 → SARIF-lite 发现结果。
audit_account_hooks	拉取账户上的所有 Hook 并逐一分析。
inspect_hook_wasm	解析 CreateCode WASM：导入项、导出项（hook/cbak）、内存、自定义段、循环、_g 守卫和指令计数。
estimate_hook_fee	字节大小（SetHook 费用）+ 静态指令计数（复杂度代理指标），ESTIMATE。
hook_dry_run	STATIC_ONLY 快速检查——是否会因交易而触发 + 是否存在退出调用（真实运行请使用 execute_hook）。
list_rules · hook_api_lookup	枚举分析器规则 · 查询 Hook API 函数的作用和风险。
编解码（离线）
工具	用途
---	---
decode_hook_on / encode_hook_on	HookOn 位图 ⇄ 交易类型列表。
decode_hook_can_emit / encode_hook_can_emit	HookCanEmit 位图 ⇄ Hook 可 发出 的交易类型（HookCanEmit 修正案；缺省 = 可发出任何类型）。
estimate_hook_state_cost	ExtendedHookState 储备金计算：值字节数 + scale（1–16）→ 每条目容量（256×scale）、储备单位（= scale）、总计、溢出 + 最小 scale 警告，可选 XAH。
simulate_hook_trigger	静态预测（无 RPC、无字节码）：某笔交易会触发哪些账户的 Hook，区分强触发（可回滚）与弱触发。可补充 simulate_transaction。
decode_sethook	将 SetHook 交易解码为其 Hook 定义，并解码 HookOn。
decode_tx_blob / encode_tx_blob	Xahau 交易 blob ⇄ JSON（未签名）。
decode_uritoken_id · xah_amount	URIToken ID 验证 · XAH ⇄ drops。
decode_xpop	解码 Import/Burn2Mint XPOP → 源账本、内部销毁交易、销毁的 drops、UNL 验证者。
decode_result	引擎结果代码 ⇄ 名称（例如，153 ⇄ tecHOOK_REJECTED）。
diagnose_failed_tx	“为什么我的交易失败了？” — 根据链上事实提供通俗易懂的诊断：引擎结果 → 原因 + 具体修复方法（约 30 个代码的目录）、解码并解释 Hook 回滚返回字符串（奖励 Hook 的“You must wait N seconds”会转换为可领取日期）、提示“成功” Payments 中的部分付款陷阱，以及交易未找到时的排查（LastLedgerSequence 已过期 / 网络错误）。1 次读取。
validate_address · xaddress	验证经典地址/X-address（类型、账户 ID、标签）· 对 X-address 进行编码/解码。
currency_code · ripple_time	3 字符 ISO ⇄ 160 位货币 · Ripple 时间 ⇄ Unix/ISO。
decode_amount	解码原生 drops / 8 字节 / 48 字节已发行 STAmount / 金额对象 → 值 + 货币 + 发行方。
decode_sign_request	解码 Xaman txjson 或 tx_blob → 通俗易懂的“你将授权的内容” + 安全警告。
decode_lease_uri	解码 Evernode 租约 URIToken（evrlease/LTV）→ 租约索引、EVR 金额（XFL）、服务条款哈希、IP。
evernode_host_diagnostics	一次调用检查 Evernode 主机运行状况（自动执行官方故障排查清单）：注册条目、心跳存活状态与链上活跃规则的对比、实例负载、信誉、EVR 信任线/余额、注册 URIToken、租约报价、机器规格 + 累计 EVR 奖励。布局已根据规范的 evernode-js-client 和一个主网主机进行验证（约 9 次串行读取）。
inspect_emitted_tx	解码 Hook 的 emit() blob → 交易 JSON + 通俗易懂的摘要 + 危险评分。
scam_check	对签名请求（txjson 或 tx_blob）进行风险模式评分 → dangerScore 0-100 + SAFE/CAUTION/DANGER 等级 + 逐规则发现结果（SetHook、向其他账户执行 AccountDelete、更改 regular key/signer list、大额原生币付款、无过期时间、预签名）。仅根据交易结构进行离线启发式分析 — 每条发现都只是潜在风险，绝非已确认的诈骗；不会查询屏蔽列表，也不会检查链上恶意行为。

账本（只读 RPC）

工具	用途
xahau_server_info · get_account_info · get_account_objects	节点/账户读取。
get_account_hooks · get_hook_definition · get_hook_state	Hook 读取。get_account_hooks 会显示每个 Hook 的 HookName（只有携带该名称的交易才会触发具名 Hook）。
get_transaction · get_ledger · get_fee	交易（含 HookExecutions）· 账本 · 当前网络费用。
get_account_lines · get_account_offers · get_account_uritokens	信任线 · DEX 报价 · URIToken（NFT，已解码 URI）。
explain_account	一次调用生成通俗易懂的账户快照 — 余额、密钥安全、Hook、信任线、Evernode 租约、近期活动（5 次串行读取）。
经济 / 治理
工具	用途
---	---
reward_status	Balance Adjustment 诊断工具——是否已选择加入？精确应计的 XAH（采用 genesis 奖励钩子自身的公式，该公式来自 reward.c，并从 genesis 钩子状态读取实时 RR/RD；可复现真实链上的 GenesisMint 发放至该空投），下次领取倒计时、逾期领取警告（延迟领取会失去收益），以及适用时提供未签名的选择加入 / 领取 ClaimReward（3 次串行读取）。
compute_reward	估算可领取的 XAH 网络奖励（DOCUMENTED_MODEL；旧版工具——优先使用 reward_status）。
quantum_grade	评估账户是否已为量子（HNDL）做好准备——主密钥 / 常规密钥 / 多重签名 + 钩子 → 评分、等级和建议（包含 Hook / PQC 视角）。
governance_state	完整实时解码治理游戏：全部 20 个席位及成员、成员数量、实时奖励率 / 延迟、每个进行中的投票（谁投了什么），以及每项计票结果及其门槛（成员的 80% / 其他情况的 100%）和已达成标记。布局以 xahaud hook/genesis/govern.c 为准。
decode_b2m	Burn2Mint 分类。

修正案情报（只读，无需管理节点）

工具	用途
get_amendment_status	所有已启用的修正案（已知时解析为人类可读名称，否则显示原始哈希）+ 投票中的修正案（已超过 80%，正在计入启用条件）。读取账本上的 Amendments 单例——无需调用管理 feature。
predict_amendment_activation	对每项获得多数支持的修正案：显示其达到 80% 以上的时间和预计启用时间（多数支持 + Xahau 的 5 天窗口），并列出剩余天数及是否当前已符合条件。
check_amendment_blocked	配置的节点是否受修正案阻止（xahaud 版本过旧，无法读取已启用的修正案）？构建版本、已验证账本、升级补救措施。
diff_node_amendments	对比两个网络（例如主网与测试网）上的已启用修正案集合——说明为何某项交易 / Hook 功能在一个网络上可用、在另一个网络上不可用。

审计 / 取证

工具	用途
trace_transaction_stakeholders	根据元数据列出交易涉及的所有账户。Touch 修正案会将所有利益相关方写入元数据，因此这是权威的参与者列表（角色 + 条目类型 + 是否发生实质性更改标记）。
verify_double_threading	对交易的元数据线程结构进行审计；标记 fixProvisionalDoubleThreading 所处理的重复节点现象。
audit_account_remarks	解码账户对象上附加的 Remarks（名称 / 值从十六进制转换为文本、不可变标记）——适用于动态 NFT 和注释模式。
未签名构建工具（无需密钥，默认使用测试网）
工具	用途
---	---
build_sethook_unsigned	未签名的 SetHook，并自动执行 analyze_hook 预检。若发现 CRITICAL 问题，则暂不提供交易内容，只返回发现的问题；除非设置 overrideCritical: true。
build_claimreward_unsigned · build_import_unsigned · build_payment_unsigned	未签名的 ClaimReward · Import/B2M · Payment。
build_remit_unsigned	未签名的 Remit (XLS-55) — 原子性多资产推送：向一个目标地址转移多种货币（原生货币 + 已发行货币）和/或 URIToken，和/或直接铸造 URIToken；全部成功或全部失败。采用规范的 AmountEntry/MintURIToken 嵌套结构；自动处理信任线/储备金/账户创建语义；可选第三方 Inform。包含负载预检。
build_set_remarks_unsigned	未签名的 SetRemarks（Remarks 修正案）— 为你拥有/发行的账本对象添加、更新或删除键值备注。支持 immutable（tfImmutable），可通过省略来删除，并设有最多 32 条 + 唯一性 + 大小限制。为动态 NFT 提供支持。
build_clawback_unsigned	未签名的 Clawback — 发行方从持有人处收回已发行代币（Amount.issuer = 持有人，这是常见易错点）。包含选择启用 + XAH 防护。
build_deepfreeze_unsigned	未签名的 TrustSet 冻结切换 — deep_freeze（阻止发送和接收）、freeze 及其清除操作，并映射到正确的 tfSetDeepFreeze/tfSetFreeze 标志。
prepare_transaction	从实时网络自动填入 Sequence/Fee/LastLedgerSequence/NetworkID → 可供离线签名（绝不签名）。

Cron（定时执行 Hook）

工具	用途
build_cronset_unsigned	未签名的 CronSet — 为 Hook 安排未来的自主调用：StartTime（Ripple 纪元时间，0=尽快）或 startInSeconds、RepeatCount（0–256）、DelaySeconds，或 cancel（tfCronUnset）。预检会发现缺少间隔的重复执行，以及没有 Hook 的情况。
list_cron_jobs	读取账户的 Cron 账本对象，包含解码后的 StartTime（ISO）、DelaySeconds、剩余 RepeatCount 和预计的下次触发时间（包含原始对象）。
monitor_cron_health	标记剩余重复次数接近耗尽（≤ 阈值）的 Cron，避免周期性治理/游戏 Hook 悄然停止。

安装

新手或非技术人员？请从**通俗易懂的教程**开始——了解它的用途，以及可以直接询问的有趣功能。

需要 Node.js 20+。此服务通过 stdio 使用 MCP；由 MCP 客户端启动。

从 npm 安装

npx -y xahau-mcp --help      # run without installing (prints usage and exits)
npm install -g xahau-mcp     # or install the `xahau-mcp` command globally
xahau-mcp --smoke            # health check: local data + one live mainnet read

不带参数运行时，xahau-mcp 会等待通过 stdin/stdout 连接的 MCP 客户端——它不是交互式命令行工具。

添加到 MCP 客户端

Claude Code：

claude mcp add xahau -- npx -y xahau-mcp

Claude Desktop（claude_desktop_config.json），或任何支持 mcpServers 配置块的客户端：

{
  "mcpServers": {
    "xahau": { "command": "npx", "args": ["-y", "xahau-mcp"] }
  }
}

如果你是全局安装的，也可以使用 "command": "xahau-mcp"，不需要 args。若要指定自己的 RPC 节点，请添加 "env": { "XAHAU_RPC_URLS": "https://your-node.example" }（以逗号分隔；测试网使用 XAHAU_TEST_RPC_URLS）。

此服务不会向网络写入数据：它通过公共 JSON-RPC 读取账本状态，绝不签名或提交交易，也不持有密钥。离线工具（Hook VM、静态分析器、codec、HookOn）完全不需要网络。

从 GitHub / 源码安装

npm install -g github:Hugegreencandle/xahau-mcp   # builds on install via `prepare`

或者克隆并构建：

git clone https://github.com/Hugegreencandle/xahau-mcp && cd xahau-mcp
npm install        # the `prepare` script compiles dist/ automatically
npm run smoke      # health check + a live mainnet read
npm test           # offline test suite

旧版本（≤ 1.4.0）曾以 @hugegreencandle/xahau-mcp 的名称发布到 GitHub Packages；即使公开安装，该 scope 也需要 GitHub token。请改用上方无 scope 的 npm 包。

HTTP shim（浏览器、钱包、Web 工具）

MCP 服务使用 stdio 通信——浏览器、Xaman WebView 和公开的“模拟任意 Hook”Web 工具无法使用。HTTP shim（src/http.ts）通过普通 HTTP 提供相同的飞行模拟器核心功能。只读；绝不签名或提交交易。

PORT=8787 npm run http        # or: PORT=8787 node dist/http.js
curl localhost:8787/health

# or deploy the container (non-root, healthchecked):
docker build --target http -t xahau-mcp-http .
docker run -p 8787:8787 -e MAX_INFLIGHT=2 -e XAHC_HOOK_MEM_MB=128 xahau-mcp-http

对于会构建 最后一个 Dockerfile 阶段的平台（Railway 等），请使用 Dockerfile.http（设置 RAILWAY_DOCKERFILE_PATH=Dockerfile.http）——它会将 http 阶段作为最终阶段。

端点

方法 · 路径	请求体	返回值
POST /simulate	{ tx, network?, ledgerIndex?, candidateCode?, candidateHookOn?, candidateNamespace?, candidateHookName? }	完整的 Simulation — 按 Hook 显示 accept/rollback、解码后的 emits、状态写入和静态预检
POST /what-if	{ txHash, overrides?, network? }	在原始账本重新运行真实历史交易（应用你的覆盖项）得到的 Simulation
POST /execute	{ wasmHex, txType?, otxnFields?, hookAccountId?, state?, … }	SandboxResult — 隔离运行 Hook 的字节码（离线，无 RPC）
POST /analyze	{ wasmHex, hookOn?, namespace?, … }	{ findings, summary } — 静态规则引擎（离线、即时、成本低的漏斗入口）
GET /fidelity	—	VM 保真度报告 + corpusHash + lastRun（逐字回显仅 accept 时的 coverageWarning）
GET /health	—	{ ok, inflight, endpoints }

模拟尚未部署的 Hook — 在 /simulate 中传入 candidateCode（已构建的 wasm hex）。它会替换 tx.Account 的链上 Hook 链，因此新编译的 Hook 可以在你执行 SetHook 之前，针对实时账本 + 完整 TSH 链运行。（这也是 xahc verify 和公开模拟工具的调用方式。）

配置（env）

变量	默认值	用途
PORT	8787	监听端口
RL_MAX	20	每个 IP 每分钟的请求数
MAX_INFLIGHT	4	并发模拟数
XAHC_HOOK_TIMEOUT_MS	3000	每次 Hook 执行的硬性墙钟时间限制
XAHC_HOOK_MEM_MB	256	每次 Hook 执行的内存上限
XAHC_SIM_SPACING_MS	sim 默认值	RPC 读取间隔 — 使用自己的节点时设为 0，使用共享公共节点时设为约 300
TRUST_PROXY	未设置	仅在位于会设置 X-Forwarded-For 的反向代理之后时设置
XAHAU_RPC_URLS	data/endpoints.json	逗号分隔的主网 RPC 故障转移列表

公开运行

该 shim 会处理不受信任、由用户提供的 wasm，因此每次 Hook 执行都在临时的 worker_thread 中运行，并受到上述超时和内存上限的限制 — 挂起或大量分配内存的 Hook 会被终止，不会阻塞或导致主进程崩溃（已经过安全审计；无限循环 / 未设防的递归会返回 422，而不会导致服务中断）。公开部署时：

• 在进程监控器之后运行（systemd / pm2 / 容器重启策略），以实现纵深防御。
• 仅在确实位于会设置 X-Forwarded-For 的代理之后时设置 TRUST_PROXY；否则，速率限制器会按套接字地址进行限制（设置该变量会允许客户端伪造此标头并绕过限制）。
• 默认启用每 IP 速率限制和全局并发上限 — 可通过 env 调整。

安全性

采用防御性设计并经过审查（npm audit + 危险面检查）：

• 只读且不保管密钥 — 任何地方都没有 sign/submit；构建器工具从不接受密钥，只会生成未签名交易，供离线签名。
• 无代码执行入口 — 不使用 eval/Function、child_process/shell，不写入文件系统，也不动态调用 require。RPC fetch 只会访问 data/endpoints.json 中的固定端点（或你为主网/测试网设置的 XAHAU_RPC_URLS / XAHAU_TEST_RPC_URLS 覆盖值）——绝不会访问由工具输入构造的 URL，因此不存在 SSRF。
• 不受信任的 Hook WASM 在沙箱中运行 — execute_hook/fuzz_hook 会在 Node 的 WebAssembly 引擎中运行 Hook 字节码，该引擎无法访问系统调用、文件系统或网络；Hook 只能调用内存中的 JS Hook-API 模拟接口，且内存读写均经过边界检查。
• **不受信任字节码的加固：**执行 Hook 前，虚拟机会拒绝包含未受保护循环（循环数量多于 _g 守卫调用点）、无法通过操作码扫描验证循环、字节码超过 128 KiB 或声明超过 512 个内存页的模块；受保护循环则受累计守卫预算和运行时间上限约束。因此，攻击者提供的 Hook 无法令运行卡住或耗尽内存。工具输出是数据，而非指令（应像对待任何 MCP 一样处理）。
• 依赖项：npm audit 仅报告了 xrpl-accountlib 签名库（elliptic/bip32/tiny-secp256k1）的低严重性传递依赖安全公告——此服务从不调用这些代码路径（它只使用二进制编解码器）。

工作原理

• **无繁重依赖项。**三个运行时依赖项：@modelcontextprotocol/sdk、zod 和 xrpl-accountlib（仅用于支持 Xahau 的二进制编解码器；从不调用其签名功能）。RPC 使用普通的 fetch；WASM 读取器是手工编写且零依赖的；虚拟机使用 Node 内置的 WebAssembly 引擎，通过 JS Hook API 模拟接口运行字节码——无需 WASM 工具链或原生依赖项。
• 真实数据，可重新生成。data/ 由 Xahau 节点的实时 server_definitions 和规范 Hook API 列表（Xahau/hooks-rs c/extern.h）通过 npm run fetch:all 构建。包含 78 个函数的 Hook API 目录为每个函数提供危险元数据，用于驱动分析器。
• HookOn 语义已根据 Xahau 文档验证：256 位，位 n = 交易类型 n，反向／低电平有效（置位 = 不触发），其中位 22（SetHook）为高电平有效。

许可证

MIT © 2026 Dane Brown。与 XRPL Labs 或 Xahau 项目无关联。分析器的发现仅为启发式指导，不构成安全保证——在主网使用前，请务必在测试网上测试并独立审查 Hook。