walletrpc: add SubmitPackage RPC

Author: bhandras

lnrpc/walletrpc/walletkit.pb.go

@@ -357,6 +357,14 @@ service WalletKit {
     unlock/release any locked UTXOs in case of an error in this method.
     */
     rpc FinalizePsbt (FinalizePsbtRequest) returns (FinalizePsbtResponse);
+
+    /*
+    SubmitPackage attempts to broadcast a transaction package, consisting of
+    one or more parent transactions and exactly one child transaction.
+    The package is submitted to the backend node's mempool atomically.
+    This RPC is primarily used for Child-Pays-For-Parent (CPFP) fee bumping.
+    */
+    rpc SubmitPackage (SubmitPackageRequest) returns (SubmitPackageResponse);
 }
 
 message ListUnspentRequest {
@@ -1592,3 +1600,60 @@ message ListLeasesResponse {
     // The list of currently leased utxos.
     repeated UtxoLease locked_utxos = 1;
 }
+
+message SubmitPackageRequest {
+    // A list of raw, serialized parent transactions. These transactions are
+    // typically the ones being fee-bumped.
+    repeated bytes parent_txs = 1;
+
+    // The raw, serialized child transaction. This transaction spends outputs
+    // from one or more of the parent_txs and should provide sufficient fees for
+    // the entire package.
+    bytes child_tx = 2;
+
+    // An optional fee rate cap for the package, expressed in satoshis per
+    // kilo-weight (sat/kw). If non-zero, the backend node may reject the
+    // package if its effective fee rate exceeds this value. A value of 0
+    // indicates no specific limit should be enforced by the caller.
+    uint32 max_fee_rate_sat_per_kw = 3;
+}
+
+message SubmitPackageResponse {
+    // Overall status message for the package submission (e.g., "success",
+    // or a general reason if the entire package is rejected before individual
+    // transaction checks).
+    string package_msg = 1;
+
+    // Detailed result for each transaction within the submitted package.
+    // The key is the wtxid (witness transaction ID, hex-encoded) of the
+    // transaction as submitted in the package.
+    map<string, TxResult> tx_results = 2;
+
+    // A list of hex-encoded transaction IDs of transactions that were evicted
+    // from the mempool due to replacement by transactions in this package
+    // (as a result of Package RBF).
+    repeated string replaced_transactions = 3;
+
+    // TxResult provides information about a single transaction within the
+    // submitted package.
+    message TxResult {
+        // The transaction hash (txid, hex-encoded) of this transaction.
+        string txid = 1;
+
+        // If the submitted transaction was recognized as a witness-replacement
+        // for an existing mempool transaction (i.e., same txid but different
+        // witness), this field will contain the wtxid (hex-encoded) of the
+        // pre-existing transaction that was kept in the mempool.
+        // This field will be empty if this was not a witness-replacement
+        // scenario or if the submitted transaction was preferred.
+        string other_wtxid = 2;
+
+        // If the transaction was rejected or failed processing for any reason
+        // (either individual checks or package validation rules), this field
+        // contains a human-readable error message.
+        // This field will be empty if the transaction was successfully
+        // processed (i.e., accepted into the mempool or was already present and
+        // valid).
+        string error_message = 3;
+    }
+}

lnrpc/walletrpc/walletkit.pb.json.go

@@ -968,6 +968,24 @@
         }
       }
     },
+    "SubmitPackageResponseTxResult": {
+      "type": "object",
+      "properties": {
+        "txid": {
+          "type": "string",
+          "description": "The transaction hash (txid, hex-encoded) of this transaction."
+        },
+        "other_wtxid": {
+          "type": "string",
+          "description": "If the submitted transaction was recognized as a witness-replacement\nfor an existing mempool transaction (i.e., same txid but different\nwitness), this field will contain the wtxid (hex-encoded) of the\npre-existing transaction that was kept in the mempool.\nThis field will be empty if this was not a witness-replacement\nscenario or if the submitted transaction was preferred."
+        },
+        "error_message": {
+          "type": "string",
+          "description": "If the transaction was rejected or failed processing for any reason\n(either individual checks or package validation rules), this field\ncontains a human-readable error message.\nThis field will be empty if the transaction was successfully\nprocessed (i.e., accepted into the mempool or was already present and\nvalid)."
+        }
+      },
+      "description": "TxResult provides information about a single transaction within the\nsubmitted package."
+    },
     "lnrpcAddressType": {
       "type": "string",
       "enum": [
@@ -2180,6 +2198,29 @@
         }
       }
     },
