tx-lifecycle concept doc #4497

glozow · 2019-06-06T07:09:38Z

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)

glozow · 2019-06-06T07:10:32Z

#3108

codecov · 2019-06-06T08:45:54Z

Codecov Report

Merging #4497 into master will increase coverage by 1.33%.
The diff coverage is 53.53%.

@@            Coverage Diff             @@
##           master    #4497      +/-   ##
==========================================
+ Coverage   52.65%   53.98%   +1.33%     
==========================================
  Files         261      272      +11     
  Lines       16410    17324     +914     
==========================================
+ Hits         8640     9352     +712     
- Misses       7124     7290     +166     
- Partials      646      682      +36

fedekunze · 2019-06-06T10:02:46Z

shouldn't this be rebased to @gamarin2 branch ? #4426

alexanderbez · 2019-06-06T12:47:29Z

Thanks @gzhao408!

@fedekunze probably? @gamarin2 what are your thoughts?

gamarin2

Thanks @gzhao408. I left comments.

Also please rebase on gamarin/app-anatomy

gamarin2 · 2019-06-10T13:35:46Z

docs/concepts/tx-lifecycle.md

+
+## Prerequisite Reading
+* [High-level overview of the architecture of an SDK application](https://github.com/cosmos/cosmos-sdk/docs/intro/sdk-app-architecture.md)
+* Baseapp concept doc (link in future)


baseapp can't be a prerequisite to this doc, it should be the other way around. See #3065 for an idea of the "order" of concept docs.

gamarin2 · 2019-06-10T13:53:02Z

docs/concepts/tx-lifecycle.md

+* [High-level overview of the architecture of an SDK application](https://github.com/cosmos/cosmos-sdk/docs/intro/sdk-app-architecture.md)
+* Baseapp concept doc (link in future)
+
+## Synopsis


Need to improve formatting throughout (line break after title)

gamarin2 · 2019-06-10T13:54:24Z

docs/concepts/tx-lifecycle.md

+* Baseapp concept doc (link in future)
+
+## Synopsis
+1. **Definition and Creation:** Transactions are comprised of metadata and `Msg`s specified by the developer. An application user creates a transaction when he performs an action that causes state change.


Synopsis is more like a quick summary of what the doc contains + a table of contents. If you add an explanation sentence after the section title, it should be very short

Like if you do want to have explanation sentences, it should really just be a very high-level overview of the tx workflow. No need to explain the details of what txs are at this point

gamarin2 · 2019-06-10T13:55:36Z

docs/concepts/tx-lifecycle.md

+
+## Synopsis
+1. **Definition and Creation:** Transactions are comprised of metadata and `Msg`s specified by the developer. An application user creates a transaction when he performs an action that causes state change.
+2. **Addition to Mempool:** All full nodes that receive transactions validate them first by running stateless and stateful checks on a copy of the internal state. Approved transactions are kept in the node's Mempool pending inclusion in the next block.


Add anchor for each section title

stateless/stateful/mempool -> any non-obvious word should either be explained or link to another doc that explains it. It's a bit much in the Synopsis, and that's why you don't necessarily want to go into detail on the various steps at this stage

gamarin2 · 2019-06-10T13:58:05Z

docs/concepts/tx-lifecycle.md

+4. **State Changes:** Transactions are delivered, creating state changes and expending gas. To commit state changes, internal state is updated and all copies are reset; the new state root is returned as proof.
+
+## Definition and Creation
+**[Transactions](https://github.com/cosmos/cosmos-sdk/blob/97d10210beb55ad4bd6722f7186a80bf7cb140e2/types/tx_msg.go#L36-L43)** are comprised of one or multiple **Messages** (link concept doc) and trigger state changes. The developer defines the specific messages to describe possible actions for the application by implementing the [`Msg`](https://github.com/cosmos/cosmos-sdk/blob/97d10210beb55ad4bd6722f7186a80bf7cb140e2/types/tx_msg.go#L10-L31) interface. He also defines [`Handler`](https://github.com/cosmos/cosmos-sdk/blob/1cfc868d86a152b523443154c8723de832dbec81/types/handler.go#L4)s that execute the actions for each message and return the [`Result`](https://github.com/cosmos/cosmos-sdk/blob/1cfc868d86a152b523443154c8723de832dbec81/types/result.go#L14-L37). An [`AnteHandler`](https://github.com/cosmos/cosmos-sdk/blob/1cfc868d86a152b523443154c8723de832dbec81/types/handler.go#L8) can be defined to execute a message's actions in simulation mode (i.e. without persisting state changes).


You might want to rebase on branch gamarin/app-anatomy, where I've started adding concepts docs you can reference

The Developer -> Developers

Ended up defaulting to plural "the nodes" and "the developers" and following one transaction tx

gamarin2 · 2019-06-11T13:03:20Z

docs/concepts/tx-lifecycle.md

+		-----------------------
+```
+#### BeginBlock
+`BeginBlock` is run first, and mainly transmits important data such as block header and Byzantine Validators from the last round of consensus to be used during the next few steps. No transactions are handled here.


Link to ./app-anatomy.md#beginblocker-and-endblocker

Also not technically part of tx lifecycle, but can remain

gamarin2 · 2019-06-11T13:04:19Z

docs/concepts/tx-lifecycle.md

+`BeginBlock` is run first, and mainly transmits important data such as block header and Byzantine Validators from the last round of consensus to be used during the next few steps. No transactions are handled here.
+
+#### DeliverTx
+The `DeliverTx` ABCI function defined in [`baseapp`](https://github.com/cosmos/cosmos-sdk/blob/8b1d75caa2099800ee9983e4a4528bcd00fec302/baseapp/baseapp.go


do not link to baseapp codebase here, but to baseapp concept doc. Only the concept doc of component X should directly reference code of component X

gamarin2 · 2019-06-11T13:08:02Z

docs/concepts/tx-lifecycle.md

+
+#### DeliverTx
+The `DeliverTx` ABCI function defined in [`baseapp`](https://github.com/cosmos/cosmos-sdk/blob/8b1d75caa2099800ee9983e4a4528bcd00fec302/baseapp/baseapp.go
+) does the bulk of the state change work: it is run for each transaction in the block in sequential order as committed to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx` but calls the [`runTx`](https://github.com/cosmos/cosmos-sdk/blob/cec3065a365f03b86bc629ccb6b275ff5846fdeb/baseapp/baseapp.go#L757-L873) function in deliver mode instead of check mode. 


Same, link to ./baseapp.md#runtx instead of the code directly

gamarin2 · 2019-06-11T13:09:10Z

docs/concepts/tx-lifecycle.md

+The `DeliverTx` ABCI function defined in [`baseapp`](https://github.com/cosmos/cosmos-sdk/blob/8b1d75caa2099800ee9983e4a4528bcd00fec302/baseapp/baseapp.go
+) does the bulk of the state change work: it is run for each transaction in the block in sequential order as committed to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx` but calls the [`runTx`](https://github.com/cosmos/cosmos-sdk/blob/cec3065a365f03b86bc629ccb6b275ff5846fdeb/baseapp/baseapp.go#L757-L873) function in deliver mode instead of check mode. 
+
+The application utilizes both `AnteHandler` to check and `MsgHandler` to deliver, persisting changes in both `checkTxState` and `deliverTxState`, respectively. This second check happens because nodes may not have seen the same transactions in the same order during the Addition to Mempool stage and a malicious proposer may have included invalid transactions. 


DeliverTx should be explained more in-depth, as it constitutes the bulk of the tx lifecycle:

Should outline the routing functionality of baseapp.

Explain the role of modules

Explain the lifecycle of the tx inside the module.

I think I should introduce modules earlier, such as include in the short definition section?

gamarin2 · 2019-06-11T13:10:07Z

docs/concepts/tx-lifecycle.md

+[`EndBlock`](https://github.com/cosmos/cosmos-sdk/blob/9036430f15c057db0430db6ec7c9072df9e92eb2/baseapp/baseapp.go#L875-L886) is always run at the end and is useful for automatic function calls or changing governance/validator parameters. No transactions are handled here.
+
+#### Commit
+The application's `Commit` method is run in order to finalize the state changes made by executing this block's transactions. A new state root should be sent back to serve as a merkle proof for the state change. Any application can inherit Baseapp's [`Commit`](https://github.com/cosmos/cosmos-sdk/blob/cec3065a365f03b86bc629ccb6b275ff5846fdeb/baseapp/baseapp.go#L888-L912) method; it synchronizes all the states by writing the `deliverTxState` into the application's internal state, updating both `checkTxState` and `deliverTxState` afterward.


A bit confusing: sometimes it seems like we're following the lifecycle of a specific tx, and sometimes it feels like it's more of an abstract description of the lifecycle of txS. Need to choose one or the other

All the internal states (LIST), always good to list stuff again. Reiteration is how people learn

Re-explain why it's important that every internal state is reset after Commit()

client/input.GetConfirmation() returns true if and only if the user's input is confirmative. The function is used in places where fat-fingering may cause financial loss, e.g. gaiacli tx send command. Thus it seems wiser to provide a conservative default in order to protect users from accidental mistyping. Closes: #4564

Closes: #4560

Closes #4556

closes #4578

fedekunze · 2019-07-18T15:56:24Z

Why are there so many files on the diff?

glozow · 2019-07-18T17:15:26Z

Why are there so many files on the diff?

My apologies, I didn't realize Gautier had moved tx-lifecycle.md and deleted the concepts folder to reorganize docs, so in my git-confused-ness I had added it back in the merging. Just made a new PR to undo the changes: #4739

create tx-lifecycle.md, skeleton, recycle diagrams

7435378

first draft of content

892a8c1

glozow added 6 commits June 7, 2019 15:07

added links

4c55398

corrected handlers info and diagram

62e90e8

oops, formatting error

77fe3fc

added appcli info

9a53729

added mempool information

7a3faac

fix

c626a3a

gamarin2 reviewed Jun 11, 2019

View reviewed changes

glozow changed the title ~~create tx-lifecycle.md, skeleton, recycle diagrams~~ tx-lifecycle concept doc Jun 12, 2019

glozow and others added 16 commits June 16, 2019 11:40

added msgtx file

5769256

tx creation

877218f

checking functions

c078203

fix merge

d8691e3

Merge branch 'master' into gloria/tx-lifecycle-doc

2573a3c

fixed link

0385312

more work

cd21686

Merge PR #4567: Update README.md

36142ab

Merge PR #4571: Update .vuepress

a797495

Move /bank/balances/{address} REST endpoint into /x/bank (#4570)

1e7c4dd

Closes: #4560

Reintroduce Coin.IsValid() (#4558)

314af42

Closes #4556

Fix BaseAccount's YAML serialization (#4577)

55928ad

remove BlockHeight in context (#4580)

84a2582

closes #4578

implemented suggestions

5933b03

fixed links

995fc4e

glozow added 24 commits July 18, 2019 07:44

checking functions

79fa1d7

fixed link

e2fc937

more work

9e43f6f

implemented suggestions

93e2b04

fixed links

2059ff4

add decoding step

c40365e

links

95a140f

extra asterisk

d6b7488

tx sign broadcast with cli

e543cd0

comments

1a11824

update and rename tx-msg

2c1dee1

skeleton only

51c0333

oops, delete multistore changes

eacbc0b

comments update

01e38db

minor edits, ready for review

f091051

Update tx-lifecycle.md

b1f1738

following lifecycle of JUST ONE TX

3de26b2

comments and new consensus+commit section

cb2e4d5

links and minor changes

59c9a5a

final edits

a2d3035

rename transactions.md

4c17601

hans comments

5b88c03

noticed a typo

3c034e8

merging?

1aa8791

glozow requested a review from fedekunze as a code owner July 18, 2019 14:51

jackzampolin merged commit c03f969 into master Jul 18, 2019

alexanderbez deleted the gloria/tx-lifecycle-doc branch August 28, 2019 15:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tx-lifecycle concept doc #4497

tx-lifecycle concept doc #4497

glozow commented Jun 6, 2019 •

edited

Loading

glozow commented Jun 6, 2019

codecov bot commented Jun 6, 2019 •

edited

Loading

fedekunze commented Jun 6, 2019

alexanderbez commented Jun 6, 2019

gamarin2 left a comment

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

gamarin2 Jun 10, 2019

glozow Jun 18, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

glozow Jun 18, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

gamarin2 Jun 11, 2019

fedekunze commented Jul 18, 2019

glozow commented Jul 18, 2019

tx-lifecycle concept doc #4497

tx-lifecycle concept doc #4497

Conversation

glozow commented Jun 6, 2019 • edited Loading

glozow commented Jun 6, 2019

codecov bot commented Jun 6, 2019 • edited Loading

Codecov Report

fedekunze commented Jun 6, 2019

alexanderbez commented Jun 6, 2019

gamarin2 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

fedekunze commented Jul 18, 2019

glozow commented Jul 18, 2019

glozow commented Jun 6, 2019 •

edited

Loading

codecov bot commented Jun 6, 2019 •

edited

Loading