From 6f4ffab6e8df73cb2661b23241987b37b0b50806 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 18 Feb 2018 20:52:59 -0500 Subject: [PATCH] docs: notes about the different apps --- docs/apps.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/apps.md diff --git a/docs/apps.md b/docs/apps.md new file mode 100644 index 0000000000..13a356b38c --- /dev/null +++ b/docs/apps.md @@ -0,0 +1,66 @@ +# Apps in the SDK + +The SDK has multiple levels of "application": the ABCI app, the BaseApp, the BasecoinApp, and now your App. + +## ABCI App + +The basic ABCI interface allowing Tendermint to drive the applications state machine with transaction blocks. + +## BaseApp + +Implements an ABCI App using a MultiStore for persistence and a Router to handle transactions. +The goal is to provide a secure interface between the store and the extensible state machine +while defining as little about that state machine as possible (staying true to the ABCI). + +BaseApp requires stores to be mounted via capabilities keys - handlers can only access +stores they're given the key for. The BaseApp ensures all stores are properly loaded, cached, and committed. +One mounted store is considered the "main" - it holds the latest block header, from which we can find and load the +most recent state. + +BaseApp distinguishes between two handler types - the `AnteHandler` and the `Handler`. +The former is a stateful validity check (eg. checking nonce and sufficient balance), +the later the full state transition function. Only AnteHandler runs during CheckTx, +while both run in DeliverTx. + +BaseApp is responsible for managing the context passed into handlers - +it makes the block header available and provides the right stores for CheckTx and DeliverTx. + +BaseApp is completely agnostic to serialization formats. + +## Basecoin + +Basecoin is the first complete application in the stack. +Complete applications require extensions to the core modules of the SDK to actually implement handler functionality. +The native extensions of the SDK, useful for building Cosmos Zones, live under `x`. +Basecoin implements a `BaseApp` state machine using the `x/auth` and `x/bank` extensions, +which define how transaction signers are authenticated and how coins are transferred. +It should also use `x/ibc` and probably a simple staking extension. + +Basecoin and the native `x` extensions use go-wire for all serialization needs, +including for transactions and accounts. + +## Your Cosmos App + +Your Cosmos App is a fork of Basecoin - copy the `examples/basecoin` directory and modify it to your needs. +You might want to: + +- add fields to accounts +- copy and modify handlers +- add new handlers for new transaction types +- add new stores for better isolation across handlers + +The Cosmos Hub takes Basecoin and adds more stores and extensions to handle additional +transaction types and logic, like the advanced staking logic and the governance process. + +## Ethermint + +Ethermint is a new implementation of `BaseApp` that does not depend on Basecoin. +Instead of `cosmos-sdk/x/` it has its own `ethermint/x` based on `go-ethereum`. + +Ethermint uses a Patricia store for its accounts, and an IAVL store for IBC. +It has `x/ante`, which is quite similar to Basecoin's but uses RLP instead of go-wire. +Instead of `x/bank`, it has `x/eth`, which defines the single Ethereum transaction type +and all the semantics of the Ethereum state machine. + +Within `x/eth`, transactions sent to particular addresses can be handled in unique ways, +for instance to handle IBC and staking.