chain: add SubmitPackage API for atomic parents+child relay

This commit introduces first-class support for Bitcoin Core's
`submitpackage` RPC (v26+), allowing btcwallet users to broadcast
(potentially zero‑fee) unconfirmed parent txns together with its
(fee‑paying) child in one call.

Author: bhandras

chain/bitcoind_client.go

@@ -1,8 +1,10 @@
 package chain
 
 import (
+	"bytes"
 	"container/list"
 	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"sync"
@@ -1335,6 +1337,130 @@ func (c *BitcoindClient) LookupInputMempoolSpend(op wire.OutPoint) (
 	return c.chainConn.events.LookupInputSpend(op)
 }
 
+// SubmitPackage broadcasts a parents+child package atomically.
+//
+// `parents` must contain at least one transaction. The returned slice
+// holds the txids of every transaction that entered the mempool.
+//
+// `maxFeeRateBTCPerVByte` caps the effective feerate the node will
+// accept for the entire package, expressed in BTC per virtual byte.
+// Pass nil to leave the limit unset.
+//
+// If the active backend cannot relay packages, ErrUnimplemented is
+// returned.
+func (c *BitcoindClient) SubmitPackage(parents []*wire.MsgTx, child *wire.MsgTx,
+	maxFeeRateBTCPerVByte *float64) ([]*chainhash.Hash, error) {
+
+	// Sanity check inputs.
+	if len(parents) == 0 {
+		return nil, errors.New("submitpackage: need at least one " +
+			"parent txn")
+	}
+
+	if child == nil {
+		return nil, errors.New("submitpackage: child txn not defined")
+	}
+
+	// Prepare the hex encoded transactions to that we'll add the the
+	// request.
+	toHex := func(tx *wire.MsgTx) (string, error) {
+		var buf bytes.Buffer
+		if err := tx.Serialize(&buf); err != nil {
+			return "", err
+		}
+
+		return hex.EncodeToString(buf.Bytes()), nil
+	}
+
+	rawTxs := make([]string, 0, len(parents)+1)
+
+	for i, ch := range parents {
+		h, err := toHex(ch)
+		if err != nil {
+			return nil, fmt.Errorf("cannot serialize parent txn "+
+				"%d: %w", i, err)
+		}
+
+		rawTxs = append(rawTxs, h)
+	}
+
+	h, err := toHex(child)
+	if err != nil {
+		return nil, fmt.Errorf("cannot serialize child txn: %w", err)
+	}
+
+	rawTxs = append(rawTxs, h)
+
+	// Parameter 1: The package (array of hex strings).
+	rawTxsJSON, err := json.Marshal(rawTxs)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal raw txs array: %w",
+			err)
+	}
+
+	params := []json.RawMessage{rawTxsJSON}
+
+	// Parameter 2: maxfeerate (optional, numeric, in BTC/kvB)
+	if maxFeeRateBTCPerVByte != nil {
+		// Convert BTC/vByte to BTC/kvB.
+		maxFeeRateBTCPerKvB := *maxFeeRateBTCPerVByte * 1000
+		maxFeeRateJSON, err := json.Marshal(maxFeeRateBTCPerKvB)
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal "+
+				"maxfeerate: %w", err)
+		}
+
+		params = append(params, maxFeeRateJSON)
+	}
+
+	resp, err := c.chainConn.client.RawRequest("submitpackage", params)
+	if err != nil {
+		if isMethodNotFound(err) {
+			return nil, ErrUnimplemented
+		}
+		return nil, err
+	}
+
+	// Unmarshall the response.
+	var result btcjson.SubmitPackageResult
+	if err := json.Unmarshal(resp, &result); err != nil {
+		return nil, err
+	}
+
+	submittedIDs := make([]*chainhash.Hash, 0, len(result.TxResults))
+	for _, txRes := range result.TxResults {
+		if txRes.Error != nil {
+			// Skip rejected transactions.
+			continue
+		}
+
+		if txRes.OtherWtxid != nil {
+			// This is a child transaction that was already
+			// in the mempool.
+			continue
+		}
+
+		h, err := chainhash.NewHashFromStr(txRes.TxID)
+		if err != nil {
+			// Note that this should never happen.
+			return nil, fmt.Errorf("failed to parse txid '%s' "+
+				"from submitpackage result: %w", txRes.TxID,
+				err)
+		}
+
+		submittedIDs = append(submittedIDs, h)
+	}
+
+	return submittedIDs, nil
+}
+
+// isMethodNotFound returns true if err is exactly the JSON‑RPC "method not
+// found" error, regardless of the transport.
+func isMethodNotFound(err error) bool {
+	rpcErr, ok := err.(*btcjson.RPCError)
+	return ok && rpcErr.Code == btcjson.ErrRPCMethodNotFound.Code
+}
+
 // resetWatchedFilters empties the maps used to track outpoints, addresses, and
 // txns.
 func (c *BitcoindClient) resetWatchedFilters() {

chain/btcd.go

@@ -639,3 +639,11 @@ func (c *RPCClient) SendRawTransaction(tx *wire.MsgTx,
 
 	return txid, nil
 }
+
+// SubmitPackage is currently unimplemented for btcd. The method is added to
+// satisfy the chain.Interface interface.
+func (c *RPCClient) SubmitPackage(_ []*wire.MsgTx, _ *wire.MsgTx,
+	maxFeeRateBTCPerVByte *float64) ([]*chainhash.Hash, error) {
+
+	return nil, ErrUnimplemented
+}

chain/interface.go

@@ -49,6 +49,21 @@ type Interface interface {
 	Notifications() <-chan interface{}
 	BackEnd() string
 	TestMempoolAccept([]*wire.MsgTx, float64) ([]*btcjson.TestMempoolAcceptResult, error)
+
+	// SubmitPackage broadcasts a parents+child package atomically.
+	//
+	// `parents` must contain at least one transaction. The returned slice
+	// holds the txids of every transaction that entered the mempool.
+	//
+	// `maxFeeRateBTCPerVByte` caps the effective feerate the node will
+	// accept for the entire package, expressed in BTC per virtual byte.
+	// Pass nil to leave the limit unset.
+	//
+	// If the active backend cannot relay packages, ErrUnimplemented is
+	// returned.
+	SubmitPackage(parents []*wire.MsgTx, child *wire.MsgTx,
+		maxFeeRateBTCPerVByte *float64) ([]*chainhash.Hash, error)
+
 	MapRPCErr(err error) error
 }
 

chain/neutrino.go

@@ -844,3 +844,11 @@ func (s *NeutrinoClient) MapRPCErr(rpcErr error) error {
 	// If not matched, return the original error wrapped.
 	return fmt.Errorf("%w: %v", ErrUndefined, rpcErr)
 }
+
+// SubmitPackage is currently unimplemented for neutrino. The method is added to
+// satisfy the chain.Interface interface.
+func (s *NeutrinoClient) SubmitPackage(_ []*wire.MsgTx, _ *wire.MsgTx,
+	maxFeeRateBTCPerVByte *float64) ([]*chainhash.Hash, error) {
+
+	return nil, ErrUnimplemented
+}

go.mod

@@ -53,4 +53,7 @@ require (
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
+// TODO(bhandras): remove this replace once the upstream PR is merged
+replace github.com/btcsuite/btcd => github.com/bhandras/btcd v0.22.0-beta.0.20250505192317-88de59959669
+
 go 1.22