IBC Improvements

src/pages/ibc.mdx

@@ -4,13 +4,14 @@ tags: ["ibc"]
 
 # Introduction
 
-IBC is a protocol that allows different blockchains to communicate with each other. It is a standard
-that defines how blockchains can send and receive messages to each other. This allows for the
-creation of a network of blockchains that can interact with each other.
+IBC is a standard that defines how blockchains can send and receive messages to each other. This
+allows for the creation of a network of blockchains that can interact with each other.
 
 You can use the IBC protocol as a building block to create your own custom protocols on top of it,
 but you can also use existing protocols like the [ICS-20 token transfer protocol]. In the following sections,
-we will explain how both of these work.
+we will explain how both of these work. Using CosmWasm for this gives you a key advantages over writing
+a custom Cosmos SDK module in Go: you can easily deploy and upgrade your contract without having to go
+through a full chain upgrade (on multiple chains, mind you).
 
 [ICS-20 token transfer protocol]:
  https://github.com/cosmos/ibc/blob/main/spec/app/ics-020-fungible-token-transfer/README.md

src/pages/ibc/_meta.json

@@ -1,6 +1,6 @@
 {
  "getting-started": "Getting started",
  "basic-concepts": "Basic concepts",
- "existing-protocols": "Using existing protocols",
- "diy-protocol": "Build your own protocol"
+ "diy-protocol": "Build your own protocol",
+ "existing-protocols": "Using existing protocols"
 }

src/pages/ibc/basic-concepts.mdx

@@ -6,15 +6,48 @@ tags: ["ibc"]
 
 In order to understand how IBC works, it is important to understand some basic concepts:
 
-- **Port**: An identifier that corresponds to a single module on a chain. One module can have
- multiple ports. Each contract has its own unique port.
+- **Port**: Every instantiation of an ibc-enabled contract creates a unique port, similarly to how
+ it creates a unique address. Native Cosmos SDK modules can also have one or multiple unique ports.
 - **Channel**: A connection between two ports on different blockchains that allows them to send
  packets to each other. Each port can have multiple channels.
-- **Relayer**: A service that is responsible for passing packets between blockchains. The relayer
- watches for new packet commitments on one chain and submits them to the other chain. This is the
- way in which your packets actually reach the other chain. Anyone can run a relayer.
 - **Packet**: A piece of binary data that is sent through a channel. It can time out if it is not
  delivered within a certain time frame.
+- **Relayer**: An off-chain service that is responsible for passing packets between blockchains. The
+ relayer watches for new packet commitments on one chain and submits them to the other chain. This
+ is the way in which your packets actually reach the other chain. Anyone can run a relayer.
+
+Here's an example diagram of how these concepts are related:
+
+```mermaid
+graph LR;
+subgraph AA [Chain A]
+A[contract];
+B[port 1];
+H[channel 1];
+I[channel 2];
+end
+subgraph BB [Chain B]
+J[channel 1];
+K[channel 2];
+E[port 1];
+F[port 2];
+G[port 3];
+C[contract];
+D[module];
+end
+A --- B;
+B --- H;
+B --- I;
+
+H <-->|relayer| J;
+I <-->|relayer| K;
+
+J --- E;
+K --- F;
+E --- C;
+F --- D;
+G --- D;
+```
 
 We will go into more detail on how these concepts are related to CosmWasm in the later sections, but
 this should give you some basic terminology to start with. If you want to learn more about IBC, you

src/pages/ibc/getting-started.mdx

@@ -2,6 +2,8 @@
 tags: ["ibc"]
 ---
 
+import { Callout } from "nextra/components";
+
 # Getting started
 
 To get started, you need to enable the `stargate` feature of the `cosmwasm-std` crate. This will
@@ -11,8 +13,7 @@ enable additional functionality that is not available on all chains, including I
 cosmwasm-std = { version = "2.0.3", features = ["stargate"] }
 ```
 
----
-
-Notes:
-
-- add reference to core capabilities section
+<Callout type="info">
+ The naming "stargate" is somewhat confusing. It is a reference to the Cosmos SDK 0.40 upgrade with
+ the same name. This upgrade introduced (among other things) IBC.
+</Callout>