+    "walletrpcSubmitPackageResponse": {
+      "type": "object",
+      "properties": {
+        "package_msg": {
+          "type": "string",
+          "description": "Overall status message for the package submission (e.g., \"success\",\nor a general reason if the entire package is rejected before individual\ntransaction checks)."
+        },
+        "tx_results": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/SubmitPackageResponseTxResult"
+          },
+          "description": "Detailed result for each transaction within the submitted package.\nThe key is the wtxid (witness transaction ID, hex-encoded) of the\ntransaction as submitted in the package."
+        },
+        "replaced_transactions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "A list of hex-encoded transaction IDs of transactions that were evicted\nfrom the mempool due to replacement by transactions in this package\n(as a result of Package RBF)."
+        }
+      }
+    },
     "walletrpcTapLeaf": {
       "type": "object",
       "properties": {

lnrpc/walletrpc/walletkit.proto

@@ -185,6 +185,10 @@ var (
 			Entity: "onchain",
 			Action: "write",
 		}},
+		"/walletrpc.WalletKit/SubmitPackage": {{
+			Entity: "onchain",
+			Action: "write",
+		}},
 	}
 
 	// DefaultWalletKitMacFilename is the default name of the wallet kit
@@ -3078,3 +3082,94 @@ func (w *WalletKit) ImportTapscript(_ context.Context,
 		P2TrAddress: addr.Address().String(),
 	}, nil
 }
+
+// SubmitPackage attempts to broadcast a transaction package, consisting of one
+// or more parent transactions and exactly one child transaction. The package is
+// submitted to the backend node's mempool atomically. This RPC is primarily
+// used for Child-Pays-For-Parent (CPFP) fee bumping.
+func (w *WalletKit) SubmitPackage(ctx context.Context,
+	req *SubmitPackageRequest) (*SubmitPackageResponse, error) {
+
+	// Validate that there's at least one parent transaction.
+	if len(req.ParentTxs) == 0 {
+		return nil, fmt.Errorf("at least one parent transaction is " +
+			"required")
+	}
+
+	// Validate that there's a child transaction specified.
+	if len(req.ChildTx) == 0 {
+		return nil, fmt.Errorf("child transaction is required")
+	}
+
+	// Deserialize parent transactions.
+	parents := make([]*wire.MsgTx, 0, len(req.ParentTxs))
+	for i, parentBytes := range req.ParentTxs {
+		if len(parentBytes) == 0 {
+			return nil, fmt.Errorf("parent transaction at index "+
+				"%d is empty", i)
+		}
+
+		parentTx := wire.NewMsgTx(wire.TxVersion)
+		err := parentTx.Deserialize(bytes.NewReader(parentBytes))
+		if err != nil {
+			return nil, fmt.Errorf("failed to deserialize parent "+
+				"transaction at index %d: %w", i, err)
+		}
+
+		parents = append(parents, parentTx)
+	}
+
+	// Deserialize child transaction.
+	childTx := wire.NewMsgTx(wire.TxVersion)
+	err := childTx.Deserialize(bytes.NewReader(req.ChildTx))
+	if err != nil {
+		return nil, fmt.Errorf("failed to deserialize child "+
+			"transaction: %w", err)
+	}
+
+	// Attempt to submit the package using the underlying wallet.
+	submitPackageResult, err := w.cfg.Wallet.SubmitPackage(
+		parents, childTx,
+		chainfee.SatPerKWeight(req.MaxFeeRateSatPerKw),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("failed to submit package: %w", err)
+	}
+
+	// Translate the wallet's Go result to the protobuf response.
+	protoResponse := &SubmitPackageResponse{
+		PackageMsg: submitPackageResult.PackageMsg,
+		TxResults:  make(map[string]*SubmitPackageResponse_TxResult),
+	}
+
+	// Translate TxResults.
+	for wtxid, txRes := range submitPackageResult.TxResults {
+		protoTxRes := &SubmitPackageResponse_TxResult{
+			Txid: txRes.TxID.String(),
+		}
+		if txRes.OtherWtxid != nil {
+			protoTxRes.OtherWtxid = txRes.OtherWtxid.String()
+		}
+		if txRes.Error != nil {
+			protoTxRes.ErrorMessage = *txRes.Error
+		}
+
+		protoResponse.TxResults[wtxid] = protoTxRes
+	}
+
+	// Translate ReplacedTransactions.
+	if len(submitPackageResult.ReplacedTransactions) > 0 {
+		protoResponse.ReplacedTransactions = make(
+			[]string, 0,
+			len(submitPackageResult.ReplacedTransactions),
+		)
+		for _, hash := range submitPackageResult.ReplacedTransactions {
+			protoResponse.ReplacedTransactions = append(
+				protoResponse.ReplacedTransactions,
+				hash.String(),
+			)
+		}
+	}
+
+	return protoResponse, nil
+}