Add baseapp concept doc #4691

gamarin2 · 2019-07-05T17:55:26Z

Title

File to review: core/baseapp.md

Targeted PR against correct branch (see CONTRIBUTING.md)
Linked to github-issue with discussion and accepted design OR link to spec that describes this work.
Wrote tests
Updated relevant documentation (docs/)
Added a relevant changelog entry: clog add [section] [stanza] [message]
rereviewed Files changed in the github PR explorer

For Admin Use:

Added appropriate labels to PR (ex. wip, ready-for-review, docs)
Reviewers Assigned
Squashed all commits, uses message "Merge pull request #XYZ: [title]" (coding standards)

Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com>

Co-Authored-By: Alexander Bezobchuk <alexanderbez@users.noreply.github.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com> Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com> Co-Authored-By: frog power 4000 <rigel.rozanski@gmail.com>

Co-Authored-By: Karoly Albert Szabo <szabo.karoly.a@gmail.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com>

codecov · 2019-07-05T18:19:33Z

Codecov Report

Merging #4691 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #4691      +/-   ##
==========================================
+ Coverage   54.01%   54.02%   +0.01%     
==========================================
  Files         271      271              
  Lines       17261    17261              
==========================================
+ Hits         9324     9326       +2     
+ Misses       7257     7255       -2     
  Partials      680      680

hschoenburg

a few spelling and grammar fixes. Also I recommend removing the ABCI messages section in favor of the same content being covered elsewhere.

hschoenburg · 2019-07-08T21:36:07Z

docs/core/baseapp.md

+
+## Introduction
+
+`baseapp` is an abstraction that implements the core of an SDK application, namely:


"abstraction" is pretty vauge. Maybe call baseapp the "base class that implements the core of an SDK application, "

hschoenburg · 2019-07-08T21:39:35Z

docs/core/baseapp.md

+}
+```
+
+Extending the application with `baseapp` gives the former access to all of `baseapp`'s methods. This allows developers to compose their custom application with the modules they want, while not having to concern themselves with the hard work of implementing the ABCI, the routing and state management logic. 


"This allows developers to compose their custom application with the modules they want, while not having to concern themselves with the hard work of implementing ABCI, routing and state management logic." ----> took out two unneeded "the"s

docs/core/baseapp.md

hschoenburg · 2019-07-08T22:15:50Z

docs/core/baseapp.md

+- A [query router](#query-routing). The `query router` facilitates the routing of [queries](./querier.md) to the appropriate module for it to be processed.
+- A [`txDecoder`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#TxDecoder), used to decode transaction `[]byte` relayed by the underlying Tendermint engine.
+- A [`baseKey`], to access the [main store](./store.md#main-store) in the `CommitMultiStore`. The main store is used to persist data related to the core of the application, like consensus parameters.  
+- A [`anteHandler`](#antehandler), to handle signature verification and fee paiement when a transaction is received.


spelling "payment"

hschoenburg · 2019-07-08T22:43:58Z

docs/core/baseapp.md

+## RunTx, AnteHandler and RunMsgs
+
+### RunTx
+


Hmm this section is confusing because it collapses together a number of different subject. Also it makes it look like RunTx is another ABCI message? Its not right? Is it a method on baseapp? The way this is written it seems like RunTx is another ABCI message called by CheckTx... but ABCI messages dont call each other....

I think it would be more clear with a proper rendering of the page. If you look at the sectioning, you'll see that ## Run Tx, AnteHandler and RunMsgs is not under Main ABCI Messages. These method are called from methods that implement the ABCI though, and we need to explain what they do.

hschoenburg · 2019-07-08T22:46:01Z

docs/core/baseapp.md

+
+After that, `RunTx` calls `ValidateBasic()` on each `message`in the `Tx`, which runs prelimary *stateless* validity checks. If any `message` fails to pass `ValidateBasic()`, `RunTx` returns with an error. 
+
+Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are cached-wrapped using the [`cacheTxContext()`](https://github.com/cosmos/cosmos-sdk/blob/master/baseapp/baseapp.go#L781-L798) function. This allows `RunTx` not to commit the changes made to the state during the execution of `anteHandler` if it ends up failing. It also prevents the module implementing the `anteHandler` from writing to state, which is an important part of the [object-capabilities](./ocap.md) of the Cosmos SDK. 


This all seems perhaps better suited to the Tx Lifecycle doc? This is starting to stray from baseapp the base class, to more complex contextual info that might better fit somewhere else, with a link to it from here.

I only touch on what is implemented at baseapp level here.

Thetx-lifecycle doc is NOT a good place to detail this process, as it is an overview doc. The tx-lifecycle doc links to this doc for people that want more detail, not the other way around.

Maybe add parenthesis like so RunTx() to demonstrate that its a method?

hschoenburg · 2019-07-08T22:47:25Z

docs/core/baseapp.md

+- Perform preliminary *stateful* validity checks like ensuring signatures are valid or that the sender has enough funds to pay for fees. 
+- Play a role in the incentivisation of stakeholders via the collection of transaction fees. 
+
+`baseapp` holds an `anteHandler` as paraemter, which is initialized in the [application's constructor](../basics/app-anatomy.md#application-constructor). The most widely used `anteHandler` today is that of the [`auth` module](https://github.com/cosmos/cosmos-sdk/blob/master/x/auth/ante.go).


spelling for "parameter"

hschoenburg · 2019-07-08T22:49:00Z

docs/core/baseapp.md

+
+### RunMsgs
+
+`RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `runTxModeDeliver` to actually process the `message`s. 


