WIP IBC Solidity Demo Docs

[evanorti]

Overview, tutorial, and walkthrough docs of IBC solidity.

[greptile-apps]

Greptile Summary

This WIP PR adds a full documentation suite for the Cosmos↔EVM IBC Solidity demo, covering an architecture overview, quickstart, and six step-by-step walkthrough pages (chains, deploy, attestors, relayer, create-clients, wire), plus an attestor deployment reference guide.

• The overview.md EVM-to-Cosmos transfer flow has a copy-paste error: lines 116–117 say the relayer submits to the "EVM destination chain" when Cosmos is the destination for that direction; the rest of the bullet points in the same paragraph correctly describe Cosmos modules.
• attestor/overview.md was committed as an empty file even though introduction.md and walkthrough-attestors.md link to it, and quickstart.md still contains an unfilled <repo-url> placeholder in the clone command.

Confidence Score: 3/5

Three issues should be resolved before publishing: a factual error in the transfer flow description, an empty linked file, and an unfilled clone-URL placeholder.

The EVM-to-Cosmos flow in overview.md incorrectly names the relay target chain, which would actively mislead a reader following the flow. The empty attestor/overview.md produces a dead-end for two linked pages. The <repo-url> placeholder in quickstart.md breaks the first copy-paste command a new user would run. The rest of the walkthrough content is detailed and accurate.

demo/cosmos-evm/docs/overview.md (factual error in EVM-to-Cosmos flow), demo/cosmos-evm/docs/attestor/overview.md (empty file), demo/cosmos-evm/docs/quickstart.md (placeholder clone URL)

Important Files Changed

Filename	Overview
demo/cosmos-evm/docs/overview.md	Architecture overview with transfer flow diagrams; contains a copy-paste factual error in the EVM-to-Cosmos section (lines 116–117 say "EVM destination chain" when Cosmos is the destination), plus minor typos on lines 39 and 65.
demo/cosmos-evm/docs/attestor/overview.md	Empty file — linked from introduction.md and walkthrough-attestors.md but contains no content; will render as a blank page.
demo/cosmos-evm/docs/quickstart.md	Quickstart guide with all commands documented; line 16 contains an unfilled <repo-url> placeholder that breaks the copy-paste clone command.
demo/cosmos-evm/docs/attestor/deploy-attestor.md	Comprehensive attestor deployment guide covering configuration, CLI reference, key management, multi-chain deployments, and observability; well-structured with no issues found.
demo/cosmos-evm/docs/introduction.md	Introduction page with a clear overview of the 7-step tutorial; contains a <!-- todo: update link above --> comment for the overview link.
demo/cosmos-evm/docs/outline.md	Detailed tutorial outline covering all 10 sections; serves as a complete internal reference and appears accurate to the rest of the docs.
demo/cosmos-evm/docs/walkthrough-chains.md	Chain setup walkthrough with module tables, Besu config, and a detailed app.go diff reference; minor typo "throughly" on line 38.
demo/cosmos-evm/docs/walkthrough-deploy.md	EVM contract deployment walkthrough with ordered deploy table, access control notes, and production guidance; accurate and complete.
demo/cosmos-evm/docs/walkthrough-attestors.md	Attestor setup walkthrough with config samples and a field reference table; has a <!-- todo: fix link --> placeholder.
demo/cosmos-evm/docs/walkthrough-relayer.md	Relayer and Proof API configuration walkthrough with full YAML/JSON examples and a field reference; well-written and no issues found.
demo/cosmos-evm/docs/walkthrough-create-clients.md	Light client creation walkthrough covering verification logic, JSON templates, and production guidance for quorum and key rotation; accurate and complete.
demo/cosmos-evm/docs/walkthrough-wire.md	Bridge wiring walkthrough covering counterparty registration, IFT bridge setup on both chains, and relayer config finalization; accurate and complete.

Sequence Diagram

sequenceDiagram
    participant User
    participant CosmosChain as Cosmos Chain
    participant Attestor as Attestor
    participant ProofAPI as Proof API
    participant Relayer
    participant EVMChain as EVM Chain (Besu)

    Note over User,EVMChain: Cosmos → EVM Transfer
    User->>CosmosChain: tx ift burn + IBC send (GMP payload)
    CosmosChain->>CosmosChain: IFT module burns tokens, emits IBC packet event
    Attestor->>CosmosChain: polls for IBC events, signs packet state
    User->>Relayer: submit source tx hash
    Relayer->>ProofAPI: request proof for packet
    ProofAPI->>Attestor: collect attestation signatures
    Attestor-->>ProofAPI: signed attestation
    ProofAPI-->>Relayer: proof bundle (quorum met)
    Relayer->>EVMChain: RecvPacket(proof)
    EVMChain->>EVMChain: ICS26Router validates, AttestationLightClient verifies
    EVMChain->>EVMChain: ICS27GMP routes to IFT contract
    EVMChain->>User: IFT.iftMint() mints ERC20 to recipient

    Note over User,EVMChain: EVM → Cosmos Transfer
    User->>EVMChain: IFT.iftTransfer() burns ERC20
    EVMChain->>EVMChain: ICS27GMP emits IBC packet event
    Attestor->>EVMChain: polls for IBC events, signs packet state
    User->>Relayer: submit source tx hash
    Relayer->>ProofAPI: request proof for packet
    ProofAPI->>Attestor: collect attestation signatures
    Attestor-->>ProofAPI: signed attestation
    ProofAPI-->>Relayer: proof bundle
    Relayer->>CosmosChain: MsgRecvPacket(proof)
    CosmosChain->>CosmosChain: IBC core validates, attestation LC verifies
    CosmosChain->>CosmosChain: GMP module routes MsgIFTMint
    CosmosChain->>User: TokenFactory mints tokens to recipient

Loading

Comments Outside Diff (1)

1. demo/cosmos-evm/docs/attestor/overview.md, line 1 (link)

   Empty file committed

   attestor/overview.md is a zero-byte file. introduction.md and other walkthrough pages link to ./overview.md, and walkthrough-attestors.md links to attestor/deploy-attestor.md with a note pointing back to this file. A reader following either link will land on a blank page.

_{Reviews (1): Last reviewed commit: "Create walkthrough-wire.md" | Re-trigger Greptile}

[greptile-apps]

In the EVM-to-Cosmos section the destination chain is Cosmos, not EVM. Lines 116–117 incorrectly label the relay target and the chain executing the IBC modules as "EVM", which is the source chain for this direction. A reader following this flow would be confused about which chain the relayer is submitting to.

Suggested change

	3. The relayer takes the IBC RecvPacket transaction data and submits it to the EVM destination chain.
	- On the EVM destination chain, the core IBC modules parse the packet and execute core validation logic (sequencing, timeouts, etc), then routes it to the relevant light client module.
	3. The relayer takes the IBC RecvPacket transaction data and submits it to the Cosmos destination chain.
	- On the Cosmos destination chain, the core IBC modules parse the packet and execute core validation logic (sequencing, timeouts, etc), then routes it to the relevant light client module.

[greptile-apps]

The <repo-url> placeholder is never filled in. The actual repository URL is already given in introduction.md as https://github.com/cosmos/ibc-e2e-docs-example; the quickstart should use that directly so someone can copy-paste the clone command without hunting for it.

Suggested change

	git clone <repo-url>
	git clone https://github.com/cosmos/ibc-e2e-docs-example

[greptile-apps]

Typo: "transfering" → "transferring"

transfering is misspelled; the correct spelling is transferring (double-r).

[greptile-apps]

Missing article "a"

"The attestor is lightweight, stateless Rust service" should read "The attestor is a lightweight, stateless Rust service".

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!

[greptile-apps]

Typo: "throughly" → "thoroughly"

throughly is misspelled; the correct spelling is thoroughly.