Cosmos Code Review: Dammit, Time To Build

Billions and billions of reasons to use this SDK...

Cosmos Code Review Time To Build

Share this article

Let’s start this Cosmos code review with a look at the claims. Well, just this one really, because it’s kind of a biggie. “Cosmos solves today’s hardest blockchain problems.”

  • Scalability — Tendermint BFT fixes this
  • Usability — Cosmos SDK fixes this
  • Interoperability — IBC protocol fixes this

Only three items, but a lot to unpack here. Cosmos is a big mixed bag of different things, so sometimes it’s a bit tricky to know what we are talking about. We have the following;

  • Cosmos — The foundation
  • Tendermint — The pBFT consensus engine
  • Cosmos SDK — The software package / collection that allows you to build dapps (but not in the ethereum smart contract sense, rather in the blockchain per dapp sense)
  • IBC — A protocol for communication
  • Amino — A specific protocol for data transference (protobuff essentially — this statement is overly simplified, but it’s not that important right now)
  • Gaia — The first cosmos “hub” that is built with Cosmos SDK that runs on tendermint

So anyone can build a dapp (blockchain) by using the Cosmos SDK (Software Development Kit) that runs on Tendermint and by using Cosmos it becomes IBC compliant and thus can be interoperable.

So the scalability is addressed via two areas, area 1 Tendermint pBFT and area 2 that each dapp has it’s own consensus system (Tendermint). So if you build a Cosmos dapp you aren’t building it on Gaia, you are building a completely new blockchain, but because it is IBC compliant it can interact with other blockchains built with Cosmos SDK (thus interoperable)

Usability, is because of Cosmos SDK, which wraps all the tricky bits, the consensus, the communication, the p2p, all taken care off with the Cosmos SDK.

So the mix above covers, scalability, usability, and interoperability.

The above has some interesting implications on the token side, since other than Gaia (which is sort of a demo example of Cosmos SDK) there isn’t really anything to do with Atom. You don’t need it to build your own Cosmos blockchain, you don’t need it for IBC or interoperability. You just kind of stake it and that’s it, since Gaia doesn’t support building on top of it. That aside, let’s look at Gaia and drill down from there.

Only 20 commits? Normally a big warning sign. Here it’s 100% ok, because this is just the implementation of Cosmos SDK, the real work is in Cosmos SDK and Tendermint. Which we will get into later. Gaia itself is a fairly small, straight forward code base, and that’s really because it’s just the “demo” for Cosmos SDK. Cosmos SDK and Tendermint are the real heavy lifters. But let’s see how it works.

Golang project, so we start with /cmd/

gaiacli — command line interface, used for creating accounts, sending transfers, checking balances. This wraps around the RPC / HTTP endpoints, so we will look into it, but first, we want gaiad — daemon, this runs the nodes / software.

All the usual include candidates, cobra/viper for command line. Tendermint here is interesting, cosmos-sdk makes sense.

Bech32 prefixes for accounts, validators, and consensus nodes. Usual command candidates.

Pruning, MinGasPrice, HaltHeight and then we are sort of done. That’s it, this starts our blockchain. So the real work happens in NewGaiaApp, so let’s go hunt it down. Head over to cosmos/giaia/app


This gives a good overview of what is required to import from Cosmos SDK, baseapp is the core skeleton, codec handles all inter component communication, auth and bank for basic accounts and transfers. Distribution, mint (block rewards), slashing (bad behavior), staking (dPoS) all included. This is really all you need.

Just setup and initialization of the components, this file will mostly have setup boilerplate.

This is copy / paste stuff, just need to setup the key value stores, then you need to setup all the keepers (keepers manage all the work — we will get into them later)

AddRoute for proposals (http/rpc), allow community to setup and vote on proposals.

This is interesting, SetOrderBeginBlockers, we do mint, then distribution, then slashing, versus setOrderEndBlockers we do govern and then staking. So we first generate block minting, then distribute it, and then slash following by delegation rewards (after block). I’ll have to dig deeper to see why it’s this order.

Again, mostly boilerplate from Cosmos SDK.

And that’s kinda it.

Networks is setup scripts. docs is documentation, the rest is test systems. That’s all the “code” you need to run your own Gaia (Atom staking system — which is really all it is).

And that’s a really good sign, it shows you how powerful Cosmos SDK and Tendermint are.

Now to be fair, if this was another blockchain other than Gaia (which is Cosmos) I would be utterly unimpressed, since they didn’t do anything, but since Gaia is Cosmos is Cosmos SDK is Tendermint we can keep going.

Cosmos SDK, the real secret sauce. 5k commits, 86 branches, 112 releases, 92 contributors, this thing is as active as any of the big boys. Great PR and Issue management, great abstraction and encapsulation. We see a lot from here we already saw in the Gaia implementation, we have;

baseapp — the core client — client interacting with the server codec — manages all the comms server — runs the server side store — handles all the storage x — this is where all the core modules go

In x/ we have auth, bank, distribution, ibc, gov, mint, slashing, staking. Everything required to make your own interoperable high scalability dPoS blockchain in less than 100 lines of code.

anteHandler for fee and auth, begin / end block is where you do most of your work, what do you want to happen before you get a block and what after. This is where you normally put most of your work logic (gaia didn’t really need it). Peer filters, state checkers, version management. This is just fantastic production level code.

Not much to say, it’s just really impressive how tendermint, abci, cosmos sdk all interact with each other. It’s really well designed and thought out architecture.

Not going to go into this too much, client side, keys, rpc, tx generation. Blockchain boilerplate, even if it is fantastic blockchain boilerplate.

Codec is an amino wrapper. Amino is solid as well. But /x/ is where the real work is, so let’s go have a look at bank / mint / slashing / staking

We start from keeper.

Keeper defines what we can do;

Setcoins SubtractCoins AddCoins InputOutputCoins DelegateCoins UndelegateCoins

So the thing to note at this point, Keepers are functionality wrappers. When you bring it all down to zero, the difficult part in blockchain is the distributed systems part, consensus. This is handled by Tendermint, and consensus is basically a “save” barrier. Normally you would simply say 10+10=20 so let’s save 20 in the store (database). In this case you need consensus, but it’s taken care off without you needing to worry about it, so you can just say 10+10=20 and store. So all the Keepers are just simple basic functionality.

So for something like AddCoins, it simply takes an address, a coin type, and then adds the amount.

Really as simplistic as that.

This is side effect free code btw, not something you see often, great design principals.

Cosmos Code Review Conclusion:

Gaia is kinda pointless, it’s just a demo of Cosmos SDK, but damn, Cosmos SDK is good. Think I’ll start building a few chains with it as well.

UPDATE 6/10/19: Thanks to Alessio Treglia, a Senior Software Consultant for the Tendermint team, who added that “Gaia is 20 commits only as it has recently been extracted from its original location in the repo.”

Disclaimer: Crypto Briefing code reviews are performed by auditing what is on display in the master branch of the repo’s made available. This was performed as an educational review and any comments in the article are the opinion of the writer. It is normal for code to change rapidly, hence we timestamp our code reviews so that they present a snapshot at a moment in time. Information contained herein should not be used as any comment or advice on the project as a whole.

Cosmos Code Review Timestamp: June 5th, 2019

Share this article