Monad

Monad Documentation Audit

The docs cover real depth on architecture, consensus, and execution semantics, but the operational tables a developer reaches for first — chain ID, RPC URLs, explorers, canonical contract addresses, staking precompile address — render with empty value columns, and the OpenAPI spec wired into llms.txt is the Mintlify "Plant Store" sample.

1. Network Information page renders empty values for every critical field (critical)

Location: https://docs.monad.xyz/developer-essentials/network-information

Problem: The "Mainnet" reference table ships with the value column blank for Network Name, Chain ID, Currency Symbol, RPC URL, MonadVision, Monadscan, Socialscan, and Network Visualization. The Public RPC Endpoints table immediately below also has every RPC URL cell empty across all five providers (QuickNode, Alchemy, Goldsky Edge, Ankr, MF) — only the rate limits and notes columns render. The "best practices" page elsewhere confirms the chain ID is 143, but this page — the canonical "where do I point my wallet/SDK" page — exposes none of it.

Consequence: Every developer arriving from a search engine, an SDK README, or "Add Monad to wallet" is presented with a table whose values are blank. They cannot configure a wallet, an ethers/viem client, a hardhat/foundry config, or an RPC connection without leaving the docs and guessing from third-party sources. An AI agent fetching this page extracts a table of label/empty-string pairs and silently produces broken config files.

The fix: Restore the inline values for chain ID (143), currency symbol (MON), network name, the five RPC URLs (which clearly exist — the rate-limit columns are populated), and the three block explorer URLs. Audit the Mintlify component or data source that's feeding these cells; this is one rendering bug producing all the visible damage.

2. llms-full.txt reproduces the same empty cells, poisoning agent ingestion (critical)

Location: https://docs.monad.xyz/llms-full.txt

Problem: The official agent-oriented bundle reproduces the broken tables verbatim. The Mainnet network table appears as Network Name⏎⏎Chain ID⏎⏎Currency Symbol⏎⏎RPC URL[see below]⏎⏎Block Explorer (MonadVision)⏎⏎... with no value column. The canonical contracts table on the testnet side similarly emits Wrapped MON⏎⏎[Create2Deployer]…⏎⏎[CreateX]…⏎⏎ with the address column blank. So the bundle Monad explicitly published for agents to consume contains rows of labels with no associated values.

Consequence: Agents fetching llms-full.txt (which the docs nav explicitly tells them to do — see the "Documentation Index" callout on every Mintlify page) ingest tables they can parse structurally but that carry no data. A Claude/Cursor/Copilot session reading this file to bootstrap a Monad project sees "Chain ID" as a heading with nothing under it and either invents a value or asks the user. The very file built to make agents accurate at Monad makes them confidently wrong.

The fix: The same upstream rendering fix that repairs the HTML tables should regenerate llms-full.txt. Also add a CI smoke test that fails the build if any row in the published llms-full.txt has an empty value column (label\n\n patterns following known-required keys like Chain ID).

3. The OpenAPI spec linked from the docs is the Mintlify "Plant Store" sample (critical)

Location: https://docs.monad.xyz/api-reference/openapi.json

Problem: The OpenAPI 3.1.0 file served at this path is the boilerplate Mintlify example: it describes "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification," with endpoints GET /plants, POST /plants, DELETE /plants/{id} and a POST /plant/webhook. It is MIT-licensed and points at a sandbox server. Nothing in it relates to Monad.

Consequence: Any agent or tool that auto-discovers an OpenAPI spec from a Mintlify docs site — there are several, including SDK generators, MCP API tools, and Cursor's docs indexer — will conclude that Monad's API surface is a plant store with bearer-token auth. This silently corrupts code completion, integration scaffolds, and agent reasoning about Monad's actual JSON-RPC surface (which lives under /reference/json-rpc/).

The fix: Either remove openapi.json and the /api-reference/ route, or replace the file with a real spec describing Monad's JSON-RPC surface (Monad-specific methods plus the Ethereum-standard ones). Don't ship the Mintlify template into production.

4. Mainnet "Add to wallet" guide ends mid-sentence with no values (critical)

