broadcast_package RPC: note JSON RPC ERROR vs success=false+errors_arr

Author: SomberNight

docs/protocol-methods.rst

@@ -600,24 +600,26 @@ with the child being the last element in the array.
 
 **Result Example**
 
-When *verbose* is :const:`false`::
+When *verbose* is :const:`false`:
 
-    {
-      "success": true
-    }
+    Successful broadcast::
 
-    With errors:
+        {
+          "success": true
+        }
+
+    With errors::
 
-    {
-      "success": false,
-      "errors":
-      [
         {
-          "txid": "ec6f295cd4b1b91f59cabb0ab8fdc7c76580db08be6426e465f75a69d82b9659",
-          "error": "bad-txns-inputs-missingorspent"
+          "success": false,
+          "errors":
+          [
+            {
+              "txid": "ec6f295cd4b1b91f59cabb0ab8fdc7c76580db08be6426e465f75a69d82b9659",
+              "error": "bad-txns-inputs-missingorspent"
+            }
+          ]
         }
-      ]
-    }
 
 When *verbose* is :const:`true` (exact structure depends on bitcoind impl and version, and should not be relied upon)::
 
@@ -646,6 +648,18 @@ When *verbose* is :const:`true` (exact structure depends on bitcoind impl and ve
       ]
     }
 
+.. note:: If the input is malformed, notably if `raw_txs` is not a well-formed package,
+  errors will be sent back as JSON RPC ERROR, as usual.
+  Ultimately the distinction can depend on bitcoind.
+  Compare examples (id=3 gets JSON RPC ERROR, but id=4 gets success=false with errors array)::
+
+    <- {"id": 3, "method": "blockchain.transaction.broadcast_package", "params": [["02000000000102f758cda73a362840995d62d0079a22a11fc2652cb7740fffb8132486fe76fe730000000000fdffffff31b2d3d434d7c8f46b23a47aabc3c9498d4df5ffb9f13e13c3c3ecb52ab570b80000000000fdffffff02400d0300000000001600149f9aa3795e57c535d2f7b160ff023804c60fca6e30b3e80b00000000160014553a3b97c2cc7d3d4edeace3281ff038bd0676290247304402202c84cb82c94978b688154f06c3b91e64b99f2c2124d7c53004c81d23c4ce7e5102206a5c87986d1272140a8625a0fbd9926c2a93bf41517aca28615499140936109c0121027ba4d3ee6471a985307a37d09eb9a0a73c1a31b57616fe3e53a3d6d4540025190247304402203106d7622d3bcb415ae898558e8d414c337e2e7d4a485bbf4bffa8ba3bc620b802201340334f4d89e03735b3b183602ce4b3377225571ebbf18e97eaa24f3fcc5d4f0121027ba4d3ee6471a985307a37d09eb9a0a73c1a31b57616fe3e53a3d6d454002519a4090000", "02000000000101ab93b5c11c9a591b441de4228c942603a0479fa0d33a1a2bee72e75bd301c25e0000000000fdffffff01640c03000000000016001446116f48b60ad5b22377dcf951643e2e1aa3957a0247304402206002cc311d16b5cef7349bcd4174d3ae14d5741680ab81d7e24bc31c89634fd6022072d0d6b72c4ddbe62c527ebc5955677793cc13fe801ec22604d93bbc1b1f3291012102fb265cce2019e555fe23fb45e4cbc3d966bb399a52b2e93b808ad7961b426de1a4090000"]]}
+    -> {"jsonrpc":"2.0","error":{"code":1,"message":"the tx package was rejected by network rules.\n\npackage topology disallowed. not child-with-parents or parents depend on each other.."},"id":3}
+
+    <- {"id": 4, "method": "blockchain.transaction.broadcast_package", "params": [["0200000000010148d372010d796a89f12864b5c86495d67bce98cb9ac3ba652bf811aa6b82c36c0000000000fdffffff01d20c030000000000160014e437538b7f13871562066babd1fbab72b4fba958024730440220662e4d917c0af3b37dd0bad65c9b46ba2a1504cd4f1346f35c0020f6d0edbd0e02207b44f98612bd3f58164385f4a572af2a2f471c924f6569aa6f3ddcaaa0e57753012103c3172a9f8820681c62b8bf28961988a4642b33f4920b9da14b06965c7fff83fd68090000", "02000000000101ab93b5c11c9a591b441de4228c942603a0479fa0d33a1a2bee72e75bd301c25e0000000000fdffffff014e0c03000000000016001446116f48b60ad5b22377dcf951643e2e1aa3957a0247304402202850349c76c41b801c429feaee96d773788b478c1cf051e967824fe504e5948902204bbede1252490c06c38feb206266aaf126937f6a3bc0a16d038fabde9781c6fd012102fb265cce2019e555fe23fb45e4cbc3d966bb399a52b2e93b808ad7961b426de1a4090000"]]}
+    -> {"jsonrpc":"2.0","result":{"success":false,"errors":[{"txid":"c13d8d63284853d3417a150cfddcfc62d31cab4b311c9322cb43f979a518ac3a","error":"insufficient fee, rejecting replacement c13d8d63284853d3417a150cfddcfc62d31cab4b311c9322cb43f979a518ac3a, not enough additional fees to relay; 0.00000022 < 0.0000011"}]},"id":4}
+
+
 blockchain.transaction.get
 ==========================