From c37faf3ac18b02b961430d0b1159197912ea7d2b Mon Sep 17 00:00:00 2001
From: Anton Kaliaev <anton.kalyaev@gmail.com>
Date: Mon, 24 Jun 2019 17:49:49 +0400
Subject: [PATCH] docs: (rpc/broadcast_tx_*) write expectations for a client
 (#3749)

Refs #3322
---
 rpc/core/mempool.go | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/rpc/core/mempool.go b/rpc/core/mempool.go
index 967466e73..1a0954438 100644
--- a/rpc/core/mempool.go
+++ b/rpc/core/mempool.go
@@ -19,6 +19,19 @@ import (
 // Returns right away, with no response. Does not wait for CheckTx nor
 // DeliverTx results.
 //
+// If you want to be sure that the transaction is included in a block, you can
+// subscribe for the result using JSONRPC via a websocket. See
+// https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html
+// If you haven't received anything after a couple of blocks, resend it. If the
+// same happens again, send it to some other node. A few reasons why it could
+// happen:
+//
+// 1. malicious node can drop or pretend it had committed your tx
+// 2. malicious proposer (not necessary the one you're communicating with) can
+// drop transactions, which might become valid in the future
+// (https://github.com/tendermint/tendermint/issues/3322)
+// 3. node can be offline
+//
 // Please refer to
 // https://tendermint.com/docs/tendermint-core/using-tendermint.html#formatting
 // for formatting/encoding rules.
@@ -69,6 +82,18 @@ func BroadcastTxAsync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadca
 
 // Returns with the response from CheckTx. Does not wait for DeliverTx result.
 //
+// If you want to be sure that the transaction is included in a block, you can
+// subscribe for the result using JSONRPC via a websocket. See
+// https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html
+// If you haven't received anything after a couple of blocks, resend it. If the
+// same happens again, send it to some other node. A few reasons why it could
+// happen:
+//
+// 1. malicious node can drop or pretend it had committed your tx
+// 2. malicious proposer (not necessary the one you're communicating with) can
+// drop transactions, which might become valid in the future
+// (https://github.com/tendermint/tendermint/issues/3322)
+//
 // Please refer to
 // https://tendermint.com/docs/tendermint-core/using-tendermint.html#formatting
 // for formatting/encoding rules.