@bsv/overlay 2.1.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "type": "module",
   "description": "BSV Blockchain Overlay Services Engine",
   "main": "dist/cjs/mod.js",

package/src/Engine.ts

@@ -593,8 +593,26 @@ export class Engine {
     // ===================================================================
     // PHASE 2: BROADCAST (before any mutations)
     // ===================================================================
+    // Only broadcast when at least one topic actually accepted the
+    // transaction. For a non-failed topic, acceptance means: previously
+    // accepted (dupe / client retry), outputs admitted, coins retained, or
+    // previously-admitted coins consumed (e.g. a consume-only deletion such
+    // as a KVStore remove, even one that retains nothing). A topic manager
+    // REJECTS by throwing from identifyAdmissibleOutputs (tracked in
+    // failedTopics). A transaction every topic rejected must never reach the
+    // network: submitters treat an empty STEAK as a rejection and
+    // abort/release their held inputs, so broadcasting it anyway would
+    // desync their wallets from the chain.
+    const anyTopicAccepted = validations.some(v =>
+      !failedTopics.has(v.topic) && (
+        v.isDupe ||
+        v.admissibleOutputs.outputsToAdmit.length > 0 ||
+        v.admissibleOutputs.coinsToRetain.length > 0 ||
+        v.previousCoins.length > 0
+      )
+    )
     this.startTime(`broadcast_${txid.substring(0, 10)}`)
-    if (mode !== 'historical-tx' && this.broadcaster !== undefined) {
+    if (mode !== 'historical-tx' && this.broadcaster !== undefined && anyTopicAccepted) {
       try {
         let response: BroadcastResponse | BroadcastFailure
         if (tx.merklePath !== undefined) {

package/src/__tests/Engine.test.ts

@@ -504,6 +504,88 @@ describe('BSV Overlay Services Engine', () => {
         topics: ['Hello']
       })).rejects.toHaveProperty('message', 'Invalid merkle path for transaction 3ecead27a44d013ad1aae40038acbb1883ac9242406808bb4667c15b4f164eac')
     })
+    describe('Broadcast gating (PHASE 2)', () => {
+      const makeBroadcaster = (): { broadcast: jest.Mock } => ({
+        broadcast: jest.fn(async () => ({ status: 'success', txid: exampleTXID, message: 'ok' }))
+      })
+      const makeEngine = (broadcaster: any): Engine => new Engine(
+        { Hello: mockTopicManager },
+        {},
+        mockStorageEngine,
+        mockChainTracker,
+        undefined,
+        undefined,
+        undefined,
+        broadcaster
+      )
+
+      it('broadcasts when at least one topic admits outputs', async () => {
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).toHaveBeenCalledTimes(1)
+      })
+
+      it('never broadcasts a transaction every topic manager rejected', async () => {
+        mockTopicManager.identifyAdmissibleOutputs = jest.fn(async () => ({
+          outputsToAdmit: [],
+          coinsToRetain: []
+        }))
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).not.toHaveBeenCalled()
+      })
+
+      it('never broadcasts when topic validation throws, even with tracked coins consumed', async () => {
+        // The rejected tx spends previously-admitted coins — a throw must
+        // still gate the broadcast (this is the rejected-transfer shape).
+        mockStorageEngine.findOutput = jest.fn(async () => mockOutput)
+        mockTopicManager.identifyAdmissibleOutputs = jest.fn(async () => {
+          throw new Error('rule violation')
+        })
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).not.toHaveBeenCalled()
+      })
+
+      it('broadcasts a consume-only transaction that retains nothing (history purge)', async () => {
+        // e.g. a KVStore remove that also purges history: previously-admitted
+        // coins are consumed, nothing admitted, nothing retained. That is an
+        // acceptance, not a rejection (rejection = throw).
+        mockStorageEngine.findOutput = jest.fn(async () => mockOutput)
+        mockTopicManager.identifyAdmissibleOutputs = jest.fn(async () => ({
+          outputsToAdmit: [],
+          coinsToRetain: []
+        }))
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).toHaveBeenCalledTimes(1)
+      })
+
+      it('still broadcasts a duplicate (previously accepted) transaction', async () => {
+        mockStorageEngine.doesAppliedTransactionExist = jest.fn(async () => true)
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).toHaveBeenCalledTimes(1)
+      })
+
+      it('broadcasts when outputs are consumed but none admitted (coinsToRetain only)', async () => {
+        mockStorageEngine.findOutput = jest.fn(async () => mockOutput)
+        mockTopicManager.identifyAdmissibleOutputs = jest.fn(async () => ({
+          outputsToAdmit: [],
+          coinsToRetain: [0]
+        }))
+        const broadcaster = makeBroadcaster()
+        const engine = makeEngine(broadcaster)
+        await engine.submit({ beef: exampleBeef, topics: ['Hello'] })
+        expect(broadcaster.broadcast).toHaveBeenCalledTimes(1)
+      })
+    })
+
     describe('For each topic being processed', () => {
       it('Checks for duplicate transactions', async () => {
         const engine = new Engine(