Babylon Documentation Audit

One-line state of the docs: a genuinely deep operator/developer corpus (node, validator, finality-provider, CLI, and Staking API references, plus a versioned llms.txt) undermined by network-, version-, date-, and key-storage contradictions between pages — the exact failures that silently break copy-paste setup and AI coding agents. (The operator node docs are also buried two levels under "Babylon Genesis → Run a Node" while the landing page fronts "Trustless Bitcoin Vault," but that discoverability gap is secondary to the contradictions below.)

1. The validator guide contradicts itself on where your BLS signing key lives (critical)

Location: /operators/babylon_validators/installation_guide (§3.1 vs §5); cross-referenced by /operators/babylon_node/installation_guide and /operators/babylon_node/babylon_cli/init

Problem: On a single page, §3.1 says the BLS key "is stored in bls_key.json along with bls_password.txt following EIP-2335." Then §5 says "ensure that your <path>/config/priv_validator_key.json file contains both your CometBFT consensus and BLS key pair" and warns that "Running unsafe-reset-all will result in the removal of the BLS keys within the priv_validator_key.json file." The node installation guide independently describes a separate bls_key.json + bls_password.txt, while the init CLI page shows BLS material as a bls_key field inside priv_validator_key.json with no separate file at all.

Consequence: A validator cannot tell which file actually holds the key, and therefore which file to back up. The destructive unsafe-reset-all warning only names priv_validator_key.json; an operator who followed the node install guide believes the key is in bls_key.json and backs up the wrong file. Losing the BLS key of an active validator is not cosmetic — it forces re-registration and can mean missed signing/slashing exposure.

The fix: Determine the real on-disk layout for the current mainnet binary (v1.0.1+), document it once canonically, and make every page (node install, validator install §3.1/§5, init, create-bls-key) link to that single source instead of restating divergent layouts.

2. The BLS password flag has two names, a contradictory default, and a wrong description (critical)

Location: /operators/babylon_node/babylon_cli/start and /operators/babylon_node/installation_guide

Problem: The installation guide's init section documents --no-bls-password ("designates that an empty BLS password should be used"), but the same guide's start section calls the flag --no-bls-key with the identical description — "is a flag that if set designates that an empty BLS password should be used" (a flag literally named "no-bls-key" described as controlling a password). Separately, the start CLI reference lists --no-bls-password with Default: true and the description "Generate BLS key without password (suitable for RPC nodes)" — meaning the documented default generates a passwordless key, which contradicts the install guide's interactive password-prompt flow.

Consequence: Operators can't reliably set or suppress the BLS password because the flag name changes between pages, and the documented true default implies validators get a passwordless BLS key out of the box. An agent parsing the installation guide's start section would emit --no-bls-key — a flag that appears nowhere in the CLI start reference (which documents only --no-bls-password), so the copied command may not exist as written.

The fix: Use one canonical flag name across all pages, correct the description to match what the flag actually gates, and verify/correct the default (a security-sensitive key flag defaulting to "no password" needs an explicit, loud rationale or correction).

3. The Operators overview is stale on network identity and binary version (critical)

Location: /operators/ (vs /developers/babylon_genesis_chain/node_information, /chain_information, and the Phase 2 Registration guide)

Problem: The Operators landing page lists "Phase 2 testnet (Staking on Babylon Genesis)" and instructs: "For Phase 2 testnet users, please use the v1.0.0-rc.3 tag for babylon binary." But node_information and chain_information treat Phase 2 / Babylon Genesis (bbn-1) as the live mainnet (Version v1.0.1, Genesis Date 2025-03-15), and the Phase 2 Registration guide also describes it as a live network.

Consequence: This is the first page an operator hits. It tells them Babylon Genesis is a testnet and tells them to build a release-candidate tag (v1.0.0-rc.3) instead of the mainnet release (v1.0.1). An operator who trusts the overview builds the wrong binary for mainnet participation.

The fix: Update the overview to label bbn-1 as mainnet and reconcile the binary tag with chain_information (mainnet v1.0.1), or remove the hardcoded tag and link to the canonical chain-info table.

4. Build instructions cite a different Go version than the binary's main-branch source (significant)

Location: /operators/babylon_node/installation_guide (and its upstream bbn-1/babylon-node README) vs github.com/babylonlabs-io/babylon/README.md (main branch)

Problem: The installation guide says "Install Golang 1.23," then tells you to git checkout v1.0.1 and make install. The guide's own version-pinned upstream source (the bbn-1/babylon-node networks README) is self-consistent — it also specifies Go 1.23 for the v1.0.1 build. But the babylond source repo's main-branch README — the natural place a developer reads about building babylond — states "To build and install, you need to have Go 1.25 available." Nothing reconciles which toolchain goes with which source.

