Improve DX: one-command local demo & troubleshooting guide for cosmos-ethereum-ibc-lcp

[ddkluchnikov]

Hi, and thanks for the great work on cosmos-ethereum-ibc-lcp and the related IBC/LCP tooling.
While going through the repository, the demo is very powerful but a bit hard to approach for newcomers because the setup spans multiple components (Cosmos chain, Ethereum node, contracts, relayer, LCP/TEE).

Motivation

• Running the full Cosmos ↔ Ethereum bridge demo currently requires multiple manual steps and coordination of several moving parts.
• It is easy to get stuck on environment issues (versions, Docker, SGX/TEE, relayer config, gas limits, etc.), especially for first‑time users of IBC+LCP.
• A more streamlined “DX layer” around the demo could make it much easier for developers to try, debug and build on top of this work.

Proposal

1. One‑command local demo script / Makefile target

   • Add a single entry point to run the local Cosmos ↔ Ethereum bridge demo end‑to‑end, e.g.:
     • make demo-up or make e2e-local, or
     • ./scripts/demo_local.sh.
   • This command should, as much as possible:
     • start the required local chains (Cosmos, Ethereum) and any necessary services/containers;
     • deploy the required contracts on Ethereum;
     • configure and start the relayer;
     • initialize / start the LCP/TEE (or emulator) with the expected configuration;
     • run a minimal e2e test (e.g. send a packet Cosmos → Ethereum and verify it was processed).
   • The script/target can print a short summary at the end (which chains are running, which channels are open, how to send an additional test transfer or query logs).

2. Short “Quick Start” section in README

   • Introduce a brief “Quick Start” section near the top of the README for people who just want to run the demo in 5–10 minutes.
   • Suggested structure:
     • Prerequisites: list required tools (Go, Rust if needed, Docker, SGX/SGX emulator, minimal versions of ibc‑solidity, relayer, etc.).
     • Clone & run: a minimal sequence like:
       • git clone ...
       • cd cosmos-ethereum-ibc-lcp
       • make demo-up (or another agreed command).
     • What you should see: a short description of the expected successful state (chains running, channels established, one test transaction relayed).

3. Troubleshooting / FAQ

   • Add a dedicated “Troubleshooting” or “FAQ” section to the README (or a separate TROUBLESHOOTING.md) with the most common issues developers may hit while running the demo.
   • Example entries (to be adjusted based on your experience):
     • version mismatches between ibc‑solidity / relayer / LCP components;
     • local Ethereum node issues (gas limits, chain ID, RPC config);
     • SGX/TEE initialization problems (missing environment variables, emulator vs real SGX, attestation errors);
     • relayer failures when channels/connections are not properly set up or when one of the chains is not fully started.
   • For each problem:
     • show a recognizable error snippet;
     • provide a short explanation;
     • list 1–3 concrete steps to fix it.

What I can contribute

• I can prepare a PR that:
  • adds a draft one‑command local demo script or Makefile target;
  • introduces a “Quick Start” section to the README;
  • adds an initial Troubleshooting/FAQ section with common errors and fixes, which can be refined based on your feedback.

If this direction sounds useful, I’ll be happy to implement the initial version and iterate on it based on your suggestions.