rpc: document RPC_TRANSACTION_ALREADY_IN_CHAIN exception #20941

suggestion to improve, tighten this up, and remove "Note that" and "NOTE:" while grouping together those two messages and keeping the related RPCs sentence at the end

+++ b/src/rpc/rawtransaction.cpp
@@ -816,12 +816,11 @@ static RPCHelpMan sendrawtransaction()
 {
     return RPCHelpMan{"sendrawtransaction",
                 "\nSubmit a raw transaction (serialized, hex-encoded) to local node and network.\n"
-                "\nNote that the transaction will be sent unconditionally to all peers, so using this\n"
+                "\nThe transaction will be sent unconditionally to all peers, so using sendrawtransaction\n"
                 "for manual rebroadcast may degrade privacy by leaking the transaction's origin, as\n"
                 "nodes will normally not rebroadcast non-wallet transactions already in their mempool.\n"
-                "\nAlso see createrawtransaction and signrawtransactionwithkey calls.\n"
-                "\nNOTE: an RPC_TRANSACTION_ALREADY_IN_CHAIN exception will be raised if you are\n"
-                "attempting to send a transaction that already exists in a block.\n",
+                "\nRPC_TRANSACTION_ALREADY_IN_CHAIN will be raised if the transaction already exists in a block.\n"
+                "\nRelated RPCs: createrawtransaction, signrawtransactionwithkey\n",

which would change the help from

Submit a raw transaction (serialized, hex-encoded) to local node and network.

Note that the transaction will be sent unconditionally to all peers, so using this
for manual rebroadcast may degrade privacy by leaking the transaction's origin, as
nodes will normally not rebroadcast non-wallet transactions already in their mempool.

Also see createrawtransaction and signrawtransactionwithkey calls.

NOTE: an RPC_TRANSACTION_ALREADY_IN_CHAIN exception will be raised if you are
attempting to send a transaction that already exists in a block.

to

Submit a raw transaction (serialized, hex-encoded) to local node and network.

The transaction will be sent unconditionally to all peers, so using sendrawtransaction
for manual rebroadcast may degrade privacy by leaking the transaction's origin, as
nodes will normally not rebroadcast non-wallet transactions already in their mempool.

RPC_TRANSACTION_ALREADY_IN_CHAIN will be raised if the transaction already exists in a block.

Related RPCs: createrawtransaction, signrawtransactionwithkey

addressed in 35bc72a1bcc6c7bb7618803490fc7957d070dc02 Thanks, this is much better :)

This makes it sound like the only exception that can be thrown

We can either document every exception that can be thrown or revert back to specifying that this is a note.

                "\nNOTE: an RPC_TRANSACTION_ALREADY_IN_CHAIN will be raised if the transaction already exists in a block\n"

I would avoid both adding "note this"/"note that" (IIRC I added the first note but have since seen review feedback to avoid needless "note: "s, which I agree with) and listing all the exceptions. Is there a concrete suggestion how this change can be improved?

"This may throw if the transaction couldn't be added to the mempool"

"This may throw if the transaction couldn't be added to the mempool"

That still sounds like it's the only exception which may be thrown. It also sounds like it's the only reason that a transaction fails to enter the mempool.

As-is seems more explicit but I don't have a strong opinion regarding it versus Marco's suggestion (thanks for the proposal!) I think they are both an improvement and don't see the implication that this the only exception.

                "\nRPC_TRANSACTION_ALREADY_IN_CHAIN will be raised if the transaction already exists in a block.\n"

Maybe:

This will throw a specific exception, RPC_TRANSACTION_ALREADY_IN_CHAIN, if the transaction cannot be added to the mempool.

addressed in 74d23bf

addressed in 74d23bf