[docs] document transactional semantics

Refs #1494, #345

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<https://github.com/tendermint/tendermint/issues/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.

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