v2.0.1 — Hardening & honesty

v2.0.1 — Hardening & honesty

A correctness/security patch on top of v2.0.0, from a full audit of the codebase. No new tools (still 61), no API surface changes beyond one small input rename (below). Tests 249 → 261; CI green; smoke verified against live mainnet. If you run simulate_transaction / what_if / audit_account_hooks against hooks pulled from the chain, this is worth upgrading to.

Untrusted-bytecode hardening

The local Hook VM and WASM parser execute hook bytecode fetched straight from Xahau, so the parse and pre-execution path is a trust boundary. v2.0.1 closes four DoS vectors there:

• Parser: import/export/function/local vector counts are bounded against the bytes that follow — a malformed length can no longer drive a huge allocation before any real data is read.
• Loop guarding: the VM now refuses a module unless every loop is guarded (more loops than _g call-sites → refused), and refuses when the opcode scan couldn't verify the loops. The VM has no fuel metering, so an unguarded loop must never reach execution.
• Size/memory caps: modules over 128 KiB of bytecode, or declaring more than 512 memory pages, are refused before instantiation.

Truthful simulation

• Partial transactions are flagged, not silently wrong. A tx field the byte-walker can't size (e.g. PathSet) used to drop the entire otxn reconstruction while the run was still scored as faithful. It now keeps every field before the unparseable one (Account/Amount/Destination) and marks the run degraded with an explicit caveat — no more confident verdict on a hook that actually saw DOESNT_EXIST.
• what_if is pinned to history. Account hooks, hook definitions and account info are now read at the historical (pre-execution) ledger, not today's — a replay no longer runs yesterday's transaction against today's hooks and parameters.
• evernode_host_diagnostics won't lie on a node hiccup. A failed governor read (node down / rate-limited) is now distinguished from a genuinely absent registration entry: it raises an actionable error instead of falsely reporting a healthy host as "not a registered Evernode host."
• Error results are marked isError so MCP clients and agents don't treat an error payload as data.

Honest fidelity metric

The committed fidelity corpus is 30/30 accept-direction (live Xahau traffic is heartbeat-dominated), which means an unconditional-accept VM would also score 100% on it. The metric now says so itself: vm_fidelity_report returns the accept/rollback composition and a coverage warning, and the headline carries the note whenever the scored set is single-direction. The rollback direction is exercised on real mainnet genesis bytecode (governance Invoke → rollback) in tests/regression.test.ts. The number is unchanged and real — it's now un-spinnable.

Docs & ergonomics

• build_payment_unsigned: input param amountXahDrops → amountDrops (+ describes the unit) so an agent can't fat-finger a 1,000,000× payment. This is the one breaking change — update any caller using the old key.
• prepare_transaction now states its testnet default; XAHAU_TEST_RPC_URLS is documented (server.json + README); README test count and a duplicated tool row corrected; Dockerfile runs as non-root.

Upgrade

npm install -g github:Hugegreencandle/xahau-mcp (or reinstall the MCPB bundle below). No config changes required apart from the amountDrops rename if you call build_payment_unsigned directly.

Full diff: v2.0.0...v2.0.1

v2.0.0 — The Flight Simulator: see a transaction's future before you sign it

simulate_transaction — the pre-sign flight simulator

Paste an unsigned transaction. Every hook it would trigger runs as real bytecode against real ledger state in the local VM — the one measured at 100% agreement on 30/30 real mainnet executions.

PREFLIGHT: WOULD FAIL — TSH:Issuer (strong) hook 610F33B8… on rHb9CJ…
rolls back ("You must wait 2475980 seconds") → tecHOOK_REJECTED
(fee would still burn)

That's a real live-mainnet run: an ineligible reward claim caught before the fee burned.

• Execution order canonical from xahaud Transactor.cpp/applyHook.cpp: originator chain (strong) → strong stakeholders (can reject) → weak stakeholders (labeled collect-only)
• Per-hook verdicts + return strings, simulated state writes, decoded emitted transactions, labeled STATIC engine preflights (sequence/balance/destination-tag/expiry), scam score
• Iterative live state resolution: the simulator fetches exactly the foreign-state entries, own-state keys and ledger objects each hook asks for

what_if — the time machine

Fetch a real historical transaction, apply your overrides, re-simulate at its original ledger.

Test-locked proof: replaying the real reward claim 2A096461… emits a decodable GenesisMint of exactly 72,251,963 drops to the real claimer — the on-chain emission reproduced by bytecode execution, to the drop.

Foundation fixes (surfaced by building this, all regression-tested)

• Codec speaks full Xahau now — Xahau-only tx types (ClaimReward, Invoke, Import, URIToken*, Remit) previously failed to encode (silently weakening the fidelity path; two tests passed because of the bug — fixed and tightened)
• VM slot() int64-return semantics (how hooks read numeric subfields)
• etxn_details now writes a structurally valid (disclosed-synthetic) EmitDetails — emitted blobs decode
• Confirmed-absent semantics for slotted ledger objects (faithful DOESNT_EXIST, not degraded)

