WIP Ibc intro docs

[evanorti]

Add IBC intro section (what-is-ibc, how-ibc-works, ibc-lifecycle)

Adds three new conceptual overview pages to ibc/latest/intro/:

• What is IBC — introduces the chain isolation problem, how IBC replaces trusted operators with cryptographic proofs, the three-layer architecture (verification, core, application), and what the protocol can carry.
• How IBC works — explains each component in depth: packets and payloads, consensus vs. attestation light clients, relayer responsibilities, IBC Core internals (IBC store, client router, port router), and how IBC applications plug in.
• IBC lifecycle — step-by-step walkthrough of the full packet flow from setup through send, receive, acknowledgement, and timeout, including packet/payload field definitions, sequence diagrams, and a message/callback reference table.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟢 Ready	View Preview	Apr 24, 2026, 6:08 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

This PR adds three new conceptual overview pages (what-is-ibc, how-ibc-works, ibc-lifecycle) under ibc/latest/intro/. The content is clear and well-structured, but several mechanical issues need to be resolved before the pages are usable.

• All five internal cross-links across the three files are missing the required leading /, making them relative paths that will 404 in Mintlify (ibc/latest/intro/… → /ibc/latest/intro/…). One link in what-is-ibc.mdx also has a stray space inside the URL.
• docs.json was not updated, so none of the new pages will appear in the sidebar.
• Counterpart files under ibc/next/intro/ have not been created and the sync script has not been run, as required by CLAUDE.md when editing latest/.

Confidence Score: 4/5

Not safe to merge until broken internal links, missing docs.json registration, and missing next/ counterparts are fixed.

Three P1 findings block correct behavior: five internal links will 404, the pages won't appear in the sidebar (docs.json not updated), and the next/ sync is missing. The one P2 (bold text) is minor. Once the P1s are addressed this is safe to merge.

All three new files need link fixes; docs.json and ibc/next/intro/ counterparts need to be created outside this diff.

Important Files Changed

Filename	Overview
ibc/latest/intro/what-is-ibc.mdx	New introductory page for IBC; two internal links use relative paths (missing leading /) and one has a stray leading space in the URL, breaking Mintlify navigation.
ibc/latest/intro/how-ibc-works.mdx	New component-deep-dive page; three internal links use relative paths without a leading /, violating the absolute-path rule.
ibc/latest/intro/ibc-lifecycle.mdx	New packet-lifecycle reference page; contains one instance of bold text (**payloads**) which violates the repo style rule against bold/italic in documentation.

Sequence Diagram

sequenceDiagram
    participant User
    participant ChainA as Chain A (IBC Core)
    participant Relayer
    participant ChainB as Chain B (IBC Core)

    Note over ChainA,ChainB: Setup (once)
    ChainA->>ChainA: MsgCreateClient (light client of B)
    ChainB->>ChainB: MsgCreateClient (light client of A)
    ChainA->>ChainA: MsgRegisterCounterparty
    ChainB->>ChainB: MsgRegisterCounterparty

    Note over User,ChainB: Send
    User->>ChainA: MsgSendPacket
    ChainA->>ChainA: CommitPacket() → write commitment
    ChainA->>ChainA: OnSendPacket() callback

    Note over Relayer,ChainB: Receive
    Relayer->>ChainB: MsgUpdateClient (advance light client of A)
    Relayer->>ChainB: MsgRecvPacket + Merkle proof
    ChainB->>ChainB: VerifyMembership() via light client
    ChainB->>ChainB: setPacketReceipt()
    ChainB->>ChainB: OnRecvPacket() callback
    ChainB->>ChainB: CommitAcknowledgement()

    alt Acknowledgement path
        Note over Relayer,ChainA: Acknowledge
        Relayer->>ChainA: MsgUpdateClient (advance light client of B)
        Relayer->>ChainA: MsgAcknowledgement + proof
        ChainA->>ChainA: VerifyMembership()
        ChainA->>ChainA: deletePacketCommitment()
        ChainA->>ChainA: OnAcknowledgementPacket() callback
    else Timeout path
        Note over Relayer,ChainA: Timeout
        Relayer->>ChainA: MsgUpdateClient (advance light client past timeout)
        Relayer->>ChainA: MsgTimeout + non-membership proof
        ChainA->>ChainA: VerifyNonMembership()
        ChainA->>ChainA: deletePacketCommitment()
        ChainA->>ChainA: OnTimeoutPacket() callback
    end

Loading

_{Reviews (1): Last reviewed commit: "Create what-is-ibc.mdx" | Re-trigger Greptile}

[greptile-apps]

docs.json not updated and next/ counterparts missing

Three new pages are added under ibc/latest/intro/ but two required follow-up steps were skipped. First, docs.json must be updated to register each new .mdx file — without that, the pages are unreachable from the sidebar. Second, CLAUDE.md requires running node scripts/sync-latest-to-next.js ibc/latest/intro/ (or adding the files directly to ibc/next/intro/) after editing latest/. Neither ibc/next/intro/what-is-ibc.mdx, how-ibc-works.mdx, nor ibc-lifecycle.mdx appear to exist yet in next/.

Context Used: CLAUDE.md (source)

[greptile-apps]

The repo style guide prohibits bold or italic text in documentation content. **payloads** should be plain text.

Suggested change

A packet contains routing information (which clients are involved, what sequence number it has, when it expires) and one or more **payloads**. Each payload carries the actual application data: which ports are involved, what version and encoding the data uses, and the raw bytes of the message itself. Multiple payloads in a single packet execute atomically, which makes it possible to bundle cross-chain operations together.

A packet contains routing information (which clients are involved, what sequence number it has, when it expires) and one or more payloads. Each payload carries the actual application data: which ports are involved, what version and encoding the data uses, and the raw bytes of the message itself. Multiple payloads in a single packet execute atomically, which makes it possible to bundle cross-chain operations together.

Context Used: CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[dhfang]

typo "which contains the ports are involved"

[dhfang]

• You can use attestor clients in cosmos-to-cosmos connections as well. I would just mention the connection chain types in this paragraph and just focus on the different client types.
• Proof construction is delegated to a proof api in all cases for ibc v2 right now. I would just not mention the proof api.
• Attestation clients do not have a trusting period or expiration.