The Gnosis Chain docs cover a broad surface (build, bridge, node, tools, Shutter) but the content is riddled with contradictions about its own bridge multisig thresholds, stale "coming soon" sections for products that shipped years ago, dead internal links, an unfinished llms.txt, a security-audit page frozen since 2021, and content that still talks about the Merge in future tense in 2026.
1. Bridge governance threshold contradicts itself across three pages (critical)
Problem: The Beacon Chain upgradeability page states "a minimum of 7 signatures are required to enact any proposal." The Bridge Management page says "8 signatures are required to approve any management proposal" and "There are currently 15 Bridge Governors, of which 8-of-15 are required to pass a proposal." The Omnibridge and xDai bridge pages both list "Governance: 8-of-15 Multisig." Meanwhile the decisions log records a December 12, 2025 entry titled "Replace CoW brodge validator address" alongside a separate entry noting that a governor was removed and the threshold changed — implying the management page previously stated a different denominator and was silently updated when the set changed.
Consequence: A security researcher or integrator trying to verify the trust model of the bridge sees three different quorum numbers (7, 8-of-15, and a now-changed historical denominator) for what is functionally the same governance board. Auditors cannot cite the docs as a source of truth, and AI agents indexing the docs will silently reproduce whichever conflicting page they happened to chunk.
The fix: Pick one canonical "Bridge Governance" page, state the current threshold (8-of-15) with the multisig address, and have every other page (gbc/upgradeability, Omnibridge, xDai) link to it instead of restating the number. Record threshold changes in the decisions log with the old → new transition spelled out and dated.
2. Dead internal links throughout core navigation paths (critical)
Problem: All of the URLs above are linked from elsewhere in the docs but resolve to the Docusaurus homepage shell (the SPA router falls back to the index). The pattern is systematic: pages live under bridges/About%20Token%20Bridges/omnibridge (capitalized folder) while internal links point at bridges/Token%20Bridge/omnibridge (lowercase, different folder name). The homepage's own default FAQ tile points at /faq/Node FAQs/changingwc — a niche withdrawal-credential page, not a FAQ index.
Consequence: A developer following the docs flow for "how do I run a node" → troubleshooting hits a blank page that looks like the homepage, with no 404. AI agents crawling the site will index those URLs as valid and serve users dead-end links. The casing/folder mismatch is invisible because the site doesn't 404 — it silently swallows the broken link.
The fix: Add a real 404 page, audit every internal link, and either redirect the lowercase paths to the capitalized canonical paths or rename the folders. Change the homepage's FAQ chip to point at an actual FAQ index, not changingwc.
3. Security audit page lists nothing newer than October 2021 (critical)
Location:/about/specs/security-audit
Problem: The security audits page lists Stake Beacon Chain by ChainSecurity (October 1, 2021), OmniBridge v6.0 (September 7, 2021), and POSDAO (August 2019) as the most recent items. The intro still reads "Most Audits were completed prior to the rebrand from xDai Chain to Gnosis" and "the chain is in the process of transferring to GNO-only security" — a state of affairs that completed with the Merge in December 2022. Nothing post-Merge, post-Dencun, post-Pectra, nor any of the multisig/governance upgrades discussed elsewhere in the docs is documented here.
Consequence: A chain that asks integrators to trust a 4-of-7 validator multisig, an 8-of-15 governance board, and contract upgradeability has no public audit trail for any of those components for nearly five years. Security reviewers and exchange listing committees have to assume "no public audit since 2021" or go hunt down GitHub repos. AI agents quoting this page will tell users the most recent audit is four+ years old.
The fix: Add audits for Merge / post-Merge contracts, the Hashi integration (called out elsewhere in the docs as approved April 2024), the Pectra hard-fork changes, and any audits of the current bridge governance / validator contracts. If those audits don't exist, say so explicitly rather than letting the page imply nothing has changed since 2021.
4. llms.txt is broken, partial, and contains marketing junk and raw EVM bytecode (significant)
Problem: The llms.txt file is partially populated — it covers only ~17 files under about/specs/hard-forks/*, about/specs/gbc/upgradeability, about/specs/security-audit, and about/tokens/README, leaving the entire Build / Bridge / Node / Tools / Shutter / FAQ trees absent. It opens with a context-free marketing snippet ("4096 validators / 131,072 mGNO / 83% APY ... 50K+ validators / 1.6M+ mGNO / 23% APY"), it inlines huge raw EVM bytecode blobs (GIP-31 hard-fork token contract), and the file uses inline // File: markers instead of the standard llms.txt link list format. There is no /llms-full.txt at all — that URL returns the homepage HTML.
Consequence: Coding agents (Claude Code, Cursor, etc.) that rely on llms.txt for efficient indexing will get a small, noisy, and partly misleading slice of the docs. The marketing snippet conflates "4096 validators" with "50K+ validators" with no narrative, and the bytecode burns the agent's context window without informing it about RPCs, faucets, bridge contracts, or node setup.
The fix: Regenerate llms.txt to follow the standard format (linked sections covering Build, Bridge, Run a Node, Tools, Technical Guides, Shutter). Remove the inlined bytecode. Drop the orphan marketing snippet. Ship a real llms-full.txt that includes the full prose of the core docs.
5. Stale "coming soon" and future-tense content for things that shipped years ago (significant)
Problem: The Developer Overview still has a "Coming Soon: Building on Top of Gnosis Pay" section ("We will soon be opening our SDK..."), but Gnosis Pay launched in mid-2023. The Merge page still presents "How to Prepare / For Validators" with a status table that shows "Erigon TBA ⌛ Coming soon" and "Nimbus TBA ⌛ Coming soon" for an upgrade that completed December 8, 2022. The tokens overview says "Proof of Stake protection will be provided by GNO with the consensus-layer Gnosis Beacon Chain" — future tense, 3.5 years post-Merge. The site copyright reads 2026.
Consequence: A developer landing on /developers/Overview reasonably concludes the Gnosis Pay SDK is unreleased and waits for it. A node runner reading the Merge page thinks the upgrade hasn't happened yet and looks for "merge-ready" clients. AI agents quoting "coming soon" content will spread the misinformation downstream.
The fix: Archive the Merge "How to Prepare" section behind a clear "Historical" banner with the actual completion date. Remove the "Coming Soon" Gnosis Pay section or link to the actual live Gnosis Pay developer portal. Rewrite tokens overview to past tense ("GNO secures the Gnosis Beacon Chain since the December 2022 Merge").
6. BSC compatibility is marketed on the developer overview but deprecated in the bridge FAQ (significant)
Location:/developers/Overview vs /faq/bridges
Problem:/developers/Overview markets the chain as having "Smart Contract, DApp & toolset compatibility with other Ethereum-based chains like Ethereum, Ethereum Classic, BSC and others." The Bridges FAQ, by contrast, opens with: "Can I bridge tokens between Gnosis Chain and BSC using Omni Bridge — The BSC - Gnosis Chain bridge has been deprecated you can instead use a third party bridge like Jumper for example."
Consequence: A developer evaluating cross-chain feasibility reads the marketing bullet and assumes there is a first-party BSC bridge, then discovers (or doesn't, until production) that they need a third-party aggregator. This is the same class of contradiction as the multisig-threshold issue: two pages, two answers, no callout.
The fix: Drop BSC from the compatibility bullet in /developers/Overview, or rewrite it to clarify that BSC is supported only via third-party bridges and link to the bridge FAQ entry.
7. Documented validator setup points at a single person's personal GitHub fork (significant)
Location:/bridges/management/validators
Problem: The "Setting up bridge validators with docker compose" resources link to https://github.com/dharmendrakariya/chiado-ansible-bridges with the parenthetical disclaimer "(yes I know it says Chiado but we use it for mainnet)". The page also lists the "Current Bridge Validators" tables with the Organization Name column empty — only two anonymous addresses (0x725bC6F18F8CDd7f57A9aB9A9f2Ea17A199185e5, 0xb1562173109932146a7fBBF28d7c6652bc2DaACE) are shown for both ETH↔Gnosis and Sepolia↔Chiado. It says "transactions currently requires signatures from 4 of 7 validators" but never enumerates the 7 validators.
Consequence: Anyone wanting to verify or join the bridge validator set has no way to see who the validators are, the canonical setup instructions live on a personal fork that could be deleted or rewritten unilaterally, and the chiado-vs-mainnet caveat is the kind of thing that gets misread under deadline pressure. This is a load-bearing security claim ("4-of-7 validator multisig") that the docs can't substantiate.
The fix: Move the Ansible/docker-compose setup into a gnosischain/ org repo. Fill in the organization name column for all bridge validators. Disclose the seven AMB validators and the seven xDai validators with their public identities, matching the format used for Bridge Governors.
8. Unfinished placeholders in the governance decisions log (significant)
Location:/bridges/management/decisions
Problem: Recent decision entries (Apr 10, 2026; Dec 12, 2025; Nov 26, 2025; Nov 7, 2025; Nov 3, 2025) literally contain the strings "Tx on Ethereum: url Tx on Gnosis Chain: url" instead of actual transaction hashes. The entry title "Replace CoW brodge validator address" is misspelled, and the word "alidator" appears in the page. The "Freeze outflow of major tokens" entry crams a multi-row token/address table into one paragraph. One WBTC address (0x8e5bBbb09Ed1ebdE8674Cda39A0c169401db425) has only 39 hex characters after 0x rather than the required 40 — meaning either a typo or a truncated address copied into the docs.
Consequence: A user verifying bridge governance actions cannot see the on-chain proof — the URL is the literal word "url". The truncated/invalid address could send someone freezing or interacting with the wrong contract. This is the audit trail for a multi-million-dollar bridge multisig.
The fix: Add a lint step to the docs CI that flags url / TBD placeholders in decisions.md and that validates EVM addresses match ^0x[a-fA-F0-9]{40}$. Backfill the missing transaction links and fix the truncated address.
9. Hard-fork specs are unfinished, ambiguous, and stale (significant)
Problem: The general spec card still lists Patchset: Cancun even though /hard-forks/pectra is published. The hard-forks index is a single-paragraph stub with no list/index of forks (Merge, Dencun, Pectra, Shanghai-Capella, the archived block-number pages). The Pectra page footer says "Differences with Ethereum mainnet are shown in the table above" but the table only labels rows "Not modified" / "Constants modified" without listing the actual modified constants — e.g. EIP-7691 says "Constants modified" with no values. The Dencun page uses the ambiguous qualifier "Constants maybe modified from Ethereum" in its summary table; readers have to scroll past the table to a dedicated "Differences with Ethereum mainnet" section to find concrete values (e.g. MIN_BLOB_GASPRICE=1000000000, MAX_BLOB_GAS_PER_BLOCK=262144).
Consequence: A developer or client implementer cannot determine what Gnosis-specific constants Pectra changed without reading Gnosis client source — the pattern that works on Dencun is simply missing from Pectra. "Patchset: Cancun" tells a node operator the chain hasn't moved past Cancun, which is wrong. "Maybe modified" in a summary table forces a reader to scroll to confirm whether or not something actually changed.
The fix: Update the general spec card to Pectra. Promote Dencun's "Differences with Ethereum mainnet" concrete constants pattern onto the Pectra page — list MAX_BLOB_GAS_PER_BLOCK, TARGET_BLOB_GAS_PER_BLOCK, BLOB_GASPRICE_UPDATE_FRACTION, etc. Replace the "maybe modified" qualifier on Dencun's summary table with a direct in-row reference to the differences section. Make the hard-forks index a navigable list of every fork with dates.
10. RPC providers page mixes formats and embeds a hardcoded API key (significant)
Location:/tools/RPC Providers
Problem: The RPC Providers list is inconsistent: Gnosis core team and Ankr list both Mainnet and Chiado endpoints, Nodies DLB / POKT / BlockPI list one URL, and Quicknode / Chainstack / dRPC / Chainnodes give no URL at all — just a "Docs" link. The Nodies DLB endpoint includes what looks like a long-lived API key path segment hardcoded into the docs (/v1/406d8dcc043f4cb3959ed7d6673d311a).
Consequence: Developers cannot copy-paste an RPC URL for half the listed providers — they have to leave the docs to figure out the endpoint. Whether the embedded Nodies DLB key is per-user or a shared public endpoint, hardcoding it into the docs trains every reader to copy it verbatim into their app.
The fix: Require every listed provider to publish a canonical Mainnet URL + Chiado URL (or remove them). Replace the hardcoded Nodies DLB API key with a placeholder (https://gnosis.nodies.app/v1/<YOUR_API_KEY>) and link to the signup flow. Add an OpenRPC-style schema or at least a copyable code block per provider.
11. Quickstart sends developers down the wrong Chainlist path (significant)
Location:/developers/quickstart
Problem: Under "Add Chiado to your wallet," the instructions read: "1. Go to Chainlist 2. Search for Gnosis 3. Connect your wallet 4. Approve a new network." Searching Chainlist for "Gnosis" returns Gnosis (Mainnet, chain ID 100), not Chiado (chain ID 10200). The section header says Chiado but the steps add Mainnet. The page also references screenshots ("you'll see the result in your logs that looks as follows:") that are absent in the rendered output.
Consequence: A first-time builder following the quickstart will add Gnosis Mainnet (real money), then try to deploy with testnet xDAI from the Chiado faucet — and fail confusingly, or worse, attempt to deploy a contract to Mainnet thinking it's Chiado.
The fix: Tell users to search for "Chiado" specifically, and include the canonical Chiado parameters inline (Chain ID 10200, RPC URL, currency symbol, explorer) as a copy-paste fallback. Restore the missing screenshots or replace them with text.
Problem: The "Technical guides" landing page (linked from a homepage tile) is three paragraphs of welcome boilerplate with no links to any guides. /node/architecture ends with "Types of Nodes" listing four bullet headings (Light Nodes, Full Nodes, Full Nodes (w/o Validator), Archival Nodes) and no descriptions of any. /tools/ is six bullets and a "share request here" link with no link target. /tools/Faucets is six bullets with zero text on rate limits / drip amounts / eligibility. /bridges/ is two sentences and does not enumerate the three bridges (xDai, Omnibridge, AMB) that are central to the section. /about/communication collapses every channel into a single dense paragraph with no links rendered.
Consequence: Top-level navigation tiles on the homepage lead to dead-end pages. A developer who clicks "Technical guides" gets a welcome message and has to leave the docs to find actual integration guides. Faucet users can't tell how much they'll get or how often they can claim.
The fix: Either populate these pages or remove them from the navigation. At minimum, turn every stub into a curated link list pointing at the deeper sub-pages that already exist (architecture → list of EL/CL clients with descriptions, tools → blockchain explorers / faucets / oracles / RPC providers / etc.).
13. xDai bridge page is mid-migration: claims USDS is the default but body still describes DAI flow (significant)
Location:/bridges/About Token Bridges/xdai-bridge
Problem: The page leads with "DAI is replaced with USDS as the default accepted token on Ethereum, while xDAI will continue to be minted on Gnosis Chain." The body, however, continues to describe protocol mechanics in DAI terms and the contract list includes a USDSDepositContract alongside the original xDAI Bridge Contract without an end-to-end USDS user flow. The page also flags that "Some of the information from TokenBridge Docs are outdated, please verify the information before you bridge" and contains "Hashi acts as an additional bridge valdiator" (typo).
Consequence: A user bridging today cannot tell whether to deposit DAI or USDS on Ethereum, which contract address to call, or what gets minted on Gnosis. The "verify before you bridge" disclaimer is the docs admitting they can't guide you safely on a critical flow.
The fix: Rewrite the page top-to-bottom in USDS-first terms, with a one-paragraph "Legacy DAI flow" note pointing at the prior contracts. Show the canonical USDS deposit → xDAI mint sequence with addresses. Resolve the "outdated" disclaimer by either fixing the content it refers to or removing the link.
14. Broken admonition fragment on the page that states the contested security claim (minor)
Location:/about/specs/gbc/upgradeability
Problem: The page that states "a minimum of 7 signatures are required to enact any proposal" renders a stranded lowercase c on its own line immediately followed by a bare "Governance Board Members" line — clearly a broken Docusaurus :::caution (or similar) admonition that didn't compile.
Consequence: The single page anchoring one side of the multisig-threshold contradiction also visibly has broken Markdown. Anyone using this page to verify a trust claim immediately loses confidence in it, and the broken admonition may be hiding the very link/context that would resolve the contradiction.
The fix: Repair the admonition syntax (:::caution ... :::) so the "Governance Board Members" reference renders correctly with a working link to /bridges/management#current-bridge-governors.
15. /updates is meeting minutes, not release notes, and is months stale (minor)
Location:/updates
Problem: The "Updates" page (linked from the global nav as "Updates") is raw paste-style minutes of weekly Core Devs calls. Entries are in plain-text dates ("July 23, 2025", "July 09, 2025"), "Watch the call record here" is rendered as plain text (no link), and "Geth — Not present" appears as a recurring line item. The page is not machine-readable, not RSS-able, and the most recent entries are months out of date relative to the 2026 site copyright.
Consequence: A developer expecting a changelog ("did Pectra ship? what fixed in 1.32.3?") instead gets a transcript of attendance. Tooling that wants to subscribe to network updates has nothing structured to read.
The fix: Split this into two pages: (a) a real release notes / changelog with per-version entries (date, client, version, links), and (b) optional meeting notes archived under /community/coredevs for those who want them. Add an RSS feed.
16. Shutter docs mix block explorer domain conventions, render config as prose, and have unlinked "test here" pointers (minor)
Location:/shutterized-gc
Problem: The Chain Config table renders as prose, not a table. Block explorer URLs disagree across the page: mainnet listed as https://gnosis.blockscout.com/ (current Blockscout domain) but Chiado listed as https://blockscout.com/gnosis/chiado (the older, deprecated Blockscout domain pattern). The "Shutterized Chiado Test dApp" section reads "You can test out the test version of Shutterized Chiado here" — with "here" not actually linked.
Consequence: A developer trying to inspect a Chiado transaction may land on an old/deprecated explorer page. Users looking for the test dApp have nowhere to click.
The fix: Normalize explorer URLs to the current Blockscout pattern (https://gnosis-chiado.blockscout.com/ or whatever the canonical is). Add the actual URL to the "test dApp here" link. Re-render the chain config as a proper Markdown table.
17. Interactive node setup guide is incomplete and truncated (minor)
Location:/node/manual
Problem: The "Interactive Guide" advertises a 4×4×2×2 matrix of Operating system × Network × Execution client × Consensus client. The export shows only Nethermind's commands filled in for several blocks; "Other ways to generate the jwt.hex file" is enumerated starting at item 2 (no item 1); and Windows commands are truncated mid-flag (--con…).
Consequence: An operator picking Erigon/Reth/Geth or Windows gets an incomplete or truncated runbook. Numbered lists starting at 2 suggest a deleted step.
The fix: Audit the interactive guide's content matrix for completeness — every (OS, network, EL, CL) combination should produce a complete, runnable set of commands. Renumber the jwt.hex list. Verify Windows commands aren't being clipped by a UI component.
18. Hashi integration page has trailing/unfinished sections, an empty admonition, and ambiguous duplicate labels (minor)
Location:/bridges/hashi/hashi-integration
Problem: Section "4. xDAI Bridge: in xDAI bridge, a" trails off mid-sentence. The title "xDAI briddge" is misspelled. An empty warning admonition appears at the top with no body. The Hashi Manager contracts table reuses the labels "Hashi Manager on Ethereum" and "Hashi Manager on Gnosis Chain" across both the AMB section and the xDai section with different addresses — a reader scrolling without tab context could pick the wrong manager.
Consequence: A contract integrator might wire the AMB Hashi Manager into xDai bridge logic or vice versa. The truncated section suggests the docs are mid-edit.
The fix: Finish the truncated bullet, fix the misspelling, drop the empty warning admonition, and disambiguate the contract labels (e.g. "AMB Hashi Manager on Ethereum" vs "xDai Hashi Manager on Ethereum").
19. "Sepolia-Chiaado" typo on Omnibridge contracts tab (minor)
Location:/bridges/About Token Bridges/omnibridge
Problem: The Key Contracts tab on the Omnibridge page is labeled "Sepolia - Chiaado" (sic — should be "Chiado"). This is the tab a developer clicks to find testnet contract addresses for the Omnibridge.
Consequence: Search for "Chiado" in the docs doesn't surface this tab. The mislabel undermines confidence in a page whose only job is to be the authoritative contract address reference.
The fix: Fix the typo in the tab label.
What they do well
The Pectra page does ship a clear timeline table with timestamps, fork hashes, and per-client minimum versions — that's the right shape for hard-fork documentation; it just needs the constants filled in and propagated to other forks.
Bridge contract addresses are tabulated by chain (Ethereum / Gnosis / Sepolia-Chiado), which makes verification on Blockscout straightforward when the addresses are valid.
The dual-track node setup story (Interactive Guide for experienced operators, Step-by-Step for beginners) is a sound information architecture choice — execution is the issue, not the framing.
Top 3 recommendations
Fix the security-claim contradictions first. Reconcile the 7 vs 8 vs 8-of-15 governance threshold across gbc/upgradeability, Bridge Management, Omnibridge, and xDai bridge pages, and fix the broken admonition on the upgradeability page. These are the load-bearing trust claims for a multi-billion-dollar bridge.
Refresh the security-audit page and publish post-Merge audits. Five years of silence on a page that exists specifically to answer "what's been audited?" undermines every other security claim in the docs.
Add a 404 page and fix the systematic dead-link pattern. Internal links to /node/troubleshooting, /bridges/Token Bridge/*, /developers/Smart Contracts/* silently resolve to the homepage shell. Audit every link, add redirects, and stop letting the SPA router swallow 404s.