Location: https://docs.monad.xyz/guides/add-monad-to-wallet/mainnet

Problem: The page tells users "To manually add Monad Mainnet to your wallet, navigate to your wallet's network settings and add a custom network with the following details:" followed by the heading Network Details: — and then nothing. The "automatically add" button has no surrounding description of where it lives, and the manual instructions trail off into a heading with no content.

Consequence: The single most beginner-facing page in the docs — the one a new user is directed to from app.monad.xyz, faucets, and community channels — has zero usable information for the manual flow. Users will paste random chain IDs from Reddit and ChainList rather than the canonical values.

The fix: Inline Chain ID, Network Name, Currency Symbol, RPC URL, and Block Explorer URL under "Network Details" as plain text (not as another broken table). This page should remain readable even when the network-information table component is broken.

5. Official Links page has zero populated URLs (critical)

Location: https://docs.monad.xyz/official-links

Problem: A page titled "Official Links" is the only canonical, curated index of every link a user would need — block explorers, website, X, blog, GitHub orgs, Discords, Telegrams, MIPs repo. Every cell in the "Where" column is empty across Mainnet Network, Announcements and Socials, Developer Community, Validator Community, and Tech sections.

Consequence: When users want to verify which X account or Discord is real (a serious phishing concern for an L1), they hit a page that lists labels but no links. They fall back to Google, which is exactly the trust-laundering attackers exploit.

The fix: Restore the links. Until the rendering issue is fixed, replace the table with plain-prose links — this page is specifically the anti-phishing reference, and it must remain functional independent of the broken data component.

6. Staking precompile address is missing from both staking pages (critical)

Location: https://docs.monad.xyz/reference/staking/overview and https://docs.monad.xyz/reference/staking/api

Problem: The overview page says "The staking precompile is at address ." — the address slot is literally blank in the sentence. The API reference's "Address" table lists Staking Precompile with an empty Address column. Other pages (precompiles, summary) state that the staking precompile is at 0x1000, but the dedicated staking reference itself does not.

Consequence: A developer building a staking integration starts at /reference/staking/api and finds function selectors but no to: address to call. They either guess from prose elsewhere or hardcode wrong. Agents reading the staking API page see function: addValidator(...), selector: 0xf145204c but no target address — and will happily emit transactions with no to field.

The fix: Inline 0x0000000000000000000000000000000000001000 (or whatever the actual canonical address is) in both the overview sentence and the API page's address table. Make it a static literal, not a table-driven cell that can blank out.

7. Testnet canonical contracts table has empty addresses for all 12 contracts (critical)

Location: https://docs.monad.xyz/developer-essentials/testnets

Problem: Under "Canonical Contracts" on the testnet page, all twelve canonical addresses are blank: Wrapped MON, CreateX, Foundry Deterministic Deployer, ERC-6492 UniversalSigValidator, EntryPoint v0.6/v0.7/v0.8, Multicall3, Permit2, SafeSingletonFactory, x402 ExactPermit2Proxy, x402 UptoPermit2Proxy. Chain ID, RPC URLs, faucet URL, and explorers on the same page are also empty.

Consequence: Foundry/Hardhat scripts that reference Permit2, Multicall3, or the CreateX deployer will be written against placeholders. The /guides/deploy-smart-contract/foundry guide explicitly tells developers to "add Monad Testnet configuration" to foundry.toml and points at this page for values that aren't there.

The fix: Same data-restoration fix as #1, but explicitly verify that every canonical contract row resolves to a 0x… address in the published HTML and in llms-full.txt.

8. eth_sendRawTransaction reference documents EIP-4844 even though Monad rejects type-3 transactions (significant)

Location: https://docs.monad.xyz/reference/json-rpc/api (the eth_sendRawTransaction entry) vs. https://docs.monad.xyz/developer-essentials/transactions

Problem: The JSON-RPC reference says: "Submits a raw transaction. For EIP-4844 transactions, the raw form must be the network form. This means it includes the blobs, KZG commitments, and KZG proofs." But /developer-essentials/transactions explicitly lists Type 3 ("EIP-4844") under "These types are not supported."

