Add submitpackage RPC support

tnull · tnull · commit bd6863c43d85 · 2024-11-11T10:03:20.000+01:00
diff --git a/client/src/client_sync/v28/mod.rs b/client/src/client_sync/v28/mod.rs
@@ -4,6 +4,8 @@
 //!
 //! We ignore option arguments unless they effect the shape of the returned JSON data.
 
+mod raw_transactions;
+
 use bitcoin::address::{Address, NetworkChecked};
 use bitcoin::{Amount, Block, BlockHash, Txid};
 
@@ -30,6 +32,7 @@ crate::impl_client_check_expected_server_version!({ [280000] });
 
 // == Rawtransactions ==
 crate::impl_client_v17__sendrawtransaction!();
+crate::impl_client_v28__submitpackage!();
 
 // == Wallet ==
 crate::impl_client_v17__createwallet!();
diff --git a/client/src/client_sync/v28/raw_transactions.rs b/client/src/client_sync/v28/raw_transactions.rs
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing JSON-RPC methods on a client.
+//!
+//! Specifically this is methods found under the `== Rawtransactions ==` section of the
+//! API docs of `bitcoind v28.0`.
+//!
+//! All macros require `Client` to be in scope.
+//!
+//! See or use the `define_jsonrpc_minreq_client!` macro to define a `Client`.
+
+/// Implements bitcoind JSON-RPC API method `submitpackage`
+#[macro_export]
+macro_rules! impl_client_v28__submitpackage {
+    () => {
+        impl Client {
+            /// Submit a package of transactions to local node.
+            ///
+            /// The package will be validated according to consensus and mempool policy rules. If any transaction passes, it will be accepted to mempool.
+            ///
+            /// ## Arguments:
+            /// 1. `package`:          An array of raw transactions.
+            ///                     The package must solely consist of a child and its parents. None of the parents may depend on each other.
+            ///                     The package must be topologically sorted, with the child being the last element in the array.
+            /// 2. `maxfeerate`:       Reject transactions whose fee rate is higher than the specified value.
+            ///                     Fee rates larger than 1BTC/kvB are rejected.
+            ///                     Set to 0 to accept any fee rate.
+            ///                     If unset, will default to 0.10 BTC/kvb.
+            /// 3. `maxburnamount`    If set, reject transactions with provably unspendable outputs (e.g. 'datacarrier' outputs that use the OP_RETURN opcode) greater than the specified value.
+            ///                     If burning funds through unspendable outputs is desired, increase this value.
+            ///                     This check is based on heuristics and does not guarantee spendability of outputs.
+            pub fn submit_package(
+                &self,
+                package: &[bitcoin::Transaction],
+                max_fee_rate: Option<bitcoin::FeeRate>,
+                max_burn_amount: Option<bitcoin::Amount>,
+            ) -> Result<SubmitPackage> {
+                let package_txs = package
+                    .into_iter()
+                    .map(|tx| bitcoin::consensus::encode::serialize_hex(tx))
+                    .collect::<Vec<_>>();
+                let max_fee_rate_btc_kvb =
+                    max_fee_rate.map(|r| r.to_sat_per_vb_floor() as f64 / 100_000.0);
+                let max_burn_amount_btc = max_burn_amount.map(|a| a.to_btc());
+                self.call(
+                    "submitpackage",
+                    &[package_txs.into(), max_fee_rate_btc_kvb.into(), max_burn_amount_btc.into()],
+                )
+            }
+        }
+    };
+}
diff --git a/integration_test/src/lib.rs b/integration_test/src/lib.rs
@@ -3,6 +3,7 @@
 pub mod v17;
 pub mod v19;
 pub mod v22;
+pub mod v28;
 
 /// Requires `RPC_PORT` to be in scope.
 use bitcoind::BitcoinD;
