From 85316e9388660c4b4ab995bfeec99fa7c9ba7ffe Mon Sep 17 00:00:00 2001 From: Adrian Brink Date: Sat, 3 Mar 2018 20:38:24 +0100 Subject: [PATCH] Explanation on how the module system works --- examples/basecoin/README.md | 68 +++++++++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/examples/basecoin/README.md b/examples/basecoin/README.md index ed667535d..e6de9480d 100644 --- a/examples/basecoin/README.md +++ b/examples/basecoin/README.md @@ -1,8 +1,70 @@ -This is the "Basecoin" example application built on the Cosmos-SDK. This +# Basecoin + +This is the "Basecoin" example application built on the Cosmos-Sdk. This "Basecoin" is not affiliated with [Coinbase](http://www.getbasecoin.com/), nor the [stable coin](http://www.getbasecoin.com/). -Assuming you've run `make get_tools && make get_vendor_deps` from the root of this repository, -run `make build` here to build the `basecoind` and `basecli` binaries. +Assuming you've run `make get_tools && make get_vendor_deps` from the root of +this repository, run `make build` here to build the `basecoind` and `basecli` +binaries. If you want to create a new application, start by copying the Basecoin app. + + +# Building your own Blockchain + +Basecoin is the equivalent of an ERC20 token contract for blockchains. In order +to deploy your own application all you need to do is clone `examples/basecoin` +and run it. Now you are already running your own blockchain. In the following +I will explain how to add functionality to your blockchain. This is akin to +defining your own vesting schedule within a contract or setting a specific +multisig. You are just extending the base layer with extra functionality here +and there. + +## Structure of Basecoin + +Basecoin is build with the cosmos-sdk. It is a sample application that works +with any engine that implements the ABCI protocol. Basecoin defines multiple +unique modules as well as uses modules directly from the sdk. If you want +to modify Basecoin, you either remove or add modules according to your wishes. + + +## Modules + +A module is a fundamental unit in the cosmos-sdk. A module defines its own +transaction, handles its own state as well as its own state transition logic. +Globally, in the `app/app.go` file you just have to define a key for that +module to access some parts of the state, as well as initialise the module +object and finally add it to the transaction router. The router ensures that +every module only gets its own messages. + + +## Transactions + +A user can send a transaction to the running blockchain application. This +transaction can be of any of the ones that are supported by any of the +registered modules. + +### CheckTx + +Once a user has submitted their transaction to the engine, +the engine will first run `checkTx` to confirm that it is a valid transaction. +The module has to define a handler that knows how to handle every transaction +type. The corresponding handler gets invoked with the checkTx flag set to true. +This means that the handler shouldn't do any expensive operations, but it can +and should write to the checkTx state. + +### DeliverTx + +The engine calls `deliverTx` when a new block has been agreed upon in +consensus. Again, the corresponding module will have its handler invoked +and the state and context is passed in. During deliverTx execution the +transaction needs to be processed fully and the results are written to the +application state. + + +## CLI + +The cosmos-sdk contains a number of helper libraries in `clients/` to build cli +and RPC interfaces for your specific application. +