Consequence: A developer reading the RPC reference for eth_sendRawTransaction will reasonably believe blob transactions are supported and try to send one — only to learn from another page that they aren't. An agent generating Monad client code will produce EIP-4844 fallback paths that immediately error at the node.

The fix: Strip the EIP-4844 sentence from the eth_sendRawTransaction description, or replace it with an explicit "EIP-4844 (type 3) transactions are not supported on Monad — see Transactions." This is presumably inherited Ethereum copy and needs Monad-specific scrubbing across the whole RPC reference.

9. Changelog/version contradiction across the docs (significant)

Location: /developer-essentials/network-information, /developer-essentials/changelog/mainnet, and /llms.txt

Problem: Network Information states the current mainnet revision is v0.14.3 / MONAD_NINE. The mainnet changelog's most recent entry is v0.13.1 [2026-03-16] (a patch on v0.13.0), with no entries for v0.14.0/v0.14.1/v0.14.2/v0.14.3 at all. Meanwhile llms.txt lists upgrade-instructions pages all the way through v0.14.4 — one version higher than what Network Information reports as current.

Consequence: A node operator reading the changelog believes the network is on v0.13.1; the network-info page says v0.14.3 is live; the index says v0.14.4 instructions exist. They cannot determine which version they should be running, whether an upgrade is overdue, or whether the changelog they're reading is stale. Validators receiving CODE-ORANGE announcements that reference v0.14.x have no changelog narrative to reconcile against.

The fix: Backfill changelog entries for every released version through the current one (v0.14.3+), and add a CI check that fails the build if the version on the Network Information page is newer than the latest changelog entry. The fact that llms.txt references a v0.14.4 page that the mainnet changelog has never mentioned suggests publishing pipelines that aren't coordinated — they should be.

10. Dangling references to pages not in llms.txt (significant)

Location: /developer-essentials/differences, /developer-essentials/summary

Problem: The "Differences from Ethereum" page ends with a single-line RPC section: "See: RPC Differences." The summary page links to "RPC Differences," "RPC API," and "rpc-limits." None of these page slugs appear in llms.txt's index of the docs. The JSON-RPC overview page also references "rpc-limits" via "For rate limits, see here." with no working slug surfaced in the agent index.