To our knowledge: no MCP for any blockchain — and no free local tool for any chain — does pre-sign hook-level simulation with measured fidelity. Cloud simulators exist for EVM; this runs on your machine, free, keyless.

61 tools · 249 tests · read-only · no key custody

v1.9.0 — governance_state: the Governance Game, fully decoded live

Watch Xahau governance live — seats, votes, tallies, thresholds

governance_state now decodes the entire Genesis Governance Game hook state (layout canonical from xahaud hook/genesis/govern.c):

• All 20 seats and their occupying members
• Every open vote — topic (seat / hook position / reward rate / reward delay), voter, voted-for value ((vacate) votes decoded)
• Every tally with its threshold — membership topics 80% of filled seats, everything else 100% — and whether it's REACHED (i.e. a governance change is about to action)
• Live reward rate / delay (XFL-decoded)

Live-verified on mainnet: 8/20 seats decoded, an active 7/7 seat-vacate vote correctly shown as threshold-reached, 0 unparsed entries. The real captured namespace is the committed test fixture. No explorer surfaces this today.

59 tools · 244 tests · read-only · no key custody

v1.8.0 — diagnose_failed_tx: plain-English failure diagnosis

"Why did my transaction fail?" — answered from on-chain facts

One read-only call turns a tx hash into a cause and a concrete fix:

• ~30-code cause/fix catalog for common Xahau failures (tecNO_DST, tecDST_TAG_NEEDED, tecINSUFFICIENT_RESERVE, tefMAX_LEDGER, terQUEUED, …) with the fee-burned / not-applied semantics of each result class spelled out
• Hook rollbacks interpreted: return strings decoded from meta.HookExecutions; the genesis reward hook's "You must wait N seconds" becomes a claimable-at date (+ pointer to reward_status); known hooks labeled (genesis reward / Evernode heartbeat / registry)
• The partial-payment trap: tesSUCCESS Payments that delivered less than Amount are flagged — credit delivered_amount, never Amount
• Not-found triage: expired LastLedgerSequence / never submitted / wrong network (21337 vs 21338)
• Authoritative by design — decodes what the chain recorded, re-executes nothing (hook_execution_postmortem is the replay tool)

Live-verified on a real failed mainnet URITokenBuy (tecINSUFFICIENT_RESERVE).

59 tools · 236 tests · read-only · no key custody

v1.7.0 — foreign-state reconstruction: VM fidelity 0% → 100% on live Xahau traffic

The local Hook VM now reproduces live Xahau's dominant traffic

Measured: 30/30 real mainnet HookExecutions agree with the chain — 100%, 0 degraded (regression-locked). The Evernode heartbeat hook — ~29 of every 30 live hook executions on Xahau — went from an honest 0% to 100%.

What made it possible