Consequence: A developer building from main follows 1.25; one following the version-pinned guide installs 1.23; neither doc states that the two numbers apply to different (released vs unreleased) source trees. An AI agent that scrapes the main repo README and the install guide together sees a direct "1.23 vs 1.25" conflict with no rule for choosing. (The evidence does not confirm v1.0.1's own go.mod requires >1.23, so this is a documentation inconsistency, not a proven build failure for the pinned tag.)

The fix: Pin the Go version to the checked-out tag's go.mod and state explicitly that 1.23 matches the v1.0.1 mainnet build while main (newer/unreleased) needs 1.25, so readers know which toolchain matches which source. Ideally derive the version string in the docs from the repo rather than hardcoding it.

5. "Babylon Genesis" is defined as three different things, two of them on the same page (significant)

Location: /developers/faqs (vs /developers/babylon_genesis_chain/chain_information and /node_information)

Problem: In the FAQ, one answer states "Babylon Genesis: is a US consulting company that provides services to Babylon Labs & Babylon Foundation." The very next answer asks "What is Babylon Genesis?" and answers "Babylon Genesis is a Cosmos SDK-based blockchain." Meanwhile chain_information and node_information use "Babylon Genesis" as the name of the mainnet chain (bbn-1).

Consequence: The single most important brand term in the docs has three incompatible meanings — a legal entity, a protocol/chain, and a specific mainnet — with two of them adjacent in the same FAQ. This is primarily an agent/knowledge-graph problem: a human disambiguates by context, but an agent building a glossary or knowledge graph cannot tell which "Babylon Genesis" a given page means, which poisons every downstream reference and answer the agent generates.

The fix: Reserve "Babylon Genesis" for one referent (the chain/mainnet), rename the legal entity explicitly, and add a one-line disambiguation note in the FAQ.

6. Current binary version differs on nearly every page that states one (significant)

Location: /operators/, /operators/babylon_node/installation_guide, /chain_information, /operators/finality_providers/phase_2_registration_guide, /operators/finality_providers/

Problem: The "current" version is given as: v1.0.0-rc.3 (operators overview), v1.0.1 (install guide checkout and chain_information mainnet), v2.3.1 (chain_information testnet bbn-test-6), Finality Provider v1.0.0 + Babylon Genesis node v1.0.1 (Phase 2 guide), and a release selector of v2.0.2 / v2.0.1 / v2.0.0 (Finality Providers overview). These are hand-maintained, frozen strings scattered across pages.

Consequence: No single page can be trusted for "which version do I run," and the spread (rc.3 → 1.0.1 → 2.0.x → 2.3.1) is wide enough that an operator or agent will install a wrong, possibly incompatible binary. Manual version lists like these drift the moment any release ships.

The fix: Maintain versions in one machine-readable table (the chain_information page is the natural home) and reference it everywhere else; delete hardcoded version strings from prose pages.

7. The mainnet launch date is stated three different ways (significant)

Location: /developers/babylon_genesis_chain/chain_information vs /operators/finality_providers/phase_2_registration_guide vs /llms.txt

Problem: chain_information gives the mainnet (bbn-1) Genesis Date as 2025-03-15. The Phase 2 Registration guide says the network "has entered its second phase of operation since 10 April 2025." llms.txt says "The mainnet, 'Babylon Genesis,' launched in April 2025." Three pages give three launch dates spanning roughly four weeks, and nothing distinguishes a "chain genesis" event from "Phase 2 went live."

Consequence: A developer or agent trying to anchor "when did mainnet start" (for changelog reasoning, upgrade-height math, or simply citing the launch) gets three answers with no canonical one. It also undercuts the docs' own version/network tables, which are otherwise the strongest single source of truth.

The fix: State one canonical mainnet launch date (the bbn-1 genesis date), and if "Phase 2 going live" is a distinct event, label it as such with its own date and a one-line explanation rather than presenting it as the launch.

8. The only documented node endpoints are third-party, with no first-party fallback (significant)

Location: /developers/babylon_genesis_chain/node_information

Problem: Every RPC/LCD/gRPC endpoint listed for both mainnet (bbn-1) and testnet (bbn-test-6) is a Polkachu host (https://babylon-rpc.polkachu.com, babylon-grpc.polkachu.com:20690, etc.). No first-party Babylon-operated endpoint appears anywhere on the node-information page.

Consequence: Developers and operators are silently routed to a single third-party provider with no official endpoint to fall back to. If that provider rate-limits, changes hosts, or goes down, there is no documented alternative — and an agent generating a client/node config will hardcode a third-party host as if it were canonical.

The fix: Add first-party Babylon endpoints, or clearly state that none are offered and list multiple independent providers, so there is an official source of truth plus a fallback.

9. BLS keys are both "automatic" and a required manual step (significant)

Location: /operators/babylon_node/babylon_cli/init and /operators/babylon_validators/installation_guide (§3.1) vs /operators/babylon_node/babylon_cli/create_bls_key

Problem: The init page states "Babylon automatically generates BLS keys during initialization," and the validator install §3.1 says "two types of keys are generated automatically" by babylond init. The create-bls-key page contradicts this: it documents BLS generation as a distinct post-init command (babylond create-bls-key) whose prerequisites are an already-initialized node and an existing priv_validator_key.json.

Consequence: An operator who believes init already produced the BLS key skips create-bls-key and later fails validator creation; an operator who runs both may hit "BLS key already exists." The actual required workflow is ambiguous.

The fix: State definitively whether init generates the BLS key or whether create-bls-key is mandatory, and present one ordered workflow that all three pages share.

10. The init CLI page uses non-existent chain-ids, a wrong default denom, and a dead genesis URL (significant)

Location: /operators/babylon_node/babylon_cli/init (and chain-id reuse in /create_bls_key)

Problem: The page body's examples use chain-ids babylon-1 and babylon-testnet-1, neither of which exists — the real networks are bbn-1 (mainnet) and bbn-test-6 (testnet). --default-denom is documented with default stake, whereas the chain's denom is ubbn. The testnet genesis download points at https://github.com/babylonchain/networks/raw/main/testnet/genesis.json on the old babylonchain org, which llms.txt confirms is no longer part of the canonical link set (babylonlabs-io).

Consequence: Copy-pasting these commands targets networks that don't exist and downloads genesis from a stale/likely-dead org path. The stake default denom further misleads anyone reading defaults literally. This is the page agents would scrape to learn how to initialize a node.

The fix: Replace placeholder chain-ids with bbn-1/bbn-test-6, correct the denom to ubbn, and repoint the genesis URL at the current babylonlabs-io/networks repo (matching chain_information's genesis source).

11. The --minimum-gas-prices example uses a denom that doesn't exist on Babylon (significant)

Location: /operators/babylon_node/babylon_cli/start

Problem: The --minimum-gas-prices flag description gives the example 0.01photino;0.0001stake. photino is not a Babylon denomination, and stake is the generic Cosmos placeholder; the chain's fee denom is ubbn (used as 0.002ubbn/0.005ubbn elsewhere in these docs).

Consequence: An operator copying the example sets gas prices in a denom the node doesn't recognize, so the node either rejects all transactions or accepts none at the intended price. Agents will surface photino as a valid Babylon denom.

The fix: Use ubbn in the example (e.g., 0.002ubbn) consistent with the install/usage guides.

12. The start CLI reference leaks a developer's personal machine identity as the documented defaults (significant)

Location: /operators/babylon_node/babylon_cli/start

Problem: The generated flag table lists --home with Default /Users/dariaagadzhanova/.babylond and --moniker with Default "Darias-MacBook-Air.local" — a developer's local username and laptop hostname captured during doc generation.

Consequence: Beyond exposing a person's machine name in public docs, the values are misleading: a reader's actual --home default is their own ~/.babylond and their moniker default is their own hostname. Anyone diffing their environment against the documented "default" will be confused, and agents will treat these as canonical constants.

The fix: Regenerate the reference with sanitized, generic defaults ($HOME/.babylond, "<hostname>") and add a generation step that scrubs absolute home paths and machine names.

13. The same workflow mixes the deprecated tendermint alias and the current comet subcommand (significant)

Location: /operators/babylon_node/babylon_usage_guide and /operators/babylon_validators/installation_guide

Problem: The usage guide uses babylond comet show-validator in its create-validator snippet but babylond tendermint show-validator in the slashing-signing-info query — on the same page. The validator install guide uses babylond tendermint show-validator, while create-bls-key's related commands list babylond comet show-validator.

Consequence: Operators can't tell which subcommand is current; if tendermint is a deprecated alias slated for removal, copied commands will break on newer binaries, and agents have no way to choose the supported form.

The fix: Standardize on the current subcommand (comet) everywhere and, if tendermint is deprecated, note it once rather than interleaving both.

14. The Staking API reference documents only a testnet host, undocumented errors, and a cURL missing its required parameter (significant)

Location: /api/staking-api/check-address-risk (representative of the Staking API reference)

Problem: The Base URL is https://staking-api.testnet.babylonlabs.io — a testnet host — and no mainnet base URL appears anywhere in the API reference. The response section lists codes 200 / 400 / 404 / 500, but only 200 has a description ("Risk of provided address"); the 400/404/500 bodies are undocumented. The generated cURL sample, curl -L 'https://staking-api.testnet.babylonlabs.io/address/screening' -H 'Accept: application/json', omits btc_address even though that query parameter is marked REQUIRED.

Consequence: A developer integrating against mainnet has no documented endpoint to call; the copy-paste cURL returns an error because the required parameter is missing; and there's no way to handle 4xx/5xx because the error shapes aren't specified. For an address-risk/screening endpoint, silent or unhandled errors are a compliance hazard, not just an inconvenience.

The fix: Document the mainnet base URL, include the REQUIRED btc_address in generated samples, and specify the response body and meaning for every listed status code.

15. Hardware and gas-price recommendations disagree across guides (minor)

Location: /operators/babylon_validators/installation_guide vs babylon/README.md; /operators/babylon_validators/installation_guide vs /babylon_usage_guide

Problem: The validator install guide recommends "Storage: 2TB NVMe," while the babylond README's tested spec is "1TB NVMe Storage." The validator install guide's create-validator command uses --gas-prices "0.005ubbn", whereas the usage and install guidance elsewhere use 0.002ubbn.

Consequence: Operators may over- or under-provision storage by 2x and pay inconsistent gas, with no stated reason for the difference between validator and general node setups.

The fix: Reconcile the storage figure (or explain why a validator needs 2TB vs a node's 1TB) and standardize the gas-price example, noting if validators legitimately need a higher floor.

16. An internal authoring TODO and a broken spec link shipped to the published site (minor)

Location: /operators/finality_providers/

Problem: The published overview contains an unrendered authoring comment, <!-- These are out of place right now, we need to decide where to place them -->, and points readers to a spec via a repo-relative path: "please see ./docs/SPEC-CONSUMER.md," which does not resolve on the docs site.

Consequence: Readers see internal editorial notes leak into production and get a dead link to the consumer finality-provider specification — the exact document the section promises. Agents following the link get nothing.

The fix: Strip authoring comments during build and replace ./docs/SPEC-CONSUMER.md with an absolute, resolvable URL to the spec.

17. The FAQ promises "three distinct phases" but documents only two (minor)

Location: /developers/faqs (vs /operators/)

Problem: The FAQ states "Babylon's development is strategically planned across three distinct phases," then under "Overview of Babylon Phases" details only Phase 1 (Bitcoin-Centric Development) and Phase 2 (Babylon Genesis / Cosmos Chain Launch). Phase 3 — which the operators overview lists as "Phase 3 devnet (Bitcoin Staking expansion)" — is absent.

Consequence: A reader who counts on the FAQ for the canonical phase model is told there are three but shown two, and has to cross-reference the operators page to discover Phase 3 exists at all. It's a small inconsistency, but it sits squarely in the docs' weakest area (network/phase identity).

The fix: Either add a Phase 3 entry to the FAQ (matching the operators overview) or change the framing to the number of phases actually documented, and keep the phase list in one place that both pages reference.

What they do well

• A versioned llms.txt (Version 1.4.0) exists and enumerates the canonical repo set and links — genuinely useful for agents, and ahead of most docs of this complexity.
• The create-bls-key page includes a real "Common Errors" section with exact error strings and solutions (priv_validator_key.json not found, BLS key already exists) — the model the rest of the docs should follow.
• chain_information and node_information provide clean, structured tables for chain-ids, versions, genesis dates, and endpoints, giving the docs a natural single source of truth to converge on.

Top 3 recommendations

1. Establish single sources of truth for the volatile facts — BLS key on-disk layout, current binary versions, chain-ids/denoms, network status (mainnet vs testnet), and the mainnet launch date — in one structured page each, and have all prose pages reference them instead of restating divergent values.
2. Fix the setup-blocking contradictions first: the --no-bls-key/--no-bls-password flag name and true default, the testnet-vs-mainnet labeling plus v1.0.0-rc.3 tag on the operators overview, and the bls_key.json vs priv_validator_key.json storage question that risks unrecoverable key loss.
3. Sanitize and complete the generated references: scrub the leaked /Users/dariaagadzhanova / Darias-MacBook-Air.local defaults and the photino denom from the CLI reference, repoint the dead babylonchain genesis URL and placeholder chain-ids, and give the Staking API a mainnet base URL, documented error bodies, and cURL samples that include required parameters.