Consequence: Agents that bootstrap by reading llms.txt (which Monad's pages explicitly instruct them to do) will fail to resolve these cross-references and either skip key RPC behavioral differences or fabricate answers. Human readers may get a 404 or land on the wrong page. The "RPC Differences" content is critical — it's the single canonical place to document deviations like the eth_maxPriorityFeePerGas hardcoded value and the eth_feeHistory baseFee duplication — and the docs link to it but don't index it.

The fix: Add the missing pages to llms.txt and llms-full.txt. If the pages exist but aren't published, publish them. If they don't exist, write them — the "RPC Differences" page is referenced from at least three other places and is treated as authoritative.

11. RPC overview omits the fourth block-tag commitment state it just introduced (significant)

Location: https://docs.monad.xyz/reference/json-rpc/overview

Problem: The page opens: "Monad blocks progress through four commitment states: Proposed, Voted, Finalized, and Verified." The table that follows documents three: latest → Proposed, safe → Voted, finalized → Finalized. There is no row for Verified, no JSON-RPC block tag mapping for it, and no explanation of what Verified means or how to query for it.

Consequence: Developers integrating with Monad's commitment model — particularly bridges and settlement systems that the page itself recommends use finalized — have no way to learn what the fourth state actually is or whether they should care about it. The page literally enumerates four states then explains three.

The fix: Add a row for Verified in the block-tag table (either with its tag mapping or noting that no Ethereum-compatible tag exposes it and how to query it via Monad-specific tags), and write a sentence explaining when a block transitions Finalized → Verified and why it matters.

12. Internal "Wallet developers" guidance about eth_maxPriorityFeePerGas contradicts the "Best practices" framing of the same RPC (significant)

Location: /developer-essentials/wallet-developers and the broader gas-pricing/best-practices guidance

Problem: The Wallet Developers page tells wallet teams: "eth_maxPriorityFeePerGas returns a hardcoded 2 gwei — not a live network recommendation." This is critical Monad-specific guidance. But it's only on the wallet-developers page; the general developer-facing gas-pricing page and best-practices page give EIP-1559 framing as if the method works normally. Dapp developers reading "Gas Pricing" never learn that the standard RPC their library calls under the hood returns a static 2 gwei.

Consequence: Dapps using viem/ethers defaults (which call eth_maxPriorityFeePerGas for tip suggestions) will quote a static 2 gwei tip with no warning. Under priority-gas-auction ordering (which the gas-pricing page does mention), this can cause dapps to consistently lose ordering races with no diagnostic surfaced anywhere a non-wallet-team developer reads.

The fix: Move the eth_maxPriorityFeePerGas + eth_feeHistory gotchas onto the "RPC Differences" page (which is referenced from several places — see #10) and cross-link from Gas Pricing and Best Practices. This is dapp-developer guidance buried in a wallet-developer document.

13. Contract code size figure contradicts itself between pages (minor)

Location: /developer-essentials/summary and /developer-essentials/differences

Problem: The summary page says "Max contract size 128 kb (up from 24.5 kb in Ethereum)." The differences page says "The maximum contract code size limit is 128 KB (up from 24 KB in Ethereum)." 24 KB vs 24.5 KB for the Ethereum baseline.

Consequence: Minor, but the differences page is the more technically careful one and is what tooling docs will quote. Ethereum's EIP-170 limit is 24,576 bytes (24 KiB), which is what's intended. One of the two pages is wrong on the Ethereum baseline.

The fix: Normalize to one figure across both pages — preferably "24 KB (EIP-170: 24,576 bytes)" — and use the same unit ("KB"/"KiB") consistently.

14. JSON-RPC Playground page ships in the nav but renders no functional content via fetch (minor)

Location: https://docs.monad.xyz/reference/json-rpc/playground

Problem: The page renders only the navigation chrome, the title "JSON-RPC Playground," the subtitle "Interactive JSON-RPC request builder for all Monad RPC methods" (twice), and the Mintlify "Documentation Index" callout. No interactive component is present in the server-rendered HTML.

Consequence: Agents and search engines crawling the docs see an empty page promising an interactive tool. Users with JS disabled or behind proxies see the same. The playground may work in-browser, but it has zero discoverable surface for any non-browser consumer — including the AI agents Monad's own llms.txt callout encourages to crawl the site.

The fix: Either server-render a static fallback (list of methods with curl-equivalents, linking to /reference/json-rpc/api), or noindex the page and remove it from llms.txt so agents don't waste tokens fetching a content-less stub.

What they do well

• The architecture documentation (MonadBFT, parallel execution, MonadDb, async execution) is genuinely strong — clear summaries with links to the underlying research papers, and Monad-specific guidance like the Reserve Balance / EIP-7702 interaction is precise and worked-example-driven.
• The opcode pricing and gas-charging deviations from Ethereum are documented as tables with concrete multipliers, not prose hand-waving — exactly the structured format AI agents and SDK authors need.
• The wallet-developers page contains genuinely useful Monad-specific operational nuance (no global mempool, gas-limit charging, hardcoded eth_maxPriorityFeePerGas) that few L1s document at all.

Top 3 recommendations

1. Fix the empty-table rendering bug. The Network Information, Testnets, Official Links, and staking pages all share the same failure mode: labels render, values don't. One upstream component or data source is breaking the most operationally important pages on the site. Add a CI check that fails the build if known-required values (Chain ID, RPC URL, contract addresses) are empty in published HTML or in llms-full.txt.
2. Replace the Mintlify Plant Store OpenAPI spec. Either delete /api-reference/openapi.json or replace it with a real spec for Monad's JSON-RPC surface. Shipping the template silently poisons every downstream agent and SDK tool that auto-discovers OpenAPI from a Mintlify site.
3. Reconcile versioning across changelog, Network Information, and llms.txt. The changelog stops at v0.13.1, Network Information says v0.14.3 is current, and the index lists v0.14.4 — node operators cannot tell what's true. Backfill the changelog and add a build-time invariant that the current-version on Network Information must match the most-recent changelog entry.