BSV Transaction Broadcasting: A Complete Guide from Construction to Submission

Conclusion First

Broadcasting a transaction means sending a fully constructed and signed transaction to a transaction processing service or the network, where it can be validated, propagated, and eventually included in a block.

Having a transaction hex locally only means you’ve assembled the transaction data. A successful broadcast indicates that the transaction has entered the network processing pipeline. Beginners often conflate these states into one "success", but in real development you must handle them separately.

---

Creating a Transaction Is Not the Same as Broadcasting It

When manually constructing a transaction, you need to distinguish the following states:

• Constructed – The transaction object exists.
• Signed – Inputs have valid unlocking scripts.
• Serialized – The transaction can be represented as raw hex.
• Broadcast – The transaction has been submitted to a broadcaster or node.
• Accepted – The service or network considers the transaction processable.
• Mined – The transaction is included in a block.
• Proven – You can prove the transaction is in a block using a Merkle proof / SPV.

Understanding these states helps pinpoint issues like signing failures, broadcast timeouts, or mining delays.

---

Broadcasting a Transaction with the SDK

The BSV SDK's Transaction class provides a broadcast() method that accepts different broadcasters.

Using WhatsOnChain

Using ARC

Different services require different configurations. In production, never commit API keys to the code repository.

---

Pre-Broadcast Checks

Before broadcasting, verify at least the following:

1. The transaction is signed
   TypeScript

   1await tx.sign()
2. The transaction structure can be validated
   TypeScript

   1const ok = await tx.verify()
3. Reasonable fees
   Not too low, and not excessively high due to a missing change output.
4. Inputs are still unspent
   Expired UTXOs will cause broadcast failure.
5. Correct network selection
   Testnet and mainnet cannot be mixed.
6. Service configuration is correct
   ARC, WhatsOnChain, or other services may require different endpoints, API keys, or network parameters.

---

Interpreting the Broadcast Response

The SDK's BroadcastResponse success structure includes status: "success" and txid. The failure structure contains status: "error", an error code, description, and possibly a txid.

Your application should not just do:

and assume everything is complete. Read the result instead:

---

Post-Broadcast: Still Query

After broadcasting, the transaction may take some time before it becomes visible on block explorers or query APIs. The official broadcasting tutorial also demonstrates the pattern of querying the WhatsOnChain API to check if the transaction has appeared.

Your application can query:

• Whether the txid is visible.
• Whether it has been included in a block.
• The block height.
• The number of confirmations.
• Whether there are competing transactions or double-spend related states.

Note that block explorer queries are not SPV verification. They are suitable for debugging and status observation. For formal verification, you will need to learn about Merkle proofs, BUMP, BEEF, and SPV in Stage 9.

---

Common Causes of Broadcast Failure

• Fee too low.
• Input already spent.
• Invalid signature.
• Incorrect source transaction or output index.
• Transaction does not meet the service's policy.
• Wrong network endpoint (e.g., testnet transaction sent to mainnet).
• Broadcasting service unavailable or authentication failed.
• Transaction too large, ancestor transactions unprocessed, or missing dependency transactions.

These are not signs that "the SDK is broken" but normal failure modes in the transaction processing flow.

---

Position in the BSV Tech Stack

Broadcasting connects application-side transaction construction with miner-side transaction processing.

In the BSV ecosystem you might use:

• Wallet service auto‑broadcast.
• ARC transaction processing service.
• WhatsOnChain broadcast interface.
• Interface provided by a node or miner.
• Custom broadcaster.

Each approach differs in control, authentication, feedback, and reliability. In the introduction phase, you can get started with public tutorials. For production, choose a reliable transaction processing path and implement proper status tracking.

---

Common Beginner Misconceptions

• Having a tx hex locally does not mean the transaction has been broadcast.
• A successful broadcast does not mean the transaction is confirmed.
• The txid being queryable does not mean you have performed SPV verification.
• Broadcast failure is not always a code syntax error; it could be fee, UTXO status, network policy, or service configuration issues.
• When retrying broadcasts, design them to be idempotent. Otherwise, the same business action might be submitted multiple times.

---

References

• Transaction Broadcasting tutorial
• ARC GitHub
• WhatsOnChain
• Transaction reference