docs: IBC documentation pages

[evanorti]

Adds the IBC documentation set under docs/, organised into six numbered sections. docs/README.md is the table of contents and the entry point.

Introduction

• 1-introduction/1-what-is-ibc.md — packets between chains, verified by on-chain light clients

How IBC works

• 2-how-ibc-works/1-overview.md — the components, and the packet they pass
• 2-how-ibc-works/2-packets-and-applications.md — what moves, and what gives it meaning
• 2-how-ibc-works/3-core-router-and-store.md — the entry point, and the provable record
• 2-how-ibc-works/4-clients-and-counterparties.md — how one chain verifies another
• 2-how-ibc-works/5-relayer.md — what decides when packets move
• 2-how-ibc-works/6-packet-lifecycle.md — delivered and acknowledged, or timed out

Applications

• 3-applications/1-gmp.md — contract calls on another chain
• 3-applications/2-ift.md — a token that burns here and mints there

Light clients

• 4-light-clients/1-attestation-light-client.md — accepts what a quorum of attestors signs
• 4-light-clients/2-attestors.md — the services that sign, and the keys trusted

IBC-solidity contracts

• 5-ibc-solidity-contracts/1-overview.md — the contracts, and who deploys each
• 5-ibc-solidity-contracts/2-ics26-router.md — entry points, storage, events, roles
• 5-ibc-solidity-contracts/3-ics27-gmp-and-accounts.md — GMP and its per-sender accounts
• 5-ibc-solidity-contracts/4-ift-contracts.md — the base contract and its variants
• 5-ibc-solidity-contracts/5-attestation-light-client.md — what it verifies, and how
• 5-ibc-solidity-contracts/6-permissions-and-upgrades.md — roles, proxies, and what is fixed

IBC CLI

• 6-ibc-cli/1-overview.md — the three parts, and how they run

Guides

• 6-ibc-cli/2-tutorial-deploy-ibc-and-send-a-token.md — deploy IBC on two chains and send a token
• 6-ibc-cli/3-run-a-standalone-attestor.md — an attestor in its own process
• 6-ibc-cli/4-run-a-standalone-relayer.md — connect a relayer to an existing connection
• 6-ibc-cli/5-make-a-cross-chain-gmp-call.md — call a contract across chains

Reference

• 6-ibc-cli/6-configuration.md — every key in ibc.yml
• 6-ibc-cli/7-cli-commands.md — every command and flag
• 6-ibc-cli/8-api.md — the relayer and attestor gRPC services

guides tests and ref generation

The four guides were each run end to end against two local Besu chains, from a clean teardown, in the order they appear.

The tables on the three reference pages are generated from this repository by docs/6-ibc-cli/tools/refgen.py. Prose around them is hand-written; anything between <!-- GEN:... START --> and its END is regenerated and should not be edited by hand. See the tooling README.

[linear-code]

FOU-1381

FOU-1378

FOU-1379

FOU-1380

FOU-1382

FOU-1383

FOU-1384

FOU-1385

FOU-1386

FOU-1387

FOU-1388

FOU-1393

FOU-1389

FOU-1391

FOU-1390

FOU-1392

FOU-1395

FOU-1394

[dianab-cl]

Useful to mention it is important relayer liveness and uptime, if relayer down, no messages are exchanged.
Useful to mention also who can be/run a relayer

[srdtrk]

I'll edit these later. Also, the docs may have identified a potential bug in solidity GMP

[mattac21]

I think my 3 pages look pretty good, I am no attestation light client expert so it was mostly a sanity check for accuracy, but things made sense to me and I thought it read well

[greptile-apps]

Greptile Summary

This PR adds a broad IBC documentation set covering protocol concepts, applications, light clients, Solidity contracts, and CLI workflows, along with tooling and tests that generate portions of the CLI/API reference.

• Introduces conceptual and implementation-level IBC documentation.
• Adds deployment, relayer, attestor, token-transfer, and GMP CLI tutorials.
• Adds a Python reference generator with unit and end-to-end tests.
• One tutorial workflow currently uses an unsupported CLI flag.

Confidence Score: 4/5

The PR should not merge until the unsupported --ws option is removed from the tutorial and command reference or implemented in the CLI.

The documented add-chain commands fail during argument parsing because the current Cobra command does not register the --ws option, blocking readers before they can continue the deployment workflow.

Files Needing Attention: docs/6-ibc-cli/2-tutorial-deploy-ibc-and-send-a-token.md and docs/6-ibc-cli/7-cli-commands.md

Important Files Changed

Filename	Overview
docs/6-ibc-cli/2-tutorial-deploy-ibc-and-send-a-token.md	Adds the end-to-end deployment and token-transfer tutorial, but both add-chain invocations use an unsupported --ws flag and stop the workflow.
docs/6-ibc-cli/7-cli-commands.md	Adds generated CLI command reference material but incorrectly lists --ws as an option for config add-chain.
docs/6-ibc-cli/tools/refgen.py	Adds source-driven CLI, configuration, and API documentation generation; no independently publishable generator defect was established.
docs/2-how-ibc-works/packet-lifecycle.md	Documents packet send, receive, acknowledgement, and timeout paths, including callback behavior and settlement guarantees.
docs/5-ibc-solidity-contracts/ics26-router.md	Adds detailed router contract documentation covering packet operations, verification, storage, callbacks, and permissions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Source["IBC and Link source"] --> Generator["refgen.py"]
  Generator --> Reference["Generated CLI/API reference"]
  Reference --> Reader["Documentation reader"]
  Tutorials["CLI tutorials"] --> Reader
  Reader --> CLI["ibc CLI"]
  CLI --> Workflow["Deploy and operate IBC"]

Loading

_{Reviews (1): Last reviewed commit: "docs: add IBC CLI tutorial, guides, and ..." | Re-trigger Greptile}

[greptile-apps]

Unsupported websocket flag blocks tutorial

When a reader runs this command, Cobra rejects the undocumented --ws implementation gap as an unknown flag because config add-chain registers only --chain-id, --rpc, --router, and --deployer, blocking the remainder of the deployment tutorial. The same unsupported flag is used again for the second chain and listed in the generated command reference.