opnet 1.8.2 → 1.8.4

package/build/utxos/UTXOsManager.d.ts

@@ -11,6 +11,7 @@ export declare class UTXOsManager {
     getUTXOs({ address, isCSV, optimize, mergePendingUTXOs, filterSpentUTXOs, olderThan, }: RequestUTXOsParams): Promise<UTXOs>;
     getUTXOsForAmount({ address, amount, csvAddress, optimize, mergePendingUTXOs, filterSpentUTXOs, throwErrors, olderThan, maxUTXOs, throwIfUTXOsLimitReached, }: RequestUTXOsParamsWithAmount): Promise<UTXOs>;
     getMultipleUTXOs({ requests, mergePendingUTXOs, filterSpentUTXOs, }: RequestMultipleUTXOsParams): Promise<Record<string, UTXOs>>;
+    private selectUTXOsGreedily;
     private fetchMultipleUTXOs;
     private getAddressData;
     private maybeFetchUTXOs;

package/build/utxos/UTXOsManager.js

@@ -96,44 +96,31 @@ export class UTXOsManager {
         return finalUTXOs;
     }
     async getUTXOsForAmount({ address, amount, csvAddress, optimize = true, mergePendingUTXOs = true, filterSpentUTXOs = true, throwErrors = false, olderThan, maxUTXOs = 5000, throwIfUTXOsLimitReached = false, }) {
-        const utxosPromises = [];
-        if (csvAddress) {
-            utxosPromises.push(this.getUTXOs({
+        const selected = [];
+        let currentValue = 0n;
+        const normalUTXOs = await this.getUTXOs({
+            address,
+            optimize,
+            mergePendingUTXOs,
+            filterSpentUTXOs,
+            olderThan,
+        });
+        currentValue = this.selectUTXOsGreedily(normalUTXOs, selected, currentValue, amount, maxUTXOs, throwIfUTXOsLimitReached);
+        if (currentValue < amount && csvAddress) {
+            const csvUTXOs = await this.getUTXOs({
                 address: csvAddress,
                 optimize: true,
                 mergePendingUTXOs: false,
                 filterSpentUTXOs: true,
                 olderThan: 1n,
                 isCSV: true,
-            }));
-        }
-        utxosPromises.push(this.getUTXOs({
-            address,
-            optimize,
-            mergePendingUTXOs,
-            filterSpentUTXOs,
-            olderThan,
-        }));
-        const combinedUTXOs = (await Promise.all(utxosPromises)).flat();
-        const utxoUntilAmount = [];
-        let currentValue = 0n;
-        for (const utxo of combinedUTXOs) {
-            if (maxUTXOs && utxoUntilAmount.length >= maxUTXOs) {
-                if (throwIfUTXOsLimitReached) {
-                    throw new Error(`Woah. You must consolidate your UTXOs (${combinedUTXOs.length})! This transaction is too large.`);
-                }
-                break;
-            }
-            utxoUntilAmount.push(utxo);
-            currentValue += utxo.value;
-            if (currentValue >= amount) {
-                break;
-            }
+            });
+            currentValue = this.selectUTXOsGreedily(csvUTXOs, selected, currentValue, amount, maxUTXOs, throwIfUTXOsLimitReached);
         }
         if (currentValue < amount && throwErrors) {
             throw new Error(`Insufficient UTXOs to cover amount. Available: ${currentValue}, Needed: ${amount}`);
         }
-        return utxoUntilAmount;
+        return selected;
     }
     async getMultipleUTXOs({ requests, mergePendingUTXOs = true, filterSpentUTXOs = true, }) {
         if (requests.length === 0) {
@@ -190,6 +177,28 @@ export class UTXOsManager {
         }
         return result;
     }
+    selectUTXOsGreedily(candidates, selected, currentValue, amount, maxUTXOs, throwIfLimitReached) {
+        candidates.sort((a, b) => {
+            if (b.value > a.value)
+                return 1;
+            if (b.value < a.value)
+                return -1;
+            return 0;
+        });
+        for (const utxo of candidates) {
+            if (currentValue >= amount)
+                break;
+            if (maxUTXOs && selected.length >= maxUTXOs) {
+                if (throwIfLimitReached) {
+                    throw new Error(`Woah. You must consolidate your UTXOs (${candidates.length + selected.length})! This transaction is too large.`);
+                }
+                break;
+            }
+            selected.push(utxo);
+            currentValue += utxo.value;
+        }
+        return currentValue;
+    }
     async fetchMultipleUTXOs(requests) {
         const payloads = requests.map((request) => {
             const data = [request.address, request.optimize ?? true];

package/docs/api-reference/provider-api.md

@@ -218,6 +218,22 @@ Broadcast multiple transactions.
 sendRawTransactions(txs: string[]): Promise<BroadcastedTransaction[]>
 ```
 
+### sendRawTransactionPackage
+
+Broadcast a package of raw transactions atomically via Bitcoin Core's `submitpackage` RPC, or fall back to validated sequential broadcast.
+
+```typescript
+sendRawTransactionPackage(
+    txs: string[],
+    isPackage?: boolean
+): Promise<BroadcastedTransactionPackage>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `txs` | `string[]` | Required | Raw transactions as hex strings (max 25) |
+| `isPackage` | `boolean` | `true` | Use atomic `submitpackage` (`true`) or validated sequential broadcast (`false`) |
+
 ### getChallenge
 
 Get the current PoW challenge.

package/docs/api-reference/types-interfaces.md

@@ -274,6 +274,97 @@ interface BroadcastedTransaction {
 }
 ```
 
+### BroadcastedTransactionPackage
+
+Result of a package broadcast via [`sendRawTransactionPackage()`](./provider-api.md#sendrawtransactionpackage).
+
+```typescript
+interface BroadcastedTransactionPackage {
+    /** Whether the overall package broadcast succeeded. */
+    readonly success: boolean;
+    /** Error message if the broadcast failed. */
+    readonly error?: string;
+    /** Present when testMempoolAccept was used (sequential or single tx path). */
+    readonly testResults?: readonly TestMempoolAcceptResult[];
+    /** Present when submitPackage was used successfully. */
+    readonly packageResult?: PackageResult;
+    /** Per-transaction results for sequential or single tx broadcasts. */
+    readonly sequentialResults?: readonly SequentialBroadcastTxResult[];
+    /** True when submitPackage failed and the node fell back to sequential broadcast. */
+    readonly fellBackToSequential?: boolean;
+}
+```
+
+### SequentialBroadcastTxResult
+
+```typescript
+interface SequentialBroadcastTxResult {
+    readonly txid: string;
+    readonly success: boolean;
+    readonly error?: string;
+    readonly peers?: number;
+}
+```
+
+### TestMempoolAcceptResult
+
+```typescript
+interface TestMempoolAcceptResult {
+    readonly txid: string;
+    readonly wtxid: string;
+    readonly allowed?: boolean;
+    readonly vsize?: number;
+    readonly packageError?: string;
+    readonly rejectReason?: string;
+    readonly rejectDetails?: string;
+    readonly fees?: TestMempoolAcceptFees;
+}
+```
+
+### TestMempoolAcceptFees
+
+```typescript
+interface TestMempoolAcceptFees {
+    readonly base: number;
+    readonly effectiveFeerate: number;
+    readonly effectiveIncludes: readonly string[];
+}
+```
+
+### PackageResult
+
+```typescript
+interface PackageResult {
+    readonly packageMsg: string;
+    readonly txResults: {
+        readonly [wtxid: string]: PackageTxResult;
+    };
+    readonly replacedTransactions?: readonly string[];
+}
+```
+
+### PackageTxResult
+
+```typescript
+interface PackageTxResult {
+    readonly txid: string;
+    readonly otherWtxid?: string;
+    readonly vsize?: number;
+    readonly fees?: PackageTxFees;
+    readonly error?: string;
+}
+```
+
+### PackageTxFees
+
+```typescript
+interface PackageTxFees {
+    readonly base: number;
+    readonly effectiveFeerate?: number;
+    readonly effectiveIncludes?: readonly string[];
+}
+```
+
 ---
 
 ## Contract Types

package/docs/api-reference/utxo-manager-api.md

@@ -53,12 +53,14 @@ async getUTXOsForAmount(
 interface RequestUTXOsParamsWithAmount extends RequestUTXOsParams {
     readonly amount: bigint;                    // Amount to cover
     readonly throwErrors?: boolean;             // Throw if insufficient
-    readonly csvAddress?: string;               // CSV address for priority
-    readonly maxUTXOs?: number;                 // Max UTXOs to select
+    readonly csvAddress?: string;               // CSV address as fallback
+    readonly maxUTXOs?: number;                 // Max UTXOs to select (default: 5000)
     readonly throwIfUTXOsLimitReached?: boolean; // Throw if limit reached
 }
 ```
 
+> **Note:** `getUTXOsForAmount` prioritizes normal UTXOs first and only falls back to CSV UTXOs if normal ones cannot cover the requested amount. UTXOs are sorted by value descending (largest first) for greedy selection.
+
 ### spentUTXO
 
 Mark UTXOs as spent and register new UTXOs (for tracking).

package/docs/svg/tx-broadcast-flow.svg

@@ -0,0 +1,201 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 1080" font-family="'Segoe UI','Helvetica Neue',sans-serif">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0.3" y2="1">
+      <stop offset="0%" stop-color="#1a1520"/>
+      <stop offset="50%" stop-color="#151119"/>
+      <stop offset="100%" stop-color="#0e0b12"/>
+    </linearGradient>
+    <linearGradient id="card" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#2a2233"/>
+      <stop offset="100%" stop-color="#1f1928"/>
+    </linearGradient>
+    <linearGradient id="entryGrad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#c084fc"/>
+      <stop offset="100%" stop-color="#a855f7"/>
+    </linearGradient>
+    <filter id="softGlow">
+      <feGaussianBlur stdDeviation="6" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <filter id="cardShadow">
+      <feDropShadow dx="0" dy="4" stdDeviation="8" flood-color="#000" flood-opacity="0.35"/>
+    </filter>
+    <marker id="arrW" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
+      <path d="M0,0 L7,2.5 L0,5" fill="none" stroke="#7c6f8a" stroke-width="1.2" stroke-linejoin="round"/>
+    </marker>
+    <marker id="arrG" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
+      <path d="M0,0 L7,2.5 L0,5" fill="none" stroke="#4ade80" stroke-width="1.2" stroke-linejoin="round"/>
+    </marker>
+    <marker id="arrR" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
+      <path d="M0,0 L7,2.5 L0,5" fill="none" stroke="#fb7185" stroke-width="1.2" stroke-linejoin="round"/>
+    </marker>
+    <marker id="arrO" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
+      <path d="M0,0 L7,2.5 L0,5" fill="none" stroke="#fbbf24" stroke-width="1.2" stroke-linejoin="round"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="860" height="1080" fill="url(#bg)" rx="16"/>
+
+  <!-- Decorative ambient circles -->
+  <circle cx="780" cy="80" r="120" fill="#a855f7" opacity="0.03"/>
+  <circle cx="60" cy="950" r="160" fill="#4ade80" opacity="0.025"/>
+  <circle cx="430" cy="540" r="300" fill="#a855f7" opacity="0.012"/>
+
+  <!-- ====== TITLE ====== -->
+  <text x="430" y="52" text-anchor="middle" fill="#e8dff0" font-size="22" font-weight="600" letter-spacing="0.5">How Transactions Get Broadcast</text>
+  <text x="430" y="76" text-anchor="middle" fill="#7c6f8a" font-size="13">From your wallet to the Bitcoin network</text>
+
+  <!-- ====== ENTRY PILL ====== -->
+  <rect x="295" y="104" width="270" height="52" rx="26" fill="url(#entryGrad)" filter="url(#softGlow)" opacity="0.9"/>
+  <text x="430" y="127" text-anchor="middle" fill="#fff" font-size="14" font-weight="600">You submit transactions</text>
+  <text x="430" y="145" text-anchor="middle" fill="#ede2ff" font-size="11" opacity="0.85">one or more, as an ordered batch</text>
+
+  <!-- Arrow down -->
+  <line x1="430" y1="156" x2="430" y2="194" stroke="#7c6f8a" stroke-width="1.5" marker-end="url(#arrW)"/>
+
+  <!-- ====== DECISION: How many? ====== -->
+  <rect x="320" y="198" width="220" height="48" rx="24" fill="url(#card)" stroke="#3d3350" stroke-width="1" filter="url(#cardShadow)"/>
+  <text x="430" y="220" text-anchor="middle" fill="#d4bfea" font-size="13" font-weight="500">How many transactions?</text>
+  <text x="430" y="237" text-anchor="middle" fill="#7c6f8a" font-size="11">checking the batch size</text>
+
+  <!-- ====== PATH A: Just One (left branch) ====== -->
+  <line x1="320" y1="222" x2="150" y2="222" stroke="#4ade80" stroke-width="1.5" marker-end="url(#arrG)"/>
+  <rect x="128" y="206" width="48" height="20" rx="10" fill="#1a2e1a"/>
+  <text x="152" y="220" text-anchor="middle" fill="#4ade80" font-size="10" font-weight="600">JUST 1</text>
+
+  <rect x="22" y="258" width="220" height="120" rx="14" fill="url(#card)" stroke="#2d4a2d" stroke-width="1" filter="url(#cardShadow)"/>
+  <circle cx="50" cy="286" r="12" fill="#1a2e1a" stroke="#4ade80" stroke-width="1"/>
+  <text x="50" y="291" text-anchor="middle" fill="#4ade80" font-size="14">1</text>
+  <text x="72" y="291" fill="#d4bfea" font-size="13" font-weight="500">Simple Path</text>
+  <line x1="38" y1="306" x2="226" y2="306" stroke="#2d4a2d" stroke-width="0.7"/>
+  <text x="132" y="326" text-anchor="middle" fill="#b8a5cc" font-size="11.5">First, validate the transaction</text>
+  <text x="132" y="344" text-anchor="middle" fill="#b8a5cc" font-size="11.5">against the mempool.</text>
+  <text x="132" y="365" text-anchor="middle" fill="#b8a5cc" font-size="11.5">If it passes, send it out.</text>
+
+  <line x1="132" y1="378" x2="132" y2="410" stroke="#4ade80" stroke-width="1.2" marker-end="url(#arrG)"/>
+  <rect x="82" y="414" width="100" height="30" rx="15" fill="#0f2a14" stroke="#22c55e" stroke-width="1"/>
+  <text x="132" y="434" text-anchor="middle" fill="#4ade80" font-size="12" font-weight="500">Done</text>
+
+  <!-- ====== Multiple txs (down branch) ====== -->
+  <line x1="430" y1="246" x2="430" y2="294" stroke="#7c6f8a" stroke-width="1.5" marker-end="url(#arrW)"/>
+  <rect x="380" y="252" width="82" height="20" rx="10" fill="#1f1928"/>
+  <text x="421" y="266" text-anchor="middle" fill="#b8a5cc" font-size="10">MULTIPLE</text>
+
+  <!-- ====== DECISION: Package mode? ====== -->
+  <rect x="310" y="298" width="240" height="48" rx="24" fill="url(#card)" stroke="#3d3350" stroke-width="1" filter="url(#cardShadow)"/>
+  <text x="430" y="320" text-anchor="middle" fill="#d4bfea" font-size="13" font-weight="500">Try package mode?</text>
+  <text x="430" y="337" text-anchor="middle" fill="#7c6f8a" font-size="11">on by default</text>
+
+  <!-- ====== PATH B: Package Submission (right branch) ====== -->
+  <line x1="550" y1="322" x2="618" y2="322" stroke="#4ade80" stroke-width="1.5" marker-end="url(#arrG)"/>
+  <rect x="560" y="306" width="44" height="20" rx="10" fill="#1a2e1a"/>
+  <text x="582" y="320" text-anchor="middle" fill="#4ade80" font-size="10" font-weight="600">YES</text>
+
+  <rect x="622" y="270" width="216" height="142" rx="14" fill="url(#card)" stroke="#2d4a2d" stroke-width="1" filter="url(#cardShadow)"/>
+  <circle cx="650" cy="298" r="12" fill="#1a2e1a" stroke="#4ade80" stroke-width="1"/>
+  <text x="650" y="303" text-anchor="middle" fill="#4ade80" font-size="14">2</text>
+  <text x="672" y="303" fill="#d4bfea" font-size="13" font-weight="500">Package Relay</text>
+  <line x1="638" y1="318" x2="822" y2="318" stroke="#2d4a2d" stroke-width="0.7"/>
+  <text x="730" y="339" text-anchor="middle" fill="#b8a5cc" font-size="11.5">Submit all transactions as</text>
+  <text x="730" y="357" text-anchor="middle" fill="#b8a5cc" font-size="11.5">a single atomic package.</text>
+  <text x="730" y="378" text-anchor="middle" fill="#b8a5cc" font-size="11.5">The network validates them</text>
+  <text x="730" y="396" text-anchor="middle" fill="#b8a5cc" font-size="11.5">together, including fees.</text>
+
+  <!-- Package success -->
+  <line x1="838" y1="341" x2="852" y2="341" stroke="#4ade80" stroke-width="1"/>
+  <line x1="852" y1="341" x2="852" y2="430" stroke="#4ade80" stroke-width="1"/>
+  <line x1="852" y1="430" x2="790" y2="430" stroke="#4ade80" stroke-width="1.2" marker-end="url(#arrG)"/>
+  <rect x="690" y="416" width="95" height="30" rx="15" fill="#0f2a14" stroke="#22c55e" stroke-width="1"/>
+  <text x="737" y="436" text-anchor="middle" fill="#4ade80" font-size="12" font-weight="500">Done</text>
+  <text x="848" y="390" fill="#4ade80" font-size="10" font-weight="500">OK</text>
+
+  <!-- Package failure: fallback -->
+  <line x1="730" y1="412" x2="730" y2="482" stroke="#fbbf24" stroke-width="1.5" stroke-dasharray="5,4" marker-end="url(#arrO)"/>
+  <rect x="688" y="454" width="84" height="20" rx="10" fill="#2e2510"/>
+  <text x="730" y="468" text-anchor="middle" fill="#fbbf24" font-size="10" font-weight="600">FAILED</text>
+
+  <rect x="640" y="486" width="180" height="56" rx="12" fill="#2a2010" stroke="#92400e" stroke-width="1" filter="url(#cardShadow)"/>
+  <text x="730" y="510" text-anchor="middle" fill="#fbbf24" font-size="12" font-weight="500">Falls back gracefully</text>
+  <text x="730" y="528" text-anchor="middle" fill="#a08050" font-size="10.5">tries the one-by-one approach</text>
+
+  <!-- Fallback arrow merges into sequential path -->
+  <path d="M640,514 Q560,560 500,580" fill="none" stroke="#fbbf24" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrO)"/>
+
+  <!-- ====== PATH C: Sequential (down from package decision) ====== -->
+  <line x1="430" y1="346" x2="430" y2="488" stroke="#fb7185" stroke-width="1.5" marker-end="url(#arrR)"/>
+  <rect x="408" y="352" width="38" height="20" rx="10" fill="#2e1a1f"/>
+  <text x="427" y="366" text-anchor="middle" fill="#fb7185" font-size="10" font-weight="600">NO</text>
+
+  <!-- Merge zone label -->
+  <rect x="126" y="480" width="410" height="28" rx="14" fill="none" stroke="#3d3350" stroke-width="0.8" stroke-dasharray="6,4"/>
+  <text x="331" y="499" text-anchor="middle" fill="#7c6f8a" font-size="10.5">One-by-one approach (or fallback from package failure)</text>
+
+  <!-- Step 3: Validate all -->
+  <rect x="250" y="530" width="290" height="100" rx="14" fill="url(#card)" stroke="#3d2d4a" stroke-width="1" filter="url(#cardShadow)"/>
+  <circle cx="282" cy="560" r="14" fill="#2a1a38" stroke="#a855f7" stroke-width="1"/>
+  <text x="282" y="565" text-anchor="middle" fill="#c084fc" font-size="13" font-weight="600">3</text>
+  <text x="306" y="565" fill="#d4bfea" font-size="13" font-weight="500">Validate Everything First</text>
+  <line x1="266" y1="580" x2="524" y2="580" stroke="#3d2d4a" stroke-width="0.7"/>
+  <text x="395" y="600" text-anchor="middle" fill="#b8a5cc" font-size="11.5">Check every transaction against</text>
+  <text x="395" y="618" text-anchor="middle" fill="#b8a5cc" font-size="11.5">the mempool before sending any.</text>
+
+  <line x1="395" y1="630" x2="395" y2="668" stroke="#7c6f8a" stroke-width="1.5" marker-end="url(#arrW)"/>
+
+  <rect x="290" y="672" width="210" height="42" rx="21" fill="url(#card)" stroke="#3d3350" stroke-width="1"/>
+  <text x="395" y="698" text-anchor="middle" fill="#d4bfea" font-size="12.5">Did they all pass?</text>
+
+  <!-- Fail left -->
+  <line x1="290" y1="693" x2="180" y2="693" stroke="#fb7185" stroke-width="1.5" marker-end="url(#arrR)"/>
+  <rect x="236" y="680" width="42" height="18" rx="9" fill="#2e1a1f"/>
+  <text x="257" y="693" text-anchor="middle" fill="#fb7185" font-size="10" font-weight="600">NO</text>
+
+  <rect x="36" y="676" width="140" height="42" rx="12" fill="#2a0f15" stroke="#9f1239" stroke-width="1" filter="url(#cardShadow)"/>
+  <text x="106" y="695" text-anchor="middle" fill="#fb7185" font-size="12" font-weight="500">Rejected</text>
+  <text x="106" y="710" text-anchor="middle" fill="#885060" font-size="10">tells you what failed</text>
+
+  <!-- Pass down -->
+  <line x1="395" y1="714" x2="395" y2="758" stroke="#4ade80" stroke-width="1.5" marker-end="url(#arrG)"/>
+  <rect x="370" y="722" width="44" height="18" rx="9" fill="#1a2e1a"/>
+  <text x="392" y="735" text-anchor="middle" fill="#4ade80" font-size="10" font-weight="600">YES</text>
+
+  <!-- Step 4: Send one by one -->
+  <rect x="250" y="762" width="290" height="118" rx="14" fill="url(#card)" stroke="#3d2d4a" stroke-width="1" filter="url(#cardShadow)"/>
+  <circle cx="282" cy="792" r="14" fill="#2a1a38" stroke="#a855f7" stroke-width="1"/>
+  <text x="282" y="797" text-anchor="middle" fill="#c084fc" font-size="13" font-weight="600">4</text>
+  <text x="306" y="797" fill="#d4bfea" font-size="13" font-weight="500">Send One by One</text>
+  <line x1="266" y1="812" x2="524" y2="812" stroke="#3d2d4a" stroke-width="0.7"/>
+  <text x="395" y="832" text-anchor="middle" fill="#b8a5cc" font-size="11.5">Send each transaction in order.</text>
+  <text x="395" y="852" text-anchor="middle" fill="#b8a5cc" font-size="11.5">If one fails, stop immediately</text>
+  <text x="395" y="870" text-anchor="middle" fill="#b8a5cc" font-size="11.5">since later ones depend on it.</text>
+
+  <!-- Fail branch from send loop -->
+  <line x1="250" y1="840" x2="180" y2="840" stroke="#fb7185" stroke-width="1.2" marker-end="url(#arrR)"/>
+  <rect x="36" y="822" width="140" height="42" rx="12" fill="#2a0f15" stroke="#9f1239" stroke-width="1" filter="url(#cardShadow)"/>
+  <text x="106" y="841" text-anchor="middle" fill="#fb7185" font-size="12" font-weight="500">Stopped early</text>
+  <text x="106" y="856" text-anchor="middle" fill="#885060" font-size="10">partial results returned</text>
+
+  <!-- Loop indicator -->
+  <path d="M540,800 C574,800 574,864 540,864" fill="none" stroke="#7c6f8a" stroke-width="1" stroke-dasharray="3,3"/>
+  <text x="582" y="836" fill="#7c6f8a" font-size="10">repeats</text>
+
+  <!-- Success from send loop -->
+  <line x1="395" y1="880" x2="395" y2="920" stroke="#4ade80" stroke-width="1.5" marker-end="url(#arrG)"/>
+
+  <!-- Final success -->
+  <rect x="335" y="924" width="120" height="36" rx="18" fill="#0f2a14" stroke="#22c55e" stroke-width="1.2" filter="url(#softGlow)"/>
+  <text x="395" y="948" text-anchor="middle" fill="#4ade80" font-size="13" font-weight="600">All sent</text>
+
+  <!-- ====== LEGEND ====== -->
+  <rect x="50" y="990" width="760" height="70" rx="14" fill="#1a1520" stroke="#2a2233" stroke-width="1"/>
+  <circle cx="100" cy="1025" r="8" fill="#0f2a14" stroke="#22c55e" stroke-width="1"/>
+  <text x="118" y="1030" fill="#9a8aaa" font-size="11">Success</text>
+  <circle cx="220" cy="1025" r="8" fill="#2a0f15" stroke="#f43f5e" stroke-width="1"/>
+  <text x="238" y="1030" fill="#9a8aaa" font-size="11">Failure</text>
+  <circle cx="340" cy="1025" r="8" fill="#2a2010" stroke="#f59e0b" stroke-width="1"/>
+  <text x="358" y="1030" fill="#9a8aaa" font-size="11">Fallback</text>
+  <line x1="460" y1="1025" x2="490" y2="1025" stroke="#7c6f8a" stroke-width="1.5" marker-end="url(#arrW)"/>
+  <text x="500" y="1030" fill="#9a8aaa" font-size="11">Flow</text>
+  <line x1="570" y1="1025" x2="600" y2="1025" stroke="#fbbf24" stroke-width="1.5" stroke-dasharray="5,4" marker-end="url(#arrO)"/>
+  <text x="610" y="1030" fill="#9a8aaa" font-size="11">Graceful retry</text>
+</svg>

package/docs/transactions/broadcasting.md

@@ -6,15 +6,7 @@ This guide covers broadcasting raw transactions on OPNet.
 
 After building and signing a transaction, it needs to be broadcast to the network. OPNet supports both single and batch transaction broadcasting.
 
-```mermaid
-flowchart LR
-    A[Signed Transaction] --> B[sendRawTransaction]
-    B --> C[Network]
-    C --> D[BroadcastedTransaction]
-    D --> E{Success?}
-    E -->|Yes| F[Propagated]
-    E -->|No| G[Error]
-```
+![Transaction Broadcast Flow](../svg/tx-broadcast-flow.svg)
 
 ---
 
@@ -81,6 +73,129 @@ interface BroadcastedTransaction {
 
 ---
 
+## Send Transaction Package
+
+### Atomic Package Broadcasting
+
+Use `sendRawTransactionPackage` to broadcast an ordered array of raw transactions atomically via Bitcoin Core's `submitpackage` RPC. This is ideal for CPFP (Child-Pays-For-Parent) chains or any set of dependent transactions that must be accepted together.
+
+```typescript
+import { JSONRpcProvider, BroadcastedTransactionPackage } from 'opnet';
+import { networks } from '@btc-vision/bitcoin';
+
+const network = networks.regtest;
+const provider = new JSONRpcProvider({ url: 'https://regtest.opnet.org', network });
+
+const parentTx = '02000000000101...';
+const childTx = '02000000000101...';
+
+// Atomic package submission (uses submitpackage RPC)
+const result: BroadcastedTransactionPackage = await provider.sendRawTransactionPackage(
+    [parentTx, childTx],
+    true,  // isPackage=true (default) for atomic submission
+);
+
+if (result.success) {
+    console.log('Package broadcast successfully!');
+
+    if (result.packageResult) {
+        console.log('Package message:', result.packageResult.packageMsg);
+        for (const [wtxid, txResult] of Object.entries(result.packageResult.txResults)) {
+            console.log(`  ${wtxid}: txid=${txResult.txid}, vsize=${txResult.vsize}`);
+        }
+    }
+
+    if (result.sequentialResults) {
+        for (const seq of result.sequentialResults) {
+            console.log(`${seq.txid}: success=${seq.success}, peers=${seq.peers}`);
+        }
+    }
+} else {
+    console.log('Package broadcast failed:', result.error);
+}
+```
+
+### Sequential Validated Broadcasting
+
+Set `isPackage=false` to use validated sequential broadcast instead. This first validates all transactions with `testmempoolaccept`, then broadcasts each one individually.
+
+```typescript
+// Sequential broadcast (testmempoolaccept + sendrawtransaction)
+const result = await provider.sendRawTransactionPackage(
+    [tx1, tx2, tx3],
+    false,  // sequential validated broadcast
+);
+
+if (result.success) {
+    if (result.testResults) {
+        for (const test of result.testResults) {
+            console.log(`${test.txid}: allowed=${test.allowed}, vsize=${test.vsize}`);
+        }
+    }
+
+    if (result.sequentialResults) {
+        for (const seq of result.sequentialResults) {
+            console.log(`${seq.txid}: success=${seq.success}, peers=${seq.peers}`);
+        }
+    }
+}
+
+// Check if the node fell back to sequential from package
+if (result.fellBackToSequential) {
+    console.log('submitpackage failed, fell back to sequential broadcast');
+}
+```
+
+### Method Signature
+
+```typescript
+async sendRawTransactionPackage(
+    txs: string[],          // Raw transactions as hex strings (max 25)
+    isPackage?: boolean     // Use atomic submitpackage (default: true)
+): Promise<BroadcastedTransactionPackage>
+```
+
+---
+
+## BroadcastedTransactionPackage Result
+
+```typescript
+interface BroadcastedTransactionPackage {
+    success: boolean;                              // Whether the overall broadcast succeeded
+    error?: string;                                // Error message if failed
+    testResults?: readonly TestMempoolAcceptResult[]; // From testmempoolaccept validation
+    packageResult?: PackageResult;                 // From submitpackage (atomic path)
+    sequentialResults?: readonly SequentialBroadcastTxResult[]; // Per-tx results (sequential path)
+    fellBackToSequential?: boolean;                // True if submitpackage failed and fell back
+}
+
+interface SequentialBroadcastTxResult {
+    txid: string;          // The txid of the transaction
+    success: boolean;      // Whether the individual transaction was broadcast
+    error?: string;        // Error message if this transaction failed
+    peers?: number;        // Number of peers that received the transaction
+}
+
+interface TestMempoolAcceptResult {
+    txid: string;
+    wtxid: string;
+    allowed?: boolean;
+    vsize?: number;
+    fees?: TestMempoolAcceptFees;
+    packageError?: string;
+    rejectReason?: string;
+    rejectDetails?: string;
+}
+
+interface PackageResult {
+    packageMsg: string;
+    txResults: { [wtxid: string]: PackageTxResult };
+    replacedTransactions?: readonly string[];
+}
+```
+
+---
+
 ## Send Multiple Transactions
 
 ### Batch Broadcasting

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "opnet",
     "type": "module",
-    "version": "1.8.2",
+    "version": "1.8.4",
     "author": "OP_NET",
     "description": "The perfect library for building Bitcoin-based applications.",
     "engines": {
@@ -104,22 +104,23 @@
         "@babel/preset-env": "^7.29.0",
         "@babel/preset-typescript": "^7.28.5",
         "@eslint/js": "^10.0.1",
-        "@microsoft/api-extractor": "7.57.6",
-        "@types/node": "^25.3.5",
-        "@vitest/browser": "^4.0.18",
-        "@vitest/browser-playwright": "^4.0.18",
-        "@vitest/ui": "^4.0.18",
+        "@microsoft/api-extractor": "7.57.7",
+        "@types/node": "^25.5.0",
+        "@vitest/browser": "^4.1.0",
+        "@vitest/browser-playwright": "^4.1.0",
+        "@vitest/ui": "^4.1.0",
+        "esbuild": "^0.27.4",
         "eslint": "^10.0.3",
         "madge": "^8.0.0",
         "playwright": "^1.58.2",
         "stream-browserify": "^3.0.0",
         "typedoc": "^0.28.17",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.56.1",
-        "vite": "^7.3.1",
+        "typescript-eslint": "^8.57.0",
+        "vite": "^8.0.0",
         "vite-plugin-dts": "4.5.4",
         "vite-plugin-node-polyfills": "^0.25.0",
-        "vitest": "^4.0.18"
+        "vitest": "^4.1.0"
     },
     "peerDependencies": {
         "react-native-worklets": ">=0.7.0"
@@ -132,17 +133,21 @@
     "dependencies": {
         "@btc-vision/bip32": "^7.1.2",
         "@btc-vision/bitcoin": "^7.0.0",
-        "@btc-vision/bitcoin-rpc": "^1.1.0",
+        "@btc-vision/bitcoin-rpc": "^1.1.2",
         "@btc-vision/ecpair": "^4.0.5",
         "@btc-vision/logger": "^1.0.8",
-        "@btc-vision/transaction": "^1.8.0",
+        "@btc-vision/transaction": "^1.8.2",
         "@noble/hashes": "^2.0.1",
         "bignumber.js": "^10.0.2",
         "long": "^5.3.2",
-        "opnet": "^1.8.1-rc.3",
         "p-limit": "^7.3.0",
         "pako": "^2.1.0",
         "protobufjs": "^8.0.0",
-        "undici": "^7.22.0"
+        "undici": "^7.24.0"
+    },
+    "overrides": {
+        "vite-plugin-node-polyfills": {
+            "vite": "$vite"
+        }
     }
 }