Cosmos modules documentation
Runtime Verification is pleased to announce the successful completion of its engagement with Cosmos. The engagement focused on the staking and the distribution modules, which are core components of the Cosmos blockchain. The team focused on describing the code, ensuring correctness of the documentation and making it easier to understand.
Cosmos SDK and its modules
Before going into detail about the engagement and the results, here’s a primer on Cosmos and some of its features. [If you are familiar with the project, you may want to skip this part of the article].
Cosmos is a decentralized network of independent parallel blockchains, each powered by BFT consensus algorithms like Tendermint consensus. The vision of Cosmos is to make it easy for developers to build blockchains and break the barriers between blockchains by allowing them to transact with each other. This vision is achieved through a set of open source tools like Tendermint, the Cosmos SDK and IBC designed to let people build custom, secure, scalable and interoperable blockchain applications quickly.
The Cosmos SDK is an open-source framework for building multi-asset public Proof-of-Stake (PoS) blockchains, as well as permissioned Proof-Of-Authority (PoA) blockchains. At the moment, there are more than 240 apps and services built in the Cosmos ecosystem with the Cosmos SDK.
The goal of the Cosmos SDK is to create an ecosystem of modules that allows developers to easily spin up application-specific blockchains without having to code each bit of functionality of their application from scratch. Anyone can create a module for the Cosmos SDK, and using ready built modules in your blockchain is as simple as importing them into your application.
We focused on two key modules for this engagement, the staking module and the distribution module. Let's take a closer look at each of these modules:
-
The Staking module enables Cosmos SDK based blockchain to support an advanced Proof-of-Stake system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system.
-
The distribution module describes a functional way to passively distribute rewards between validators and delegators. Each validator has the opportunity to charge a commission to the delegators on the rewards collected on behalf of the delegators.
Methodology and results
Speaking with stakeholders from the Cosmos ecosystem, primarily core developers and developers supporting the Cosmos Hub, we agreed that ensuring correctness of the documentation was important. The documentation works as an informal specification for the modules. Our job was to make the documentation more exact and formal, sanity-check the code against it, and keep an eye open for edge cases and bugs. Each module is considered different from the others, and should be treated independently. The methodology applied by our team to check and re-write the staking and distribution modules documentation was the following:
- The first step consisted of checking the available code and understanding any differences between what the code was supposed to do and what it actually does; in other words, to check if the code behaved as intended. At the same time, the team audited the code in search of anything suspicious, including bugs that could impact security (Which we did find).
- The following step revolved around existing documentation. The team analyzed the content to ensure it was understandable and unambiguous, looked for parts that needed to be edited and important information missing. Having reliable documentation is vital for any project: easy to understand and follow, in sync with the latest updates, access to technical support, etc.
- The final step focused on adding new content, reinforcing key information and re-writing any parts that would help the final output. Once the documentation was finalized, it was shared with the Cosmos community, and the team worked on the feedback provided by their members.
We iterated over these steps many times, presented our work to the Cosmos team and gathered feedback until there was agreement on both what the code was doing, what it was supposed to do, and how the documentation made that clear. The code behaved as expected, and although some issues were discovered, the issues have been fixed at the time of writing this blog post. Some changes and diagrams were added to the staking module, while a lot of re-writing had to be done for the distribution module.
Some interesting results:
-
The team discovered an interesting undocumented feature: it's possible and safe to delegate to a jailed validator. The previous assumption stated that such delegation transactions would fail, but the results showed that it actually worked after running some tests and deploying it on-chain. A validator who has gotten out of jail will operate with their new increased delegation.
-
The Cosmos team conducted a security upgrade to remove the possibility to set bad distribution parameters which would have caused a panic and chain halt. Even if it was unlikely to come up in practice considering that the parameters in question are usually not in the range where the issue occurs, the necessary action was taken to fix the problem.
-
The distribution documentation unearthed a possibly dangerous bug in validator incentives. The validator (or a colluding group) could get another validator punished for a liveness infraction without any cost to the byzantine validator(s). By design, the block proposer will include pre-commits showing themselves and other validators participating properly in consensus. In this case, the proposer will get rewarded for including as many pre-commits as possible. The pre-commits are used to determine whether a validator is live, and a failure to submit pre-commits can lead to slashing and jailing. A bug in this incentive mechanism would mean that the block proposer can omit pre-commits from another validator without losing any rewards. The block proposer could also leave out pre-commits to reduce the previous validator's bonus, without affecting their own rewards. The Cosmos team is still out on whether there is any real danger.
The importance of writing accurate documentation and, depending on the case, getting a 3rd party opinion, it's fundamental to assure the highest quality and avoid possible security threats. Get in touch with our team of security experts at Runtime Verification to get help with all your needs, from documentation and smart contract audits to formal verification.
Rikard Hjort (Runtime Verification) would like to thank everyone from the Cosmos ecosystem participating in this project: Shahan Khatchadourian, Sam Hart, Sunny Aggarwal, Zaki Manian, Aleksandr Bezobchuk, Ethan Buchman, and Barrie Byron.
About Cosmos
Cosmos is a decentralized network of independent parallel blockchains, each powered by BFT consensus algorithms like Tendermint consensus.
About Runtime Verification
Runtime Verification is a technology startup based in Champaign-Urbana, Illinois. The company uses runtime verification-based techniques to perform security audits on virtual machines and smart contracts on public blockchains. It is dedicated to using its dynamic software analysis approach to improve the safety, reliability, and correctness of software systems in the blockchain field.