WIP IBC Solidity documentation by evanorti · Pull Request #317 · cosmos/docs

evanorti · 2026-05-19T20:05:54Z

Add documentation for IBC solidity:

architecture overview
Tutorial: intro and quickstart
tutorial walkthroughs
Relayer architecture and guide
Attestor architecture and guide

mintlify · 2026-05-19T20:06:35Z

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

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟢 Ready	View Preview	May 19, 2026, 8:11 PM

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

greptile-apps · 2026-05-19T20:11:24Z

Greptile Summary

This WIP PR adds a new documentation section for IBC Solidity (Cosmos-EVM IFT transfers), covering architecture overview, a 7-step tutorial with walkthrough pages, relayer and attestor reference guides, plus two anchor-link fixes in existing pages.

Twelve new .md files are added under ibc/next/cosmos-solidity/ but none are registered in docs.json, so they will not appear in the sidebar and are unreachable by site visitors.
relayer-guide.md has its entire second half (API Interface, Observability, Configuration Reference, and Signing sections) duplicated verbatim, and references an image (relaying-sequence.png) that is not included in the PR.
Several internal links use relative paths with .md extensions (including a typo 07-ransfer.md in 06-wire.md) instead of the required absolute Mintlify paths; bold text and em-dashes appear throughout the new files, both of which the repo style guide prohibits.

Confidence Score: 3/5

Not ready to merge: the relayer guide has large duplicated sections, all new pages are missing from docs.json, and a broken link typo and missing image would affect users immediately on publication.

The relayer guide duplicates its entire second half (hundreds of lines repeated verbatim), a referenced image is absent, and none of the 12 new pages are wired into the navigation. The broken 07-ransfer.md link in the wire walkthrough would dead-end readers in the middle of the tutorial.

relayer-guide.md has the most significant issues (duplication, missing image). 06-wire.md has the broken link. All new files need docs.json entries before the section can go live.

Important Files Changed

Filename	Overview
ibc/next/cosmos-solidity/relayer/relayer-guide.md	Comprehensive relayer reference guide; the entire API Interface, Observability, Configuration, and Signing sections are duplicated verbatim, and an image (`relaying-sequence.png`) is referenced but not included in the PR.
ibc/next/cosmos-solidity/tutorial/walkthrough/06-wire.md	New walkthrough step for wiring IBC clients; contains a broken link typo (`07-ransfer.md`) and uses a relative `.md` path instead of the required absolute Mintlify path.
ibc/next/cosmos-solidity/overview.md	New architecture overview for Cosmos-EVM IFT transfers; content is solid but the file (along with all 12 new `.md` files) is not registered in `docs.json`, making it unreachable on the published site.
ibc/next/cosmos-solidity/attestor/attestor-guide.md	Attestor deployment and configuration guide; uses bold text and em-dashes in prose, both prohibited by the repo style guide.
ibc/next/cosmos-solidity/tutorial/introduction.md	Tutorial introduction page; uses a relative link with `.md` extension (`../overview.md`) rather than the required absolute Mintlify path.
ibc/next/cosmos-solidity/tutorial/walkthrough/07-transfer.md	Final walkthrough step covering token transfers; uses a relative `.md` link to Quickstart and bold text in the scenario list header, both against repo style rules.
ibc/next/cosmos-solidity/attestor/overview.md	Attestor architecture overview; uses bold text (`Note`, `must guarantee`) and italic text in prose, violating the repo style guide.
ibc/next/cosmos-solidity/tutorial/quickstart.md	Quickstart page with complete command reference; content is clear and well-structured with no major issues beyond the missing `docs.json` registration.
ibc/next/cosmos-solidity/tutorial/walkthrough/05-clients.md	Step 5 walkthrough covering attestation light client creation on both chains; well-structured content with detailed configuration reference tables.
ibc/next/cosmos-solidity/relayer/overview.md	New relayer overview page; content appears solid with no structural issues beyond missing `docs.json` registration.
ibc/next/apps/interchain-accounts/messages.mdx	Updates the `CacheMultiStore` anchor link to include the correct `#cachemultistore-transaction-isolation` fragment; straightforward link fix.
ibc/next/migrations/v2-to-v3.mdx	Updates the store upgrades anchor link to `#adding-new-modules-during-an-upgrade`; straightforward link fix.

Sequence Diagram

