Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Hello and Developer Tutoritials index.md, simple change case #2019

Merged
merged 2 commits into from
Jan 26, 2022
Merged

docs: Hello and Developer Tutoritials index.md, simple change case #2019

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fb5ab93
Hello and index change case
barriebyron Jan 25, 2022
125021f
simple case change, typo fix, some minor edits
barriebyron Jan 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions docs/guide/hello.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ order: 2
description: Step-by-step guidance to build your first blockchain and your first Cosmos SDK module.
---

# Hello, World
# Hello, Starport

This tutorial is a great place to start your journey into the Cosmos ecosystem. Instead of wondering how to build a blockchain, follow these steps to build your first blockchain and your first Cosmos SDK module.

## Get Started
## Get started

In the previous chapter you've learned how to install [Starport](https://github.com/tendermint/starport), the tool that offers everything you need to build, test, and launch your blockchain with a decentralized worldwide community.

Expand Down Expand Up @@ -38,7 +38,7 @@ This new blockchain imports standard Cosmos SDK modules, including:

Now that you have run your first command, take a minute to see all of the command line options for the `scaffold` command. You can use --help on any command. Run the `starport scaffold chain --help` command to learn about the command you just used.

## Blockchain Directory Structure
## Blockchain directory structure

After you create the blockchain, switch to its directory:

Expand All @@ -52,7 +52,7 @@ The `hello` directory contains a number of generated files and directories that
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| app/ | Files that wire together the blockchain. The most important file is `app.go` that contains type definition of the blockchain and functions to create and initialize it. |
| cmd/ | The main package responsible for the CLI of compiled binary. |
| docs/ | Directory for project's documentation. By default, an OpenAPI spec is generated. |
| docs/ | Directory for project documentation. By default, an OpenAPI spec is generated. |
| proto/ | Protocol buffer files describing the data structure. |
| testutil/ | Helper functions for testing. |
| vue/ | A Vue 3 web app template. |
Expand All @@ -61,19 +61,19 @@ The `hello` directory contains a number of generated files and directories that

Now you can get your blockchain up and running locally on a single node.

## Start a Blockchain
## Start a blockchain

You already have a fully-functional blockchain. To start your chain on your development machine, run the following command in the `hello` directory

```bash
starport chain serve
```

This command downloads dependencies and compiles the source code into a binary called `hellod`. By default, Starport uses the name of the repo + `d`. From now on, use this binary to run all of your chain commands. For example, to initialize a single validator node and start a node.
This command downloads dependencies and compiles the source code into a binary called `hellod`. By default, the binary name is the name of the repo + `d`. From now on, use this `hellod` binary to run all of your chain commands. For example, to initialize a single validator node and start a node.

## HTTP API Console
## HTTP API console

By default a validator node exposes two API endpoints:
By default, a validator node exposes two API endpoints:

