From 90446261f3e38df6c85c86f0b4e00f4017b48820 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 17 May 2018 12:20:29 +0400 Subject: [PATCH] [docs] document transactional semantics Refs #1494, #345 --- docs/transactional-semantics.rst | 27 +++++++++++++++++++++++++++ docs/using-tendermint.rst | 2 +- 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 docs/transactional-semantics.rst diff --git a/docs/transactional-semantics.rst b/docs/transactional-semantics.rst new file mode 100644 index 000000000..268247a22 --- /dev/null +++ b/docs/transactional-semantics.rst @@ -0,0 +1,27 @@ +Transactional Semantics +======================= + +In `"Using +Tendermint"<./specification/using-tendermint.html#broadcast-api>`__ we +discussed different API endpoints for sending transactions and +differences between them. + +What we have not yet covered is transactional semantics. + +When you send a transaction using one of the available methods, it +first goes to the mempool. Currently, it does not provide strong +guarantees like "if the transaction were accepted, it would be +eventually included in a block (given CheckTx passes)." + +For instance a tx could enter the mempool, but before it can be sent +to peers the node crashes. + +We are planning to provide such guarantees by using a WAL and +replaying transactions (See +`GH#248`__), but +it's non-trivial to do this all efficiently. + +The temporary solution is for clients to monitor the node and resubmit +transaction(s) or/and send them to more nodes at once, so the +probability of all of them crashing at the same time and losing the +msg decreases substantially. diff --git a/docs/using-tendermint.rst b/docs/using-tendermint.rst index 394a7f3ed..f572277cd 100644 --- a/docs/using-tendermint.rst +++ b/docs/using-tendermint.rst @@ -214,7 +214,7 @@ Broadcast API Earlier, we used the ``broadcast_tx_commit`` endpoint to send a transaction. When a transaction is sent to a Tendermint node, it will run via ``CheckTx`` against the application. If it passes ``CheckTx``, -it will be included in the mempool, broadcast to other peers, and +it will be included in the mempool, broadcasted to other peers, and eventually included in a block. Since there are multiple phases to processing a transaction, we offer