....."as a parameter to check the existence of a route for each message contained in the transaction, and with runTxModeDeliver to actually process the messages.

hschoenburg · 2019-07-08T22:50:20Z

docs/core/baseapp.md

+
+First, it retreives the `message`'s `route` using the `Msg.Route()` method. Then, using the application's [`router`](#routing) and the `route`, it checks for the existence of a `handler`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. If instead `mode == runTxModeDeliver`, the [`handler`](../building-modules.md#handler) function for the message is executed, before `RunMsgs` returns. 
+
+## Other ABCI Messages


this feels like the wrong place to be documenting ABCI messages.

ABCI messages in the context of the SDK are implemented as baseapp's methods, so it's the perfect place to document them...

Please remember that ABCI spec just specifies the interface and return format, it does not specify the actual logic implemented by the application.

gotcha. Yeah I got this wrong. I do think adding '()' might help clarify things, for CheckTx() and the other baseapp methods that handle the ABCI messages from tendermint to distinguish them from the tendermint docs.

hschoenburg · 2019-07-08T23:20:45Z

docs/core/baseapp.md

+                |  CheckState(t+1)(0)  |      | DeliverState(t+1)(0) |       |   QueryState(t+1)    |
+                +----------------------+      |                      |       |                      |
+                          .                              .                               .
+                          .                              .                               .


This graphic is hard to grasp.... Maybe more explanation of what each column represents? like the left most column could be labeled "Incoming ABCI Msgs"

jackzampolin · 2019-07-09T22:43:23Z

docs/core/baseapp.md

+- A [Router](#routing), to route [messages](./tx-msgs.md) and [queries](./querier.md) to the appropriate [module](../building-modules/modules.md).
+- Different [states](#states), as the state-machine can have different parallel states updated based on the ABCI message received. 
+
+The goal of `baseapp` is to provide a boilerplate SDK application that developers can easily extend to build their own custom application. Usually, developers will create a custom type for their application, like so:


Isn't the goal of baseapp to connect all the modules that make up an application and provide common utilities to them? I don't think it is to "provide boilerplate" IMO

changed formulation

jackzampolin · 2019-07-09T22:47:19Z

docs/core/baseapp.md

+- [Router](#message-routing): The `router` facilitates the routing of [`messages`](./tx-msgs.md) to the appropriate module for it to be processed. Here `message` refers to the transaction components that need to be processed by the application in order to update the state, and not to ABCI messages which implement the interface between the application and the underlying consensus engine. 
+- [Query Router](#query-routing): The `query router` facilitates the routing of [queries](./querier.md) to the appropriate module for it to be processed. These `queries` are not ABCI messages themselves, but they are relayed to the application from the underlying consensus engine via the ABCI message [`Query`](#query).
+- [`TxDecoder`](https://godoc.org/github.com/cosmos/cosmos-sdk/types#TxDecoder): It is used to decode transaction `[]byte` relayed by the underlying Tendermint engine.
+- [`DaseKey`]: This key is used to access the [main store](./store.md#main-store) in the `CommitMultiStore`. The main store is used to persist data related to the core of the application, like consensus parameters.  


I've never seen this term before. Is this right?

nope, should be basekey

jackzampolin · 2019-07-09T22:48:56Z

docs/core/baseapp.md

+- `checkState`: This state is updated during [`CheckTx`](#checktx), and reset on [`Commit`](#commit).
+- `deliverState`: This state is updated during [`DeliverTx`](#delivertx), and reset on [`Commit`](#commit).
+
+Finally, a few more important parameterd:


Suggested change

Finally, a few more important parameterd:

Finally, a few more important parameters:

gamarin2 and others added 26 commits May 20, 2019 14:08

consolidate intro

0125ca5

Merge branch 'master' into gamarin/docs-update

9264ac3

start anatomy of sdk app

a004c57

wokring

07b7415

working

4a86564

querier

a9e303c

working

0913fb6

merg

167104c

workiiiing

6346e8b

finish

23f8f78

add dep and makefile

9c2fd4e

Apply suggestions from code review

9baaed7

Co-Authored-By: Alessio Treglia <quadrispro@ubuntu.com>

typo

45f5654

typo

265ed8e

refactor for new module interface

5f883fd

pull

b06fafc

karoly review

dde15ae

Apply suggestions from code review

da2514f

Co-Authored-By: Karoly Albert Szabo <szabo.karoly.a@gmail.com> Co-Authored-By: Federico Kunze <31522760+fedekunze@users.noreply.github.com>

encoding

56c3f5b

working on baseapp doc

4f7c6b4

baseapp work

e37310f

reorg

92a0db9

almost there

94664fe

finish first draft

2624fec

Merge branch 'master' into gamarin/baseapp

9aedc16

gamarin2 added the T:Docs Changes and features related to documentation. label Jul 5, 2019

gamarin2 requested review from alessio, alexanderbez and jackzampolin as code owners July 5, 2019 17:55

gamarin2 requested a review from rigelrozanski as a code owner July 5, 2019 17:55

remove old files

3496625

hschoenburg suggested changes Jul 8, 2019

View reviewed changes

hschoenburg reviewed Jul 8, 2019

View reviewed changes

hans review'

ad230c4

hschoenburg approved these changes Jul 9, 2019

View reviewed changes

jackzampolin reviewed Jul 9, 2019

View reviewed changes

jack review + clarification on ABCI methods

7332b6a

fedekunze added the R4R label Jul 15, 2019

jackzampolin approved these changes Jul 17, 2019

View reviewed changes

jackzampolin merged commit ae77f00 into master Jul 17, 2019

jackzampolin deleted the gamarin/baseapp branch July 17, 2019 16:26

This was referenced Sep 17, 2019

Add Baseapp concepts document #3107

Closed

Expand upon BaseApp documentation #2806

Closed

gamarin2 mentioned this pull request Dec 9, 2019

[R4R] New docs V1 (merge master-docs to master) #5379

Merged

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add baseapp concept doc #4691

Add baseapp concept doc #4691

gamarin2 commented Jul 5, 2019 •

edited

Loading

codecov bot commented Jul 5, 2019 •

edited

Loading

hschoenburg left a comment

hschoenburg Jul 8, 2019

hschoenburg Jul 8, 2019

hschoenburg Jul 8, 2019

hschoenburg Jul 8, 2019

gamarin2 Jul 9, 2019

hschoenburg Jul 8, 2019

gamarin2 Jul 9, 2019

hschoenburg Jul 9, 2019

hschoenburg Jul 8, 2019

hschoenburg Jul 8, 2019

hschoenburg Jul 8, 2019

gamarin2 Jul 9, 2019

hschoenburg Jul 9, 2019

hschoenburg Jul 8, 2019

gamarin2 Jul 9, 2019

jackzampolin Jul 9, 2019

gamarin2 Jul 10, 2019

jackzampolin Jul 9, 2019

gamarin2 Jul 10, 2019

jackzampolin Jul 9, 2019


		## Introduction

		`baseapp` is an abstraction that implements the core of an SDK application, namely:


		After that, `RunTx` calls `ValidateBasic()` on each `message`in the `Tx`, which runs prelimary stateless validity checks. If any `message` fails to pass `ValidateBasic()`, `RunTx` returns with an error.

		Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are cached-wrapped using the [`cacheTxContext()`](https://github.com/cosmos/cosmos-sdk/blob/master/baseapp/baseapp.go#L781-L798) function. This allows `RunTx` not to commit the changes made to the state during the execution of `anteHandler` if it ends up failing. It also prevents the module implementing the `anteHandler` from writing to state, which is an important part of the [object-capabilities](./ocap.md) of the Cosmos SDK.


		### RunMsgs

		`RunMsgs` is called from `RunTx` with `runTxModeCheck` as parameter to check the existence of a route for each message the transaction, and with `runTxModeDeliver` to actually process the `message`s.


		First, it retreives the `message`'s `route` using the `Msg.Route()` method. Then, using the application's [`router`](#routing) and the `route`, it checks for the existence of a `handler`. At this point, if `mode == runTxModeCheck`, `RunMsgs` returns. If instead `mode == runTxModeDeliver`, the [`handler`](../building-modules.md#handler) function for the message is executed, before `RunMsgs` returns.

		## Other ABCI Messages

	Finally, a few more important parameterd:
	Finally, a few more important parameters:

Add baseapp concept doc #4691

Add baseapp concept doc #4691

Conversation

gamarin2 commented Jul 5, 2019 • edited Loading

codecov bot commented Jul 5, 2019 • edited Loading

Codecov Report

hschoenburg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gamarin2 commented Jul 5, 2019 •

edited

Loading

codecov bot commented Jul 5, 2019 •

edited

Loading