diff --git a/integration_test/src/v28/mod.rs b/integration_test/src/v28/mod.rs
@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing test methods on a JSON-RPC client for `bitcoind v28.0`.
+
+pub mod raw_transactions;
diff --git a/integration_test/src/v28/raw_transactions.rs b/integration_test/src/v28/raw_transactions.rs
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing test methods on a JSON-RPC client.
+//!
+//! Specifically this is methods found under the `== Rawtransactions ==` section of the
+//! API docs of `bitcoind v28.0`.
+
+/// Requires `Client` to be in scope
+#[macro_export]
+macro_rules! impl_test_v28__submitpackage {
+    () => {
+        #[test]
+        fn submitpackage() {
+            //let bitcoind = $crate::bitcoind_no_wallet();
+
+            let bitcoind = $crate::bitcoind_with_default_wallet();
+
+            // Submitting the empty package should simply fail.
+            assert!(bitcoind.client.submit_package(&[], None, None).is_err());
+
+            // Premine to get some funds
+            let address = bitcoind.client.new_address().expect("failed to get new address");
+            let json =
+                bitcoind.client.generate_to_address(101, &address).expect("generatetoaddress");
+            json.into_model().unwrap();
+
+            // Send to ourselves, mine, send again to generate two transactions.
+            let (tx_0, tx_1) = {
+                let new_address = bitcoind.client.new_address().expect("failed to get new address");
+                let txid = bitcoind
+                    .client
+                    .send_to_address(&new_address, bitcoin::Amount::from_sat(1000000))
+                    .unwrap()
+                    .into_model()
+                    .unwrap()
+                    .txid;
+
+                let _ =
+                    bitcoind.client.generate_to_address(1, &address).expect("generatetoaddress");
+
+                let best_block_hash = bitcoind.client.best_block_hash().unwrap();
+                let best_block = bitcoind.client.get_block(best_block_hash).unwrap();
+                let tx_0 = best_block.txdata[1].clone();
+
+                let new_address = bitcoind.client.new_address().expect("failed to get new address");
+                let txid = bitcoind
+                    .client
+                    .send_to_address(&new_address, bitcoin::Amount::from_sat(1000000))
+                    .unwrap()
+                    .into_model()
+                    .unwrap()
+                    .txid;
+
+                let _ =
+                    bitcoind.client.generate_to_address(1, &address).expect("generatetoaddress");
+
+                let best_block_hash = bitcoind.client.best_block_hash().unwrap();
+                let best_block = bitcoind.client.get_block(best_block_hash).unwrap();
+                let tx_1 = best_block.txdata[1].clone();
+                (tx_0, tx_1)
+            };
+
+            // The call for submitting this package should succeed, but yield an 'already known'
+            // error for all transactions.
+            let res = bitcoind
+                .client
+                .submit_package(&[tx_0, tx_1], None, None)
+                .expect("failed to submit package");
+            for (_, tx_result) in &res.tx_results {
+                assert!(tx_result.error.is_some());
+            }
+            assert!(res.replaced_transactions.is_empty());
+        }
+    };
+}
diff --git a/integration_test/tests/v28_api.rs b/integration_test/tests/v28_api.rs
@@ -40,6 +40,7 @@ mod raw_transactions {
     use super::*;
 
     impl_test_v17__sendrawtransaction!();
+    impl_test_v28__submitpackage!();
 }
 
 // == Wallet ==
diff --git a/json/src/v28/mod.rs b/json/src/v28/mod.rs
@@ -90,7 +90,7 @@
 //! - [ ] `joinpsbts ["psbt",...]`
 //! - [ ] `sendrawtransaction "hexstring" ( maxfeerate maxburnamount )`
 //! - [ ] `signrawtransactionwithkey "hexstring" ["privatekey",...] ( [{"txid":"hex","vout":n,"scriptPubKey":"hex","redeemScript":"hex","witnessScript":"hex","amount":amount},...] "sighashtype" )`
-//! - [ ] `submitpackage ["rawtx",...] ( maxfeerate maxburnamount )`
+//! - [x] `submitpackage ["rawtx",...] ( maxfeerate maxburnamount )`
 //! - [ ] `testmempoolaccept ["rawtx",...] ( maxfeerate )`
 //! - [ ] `utxoupdatepsbt "psbt" ( ["",{"desc":"str","range":n or [n,n]},...] )`
 //!
@@ -182,12 +182,15 @@
 
 mod blockchain;
 mod network;
+mod raw_transactions;
 
 #[doc(inline)]
 pub use self::blockchain::GetBlockchainInfo;
 #[doc(inline)]
 pub use self::network::GetNetworkInfo;
 #[doc(inline)]
