{
  "markdown": "# xahau-mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the **[Xahau](https://xahau.network) network** with two firsts: it **runs a Hook's real WebAssembly bytecode in a local VM** (no `xahaud` node required), and it runs a **Hooks-specific static-analysis / security rule engine** over it — both fully offline. Around that core it adds read-only ledger access, a Xahau-aware binary codec, an instruction-count fee estimate, network-reward math, governance helpers, and unsigned-transaction builders.\n\n> Xahau is the XRPL fork whose flagship feature is **Hooks** — small on-ledger WebAssembly smart contracts. There was no MCP for Xahau and no static analyzer for Hooks; this is both.\n\n![xahau-mcp v2.0 flight simulator demo](demo/xahau-mcp-v2-flight-simulator.gif)\n\n## The trifecta — safe Hooks, end to end\n\nThree open-source tools, one workflow: **write → simulate one tx → prove all inputs.**\nxahau-mcp is the **simulate** stage.\n\n| stage | tool | what it does |\n|---|---|---|\n| **write** | [xahc](https://github.com/Hugegreencandle/xahc) | author + compile a safe Hook to clean, lint-passed WASM |\n| **simulate one** | [xahau-mcp](https://github.com/Hugegreencandle/xahau-mcp) | run the real bytecode against one live transaction |\n| **prove all** | [xahc-prover](https://github.com/Hugegreencandle/xahc-prover) | prove an invariant holds for every input in scope — or return the counterexample |\n\n## Why it's useful\n\nPoint any MCP-capable agent (Claude, etc.) at this server and it can:\n\n- **See the future before signing** — `simulate_transaction` is a pre-sign **flight simulator**: every hook an unsigned transaction would trigger runs as real bytecode against live ledger state, with per-hook accept/rollback, decoded emitted transactions, simulated state writes and labeled static engine preflights. Its sibling `what_if` is a **time machine**: replay any real historical transaction — with your modifications — at its original ledger. Verified to reproduce a real claim's emitted `GenesisMint` payout **to the drop** (72,251,963 drops), test-locked.\n\n- **Run a Hook without deploying it** — `execute_hook` instantiates the real CreateCode WASM in a local VM, supplies the Hook API over a *simulated* transaction + ledger state, and reports the actual `accept`/`rollback` decision, return code/string, state writes, emitted transactions and a call trace. The first dev-accessible Hook simulator that needs no `xahaud` node.\n- **Audit a Hook before it's installed** — paste the CreateCode WASM (or an on-ledger hook hash) and get SARIF-lite findings: missing `accept`/`rollback` exit, unguarded loops (`_g`), unknown `env` imports, dangerous `HookGrant`s, over-broad `HookOn`, and more.\n- **Decode the cryptic `HookOn` bitmap** in both directions — the 256-bit, inverted, active-low mask (with the active-high SetHook bit) is easy to get wrong; here it's verified and round-trip-tested.\n- **Read Xahau ledger state** — accounts, installed hooks, hook definitions, hook state, transactions (with `HookExecutions` metadata), ledgers.\n- **Answer the #1 retail question** — `reward_status` tells any account whether it's opted in to Xahau network rewards (Balance Adjustments), the exact XAH accrued — computed with the genesis reward hook's own formula and live parameters, verified to reproduce a real on-chain payout **to the drop** — when it can next claim, and whether the claim is overdue (late claiming forfeits yield).\n- **Diagnose an Evernode host** — `evernode_host_diagnostics` automates the official troubleshooting checklist for Xahau's largest operator group: registration, heartbeat liveness (the actual on-chain active rule), reputation, EVR trustline, lease offers, specs and accumulated rewards, in one read-only call.\n- **Explain a failed transaction** — `diagnose_failed_tx` turns an engine result + hook return strings into a plain-English cause and a concrete fix.\n- **Watch governance live** — `governance_state` decodes the Genesis Governance Game's full hook state: who holds the 20 seats, every open vote and tally, and whether a change (member swap, reward-rate change) is about to be actioned. No explorer shows this.\n- **Build unsigned transactions** (SetHook, ClaimReward, Payment) with an automatic security preflight — returned **unsigned**, to be signed offline.\n\n## Why this is the most advanced blockchain MCP we know of\n\nStrong claim, so here is the checkable evidence (2026-06-11). To our knowledge no MCP for ANY\nchain — Ethereum, Solana, Bitcoin, XRPL or otherwise — combines even two of these; the closest\ncomparators are cloud-simulation MCPs (e.g. Tenderly's, which simulates on their hosted\ninfrastructure) and standalone analyzers (e.g. Slither, which is EVM-only and not an MCP):\n\n1. **Executes real on-chain contract bytecode in a LOCAL VM** — `execute_hook` runs the actual\n   CreateCode WASM with no node, no cloud, no account. Not an ABI wrapper, not a hosted simulator.\n2. **Publishes a measured, regression-locked fidelity score against chain ground truth** —\n   `vm_fidelity_report` replays 30 real mainnet hook executions: **30/30 agree (100%), 0 degraded**,\n   including the foreign-state-reading hook that dominates live traffic. Those 30 are all\n   **accept-direction** (live Xahau traffic is heartbeat-dominated), and the metric says so itself —\n   it reports the accept/rollback composition and warns that an accept-only corpus can't distinguish\n   the VM from an always-accept stub. The **rollback** direction is exercised on real genesis bytecode\n   (governance `Invoke` → rollback) in [`tests/regression.test.ts`](tests/regression.test.ts).\n   The corpus, the method and the honest history (25% → 0% → 100%) are in\n   [docs/FIDELITY.md](docs/FIDELITY.md). We know of no other blockchain MCP that even attempts this.\n3. **In-protocol static security analysis** — a Hooks-specific rule engine (SARIF-lite findings),\n   calibrated against the network's own genesis hooks.\n4. **In-protocol differential fuzzing** — `fuzz_hook` maps a contract's accept/reject decision\n   boundary in the local VM.\n5. **Post-mortems real transactions with real bytecode** — `hook_execution_postmortem` replays what\n   actually fired on chain and compares.\n6. **Reproduces on-chain economics exactly** — `reward_status` re-implements the genesis reward\n   hook's formula and reproduces a real emitted payout **to the drop** (verified, test-locked).\n7. **Decodes live governance end-to-end** — `governance_state` shows every seat, vote, tally and\n   threshold of the Governance Game, live.\n8. **Operational doctors** for the ecosystem's real pain: failed-tx diagnosis with cause+fix,\n   Evernode host health, claim-overdue detection.\n\nEvery claim above is reproducible from this repo: the corpus is committed, the tests assert the\nnumbers, and the canonical sources (xahaud genesis hooks, evernode-js-client) are cited in code.\n\n## Safety posture\n\n- **Read-only** toward the network. There is no `submit` and no `sign` anywhere in this server.\n- **No key custody.** Builder tools never accept a secret/seed and always return an **unsigned** transaction plus instructions to sign offline (e.g. with [xaman](https://xaman.app) or `xrpl-accountlib`). They default to **testnet**.\n- **Honest fidelity.** `execute_hook` runs the **real bytecode** against a **simulated environment**. The VM implements a large slice of the 78-function Hook API — nearly the whole **XFL float** API (verified against `float_one`; `float_root`/`float_log` are the exceptions — they return `NOT_IMPLEMENTED`), the **slot** table + **STObject subfield extraction** (`slot_subfield`/`sto_subfield`, byte-exact against real txns), state, `otxn_*`/`hook_*`, `util_accid`/`util_raddr`/`util_verify`/`util_sha512h`, and more. STObject mutation (`sto_emplace`/`erase`/`validate`), `util_keylet` (account + hook verified against live ledger indexes; offer/escrow/check/ticket/signers canonical + fail-safe), **`slot_set` + foreign hook state (`state_foreign`/`state_foreign_set`) with async pre-resolve** (`execute_hook resolveKeylets:true` fetches the ledger objects AND foreign-state entries the hook reads — iteratively, since one resolved read can expose the next — and re-runs), `slot_float`/`float_sto`/`float_sto_set` (STAmount ⇄ XFL **both ways** — parse a native **or issued/IOU** Amount into a float and serialize one back; the issued layout below bit 63 *is* the XFL layout), and 32-byte state-key padding (short keys are left-zero-padded exactly as on-ledger) are now supported. `state_foreign_set` records the write but does NOT model the on-chain HookGrant requirement; `etxn_details` serves a disclosed SYNTHETIC placeholder (listed in `syntheticCalls`, cannot change the accept/rollback decision). What still can't be faithful is honestly recorded: unverified keylet subtypes, `meta_slot`, and other un-modelled calls return the real `NOT_IMPLEMENTED` code, are listed in `unsupportedCalls`, and mark the run `degraded` — **never faked**. The VM models the guard budget (`_g` enforces each guard's declared `maxiter` → `GUARD_VIOLATION`), and reports `stateApplied` (state writes commit only on `accept`, discarded on `rollback`). It is **not** a consensus-faithful `xahaud` replica — it has no fee/fuel metering beyond guards, XFL math truncates rather than round-half-up (so `float_mulratio`'s round-up flag and last-significant-digit results can differ), value-level math is verified only where tested. Hooks with a loop but no `_g` guard are **refused before execution** (invalid on-chain), and *guarded* runs are bounded by a **VM budget** (1M cumulative guard calls / 2s wall clock — labeled as a local VM cap, not a consensus limit); always confirm financial/resource hooks on testnet. `hook_dry_run` is `STATIC_ONLY`, `compute_reward` is `DOCUMENTED_MODEL` (legacy — prefer `reward_status`, whose `REWARD_HOOK_FORMULA` re-implements `reward.c` exactly and reproduces a real on-chain `GenesisMint` payout to the drop), `estimate_hook_fee` is `ESTIMATE`.\n\n- **Resources & prompts.** Beyond tools, the server exposes MCP **resources** (`xahau://rules`, `xahau://hook-api`, `xahau://tx-types`) and guided **prompts** (`audit_hook`, `simulate_hook`, `explain_hook`) so agents can pull reference data and run the common workflows directly.\n\n## Tools\n\n**Hook intelligence (offline — the core)**\n| Tool | Purpose |\n|---|---|\n| `execute_hook` | **Run the real Hook bytecode in a local VM** against a simulated tx/state → actual accept/rollback, return code, state writes, emits, trace (`LOCAL_VM`). |\n| `simulate_transaction` | **PRE-SIGN FLIGHT SIMULATOR** — predict an unsigned tx's fate: originator + stakeholder hook chains (order canonical from xahaud `Transactor.cpp`/`applyHook.cpp`) run as real bytecode against live state; per-hook verdicts, decoded emits, state writes, static engine preflights, scam score. |\n| `what_if` | **TIME MACHINE** — fetch a real historical tx, apply your overrides, re-simulate at its original ledger. Reproduces the real reward claim's `GenesisMint` to the drop (test-locked). |\n| `fuzz_hook` | **Differential fuzzing**: sweep many generated transactions through the VM to map the hook's accept/rollback **decision boundary** (which tx types / amounts it accepts vs rejects). |\n| `annotate_hook_trace` | **Decode an `execute_hook` `trace[]`** into human-readable values by byte-width: canonical XFL float (`definite`), int64/native-drops (both endians), UInt32 + Ripple-epoch date, candidate account-id → r-address (`possible`), 32-byte hash. Raw hex always preserved; offline. |\n| `hook_report` | **One-call full report**: structure + plain-English classification + security findings + fee. |\n| `hook_execution_postmortem` | **Post-mortem a real on-chain tx's hooks**: fetch the tx + its `meta.HookExecutions` + engine result, then run each fired hook's **real bytecode** through the VM and compare the VM's accept/rollback to what the chain recorded. On-chain decision is authoritative; VM run is `LOCAL_VM`; `agree` is `null` (not false) when degraded/indeterminate. Serial RPC: 1 `tx` + 1 `ledger_entry` per unique HookHash. |\n| `vm_fidelity_report` | **Honest fidelity metric**: replays a committed corpus of real mainnet HookExecutions through the VM and reports agreement % over **comparable (non-degraded)** runs only; offline. |\n| `classify_hook` | Infer in plain English what a hook does (firewall/emitter/stateful/financial/…). |\n| `hook_diff` | Compare two hook versions — API/HookOn/size deltas + newly-gained sensitive capabilities. |\n| `scaffold_hook` | **Generate a starter Hook in C** for an intent (firewall/payment-limit/state-counter/…) — then verify with analyze/execute. |\n| `analyze_hook` | Run the static-analysis rule engine over a hook → SARIF-lite findings. |\n| `audit_account_hooks` | Pull every hook on an account and analyze all of them. |\n| `inspect_hook_wasm` | Parse CreateCode WASM: imports, exports (`hook`/`cbak`), memory, custom sections, loop, `_g` guard & instruction counts. |\n| `estimate_hook_fee` | Byte size (SetHook fee) + static instruction count (complexity proxy), `ESTIMATE`. |\n| `hook_dry_run` | `STATIC_ONLY` quick check — fires-on-tx + exit calls present (use `execute_hook` for real runs). |\n| `list_rules` · `hook_api_lookup` | Enumerate analyzer rules · look up a Hook API function's role & hazards. |\n\n**Codec / decode (offline)**\n| Tool | Purpose |\n|---|---|\n| `decode_hook_on` / `encode_hook_on` | HookOn bitmap ⇄ transaction-type list. |\n| `decode_hook_can_emit` / `encode_hook_can_emit` | HookCanEmit bitmap ⇄ the tx types a hook may **emit** (HookCanEmit amendment; absent = may emit anything). |\n| `estimate_hook_state_cost` | ExtendedHookState reserve math: value bytes + scale (1–16) → per-entry capacity (256×scale), reserve units (= scale), totals, overflow + min-scale warnings, optional XAH. |\n| `simulate_hook_trigger` | Static (no-RPC, no-bytecode) prediction of which accounts' hooks a tx would invoke, strong (can rollback) vs weak. Complements `simulate_transaction`. |\n| `decode_sethook` | A SetHook tx → its hook definitions, HookOn decoded. |\n| `decode_tx_blob` / `encode_tx_blob` | Xahau tx blob ⇄ JSON (unsigned). |\n| `decode_uritoken_id` · `xah_amount` | URIToken ID validation · XAH⇄drops. |\n| `decode_xpop` | Decode an Import/Burn2Mint XPOP → source ledger, inner burn tx, burned drops, UNL validators. |\n| `decode_result` | Engine result code ⇄ name (e.g. 153 ⇄ tecHOOK_REJECTED). |\n| `diagnose_failed_tx` | **\"Why did my transaction fail?\"** — plain-English diagnosis from on-chain facts: engine result → cause + concrete fix (~30-code catalog), hook rollback return-strings decoded and *interpreted* (the reward hook's \"You must wait N seconds\" becomes a claimable-at date), the partial-payment trap on \"successful\" Payments, and not-found triage (expired `LastLedgerSequence` / wrong network). 1 read. |\n| `validate_address` · `xaddress` | Validate classic/X-address (type, account-id, tag) · encode/decode X-addresses. |\n| `currency_code` · `ripple_time` | 3-char ISO ⇄ 160-bit currency · Ripple-time ⇄ Unix/ISO. |\n| `decode_amount` | Decode native drops / 8-byte / 48-byte issued STAmount / amount object → value+currency+issuer. |\n| `decode_sign_request` | Decode a Xaman txjson or tx_blob → plain-English \"what you authorize\" + safety warnings. |\n| `decode_lease_uri` | Decode an Evernode lease URIToken (`evrlease`/LTV) → lease index, EVR amount (XFL), ToS hash, IP. |\n| `evernode_host_diagnostics` | **One-call Evernode host health check** (the official troubleshooting checklist, automated): registration entry, heartbeat liveness vs the on-chain active rule, instance load, reputation, EVR trustline/balance, registration URIToken, lease offers, machine specs + accumulated EVR reward. Layout verified against the canonical `evernode-js-client` + a live mainnet host (~9 serial reads). |\n| `inspect_emitted_tx` | Decode a hook's `emit()` blobs → tx JSON + plain-English summary + danger score. |\n| `scam_check` | Score a sign request (txjson or tx_blob) for risky patterns → `dangerScore` 0-100 + SAFE/CAUTION/DANGER tier + per-rule findings (SetHook, AccountDelete-to-other, regular-key/signer-list changes, large native payment, no-expiry, pre-signed). Offline heuristic on tx **shape only** — every finding is a **potential** risk, never a confirmed scam; no block-list lookup, no on-chain malice check. |\n\n**Ledger (read-only RPC)**\n| Tool | Purpose |\n|---|---|\n| `xahau_server_info` · `get_account_info` · `get_account_objects` | Node/account reads. |\n| `get_account_hooks` · `get_hook_definition` · `get_hook_state` | Hook reads. |\n| `get_transaction` · `get_ledger` · `get_fee` | Tx (with `HookExecutions`) · ledger · current network fee. |\n| `get_account_lines` · `get_account_offers` · `get_account_uritokens` | Trustlines · DEX offers · URITokens (NFTs, URI decoded). |\n| `explain_account` | **One-call plain-English account snapshot** — balance, key safety, hooks, trustlines, Evernode leases, recent activity (5 serial reads). |\n\n**Economics / governance**\n| Tool | Purpose |\n|---|---|\n| `reward_status` | **Balance Adjustment doctor** — opted in? exact accrued XAH (the genesis reward hook's own formula from `reward.c`, with live `RR`/`RD` read from genesis hook state; reproduces a real on-chain `GenesisMint` payout **to the drop**), next-claim countdown, overdue-claim warning (late claiming forfeits yield), plus an unsigned opt-in/claim `ClaimReward` when applicable (3 serial reads). |\n| `compute_reward` | Project claimable XAH network reward (`DOCUMENTED_MODEL`; legacy — prefer `reward_status`). |\n| `quantum_grade` | Grade an account for quantum (HNDL) readiness — master-key/regular-key/multisig + hooks → score, tier, recommendations (with a Hook/PQC angle). |\n| `governance_state` | **Full live decode of the Governance Game**: all 20 seats + members, member count, live reward rate/delay, every open vote (who voted what) and every tally with its threshold (80% membership / 100% else) and reached-flag. Layout canonical from `xahaud hook/genesis/govern.c`. |\n| `decode_b2m` | Burn2Mint classification. |\n\n**Amendment intelligence (read-only, no admin node)**\n| Tool | Purpose |\n|---|---|\n| `get_amendment_status` | Every **enabled** amendment (resolved to its human name where known, raw hash otherwise) + any in the **voting** set (already >80%, counting toward enablement). Reads the on-ledger Amendments singleton — no admin `feature` call needed. |\n| `predict_amendment_activation` | For each amendment holding majority: when it reached >80% and its estimated enable time (majority + Xahau's 5-day window), with days remaining and an eligible-now flag. |\n| `check_amendment_blocked` | Is the configured node **amendment blocked** (xahaud too old to read an enabled amendment)? Build version, validated ledger, upgrade remedy. |\n| `diff_node_amendments` | Diff enabled-amendment sets across two networks (e.g. mainnet vs testnet) — explains why a tx/Hook feature works on one but not the other. |\n\n**Audit / forensics**\n| Tool | Purpose |\n|---|---|\n| `trace_transaction_stakeholders` | Every account a tx touched, from metadata. The **Touch** amendment forces all stakeholders into metadata, so this is the authoritative participant list (roles + entry types + materially-changed flag). |\n| `verify_double_threading` | Structural audit of a tx's metadata threading; flags the duplicate-node symptom `fixProvisionalDoubleThreading` addressed. |\n| `audit_account_remarks` | Decode the **Remarks** attached to an account's objects (name/value hex→text, immutable flag) — dynamic-NFT and annotation patterns. |\n\n**Unsigned builders (no keys, testnet-default)**\n| Tool | Purpose |\n|---|---|\n| `build_sethook_unsigned` | UNSIGNED SetHook with automatic `analyze_hook` preflight. |\n| `build_claimreward_unsigned` · `build_import_unsigned` · `build_payment_unsigned` | UNSIGNED ClaimReward · Import/B2M · Payment. |\n| `build_remit_unsigned` | UNSIGNED **Remit (XLS-55)** — atomic multi-asset push: multiple currencies (native + issued) and/or URIToken transfers and/or an inline URIToken mint to one destination, all-or-nothing. Canonical `AmountEntry`/`MintURIToken` nesting; auto trustline/reserve/account-create semantics; optional third-party `Inform`. Payload preflight included. |\n| `build_set_remarks_unsigned` | UNSIGNED **SetRemarks** (Remarks amendment) — attach/update/delete key-value remarks on a ledger object you own/issue. `immutable` (tfImmutable) support, delete-by-omission, 32-max + uniqueness + size guards. Powers dynamic NFTs. |\n| `build_clawback_unsigned` | UNSIGNED **Clawback** — issuer revokes issued tokens from a holder (`Amount.issuer` = holder, the canonical gotcha). Opt-in + XAH guards. |\n| `build_deepfreeze_unsigned` | UNSIGNED **TrustSet** freeze toggle — `deep_freeze` (blocks send+receive), `freeze`, and their clears, mapped to the correct `tfSetDeepFreeze`/`tfSetFreeze` flags. |\n| `prepare_transaction` | Autofill Sequence/Fee/LastLedgerSequence/NetworkID from the live network → ready to sign offline (never signs). |\n\n**Cron (scheduled Hook execution)**\n| Tool | Purpose |\n|---|---|\n| `build_cronset_unsigned` | UNSIGNED **CronSet** — schedule a Hook's future self-invocations: `StartTime` (Ripple-epoch, 0=ASAP) or `startInSeconds`, `RepeatCount` (0–256), `DelaySeconds`, or `cancel` (tfCronUnset). Preflight catches recurring-without-interval and no-Hook cases. |\n| `list_cron_jobs` | Read an account's Cron ledger objects with decoded StartTime (ISO), DelaySeconds, remaining RepeatCount, and an estimated next-fire time (raw object included). |\n| `monitor_cron_health` | Flag Crons whose remaining repeats are near exhaustion (≤ threshold) so a recurring governance/game Hook doesn't silently stop. |\n\n## Install\n\n> New here or non-technical? Start with the **[plain-English tutorial](docs/TUTORIAL.md)** — what it does + cool things to just *ask*.\n\nInstall straight from GitHub — no npm-registry account needed; it builds on install:\n\n```bash\nnpm install -g github:Hugegreencandle/xahau-mcp\n```\n\nOr clone and build:\n```bash\ngit clone https://github.com/Hugegreencandle/xahau-mcp && cd xahau-mcp\nnpm install        # the `prepare` script compiles dist/ automatically\nnpm run smoke      # health check + a live mainnet read\nnpm test           # 298 tests (offline)\n```\n\nAlso published to **GitHub Packages** as `@hugegreencandle/xahau-mcp`. GitHub Packages requires auth even for public installs, so add to your `.npmrc`:\n```\n@hugegreencandle:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN   # token with read:packages\n```\nthen `npm install -g @hugegreencandle/xahau-mcp`. (The `github:` install above needs no auth and is simpler.)\n\nAdd to an MCP client (e.g. Claude Code / Desktop):\n```json\n{ \"mcpServers\": { \"xahau\": { \"command\": \"xahau-mcp\" } } }\n```\n\n## HTTP shim (browsers, wallets, web tools)\n\nThe MCP server speaks **stdio** — browsers, the Xaman webview, and a public \"simulate any hook\" web tool can't. The HTTP shim (`src/http.ts`) exposes the same flight-simulator core over plain HTTP. Read-only; never signs or submits.\n\n```bash\nPORT=8787 npm run http        # or: PORT=8787 node dist/http.js\ncurl localhost:8787/health\n\n# or deploy the container (non-root, healthchecked):\ndocker build --target http -t xahau-mcp-http .\ndocker run -p 8787:8787 -e MAX_INFLIGHT=2 -e XAHC_HOOK_MEM_MB=128 xahau-mcp-http\n```\nOn platforms that build the *last* Dockerfile stage (Railway, etc.), use `Dockerfile.http` (set `RAILWAY_DOCKERFILE_PATH=Dockerfile.http`) — it's the http stage as the final stage.\n\n### Endpoints\n\n| Method · path | Body | Returns |\n|---|---|---|\n| `POST /simulate` | `{ tx, network?, ledgerIndex?, candidateCode? }` | full `Simulation` — per-hook accept/rollback, decoded emits, state writes, static preflights |\n| `POST /what-if` | `{ txHash, overrides?, network? }` | `Simulation` of a real historical tx re-run (with your overrides) at its original ledger |\n| `POST /execute` | `{ wasmHex, txType?, otxnFields?, hookAccountId?, state?, … }` | `SandboxResult` — run a hook's bytecode in isolation (offline, no RPC) |\n| `POST /analyze` | `{ wasmHex, hookOn?, namespace?, … }` | `{ findings, summary }` — the static rule engine (offline, instant, the cheap top-of-funnel) |\n| `GET /fidelity` | — | the VM fidelity report + `corpusHash` + `lastRun` (echoes the accept-only `coverageWarning` verbatim) |\n| `GET /health` | — | `{ ok, inflight, endpoints }` |\n\n**Simulate a not-yet-deployed hook** — pass `candidateCode` (the built wasm hex) on `/simulate`. It replaces `tx.Account`'s on-ledger hook chain, so a freshly-compiled hook runs against the **live ledger + full TSH chain BEFORE you SetHook it**. (This is what [`xahc verify`](https://github.com/Hugegreencandle/xahc) and a public simulate tool call.)\n\n### Config (env)\n\n| Var | Default | Purpose |\n|---|---|---|\n| `PORT` | `8787` | listen port |\n| `RL_MAX` | `20` | requests / IP / minute |\n| `MAX_INFLIGHT` | `4` | concurrent simulations |\n| `XAHC_HOOK_TIMEOUT_MS` | `3000` | hard wall-clock per hook execution |\n| `XAHC_HOOK_MEM_MB` | `256` | memory cap per hook execution |\n| `XAHC_SIM_SPACING_MS` | sim default | inter-read RPC spacing — `0` for your own node, ~`300` behind a shared public node |\n| `TRUST_PROXY` | unset | set **only** when behind a reverse proxy that sets `X-Forwarded-For` |\n| `XAHAU_RPC_URLS` | `data/endpoints.json` | comma-separated mainnet RPC failover list |\n\n### Running it publicly\n\nThe shim serves **untrusted, user-supplied wasm**, so each hook execution runs in a throwaway `worker_thread` with the timeout + memory cap above — a hanging or allocation-bombing hook is terminated without blocking or crashing the main process (security-audited; an infinite loop / unguarded recursion returns `422`, not downtime). For a public deploy:\n\n- **Run behind a process supervisor** (systemd / pm2 / container restart policy) for defense-in-depth.\n- **Only set `TRUST_PROXY`** when genuinely behind a proxy that sets `X-Forwarded-For`; otherwise the rate limiter keys on the socket address (setting it lets clients spoof the header and bypass the limit).\n- Per-IP rate limit + a global concurrency cap are on by default — tune via env.\n\n## Security\n\nDesigned defensively and reviewed (`npm audit` + a danger-surface pass):\n\n- **Read-only & no key custody** — no `sign`/`submit` anywhere; builder tools never accept a secret and only emit *unsigned* transactions to sign offline.\n- **No code-exec surface** — no `eval`/`Function`, no `child_process`/shell, no filesystem writes, no dynamic `require`. RPC `fetch` only ever hits the fixed endpoints in `data/endpoints.json` (or your `XAHAU_RPC_URLS` / `XAHAU_TEST_RPC_URLS` overrides for mainnet/testnet) — never a URL built from tool input, so no SSRF.\n- **Untrusted Hook WASM is sandboxed** — `execute_hook`/`fuzz_hook` run hook bytecode in Node's WebAssembly engine, which has no syscall/fs/network access; a hook can only call the in-memory JS Hook-API shims, with bounds-checked memory reads/writes.\n- **Untrusted-bytecode hardening:** before executing a hook the VM refuses modules with an unguarded loop (more loops than `_g` guard call-sites), with an opcode-scan that couldn't verify the loops, over 128 KiB of bytecode, or declaring more than 512 memory pages; guarded loops are bounded by a cumulative guard budget + wall-clock cap. So an attacker-supplied hook can't hang or OOM a run. Tool output is data, not instructions (treat it as such, as with any MCP).\n- **Dependencies:** `npm audit` reports only low-severity advisories transitively under `xrpl-accountlib`'s signing libraries (elliptic/bip32/tiny-secp256k1) — code paths this server never calls (it uses only the binary codec).\n\n## How it works\n\n- **No heavy deps.** Three runtime deps: `@modelcontextprotocol/sdk`, `zod`, and `xrpl-accountlib` (used only for the Xahau-aware binary codec; its signing surface is never called). RPC is plain `fetch`; the **WASM reader is hand-rolled and zero-dep**; the VM uses **Node's built-in `WebAssembly` engine** to run the bytecode with a JS Hook API shim — no WASM toolchain or native deps.\n- **Real data, regenerable.** `data/` is built from a live Xahau node's `server_definitions` and the canonical Hook API list (`Xahau/hooks-rs` `c/extern.h`) via `npm run fetch:all`. The 78-function Hook API catalog carries per-function hazard metadata that drives the analyzer.\n- **HookOn** semantics are verified against the [Xahau docs](http://xahau.network/docs/hooks/concepts/hookon-field/): 256-bit, bit *n* = tx type *n*, **inverted/active-low** (set = does *not* fire), with bit 22 (SetHook) **active-high**.\n\n## License\n\nMIT © 2026 Dane Brown. Not affiliated with XRPL Labs or the Xahau project. Analyzer findings are heuristic guidance, not a security guarantee — always test on testnet and review hooks independently before mainnet use.\n",
  "bytes": 28893,
  "sha": "76c2956cccc0991c021c3779ae485ee8b8e57c1abeb684c55c84841f8a918324",
  "repo_slug": "hugegreencandle/xahau-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hugegreencandle_xahau_mcp_ef387fa8/readme"
}