• state_foreign / state_foreign_set in the VM, with honest semantics: a supplied entry is real pre-execution data, null means confirmed absent on chain, anything else degrades the run until resolved
• Iterative pre-resolve: run the real bytecode, fetch exactly the foreign-state entries / keylet objects it asks for at the pre-execution ledger, re-run — the heartbeat hook's dependent-read chain is 6+ reads deep
• Installed hook-parameter capture (Hook object → HookDefinition defaults) — Evernode hooks read their governor address from these
• slot_float / float_sto (STAmount ⇄ XFL), real otxn_id, disclosed-synthetic etxn_details
• Found + fixed a real bug: 32-byte state-key padding — short keys (like the genesis reward hook's 2-byte RR) silently missed on-ledger-padded state and survived on compiled defaults

Honesty intact

Direction (accept/rollback) is what's compared; HookReturnCode is not asserted. etxn_details is a disclosed synthetic placeholder; HookGrant on state_foreign_set is not modeled; the corpus is Evernode-dominated because live traffic is — per-hook breakdown always reported. Full history (25% → 0% → 100%, including the memory-export bug) in docs/FIDELITY.md.

execute_hook resolveKeylets:true now live-resolves foreign state too.

58 tools · 226 tests · read-only · no key custody

v1.6.0 — evernode_host_diagnostics: one-call Evernode host health check

evernode_host_diagnostics — the official host troubleshooting checklist, automated

One read-only call for Xahau's largest operator group:

• Registration — host entry on the Evernode governor namespace, fully decoded (country, version, registration ledger, transfer-pending flag)
• Heartbeat liveness — the actual on-chain active rule (lastHeartbeat >= current-moment-start − heartbeatFreq × momentSize), with moments-missed count and a pointer to evernode status when failing
• Instance load + lease price (XFL-decoded EVR/moment)
• Reputation — on-chain byte + reputed-on-heartbeat flag (thresholds labeled as heuristics)
• EVR trustline + balance — issuer read live from governor config
• Registration URIToken held + lease-offer counts
• Machine specs + accumulated EVR reward (token-id state)

Layout verified against the canonical EvernodeXRPL/evernode-js-client and a live mainnet host (real 143-byte state fixture committed in tests). Targeted ledger_entry hook_state reads — no namespace dumps.

58 tools · 216 tests · read-only · no key custody

v1.5.0 — reward_status: Balance Adjustment doctor (exact reward.c formula, verified to the drop)

reward_status — answers Xahau's most common retail question in one call

Is this account opted in to network rewards? How much XAH is accrued? When can it claim? Is the claim overdue?

• Exact, not approximate: re-implements the genesis reward hook's math (canonical Xahau/xahaud hook/genesis/reward.c) with the same XFL routines as this server's local VM, over live values — the account's RewardLgrFirst/Last/Accumulator/Time fields plus the live RR/RD XFL parameters read from genesis hook state.
• Ground-truth verified: reproduces a real mainnet ClaimReward's emitted GenesisMint payout to the drop (72,243,333 + 8,630 fee refund = 72,251,963 drops) — locked in as a regression test.
• Overdue-claim insight: the hook pays the per-claim rate once regardless of wait, so each missed ~30.09-day period is forfeited yield — flagged with a count (this is why auto-claim xApps exist).
• Returns an unsigned opt-in or claim ClaimReward when applicable (never signs — same no-key-custody posture).
• Unit correction: the reward delay is 2,600,000 seconds (~30.09 days), not ledgers; data/governance.json now carries rewardDelaySeconds and documents the legacy misnaming. compute_reward is marked legacy.

57 tools · 205 tests · read-only · no key custody

v1.4.0 — Evernode leases, account explainer, emit inspector, VM budget

🌐 explain_account

One call → a plain-English account snapshot: balance, key-safety read, installed Hooks (+what they fire on), trustlines, URITokens (Evernode leases auto-decoded), recent activity — with warnings and notes.

📜 decode_lease_uri

Decode Evernode lease URITokens (evrlease/LTV): lease index, EVR amount (XFL-decoded), ToS hash, mint identifier, outbound IP. Verified against the canonical evernode-js-client encoder + real mainnet leases.

📤 inspect_emitted_tx

Decode what a hook's emit() actually built — tx JSON + plain-English "what it tries to send" + danger score.

⏱️ VM execution budget

Guarded-but-pathological loops are now bounded (1M cumulative guard calls / 2s wall clock, honestly labeled as a local VM cap). Unguarded loops were already refused — the VM can no longer be hung.

56 tools · 192 tests · read-only · no keys · MIT.

npm install -g github:Hugegreencandle/xahau-mcp

v1.3.0 — trace decoding, on-chain post-mortems, scam check

Three new tools, ideated and adversarially verified by a multi-agent panel:

🔍 annotate_hook_trace

Decode the cryptic hex in an execute_hook trace into human-readable values — canonical XFL floats (marked definite), int64/native drops in both endians (WASM memory is little-endian; labeled, never guessed), UInt32 + Ripple-epoch dates, account-ids → r-addresses (marked possible), hashes. Raw hex always preserved. Fully offline.

🩺 hook_execution_postmortem

Point it at a real on-chain transaction: it fetches the tx + its HookExecutions metadata, runs each fired hook's real bytecode through the local VM, and compares the VM's decision to what the chain recorded. On-chain stays authoritative; agree is null (never false-blame) when the VM can't fully reconstruct context. Serial, capped RPC. Verified live on a real mainnet ClaimReward.

🛡️ scam_check

Offline danger scorer for any sign request → 0–100 + SAFE / CAUTION / DANGER + per-rule findings (AccountDelete-to-other, regular-key/signer changes, SetHook installs code, very large payments, no-expiry replay risk…). Honest about being shape-based — pair with decode_sign_request.

53 tools · 177 tests · read-only · no keys · MIT.

Install (no npm account needed)

npm install -g github:Hugegreencandle/xahau-mcp

New here? Start with the plain-English tutorial.

v1.0.0 — first major release

xahau-mcp v1.0.0 — the first MCP for Xahau & Hooks, now feature-complete.

49 tools · 115 tests · read-only · no key custody · MIT.

New since 0.9

• scaffold_hook — generate a starter Hook in C for an intent (firewall, payment-limit, state-counter, …), then verify with analyze/execute.
• decode_xpop — decode an Import/Burn2Mint XPOP (source ledger, inner burn tx, burned drops, UNL validators). Verified against xahaud's canonical source.
• VM fidelity harness (vm_fidelity_report) + a real on-chain corpus + docs/FIDELITY.md — honestly measures the local VM against on-chain HookExecutions (and documents exactly where/why it diverges).
• Developer utilities: validate_address, xaddress, currency_code, ripple_time, decode_amount, decode_sign_request, prepare_transaction, get_fee/get_account_lines/get_account_offers/get_account_uritokens.

Install

```bash
npm install -g github:Hugegreencandle/xahau-mcp
```