+pub use self::raw_transactions::{SubmitPackage, SubmitPackageTxResult, SubmitPackageTxResultFees};
+#[doc(inline)]
 pub use crate::{
     v17::{
         GenerateToAddress, GetBalance, GetBestBlockHash, GetBlockVerbosityOne,
diff --git a/json/src/v28/raw_transactions.rs b/json/src/v28/raw_transactions.rs
@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! The JSON-RPC API for Bitcoin Core v28.0 - raw transactions.
+//!
+//! Types for methods found under the `== Rawtransactions ==` section of the API docs.
+
+use std::collections::HashMap;
+
+use bitcoin::{Amount, FeeRate, Txid, Wtxid};
+use serde::{Deserialize, Serialize};
+
+/// Models the result of JSON-RPC method `submitpackage`.
+//submitpackage ["rawtx",...] ( maxfeerate maxburnamount )
+//
+//Submit a package of raw transactions (serialized, hex-encoded) to local node.
+//The package will be validated according to consensus and mempool policy rules. If any transaction passes, it will be accepted to mempool.
+//This RPC is experimental and the interface may be unstable. Refer to doc/policy/packages.md for documentation on package policies.
+//Warning: successful submission does not mean the transactions will propagate throughout the network.
+//
+//Arguments:
+//1. package          (json array, required) An array of raw transactions.
+//                    The package must solely consist of a child and its parents. None of the parents may depend on each other.
+//                    The package must be topologically sorted, with the child being the last element in the array.
+//     [
+//       "rawtx",     (string)
+//       ...
+//     ]
+//2. maxfeerate       (numeric or string, optional, default="0.10") Reject transactions whose fee rate is higher than the specified value, expressed in BTC/kvB.
+//                    Fee rates larger than 1BTC/kvB are rejected.
+//                    Set to 0 to accept any fee rate.
+//3. maxburnamount    (numeric or string, optional, default="0.00") Reject transactions with provably unspendable outputs (e.g. 'datacarrier' outputs that use the OP_RETURN opcode) greater than the specified value, expressed in BTC.
+//                    If burning funds through unspendable outputs is desired, increase this value.
+//                    This check is based on heuristics and does not guarantee spendability of outputs.
+//
+//
+//Result:
+//{                                   (json object)
+//  "package_msg" : "str",            (string) The transaction package result message. "success" indicates all transactions were accepted into or are already in the mempool.
+//  "tx-results" : {                  (json object) transaction results keyed by wtxid
+//    "wtxid" : {                     (json object) transaction wtxid
+//      "txid" : "hex",               (string) The transaction hash in hex
+//      "other-wtxid" : "hex",        (string, optional) The wtxid of a different transaction with the same txid but different witness found in the mempool. This means the submitted transaction was ignored.
+//      "vsize" : n,                  (numeric, optional) Sigops-adjusted virtual transaction size.
+//      "fees" : {                    (json object, optional) Transaction fees
+//        "base" : n,                 (numeric) transaction fee in BTC
+//        "effective-feerate" : n,    (numeric, optional) if the transaction was not already in the mempool, the effective feerate in BTC per KvB. For example, the package feerate and/or feerate with modified fees from prioritisetransaction.
+//        "effective-includes" : [    (json array, optional) if effective-feerate is provided, the wtxids of the transactions whose fees and vsizes are included in effective-feerate.
+//          "hex",                    (string) transaction wtxid in hex
+//          ...
+//        ]
+//      },
+//      "error" : "str"               (string, optional) The transaction error string, if it was rejected by the mempool
+//    },
+//    ...
+//  },
+//  "replaced-transactions" : [       (json array, optional) List of txids of replaced transactions
+//    "hex",                          (string) The transaction id
+//    ...
+//  ]
+//}
+//
+//Examples:
+//> curl --user myusername --data-binary '{"jsonrpc": "2.0", "id": "curltest", "method": "submitpackage", "params": [["rawtx1", "rawtx2"]]}' -H 'content-type: application/json' http://127.0.0.1:8332/
+//> bitcoin-cli submitpackage '["rawtx1", "rawtx2"]'
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct SubmitPackage {
+    /// The transaction package result message. "success" indicates all transactions were accepted into or are already in the mempool.
+    pub package_msg: String,
+    /// Transaction results keyed by [`Wtxid`].
+    #[serde(rename = "tx-results")]
+    pub tx_results: HashMap<Wtxid, SubmitPackageTxResult>,
+    /// List of txids of replaced transactions.
+    #[serde(rename = "replaced-transactions")]
+    pub replaced_transactions: Vec<Txid>,
+}
+
+/// Models the per-transaction result included in the JSON-RPC method `submitpackage`.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct SubmitPackageTxResult {
+    /// The transaction id.
+    pub txid: Txid,
+    /// The [`Wtxid`] of a different transaction with the same [`Txid`] but different witness found in the mempool.
+    ///
+    /// If set, this means the submitted transaction was ignored.
+    #[serde(rename = "other-wtxid")]
+    pub other_wtxid: Option<Wtxid>,
+    /// Sigops-adjusted virtual transaction size.
+    pub vsize: Option<usize>,
+    /// Transaction fees.
+    pub fees: Option<SubmitPackageTxResultFees>,
+    /// The transaction error string, if it was rejected by the mempool
+    pub error: Option<String>,
+}
+
+/// Models the fees included in the per-transaction result of the JSON-RPC method `submitpackage`.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct SubmitPackageTxResultFees {
+    /// Transaction fee.
+    #[serde(rename = "base")]
+    pub base_fee: Amount,
+    /// The effective feerate.
+    ///
+    /// Will be `None` if the transaction was already in the mempool.
+    ///
+    /// For example, the package feerate and/or feerate with modified fees from the `prioritisetransaction` JSON-RPC method.
+    #[serde(rename = "effective-feerate")]
+    pub effective_feerate: Option<FeeRate>,
+    /// If [`Self::effective_feerate`] is provided, this holds the [`Wtxid`]s of the transactions
+    /// whose fees and vsizes are included in effective-feerate.
+    #[serde(rename = "effective-includes")]
+    pub effective_includes: Vec<Wtxid>,
+}

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ mod raw_transactions {`
`40`	`40`	`use super::*;`
`41`	`41`
`42`	`42`	`impl_test_v17__sendrawtransaction!();`
	`43`	`+ impl_test_v28__submitpackage!();`
`43`	`44`	`}`
`44`	`45`
`45`	`46`	`// == Wallet ==`