xahau-mcp

# xahau-mcp

A [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.

> 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.

![xahau-mcp v2.0 flight simulator demo](demo/xahau-mcp-v2-flight-simulator.gif)

## The trifecta — safe Hooks, end to end

Three open-source tools, one workflow: **write → simulate one tx → prove all inputs.**
xahau-mcp is the **simulate** stage.

| stage | tool | what it does |
|---|---|---|
| **write** | [xahc](https://github.com/Hugegreencandle/xahc) | author + compile a safe Hook to clean, lint-passed WASM |
| **simulate one** | [xahau-mcp](https://github.com/Hugegreencandle/xahau-mcp) | run the real bytecode against one live transaction |
| **prove all** | [xahc-prover](https://github.com/Hugegreencandle/xahc-prover) | prove an invariant holds for every input in scope — or return the counterexample |

## Why it's useful

Point any MCP-capable agent (Claude, etc.) at this server and it can:

- **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.

- **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. No `xahaud` node needed.
- **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.
- **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.
- **Read Xahau ledger state** — accounts, installed hooks, hook definitions, hook state, transactions (with `HookExecutions` metadata), ledgers.
- **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).
- **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.
- **Explain a failed transaction** — `diagnose_failed_tx` turns an engine result + hook return strings into a plain-English cause and a concrete fix.
- **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.
- **Build unsigned transactions** (SetHook, ClaimReward, Payment) with an automatic security preflight — returned **unsigned**, to be signed offline.

## Why this is the most advanced blockchain MCP we know of

Strong claim, so here is the checkable evidence (2026-06-11). To our knowledge no MCP for ANY
chain — Ethereum, Solana, Bitcoin, XRPL or otherwise — combines even two of these; the closest
comparators are cloud-simulation MCPs (e.g. Tenderly's, which simulates on their hosted
infrastructure) and standalone analyzers (e.g. Slither, which is EVM-only and not an MCP):

1. **Executes real on-chain contract bytecode in a LOCAL VM** — `execute_hook` runs the actual
   CreateCode WASM with no node, no cloud, no account. Not an ABI wrapper, not a hosted simulator.
2. **Publishes a measured, regression-locked fidelity score against chain ground truth** —
   `vm_fidelity_report` replays 30 real mainnet hook executions: **30/30 agree (100%), 0 degraded**,
   including the foreign-state-reading hook that dominates live traffic. Those 30 are all
   **accept-direction** (live Xahau traffic is heartbeat-dominated), and the metric says so itself —
   it reports the accept/rollback composition and warns that an accept-only corpus can't distinguish
   the VM from an always-accept stub. The **rollback** direction is exercised on real genesis bytecode
   (governance `Invoke` → rollback) in [`tests/regression.test.ts`](tests/regression.test.ts).
   The corpus, the method and the honest history (25% → 0% → 100%) are in
   [docs/FIDELITY.md](docs/FIDELITY.md). We know of no other blockchain MCP that even attempts this.
3. **In-protocol static security analysis** — a Hooks-specific rule engine (SARIF-lite findings),
   calibrated against the network's own genesis hooks.
4. **In-protocol differential fuzzing** — `fuzz_hook` maps a contract's accept/reject decision
   boundary in the local VM.
5. **Post-mortems real transactions with real bytecode** — `hook_execution_postmortem` replays what
   actually fired on chain and compares.
6. **Reproduces on-chain economics exactly** — `reward_status` re-implements the genesis reward
   hook's formula and reproduces a real emitted payout **to the drop** (verified, test-locked).
7. **Decodes live governance end-to-end** — `governance_state` shows every seat, vote, tally and
   threshold of the Governance Game, live.
8. **Operational doctors** for the ecosystem's real pain: failed-tx diagnosis with cause+fix,
   Evernode host health, claim-overdue detection.

Every claim above is reproducible from this repo: the corpus is committed, the tests assert the
numbers, and the canonical sources (xahaud genesis hooks, evernode-js-client) are cited in code.

## Safety posture

- **Read-only** toward the network. There is no `submit` and no `sign` anywhere in this server.
- **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**.
- **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`.

- **Resources & prompts.** Be