Starport

synopsis

Before diving into the details of how Starport helps you scaffold the basics for your application blockchain make sure to understand the main concepts presented in the following sections:

• A Blockchain App Architecture
• Accounts
• Transactions
• Messages
• Modules
• Protobuf
• BaseApp

You can follow a hands-on exercise for Starport in the sections that follow this introduction.

The Cosmos SDK provides the building blocks for a complete Tendermint blockchain, which implements the Inter-Blockchain Communication Protocol (IBC). The BaseApp of the Cosmos SDK assembles these building blocks and provides a fully-running blockchain. All there is left to do for the specific blockchain application is to create specific modules and integrate them with BaseApp to make the application your own.

Starport assists with scaffolding modules and integrating them with BaseApp. Starport is a command-line tool that writes code files and updates them when instructed to do so. If you come from an on Rails world, the concept will look familiar to you.

On top of that Starport will handle some compilation, run a local blockchain node, and help you with other tasks.

Install

Want to dedicate some time to dive deeper into installing Starport? Have a look at how to install Starport in the Starport Developer Guide (opens new window).

To install Starport at the command line:

Copy $ curl https://get.starport.com/starport! | bash

You can verify the version of Starport you have once it is installed:

Copy $ starport version Starport version: v0.17.3 ...

This entire exercise was built using the Starport version noted above. Using a newer version could work, but you might run into compatibility issues if you clone any code made with this version of Starport and then try to continue the project with your version of Starport.

To install this specific version of Starport, use:

Copy curl https://get.starport.network/starport@v0.17.0! | bash

If you'd like to upgrade an existing project to the latest version of Starport, you can follow the Starport migration documentation (opens new window).

You can also just type starport to see the offered commands:

Copy Starport is a tool for creating sovereign blockchains built with Cosmos SDK, the world’s most popular modular blockchain framework. Starport offers everything you need to scaffold, test, build, and launch your blockchain. To get started create a blockchain: starport scaffold chain github.com/cosmonaut/mars Usage: starport [command] Available Commands: scaffold Scaffold a new blockchain, module, message, query, and more chain Build, initialize and start a blockchain node or perform other actions on the blockchain generate Generate clients, API docs from source code network Launch a blockchain network in production relayer Connects blockchains via IBC protocol tools Tools for advanced users docs Show Starport docs version Print the current build information help Help about any command Flags: -h, --help help for starport Use "starport [command] --help" for more information about a command.

Your chain

Start by scaffolding a basic chain called checkers that you will place under the GitHub path alice with:

Copy $ starport scaffold chain github.com/alice/checkers

The scaffolding takes some time as it generates the source code for a fully functional ready-to-use blockchain. Starport creates a folder named checkers and scaffolds the chain inside it.

The checkers folder contains several generated files and directories that make up the structure of a Cosmos SDK blockchain. It contains the following folders:

• app: a folder for the application.
• cmd: a folder for the command-line interface commands.
• proto: a folder for the Protobuf objects definitions.
• vue: a folder for the UI.
• x: a folder for all your own modules, in particular checkers.

If Vue.js is something new to you, check out the Vue.js website (opens new window) for more on this JavaScript framework.

If you look at the code that Starport generates, for instance in ./x/checkers/module.go, you will often see comments like the following:

Copy // this line is used by starport scaffolding # 1

Caution: Do not remove or replace any such lines in your code as they provide markers for Starport on where to add further code when instructed to do so. For the same reason, do not rename or move any file that contains such a line.

Go to the checkers folder and run:

Copy $ cd checkers $ starport chain serve

The starport chain serve command downloads dependencies and compiles the source code into a binary called checkersd. The command:

• Installs all dependencies.
• Builds Protobuf files.
• Compiles the application.
• Initializes the node with a single validator.
• Adds accounts.

After this command completes, you have a local testnet with a running node. What about the added accounts? Take a look at:

In this file, you can set the accounts, the accounts' starting balances, and the validator. You can also let Starport generate a client and a faucet. The faucet gives away five token and 100,000 stake tokens belonging to Bob each time it is called.

You can observe the endpoints of the blockchain in the output of the starport chain serve command:

Copy 🌍 Tendermint node: http://0.0.0.0:26657 🌍 Blockchain API: http://0.0.0.0:1317 🌍 Token faucet: http://0.0.0.0:4500

Starport can detect any change to the source code. When it does, it immediately rebuilds the binaries before restarting the blockchain and keeping the state.

Your GUI

Now boot up the frontend created by Starport by using the commands provided in the readme.md file of the checkers folder. For this you let the chain run in its own process and open a new terminal window in your checkers folder. In this terminal execute:

Copy $ cd vue $ npm install $ npm run serve

Navigate to localhost:8080 (opens new window). On the client side no wallets have been created or imported yet. Load Alice's wallet in the GUI to have some tokens. You will need to use the mnemonic for Alice which you can find in the output of the starport chain serve command. Copy and paste it to import a wallet.

Now you should see the balance of Alice's account and can act on her behalf.

Select Custom Type in the sidebar to see custom types. There are no custom types yet, this page is empty for now.

It is good practice to make a Git commit before you create a new message. In fact, it is generally recommended to make a Git commit before running any starport scaffold command. A Git commit protects the work you have done so far and makes it easier to see what the scaffold command added. It also makes it easy to just revert all changes if you are unsatisfied and want to run a different scaffold command.

Your first message

With your Git commit tucked away, now create a simple message with:

Copy $ starport scaffold message createPost title body

The starport scaffold message command accepts a message name, here createPost, as the first argument, and a list of fields for the message, here title and body, which are strings unless mentioned otherwise.

A message is scaffolded in a module with a name that matches the name of the project by default. It is named checkers in this case. Or you could have used --module checkers. Learn more about your options with:

Copy $ starport scaffold message --help

You can see a list of files that were created or modified by the scaffold message command in the Terminal output:

Copy modify proto/checkers/tx.proto modify x/checkers/client/cli/tx.go create x/checkers/client/cli/tx_create_post.go modify x/checkers/handler.go create x/checkers/keeper/msg_server_create_post.go modify x/checkers/types/codec.go create x/checkers/types/message_create_post.go

The modify was made possible thanks to the lines like // this line is used by starport scaffolding # 1 that you did not remove. So where is everything? You can find the root definition of your new message in:

Starport also wired a new command into your chain's CLI in:

Starport scaffolded GUI elements relating to your message with a Vue.js frontend framework. You can, for instance, start with this function in:

Next up

You just created a fully working Cosmos SDK chain, one that forms the basis of the following exercise.

You can remove the MsgCreatePost message as it is not part of the guided exercise in the next sections. You can clean it all by running:

Copy $ git checkout -f && git clean -fd