sequenceDiagram
    participant User
    participant Cosmos as Cosmos Chain (IFT Module)
    participant Attestor as Attestor Service
    participant ProofAPI as Proof API
    participant Relayer
    participant EVM as EVM Chain (ICS26Router)
    participant IFT as IFT Contract (EVM)

    User->>Cosmos: iftTransfer (burn tokens)
    Cosmos->>Cosmos: Commit IBC packet, emit events
    Attestor->>Cosmos: Monitor for IBC events
    User->>Relayer: Relay(tx_hash, chain_id)
    Relayer->>ProofAPI: Request attestation proof
    ProofAPI->>Attestor: Collect signatures
    Attestor-->>ProofAPI: Signed attestations
    ProofAPI-->>Relayer: Proof bundle
    Relayer->>EVM: RecvPacket (with proof)
    EVM->>EVM: AttestationLightClient validates proof
    EVM->>IFT: iftMint(recipient, amount)
    IFT-->>User: ERC-20 tokens minted
    EVM->>EVM: Emit WriteAcknowledgement
    Relayer->>ProofAPI: Request ack proof
    ProofAPI-->>Relayer: Ack proof bundle
    Relayer->>Cosmos: MsgAcknowledgement
    Cosmos->>Cosmos: Packet lifecycle complete

_{Reviews (1): Last reviewed commit: "add ibc-solidity docs" | Re-trigger Greptile}

greptile-apps · 2026-05-19T20:11:29Z

+
+## Next steps
+
+With the bridge wired, the [next step](07-ransfer.md) sends a live token transfer and validates the full packet relay flow.


Broken link — typo drops the t in transfer

The link target 07-ransfer.md is missing the letter t, so it points to a non-existent file. Additionally, per the repo style guide, internal links must use absolute Mintlify paths and must not include .md extensions. The correct absolute path would be something like /ibc/next/cosmos-solidity/tutorial/walkthrough/07-transfer.

Context Used: CLAUDE.md (source)

greptile-apps · 2026-05-19T20:11:30Z

+
+The tutorial is built around a working demo that runs a [Cosmos sandbox chain](https://github.com/cosmos/sandbox-ledger) and a [Besu](https://github.com/hyperledger/besu) EVM node locally. You can use this demo as an example implementation for integrating Cosmos to EVM IBC functionality into your own chains.
+
+For conceptual background on how the system works before diving in, see the [architecture overview](../overview.md).


Relative links with .md extensions throughout the new files

The repo style guide requires absolute Mintlify paths for internal links and forbids relative paths and .md/.mdx extensions. This file links to ../overview.md; the same issue appears in 07-transfer.md (../../quickstart.md), and in 06-wire.md (07-ransfer.md). All internal links should follow the pattern /ibc/next/cosmos-solidity/overview (no extension, root-relative).

Context Used: CLAUDE.md (source)

greptile-apps · 2026-05-19T20:11:31Z

@@ -0,0 +1,119 @@
+# Cosmos ↔ EVM IFT Transfers: Architecture Overview


New pages not registered in docs.json

All 12 new files added under ibc/next/cosmos-solidity/ are not registered in docs.json. Per the repo guide, every page must be added to the navigation there to appear in the sidebar; without this, the pages are unreachable by site visitors. docs.json was not modified in this PR.

Context Used: CLAUDE.md (source)

greptile-apps · 2026-05-19T20:11:33Z

+## API Interface
+The relayer serves a gRPC server which clients use to specify what packets to relay and track packet relaying progress.
+
+```proto
+service RelayerApiService {
+    // Relay is used to specify a source tx hash for packets the relayer should relay.
+    // The relayer will identify all packets created by the transaction and attempt to relay them all.
+    rpc Relay(RelayRequest) returns (RelayResponse) {}
+
+    // The status endpoint is used to track the progress of packet relaying.
+    // It takes a transaction hash and returns the status of any relevant packets the relayer is aware of.
+    // The transaction must first have been passed to the relay endpoint.
+    rpc Status(StatusRequest) returns (StatusResponse) {}
+}
+
+message StatusRequest {
+    string tx_hash = 1;
+    string chain_id = 2;
+}
+
+enum TransferState {
+    TRANSFER_STATE_UNKNOWN = 0;
+    TRANSFER_STATE_PENDING = 1;
+    TRANSFER_STATE_COMPLETE = 2;
+    TRANSFER_STATE_FAILED = 3;
+}
+
+message TransactionInfo {
+    string tx_hash = 1;
+    string chain_id = 2;
+}
+
+message PacketStatus {
+    TransferState state = 1;
+    uint64 sequence_number = 2;
+    string source_client_id = 3;
+    TransactionInfo send_tx = 4;
+    TransactionInfo recv_tx = 5;
+    TransactionInfo ack_tx = 6;
+    TransactionInfo timeout_tx = 7;
+}
+
+message StatusResponse {
+    repeated PacketStatus packet_statuses = 1;
+}
+
+message RelayRequest {
+    string tx_hash = 1;
+    string chain_id = 2;
+}
+
+message RelayResponse {}
+```


Entire API Interface, Observability, Configuration, and Signing sections are duplicated

The content from ## API Interface (line ~112) through the end of ## Signing is repeated verbatim a second time starting around line 528. This means readers see two copies of the gRPC proto definitions, the full observability metrics table, the entire YAML configuration reference, and the full signing section. The second copy should be removed.

greptile-apps · 2026-05-19T20:11:35Z

+IBC v2 Relayer is a relaying service for the IBC v2 Protocol. The relayer supports interoperating between a Cosmos-based chain and major EVM networks.
+
+## Relaying Sequence
+![Relaying Sequence](./relaying-sequence.png)


Referenced image relaying-sequence.png is not in the PR

The image ./relaying-sequence.png is referenced on this line, but no such file was added in this PR. This will render as a broken image on the published page. Additionally, this uses a relative path; images should be referenced from ../images/ (the shared image directory for the IBC docs section) using an absolute path.

greptile-apps · 2026-05-19T20:11:37Z

+**Image**: `ghcr.io/cosmos/ibc-attestor:<version>` — see [releases](https://github.com/cosmos/ibc-attestor/releases) for available tags
+**Binary**: `ibc_attestor`
+
+### 2. Signer Service (external dependency)
+
+The attestor requires a secp256k1 signing key. Two deployment modes are supported:
+
+- **Local signer** — key is stored in an encrypted keystore file on disk, read directly by the attestor process
+- **Remote signer** — the attestor delegates signing to an external gRPC signer service (e.g. `platform-signer`) over the network


Bold text and em-dashes in documentation content

The repo style guide prohibits both bold/italic text and em-dashes (—) in documentation content. Lines 18 and 25–26 use both. The same pattern appears across many of the new files: 07-transfer.md (bold scenario labels), relayer-guide.md (bold signing mode labels and method lists), and attestor/overview.md (**Note**, **must guarantee**). All bold formatting should be removed and em-dashes replaced with commas, periods, or rephrased sentences.

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 · 2026-05-20T04:35:00Z

+
+### Access control
+
+The demo uses the deployer address as both the AccessManager admin and the relayer EOA. For production, grant roles explicitly:


So there are alot more restricted functions than what is mentioned here. It would be good to work with serdar here on a set of recommendations for the permission levels of the various restricted functions for production use.

This tutorial walkthrough may not be the best place, but this should exist somewhere.

dhfang · 2026-05-22T04:21:03Z

@@ -0,0 +1,244 @@
+---
+title: "Attestation Light Client"


why is this under cosmos-evm

evanorti added 2 commits May 19, 2026 15:40

update anchors

28c8d65

add ibc-solidity docs

7211a6d

evanorti requested review from dhfang and srdtrk May 19, 2026 20:06

mintlify Bot deployed to staging May 19, 2026 20:11 View deployment

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Update attestor-guide.md

e13e77c

mintlify Bot deployed to staging May 19, 2026 20:17 View deployment

Update relayer-guide.md

984ee03

mintlify Bot deployed to staging May 19, 2026 20:20 View deployment

dhfang requested changes May 20, 2026

View reviewed changes

evanorti added 3 commits May 20, 2026 17:09

update documentation

5321aef

Update 05-clients.mdx

30381d5

Update 06-wire.mdx

6dcdfd2

mintlify Bot deployed to staging May 20, 2026 21:23 View deployment

dhfang requested changes May 21, 2026

View reviewed changes

evanorti added 2 commits May 21, 2026 14:01

update docs

fa29d32

update doc

5a3e0c2

mintlify Bot deployed to staging May 21, 2026 18:04 View deployment

Update quickstart.mdx

5e884b3

mintlify Bot deployed to staging May 21, 2026 18:09 View deployment

update docs

e8cff17

mintlify Bot deployed to staging May 21, 2026 21:07 View deployment

dhfang requested changes May 22, 2026

View reviewed changes


		## Next steps

		With the bridge wired, the [next step](07-ransfer.md) sends a live token transfer and validates the full packet relay flow.


		The tutorial is built around a working demo that runs a [Cosmos sandbox chain](https://github.com/cosmos/sandbox-ledger) and a [Besu](https://github.com/hyperledger/besu) EVM node locally. You can use this demo as an example implementation for integrating Cosmos to EVM IBC functionality into your own chains.

		For conceptual background on how the system works before diving in, see the [architecture overview](../overview.md).

		@@ -0,0 +1,119 @@
		# Cosmos ↔ EVM IFT Transfers: Architecture Overview


		### Access control

		The demo uses the deployer address as both the AccessManager admin and the relayer EOA. For production, grant roles explicitly:

Conversation

evanorti commented May 19, 2026

Uh oh!

mintlify Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented May 19, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dhfang May 20, 2026

Choose a reason for hiding this comment

Uh oh!

dhfang May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dhfang May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented May 19, 2026 •

edited

Loading