Supra Documentation Audit
The docs cover a broad surface — L1, MoveVM, EVM/MultiVM, Oracles, dVRF, Automation, SupraNova bridge, AI Agents — but the published llms.txt index advertises pages that 404, the SupraNova section contradicts itself on supported assets and network maturity, and key integration tracks (third-party EVM dVRF, HyperLoop, the bridge contract interface) ship without addresses, ABIs, or runnable code.
1. llms.txt advertises pages that 404 (critical)
Location: https://docs.supra.com/llms.txt — top of the file ("Layer 1 Blockchain" and "MoveVM Development" sections)
Problem: The published machine-readable index lists https://docs.supra.com/overview, https://docs.supra.com/useful-links, and https://docs.supra.com/network/move/overview as canonical pages. All three return HTTP 404. /overview is the very first entry under "Layer 1 Blockchain"; /network/move/overview is the first entry under "MoveVM Development".
Consequence: llms.txt is the file AI coding agents (Claude Code, Cursor, Copilot) load first to enumerate the documentation surface. Agents following Supra's own sitemap dead-end on the introductory page of the L1 section and on the entry page for MoveVM development — the two most important starting points. Humans clicking those links from search results get a 404.
The fix: Either restore the pages at those URLs or remove the dead entries from llms.txt. Add a CI check that fetches every URL in llms.txt and fails the build on any non-200 response.
2. SupraNova supported-asset list contradicts itself across three pages (critical)
Location: /supranova (overview), /supranova/token-bridging-model-lock-mint, /supranova/fee-structure
Problem: Three pages give three different supported-token lists for the same bridge:
- /supranova: "initial release bridges native ETH, wETH, and USDC"
- /supranova/token-bridging-model-lock-mint: only ETH→supETH and USDC→supUSDC (no wETH)
- /supranova/fee-structure: "ETH, USDC/USDT, SolvBTC, and WBTC" with concrete caps (23 ETH global / 4.5 ETH per tx; $100K global / $20K per tx)
USDT, SolvBTC, and WBTC appear nowhere else. wETH appears only on the overview.
Consequence: An integrator cannot answer the basic question "which assets can I bridge today?" by reading the docs. Worse, the lock-mint page calls the current release "the current testnet release" while the fee-structure page calls these "Mainnet tokens" with hard caps — so the docs disagree on whether SupraNova is on testnet or mainnet. Agents trying to generate bridge integration code will pick the first list they find and hallucinate support for assets that may not exist.
The fix: Designate one canonical "Supported Assets and Networks" page, list mainnet vs. testnet status per asset with the cap values, and reduce every other reference to a link. Run a docs lint that flags any new bridge-asset list outside that page.
3. EVM network info contradicts the L1 network info pages (critical)
Location: /network-information, /network/move/network-information, /network/evm/network-information
Problem: The two top-level network-info pages both say Supra EVM RPC, Chain ID, and Faucet are "Coming soon… / TBA". But /network/evm/network-information ships functional MultiVM Testnet endpoints: direct RPC https://rpc-multivm.supra.com/rpc/v1/eth and wallet integration https://rpc-multivm.supra.com/rpc/v1/eth/wallet_integration. /network/evm/getting-started tells developers to "consult the Supra Network Information page" for RPC details — that page still says "Coming soon".
Consequence: Developers following the EVM getting-started flow are routed to a page that tells them the network doesn't exist yet, when it does. Chain ID is still "TBA" on two of three pages and is never stated inline anywhere — Hardhat/Foundry/MetaMask configuration requires a chain ID, and developers will have to guess or DM the team.
The fix: Update /network-information and /network/move/network-information to match /network/evm/network-information. Add the EVM chain ID, WebSocket URL, block explorer, faucet, and native currency to the EVM network-info page (currently all blank). Make the EVM getting-started page link directly to /network/evm/network-information instead of the stale parent.
4. Mainnet/testnet target node versions diverge with no migration guidance (significant)
Location: /network/node/node-upgrade-guide-mainnet, /network/node/node-upgrade-guide-testnet
Problem: Mainnet upgrade guide targets v9.1.10; testnet upgrade guide targets v9.0.12. Both pages share the same "Last Updated: April 21, 2026". The CLI Commands page separately notes that v9.0.12 deprecated key commands present in v6.3.0 and that "pages for these features had not yet been updated."
Consequence: Operators cannot tell whether mainnet is ahead of testnet (unusual for a Layer 1) or whether one of the version pins is stale. The split also means CLI documentation written against v9.0.12 may not match the v9.1.10 binary running on mainnet — operators following the docs may run commands that no longer exist.
The fix: State on each upgrade-guide hub which version each network is currently running and which version this guide upgrades it to. Backfill the CLI subpages (/cheat-sheet, /profiles, /accounts, /tools) for v9.x, and add a banner on the CLI hub when those pages diverge from the latest release.
5. Third-party EVM dVRF integration track ships no addresses, no interface, no Solidity (critical)
Location: /dvrf/build-third-party-evm-networks, /dvrf/build-supra-l1, /dvrf/learn-supra-dvrf
Problem: The two integration landing pages ("Build Third-Party EVM Networks" and "Build Supra L1") are functionally identical — same four-step subscription workflow, same prepaid-phone-plan analogy, no chain-specific content. Neither page lists supported chains, router/coordinator contract addresses, the callback interface signature (fulfillRandomness or equivalent), gas estimation guidance, or a sample consumer contract. The "Learn Supra dVRF" hub is essentially a stub with section titles only.
Consequence: A developer cannot integrate dVRF on either Supra L1 or a third-party EVM without leaving the docs entirely. Agents asked to "write a dVRF consumer contract on Supra" have nothing parseable to anchor on and will fabricate Chainlink-shaped boilerplate.
The fix: Publish a per-network table of dVRF router addresses (mainnet and testnet, every supported chain). Publish the consumer interface (Solidity for EVM tracks, Move module signature for L1) inline. Add at least one complete, copy-pasteable end-to-end example per track. Differentiate the L1 page from the EVM page with Move-specific code.
6. Bridge contract interface page has no addresses, no ABI, no event signatures (critical)
Location: /supranova/token-bridge-smart-contract-interface
Problem: The page lists five functions — sendNative(), sendTokens(address, uint256), calculateTokenBridgeFee(address, uint256), isRegistered(address), isChainIdRegistered(uint256) — with one-sentence descriptions. It claims sendNative "emits a bridge event" but does not give the event signature. There is no mainnet contract address, no testnet contract address, no ABI, no revert/error list, and no example call.
Consequence: A protocol that wants to programmatically bridge from a contract (the actual audience for "smart contract interface") cannot do so from this page. They have to reverse-engineer the deployed contract or contact the team — exactly what a smart-contract-interface page exists to prevent.
The fix: Publish the bridge contract addresses (mainnet + testnet), the Solidity interface verbatim, the full event signatures (indexed parameters spelled out), and at least one example Foundry/Hardhat call. Link the verified contract on the block explorer.
7. Automation CLI arg-type casing inconsistent between docs pages (significant)
Location: /automation/getting-started vs. /automation/using-type-args
Problem: /automation/getting-started shows --args address:<recipient> U64:<amount> (uppercase U64). /automation/using-type-args shows --args address:TARGET u64:600000000 u64:100000000 (lowercase u64). Both samples are presented as valid supra move automation register invocations. Neither page mentions that the other casing exists or which is canonical.
Consequence: Developers copy-paste one example, fail with an unrecognized type error, and have to bisect which casing the CLI actually accepts. Agents generating registration commands will pick whichever page they saw first and emit broken commands half the time.
The fix: Pick one casing, replace all occurrences, and add a one-line note that the CLI is case-sensitive (or, if not, document that explicitly).
8. supra_framework::supra_coin::SupraCoin is both required and forbidden depending on which page you're on (significant)
Location: /network/move/aptos-to-supra-cheatsheet vs. /automation/using-type-args
Problem: The Aptos→Supra cheatsheet tells developers to replace aptos_framework::aptos_coin::AptosCoin with supra_framework::supra_coin::SupraCoin in Move source. The Automation type-args page emphasizes the opposite as a "Critical Format Rule": ✅ 0x1::supra_coin::SupraCoin / ❌ supra_framework::supra_coin::SupraCoin. Neither page acknowledges the other or explains that one is for Move use statements and the other is for CLI --type-args.
Consequence: A developer who has just migrated a Move module using the cheatsheet will fail when registering automation tasks against it. The error message is unlikely to be helpful. Agents are particularly vulnerable here — they will mix the two conventions in the same generated file.
The fix: On the using-type-args page, add a callout: "This is the runtime CLI form. Inside Move source you still use use supra_framework::supra_coin::SupraCoin; — see the cheatsheet." Cross-link both directions.
9. Hyperloop / HyperLoop spelled three ways across the docs (minor)
Location: /network (landing), /supranova (landing), /supranova/hypernova-vs-hyperloop
Problem: The /network landing page writes "Hyperloop". The /supranova landing page writes "Hyperloop". The hypernova-vs-hyperloop page writes "HyperLoop" (capital L). Same product, three pages, two capitalizations.
Consequence: Search and grep miss results across the docs. Agents pattern-matching on the brand name will produce inconsistent output. Trademark/brand consistency suffers but the developer impact is small.
The fix: Pick one canonical capitalization, replace globally, add a lint rule.
10. HyperLoop is documented as a product with no integration page (significant)
Location: /supranova/hypernova-vs-hyperloop, /network
Problem: HyperLoop is presented in the protocol-comparison table as a deployable bridge for L2s/high-throughput chains with "multi-signature validator committee with game-theoretic security." But there is no /supranova/hyperloop page, no supported-chain list, no contract addresses, no integration steps, no fee model. Every other piece of the SupraNova section documents HyperNova exclusively.
Consequence: Developers reading the L1 landing page see HyperLoop advertised as one of two native bridging options, then discover the docs have no way to use it. It's unclear whether HyperLoop is shipped, in preview, or planned.
The fix: Either publish a HyperLoop integration page (status, supported chains, addresses, contract interface) or relabel HyperLoop as "planned" on the landing and comparison pages until it ships.
11. Oracle dependency rev pins are implausible/copy-pasted between testnet and mainnet (significant)
Location: /oracles/data-feeds/pull-oracle, /oracles/data-feeds/push-oracle
Problem: On the push-oracle page, both Sui testnet and Sui mainnet pin rev = "51c1875d86f20abe2a22e8d2ae7a3a2a2a56d5a1" — the exact same 40-character SHA. The pull-oracle page uses the same SHA for Aptos testnet, but its Sui mainnet entry uses rev = "master" (a moving branch ref, not pinned at all) and Sui testnet uses rev = "testnet". So the docs simultaneously recommend a pinned SHA, a master branch ref, and a testnet branch ref for what should be the same dependency strategy. Also, the pull-oracle EVM interface declares _bytesproof in V1 and _bytesProof in V2 — a casing inconsistency carried into the published interface.
Consequence: Production deployments end up tracking a moving master branch — a security and reproducibility hazard. Developers reading both pages will not be able to determine the correct pin. Agents will copy whichever they read first. The _bytesproof vs _bytesProof mismatch is a real Solidity gotcha for anyone implementing the interface.
The fix: Pin testnet and mainnet to different SHAs (or, if branch refs are intentional, document why and how upgrades are coordinated). Reconcile the parameter naming across V1 and V2 of ISupraOraclePull, or call out the inconsistency explicitly.
12. Data Feeds Index has overlapping pair-ID ranges and no per-chain availability (significant)
Location: /oracles/data-feeds/data-feeds-index
Problem: The catalog table gives Crypto IDs as 0–575 and Primary Rates IDs as 185–572 — overlapping ranges with no explanation of how a developer disambiguates pair 200 (Crypto vs. Primary Rates). The page also does not specify which chains publish which feeds — a developer integrating on EVM, Sui, or Aptos has no way to confirm a given pair is supported on their target chain. SUPRA_USDT (pair 500) is tagged "Under Supervision" rather than "Supra Premium" with no commentary.
Consequence: A developer integrating an oracle picks a pair ID, deploys, and discovers the feed isn't published on their chain — or worse, picks an ID in the overlap range and gets a different asset than expected. Agents have no way to infer chain coverage from this page.
The fix: Disambiguate the ID ranges (or document the rule that resolves the overlap). Add a per-pair "Available On" column listing Supra L1 / EVM / Sui / Aptos / etc. Publish the full list inline or as a downloadable CSV rather than ranges plus "500+" / "115+".
13. Indices page calls a meme-coin index "equal-weighted Move ecosystem assets" (minor)
Location: /oracles/indices
Problem: Both "Supra Move" and "Supra Meme" indices are described with the identical text "Equal-weighted assets in the Move ecosystem." A meme-coin index and a Move-ecosystem index are not the same basket.
Consequence: Anyone reading on-chain index addresses can't tell what each index actually tracks. Whichever description is wrong, integrators may price exposure against the wrong basket.
The fix: Replace the duplicated description with a real composition for the Supra Meme index (what coins, what eligibility rule).
14. Supra L1 has no published security audit while everything built on top is audited (significant)
Location: /audit-reports
Problem: The audit table lists Supra L1 with status "In-Progress". Every other product — dVRF, DORA oracles, PoEL, SupraNova, StarKey — has published audits. The L1 chain itself, which has a public mainnet running validator nodes, has no public audit artifact. Most other audits link to Google Drive (gated by share settings) rather than stable hosted PDFs, and the column headers are inconsistent — DORA/dVRF tables omit the auditor name, while PoEL/SupraNova tables include it.
Consequence: Protocols evaluating Supra for production deployment cannot retrieve an audit of the chain they're deploying onto. The Google Drive hosting model is fragile: a permissions change quietly breaks every audit link.
The fix: State the auditor and expected publication date for the L1 audit. Rehost all audit artifacts at stable URLs under docs.supra.com or supra.com. Normalize the table schema (auditor, scope, codebase, version, date, link) across every section.
15. OpenBlocks.ai is "tightly coupled at the core" but never introduced (significant)
Location: /ai-agents, /oracles/oracle-value-capture-ovc
Problem: The AI-Agents page asserts "tight coupling of OpenBlocks.ai at its core" of Supra's infrastructure. The OVC page describes OpenBlocks.ai as the execution-layer partner that manages "atomic bundling, and mempool-free delivery" for liquidation revenue. Neither page links to OpenBlocks.ai, explains the corporate relationship, names a contact, or specifies which responsibilities sit with which party. The OVC page describes the offering as live but never explains how a protocol opts in, what addresses to integrate against, or how revenue is split.
Consequence: A protocol considering OVC integration would be routing liquidation execution through an unidentified third party. The docs provide no security model, no addresses, no contract. For a feature whose pitch is "reclaim 5–15% liquidation fees", the integration story is missing entirely.
The fix: Publish a "Partners" or "Architecture" page that names OpenBlocks.ai, links to its docs, and spells out the trust and operational boundaries. On the OVC page, add concrete opt-in steps, integration addresses, and the fee-split contract terms.
16. SDK quickstarts have missing imports and unpinned versions (minor)
Location: /network/move/python-sdk, /network/move/typescript-sdk
Problem: The Python quickstart's "Submit Transaction" snippet uses Serializer.struct and Serializer but never shows the import line for Serializer. The TypeScript quickstart pins no SDK version (npm install supra-l1-sdk without @version). Neither quickstart shows error handling or a mainnet variant. The REST API page (/network/move/rest-api) is a stub that redirects to off-site Swagger UIs without any inline endpoint specs.
Consequence: An agent extracting either snippet to bootstrap a project will produce code that doesn't compile (Python) or that breaks the next time the SDK ships a major version (TypeScript). The REST API page is unreadable for agents — there are no inline endpoint paths, parameters, or schemas to index.
The fix: Add the missing Serializer import to the Python sample and run all quickstart snippets through a CI test that actually executes them. Pin a minimum SDK version in install commands. Inline at least a representative subset of REST endpoints on the REST API page rather than linking only to the hosted Swagger.
17. Node Operator FAQ answers are not present in the static HTML (minor)
Location: /network/node/node-operator-faq
Problem: Section headers (Onboarding & Setup, Staking & Rewards, Troubleshooting, General Information) and question titles render in the page, but the actual answers do not appear in the fetched HTML — they are loaded client-side by the Mintlify FAQ component.
Consequence: Node operators reading via offline mirrors, llms-full.txt indexers, or AI agents that fetch raw HTML get question titles with no answers. This is the only documentation for operator troubleshooting; if it's not in static HTML, it's not in any agent's context window.
The fix: Server-render the FAQ answers (or expose them in a static fragment) so they are present in the HTML response and indexable. At minimum, mirror the FAQ content into llms-full.txt.
18. "Token Bridging Model" claims current testnet release while "Fee Structure" lists mainnet caps (significant)
Location: /supranova/token-bridging-model-lock-mint vs. /supranova/fee-structure
Problem: The lock-mint page describes the current release as "One-way bridging only in the current testnet release." The fee-structure page describes "Mainnet tokens" with hard global and per-tx caps (23 ETH global / 4.5 ETH per tx; $100K global / $20K per tx). Both pages are presented as describing the live system.
Consequence: Users cannot tell whether bridging real value is currently possible. A user reading the fee page and bridging 4 ETH may believe they are on mainnet; a user reading the lock-mint page may believe the bridge is testnet-only and not yet handling real funds.
The fix: Mark each section explicitly with the current network (mainnet, testnet, or both with separate caps). Have a single "Status" callout that propagates to every SupraNova page from one source of truth.
19. Automation glossary distinguishes "Automated Transaction Payload" and "Payload Transaction" but the rest of the docs uses them interchangeably (minor)
Location: /automation/glossary vs. /automation/faqs, /automation/getting-started
Problem: The glossary defines "Automated Transaction Payload" (the encoded data submitted during registration) and "Payload Transaction" (the packaged Move function call that runs at trigger time) as two distinct terms. The FAQ uses "payload transaction during registration" — which by the glossary's distinction should be "Automated Transaction Payload" — without flagging the conflation.
Consequence: Developers reading the glossary will assume the two terms have distinct meanings and waste time looking for the distinction in code; agents will treat them as synonyms and miss the intended difference.
The fix: Either collapse the two into one term or audit every page in the Automation section so the two are used consistently with the glossary definitions.
What they do well
- Strong conceptual writing for Automation (overview, FAQ, glossary all cohere) and for Moonshot consensus theory.
- The Aptos→Supra and Ethereum→Move cheatsheets are genuinely useful migration references with concrete module-path mappings.
- Publishing an
llms.txtat all — most chains don't.
Top 3 recommendations
- Fix the
llms.txt404s and make it CI-enforced. The first page agents load for L1 and for MoveVM is broken; nothing else matters until this is fixed. - Pick one canonical SupraNova source-of-truth for supported assets and network maturity. Three pages with three different asset lists and a testnet-vs-mainnet contradiction is the most consequential developer-facing problem in the docs.
- Publish concrete integration artifacts for dVRF (both tracks) and the bridge contract interface — contract addresses, ABIs, event signatures, one runnable consumer per track. Right now those pages tell developers why to integrate but not how.