- [http://localhost:26657](http://localhost:26657) for the low-level Tendermint API
- [http://localhost:1317](http://localhost:1317) for the high-level blockchain API
Expand All @@ -82,34 +82,34 @@ Now that you started your `hello` chain, you can use a web browser to see the hi

![./images/api.png](./images/api.png)

## Stop a Blockchain
## Stop a blockchain

When you want to stop your blockchain, press Ctrl+C in the terminal window where it's running.
When you want to stop your blockchain, press control+C in the terminal window where it's running.

In the development environment, you don't have to restart the blockchain after you make changes. All changes you make in the `hello` directory files are automatically picked up by Starport.
In the development environment, you don't have to restart the blockchain after you make changes. Because Starport server hot reloads, all changes you make in the `hello` directory files are automatically detected.

## Say "Hello, Starport"

To get your Cosmos SDK blockchain to say "Hello", you need to make these changes:
To get your blockchain to say "Hello", you need to make these changes:

- Modify a protocol buffer file
- Create a keeper query function that returns data
- Register a query function

Protocol buffer files contain proto rpc calls that define Cosmos SDK queries and message handlers, and proto messages that define Cosmos SDK types. rpc calls are also responsible for exposing an HTTP API.
Protocol buffer files contain proto rpc calls that define Cosmos SDK queries and message handlers, and proto messages that define Cosmos SDK types. The rpc calls are also responsible for exposing an HTTP API.

For each Cosmos SDK module, the [Keeper](https://docs.cosmos.network/master/building-modules/keeper.html) is an abstraction for modifying the state of the blockchain. Keeper functions let you query or write to the state. After you add the first query to your chain, you must register the query. You only need to register a query once.
For each Cosmos SDK module, the [Keeper](https://docs.cosmos.network/master/building-modules/keeper.html) is an abstraction for modifying the state of the blockchain. Keeper functions let you query or write to the state. After you add the first query to your chain, the next step is to register the query. You only need to register a query once.

In terms of workflow, developers typically follow this sequence:

- Start with proto files to define Cosmos SDK [messages](https://docs.cosmos.network/master/building-modules/msg-services.html)
- Define and register [queries](https://docs.cosmos.network/master/building-modules/query-services.html)
- Define message handlers logic
- Finally, implement the logic of these queries and message handlers in keeper functions.
- Define message handler logic
- Finally, implement the logic of these queries and message handlers in keeper functions

## Create a Query
## Create a query

Create a `posts` query:
To create a `posts` query:

```bash
starport scaffold query posts --response title,body
Expand All @@ -126,7 +126,7 @@ The `query` command has created and modified several files:

Let's examine some of these changes. For clarity, the following code blocks do not show the placeholder comments that Starport uses to scaffold code. Don't delete these placeholders since they are required to continue using Starport's scaffolding functionality.

### Updates to the Query Service
### Updates to the query qervice

In the `proto/hello/query.proto` file, the `Posts` rpc has been added to the `Query` service.

Expand All @@ -145,7 +145,7 @@ Here's how the `Posts` rpc for the `Query` service works:
- Returns response of type `QueryPostsResponse`
- The `option` defines the endpoint that is used by gRPC to generate an HTTP API

### Request and Reponse Types
### Request and reponse types

Now, take a look at the following request and response types:

Expand All @@ -162,7 +162,7 @@ message QueryPostsResponse {
- The `QueryPostsRequest` message is empty because requesting all posts doesn't require parameters.
- The `QueryPostsResponse` message contains `title` and `body` that is returned from the chain.

## Posts Keeper Function
## Posts keeper function

The `x/hello/keeper/grpc_query_posts.go` file contains the `Posts` keeper function that handles the query and returns data.

Expand All @@ -185,7 +185,7 @@ Here's all of the actions the `Posts` function does:

Right now the response is empty.

### Update Keeper Function
### Update keeper function

From the `query.proto` file we know that response accepts `title` and `body`, so use a text editor to modify the `x/hello/keeper/grpc_query_posts.go` file that contains the keeper function. On the last line of the keeper function, change the line to return a "Hello!":

Expand All @@ -198,7 +198,7 @@ func (k Keeper) Posts(c context.Context, req *types.QueryPostsRequest) (*types.Q

Save the file to restart your chain. Visit the [posts endpoint](http://localhost:1317/cosmonaut/hello/hello/posts), you see a `Not Implemented` error. This message is expected behavior, because you still need to register the query handlers with gRPC.

## Register Query Handlers
## Register query handlers

Make the required changes to the `x/hello/module.go` file.

Expand Down
57 changes: 31 additions & 26 deletions docs/guide/ibc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,7 @@ title: "Inter-Blockchain Communication: Basics"

# Inter-Blockchain Communication: Basics

The Hello World example is a time-honored tradition in computer programming.

The Inter-Blockchain Communication protocol (IBC) is an important part of the Cosmos SDK ecosystem.

This tutorial builds an understanding of how to create and send packets across blockchain. This foundational knowledge helps you navigate between blockchains with the Cosmos SDK.
The Inter-Blockchain Communication protocol (IBC) is an important part of the Cosmos SDK ecosystem. The Hello World tutorial is a time-honored tradition in computer programming. This tutorial builds an understanding of how to create and send packets across blockchain. This foundational knowledge helps you navigate between blockchains with the Cosmos SDK.

**You will learn how to**

Expand All @@ -20,13 +16,15 @@ This tutorial builds an understanding of how to create and send packets across b

## What is IBC?

The IBC module in the Cosmos SDK is the standard for the interaction between two blockchains. The IBC module defines how packets and messages are constructed to be interpreted by the sending and the receiving blockchain.
The Inter-Blockchain Communication protocol (IBC) allows blockchains to talk to each other. IBC handles transport across different sovereign blockchains. This end-to-end, connection-oriented, stateful protocol provides reliable, ordered, and authenticated communication between heterogeneous blockchains.

The [IBC protocol in the Cosmos SDK](https://docs.cosmos.network/master/ibc/overview.html) is the standard for the interaction between two blockchains. The IBCmodule interface defines how packets and messages are constructed to be interpreted by the sending and the receiving blockchain.

The IBC relayer lets you connect between sets of IBC-enabled chains. This tutorial teaches you how to create two blockchains and then start and use the relayer with Starport to connect two blockchains.

This tutorial covers essentials like modules, IBC packets, relayer, and the lifecycle of packets routed through IBC.

## Create a Blockchain
## Create a blockchain

Create a blockchain app with a blog module to write posts on other blockchains that contain the Hello World message. For this tutorial, you can write posts for the Cosmos SDK universe that contain Hello Mars, Hello Cosmos, and Hello Earth messages.

Expand All @@ -46,11 +44,11 @@ After the transaction is acknowledged by the receiving chain, you know that the

![The Lifecycle of an IBC packet in the Blog Module](./images/packet_sendpost.png)

## Build your Blockchain App
## Build your blockchain app

Use Starport to scaffold the blockchain app and the blog module.

### Build the new blockchain
### Build a new blockchain

To scaffold a new blockchain named `planet`:

Expand Down Expand Up @@ -101,7 +99,7 @@ These `starport type` commands create CRUD code for the following transactions:

The scaffolded code includes proto files for defining data structures, messages, messages handlers, keepers for modifying the state, and CLI commands.

### Starport Scaffold List Command Overview
### Starport scaffold list command overview

```go
starport scaffold list [typeName] [field1] [field2] ... [flags]
Expand All @@ -113,11 +111,11 @@ The next arguments define the fields that are associated with the type. For the

The `--module` flag defines which module the new transaction type is added to. This optional flag lets you manage multiple modules within your Starport app. When the flag is not present, the type is scaffolded in the module that matches the name of the repo.

When a new type is scaffolded, the default behavior is to scaffold messages that can be sent by users for CRUD operations. The `--no-message` flag disables this feature. We provide this option for our app since we want the posts to be created upon reception of IBC packets and not directly from the user's messages.
When a new type is scaffolded, the default behavior is to scaffold messages that can be sent by users for CRUD operations. The `--no-message` flag disables this feature. Disable the messages option for the app since you want the posts to be created upon reception of IBC packets and not directly created from a user's messages.

### Scaffold a sendable and interpretable IBC packet

Now you need to generate code for a packet that contains the title and the content of the blog post.
You must generate code for a packet that contains the title and the content of the blog post.

The `starport packet` command creates the logic for an IBC packet that can be sent to another blockchain.

Expand All @@ -143,15 +141,15 @@ The `starport packet` command also scaffolds the CLI command that is capable of
planetd tx blog send-ibcPost [portID] [channelID] [title] [content]
```

## Modify the Source Code
## Modify the source code

After you create the types and transactions, you must manually insert the logic to manage updates in the database. Modify the source code to save the data as specified earlier in this tutorial.

### Add creator to the blog post packet

Start with the proto file that defines the structure of the IBC packet.

To identify the creator of the post in the receiving blockchain, add the creator field inside the packet. This field was not specified directly in the command because it would automatically become a parameter in the `SendIbcPost` CLI command.
To identify the creator of the post in the receiving blockchain, add the `creator` field inside the packet. This field was not specified directly in the command because it would automatically become a parameter in the `SendIbcPost` CLI command.

```proto
// planet/proto/blog/packet.proto
Expand All @@ -162,7 +160,10 @@ message IbcPostPacketData {
}
```

To make sure the receiving chain has content on the creator of a blog post, add this value to the IBC `packet`. The content of the `sender` of the message is automatically included in `SendIbcPost` message. The sender is verified as the signer of the message, so you can add the `msg.Sender` as the creator to the new packet before it is sent over IBC.
To make sure the receiving chain has content on the creator of a blog post, add the `msg.Creator` value to the IBC `packet`.

- The content of the `sender` of the message is automatically included in `SendIbcPost` message.
- The sender is verified as the signer of the message, so you can add the `msg.Sender` as the creator to the new packet before it is sent over IBC.

```go
// x/blog/keeper/msg_server_ibc_post.go
Expand Down Expand Up @@ -208,15 +209,19 @@ Append the type instance as `PostID` on receiving the packet:
- The `title` is the Title of the blog post
- The `content` is the Content of the blog post

In the `ibc_post.go` file, make sure to import `"strconv"` below `"errors"`, and then modify `OnRecvIbcPostPacket` with the following code:
In the `x/blog/keeper/ibc_post.go` file, make sure to import `"strconv"` below `"errors"`:

```go
// x/blog/keeper/ibc_post.go
import (
//...
"strconv"
)
```

Then modify the `OnRecvIbcPostPacket` keeper function with the following code:

```go
func (k Keeper) OnRecvIbcPostPacket(ctx sdk.Context, packet channeltypes.Packet, data types.IbcPostPacketData) (packetAck types.IbcPostPacketAck, err error) {
// validate packet data upon receiving
if err := data.ValidateBasic(); err != nil {
Expand Down Expand Up @@ -296,7 +301,7 @@ func (k Keeper) OnTimeoutIbcPostPacket(ctx sdk.Context, packet channeltypes.Pack

This last step completes the basic `blog` module setup. The blockchain is now ready!

## Use the IBC Modules
## Use the IBC modules

You can now spin up the blockchain and send a blog post from one blockchain app to the other. Multiple terminal windows are required to complete these next steps.

Expand All @@ -306,7 +311,7 @@ To test the IBC module, start two blockchain networks on the same machine. Both

One blockchain is named `earth` and the other blockchain is named `mars`.

The following files are required in the project directory:
The `earth.yml` and `mars.yml` files are required in the project directory:

```yaml
# earth.yml
Expand Down Expand Up @@ -366,17 +371,17 @@ Open a different terminal window and run the following command to start the `mar
starport chain serve -c mars.yml
```

### Remove Existing Relayer and Starport Configurations
### Remove existing relayer and Starport configurations

If you previously used the relayer, follow these steps to remove exiting relayer and Starport configurations:
If you previously used the relayer, follow these steps to remove existing relayer and Starport configurations:

- Stop your blockchains and delete previous configuration files:

```bash
rm -rf ~/.starport/relayer
```

If existing configurations do not exist, the command returns `no matches found` and no action is taken.
If existing relayer configurations do not exist, the command returns `no matches found` and no action is taken.

### Configure and start the relayer

Expand All @@ -400,7 +405,7 @@ starport relayer configure -a \
--target-gaslimit 300000
```

After you hit enter, it will ask for the `Source Account` and `Target Account`. Use default for both accounts.
When prompted, press Enter to accept the default values for `Source Account` and `Target Account`.

The output looks like:

Expand All @@ -422,7 +427,7 @@ Setting up chains
⛓ Configured chains: earth-mars
```

Then, start the relayer process in a separate terminal window:
In a new terminal window, start the relayer process:

```bash
starport relayer connect
Expand Down Expand Up @@ -543,11 +548,11 @@ pagination:

## Congratulations 🎉

By completing this tutorial, you've learned to build an IBC module for the Cosmos SDK, build your own blockchain app, modify the source code, and use the Inter-Blockchain Communication protocol (IBC).
By completing this tutorial, you've learned to use the Inter-Blockchain Communication protocol (IBC).

Here's what you accomplished in this tutorial:

- Built a Hello World blockchain app as an IBC module
- Built two Hello blockchain apps as IBC modules
- Modified the generated code to add CRUD action logic
- Used the relayer to connect two blockchains with each other
- Configured and used the Starport relayer to connect two blockchains with each other
- Transferred IBC packets from one blockchain to another
Binary file modified docs/guide/images/api.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading