@bsv/sdk 1.2.8 → 1.2.10

package/docs/overlay-tools.md

@@ -26,6 +26,7 @@ Instructs the Overlay Services Engine about which outputs to admit and which pre
 export interface AdmittanceInstructions {
     outputsToAdmit: number[];
     coinsToRetain: number[];
+    coinsRemoved?: number[];
 }
 ```
 
@@ -33,6 +34,15 @@ export interface AdmittanceInstructions {
 
 <summary>Interface AdmittanceInstructions Details</summary>
 
+#### Property coinsRemoved
+
+The indices of all inputs from the provided transaction which reference previously-admitted outputs,
+which are now considered spent and have been removed from the managed topic.
+
+```ts
+coinsRemoved?: number[]
+```
+
 #### Property coinsToRetain
 
 The indices of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
@@ -43,7 +53,7 @@ coinsToRetain: number[]
 
 #### Property outputsToAdmit
 
-The indices of all admissable outputs into the managed topic from the provided transaction.
+The indices of all admissible outputs into the managed topic from the provided transaction.
 
 ```ts
 outputsToAdmit: number[]

package/docs/transaction.md

@@ -592,6 +592,7 @@ export class Beef {
     constructor(version?: BeefVersion) 
     get magic(): number 
     findTxid(txid: string): BeefTx | undefined 
+    makeTxidOnly(txid: string): BeefTx | undefined 
     findBump(txid: string): MerklePath | undefined 
     findTransactionForSigning(txid: string): Transaction | undefined 
     findAtomicTransaction(txid: string): Transaction | undefined 
@@ -779,6 +780,23 @@ Argument Details
 + **allowTxidOnly**
   + optional. If true, transaction txid only is assumed valid
 
+#### Method makeTxidOnly
+
+Replaces `BeefTx` for this txid with txidOnly.
+
+Replacement is done so that a `clone()` can be
+updated by this method without affecting the
+original.
+
+```ts
+makeTxidOnly(txid: string): BeefTx | undefined 
+```
+See also: [BeefTx](#class-beeftx)
+
+Returns
+
+undefined if txid is unknown.
+
 #### Method mergeBump
 
 Merge a MerklePath that is assumed to be fully valid.
@@ -847,7 +865,7 @@ Argument Details
 #### Method sortTxs
 
 Sort the `txs` by input txid dependency order:
-- Oldest Tx Anchored by Path
+- Oldest Tx Anchored by Path or txid only
 - Newer Txs depending on Older parents
 - Newest Tx
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/overlay-tools/SHIPBroadcaster.ts

@@ -18,14 +18,20 @@ export interface TaggedBEEF {
  */
 export interface AdmittanceInstructions {
   /**
-     * The indices of all admissable outputs into the managed topic from the provided transaction.
-     */
+   * The indices of all admissible outputs into the managed topic from the provided transaction.
+   */
   outputsToAdmit: number[]
 
   /**
-     * The indices of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
-     */
+   * The indices of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
+   */
   coinsToRetain: number[]
+
+  /**
+   * The indices of all inputs from the provided transaction which reference previously-admitted outputs,
+   * which are now considered spent and have been removed from the managed topic.
+   */
+  coinsRemoved?: number[]
 }
 
 /**
@@ -180,8 +186,9 @@ export default class SHIPCast implements Broadcaster {
       for (const [topic, instructions] of Object.entries(steak)) {
         const outputsToAdmit = instructions.outputsToAdmit
         const coinsToRetain = instructions.coinsToRetain
-        // TODO: Account for coins removed property on STEAK
-        if ((outputsToAdmit && outputsToAdmit.length > 0) || (coinsToRetain && coinsToRetain.length > 0)) {
+        const coinsRemoved = instructions.coinsRemoved
+
+        if ((outputsToAdmit?.length > 0) || (coinsToRetain?.length > 0) || (coinsRemoved?.length > 0)) {
           acknowledgedTopics.add(topic)
         }
       }

package/src/overlay-tools/__tests/SHIPBroadcaster.test.ts

@@ -652,6 +652,88 @@ describe('SHIPCast', () => {
     })
   })
 
+  it('should succeed when interested hosts only remove coins in a transaction broadcast', async () => {
+    const shipHostKey1 = new PrivateKey(42)
+    const shipWallet1 = new ProtoWallet(shipHostKey1)
+    const shipLib1 = new OverlayAdminTokenTemplate(shipWallet1)
+    const shipScript1 = await shipLib1.lock('SHIP', 'https://shiphost1.com', 'tm_foo')
+    const shipTx1 = new Transaction(1, [], [{
+      lockingScript: shipScript1,
+      satoshis: 1
+    }], 0)
+
+    const shipHostKey2 = new PrivateKey(43)
+    const shipWallet2 = new ProtoWallet(shipHostKey2)
+    const shipLib2 = new OverlayAdminTokenTemplate(shipWallet2)
+    const shipScript2 = await shipLib2.lock('SHIP', 'https://shiphost2.com', 'tm_bar')
+    const shipTx2 = new Transaction(1, [], [{
+      lockingScript: shipScript2,
+      satoshis: 1
+    }], 0)
+
+    // Resolver returns two hosts
+    mockResolver.query.mockReturnValueOnce({
+      type: 'output-list',
+      outputs: [
+        { beef: shipTx1.toBEEF(), outputIndex: 0 },
+        { beef: shipTx2.toBEEF(), outputIndex: 0 }
+      ]
+    })
+
+    // First host acknowledges 'tm_foo' with coinsRemoved
+    mockFacilitator.send.mockImplementationOnce(async (host, { beef, topics }) => {
+      const steak = {}
+      for (const topic of topics) {
+        steak[topic] = {
+          outputsToAdmit: [],
+          coinsToRetain: [],
+          coinsRemoved: topic === 'tm_foo' ? [0] : []
+        }
+      }
+      return steak
+    })
+
+    // Second host does not acknowledge 'tm_bar'
+    mockFacilitator.send.mockImplementationOnce(async (host, { beef, topics }) => {
+      const steak = {}
+      for (const topic of topics) {
+        steak[topic] = {
+          outputsToAdmit: [],
+          coinsToRetain: [],
+          coinsRemoved: []
+        }
+      }
+      return steak
+    })
+
+    const b = new SHIPCast(['tm_foo', 'tm_bar'], {
+      facilitator: mockFacilitator,
+      resolver: mockResolver as unknown as LookupResolver,
+      requireAcknowledgmentFromSpecificHostsForTopics: {
+        'https://shiphost1.com': ['tm_foo']
+      },
+      requireAcknowledgmentFromAllHostsForTopics: [],
+      requireAcknowledgmentFromAnyHostForTopics: []
+    })
+
+    const testTx = new Transaction(1, [], [], 0)
+    const response = await b.broadcast(testTx)
+
+    expect(response).toEqual({
+      status: 'success',
+      txid: testTx.id('hex'),
+      message: 'Sent to 2 Overlay Services hosts.'
+    })
+
+    // Verify the resolver was queried correctly
+    expect(mockResolver.query).toHaveBeenCalledWith({
+      service: 'ls_ship',
+      query: {
+        topics: ['tm_foo', 'tm_bar']
+      }
+    }, 1000)
+  })
+
   it('should fail when specific hosts do not acknowledge required topics', async () => {
     const shipHostKey1 = new PrivateKey(42)
     const shipWallet1 = new ProtoWallet(shipHostKey1)

package/src/primitives/PublicKey.ts

@@ -30,7 +30,7 @@ export default class PublicKey extends Point {
    * const myPrivKey = new PrivateKey(...)
    * const myPubKey = PublicKey.fromPrivateKey(myPrivKey)
    */
-  static fromPrivateKey(key: PrivateKey): PublicKey {
+  static fromPrivateKey (key: PrivateKey): PublicKey {
     const c = new Curve()
     const p = c.g.mul(key)
     return new PublicKey(p.x, p.y)
@@ -46,7 +46,7 @@ export default class PublicKey extends Point {
    * @example
    * const myPubKey = PublicKey.fromString("03....")
    */
-  static fromString(str: string): PublicKey {
+  static fromString (str: string): PublicKey {
     const p = Point.fromString(str)
     return new PublicKey(p.x, p.y)
   }
@@ -61,7 +61,7 @@ export default class PublicKey extends Point {
    * @example
    * const myPubKey = PublicKey.fromString("03....")
    */
-  static fromDER(bytes: number[]): PublicKey {
+  static fromDER (bytes: number[]): PublicKey {
     const p = Point.fromDER(bytes)
     return new PublicKey(p.x, p.y)
   }
@@ -76,7 +76,7 @@ export default class PublicKey extends Point {
    * new PublicKey(point1);
    * new PublicKey('abc123', 'def456');
    */
-  constructor(
+  constructor (
     x: Point | BigNumber | number | number[] | string | null,
     y: BigNumber | number | number[] | string | null = null,
     isRed: boolean = true
@@ -85,7 +85,7 @@ export default class PublicKey extends Point {
       super(x.getX(), x.getY())
     } else {
       // Common gotcha: constructing PublicKey with a DER value when you should use .fromString()
-      if (y === null && isRed === true && typeof x === 'string') {
+      if (y === null && isRed && typeof x === 'string') {
         if (x.length === 66 || x.length === 130) {
           throw new Error('You are using the "new PublicKey()" constructor with a DER hex string. You need to use "PublicKey.fromString()" instead.')
         }
@@ -108,7 +108,7 @@ export default class PublicKey extends Point {
    * const myPrivKey = new PrivateKey(...)
    * const sharedSecret = myPubKey.deriveSharedSecret(myPrivKey)
    */
-  deriveSharedSecret(priv: PrivateKey): Point {
+  deriveSharedSecret (priv: PrivateKey): Point {
     if (!this.validate()) {
       throw new Error('Public key not valid for ECDH secret derivation')
     }
@@ -129,7 +129,7 @@ export default class PublicKey extends Point {
    * const mySignature = new Signature(...)
    * const isVerified = myPubKey.verify(myMessage, mySignature)
    */
-  verify(msg: number[] | string, sig: Signature, enc?: 'hex' | 'utf8'): boolean {
+  verify (msg: number[] | string, sig: Signature, enc?: 'hex' | 'utf8'): boolean {
     const msgHash = new BigNumber(sha256(msg, enc), 16)
     return verify(msgHash, sig, this)
   }
@@ -144,7 +144,7 @@ export default class PublicKey extends Point {
    * @example
    * const derPublicKey = myPubKey.toDER()
    */
-  toDER(enc?: 'hex' | undefined): number[] | string {
+  toDER (enc?: 'hex' | undefined): number[] | string {
     if (enc === 'hex') return this.encode(true, enc) as string
     return this.encode(true) as number[]
   }
@@ -157,7 +157,7 @@ export default class PublicKey extends Point {
    * @example
    * const publicKeyHash = pubkey.toHash()
    */
-  toHash(enc?: 'hex'): number[] | string {
+  toHash (enc?: 'hex'): number[] | string {
     const pkh = hash160(this.encode(true))
     if (enc === 'hex') {
       return toHex(pkh)
@@ -179,7 +179,7 @@ export default class PublicKey extends Point {
    * const testnetAddress = pubkey.toAddress([0x6f])
    * const testnetAddress = pubkey.toAddress('testnet')
    */
-  toAddress(prefix: number[] | string = [0x00]): string {
+  toAddress (prefix: number[] | string = [0x00]): string {
     if (typeof prefix === 'string') {
       if (prefix === 'testnet' || prefix === 'test') {
         prefix = [0x6f]
@@ -198,7 +198,7 @@ export default class PublicKey extends Point {
    * @param invoiceNumber The invoice number used to derive the child key
    * @returns The derived child key.
    */
-  deriveChild(privateKey: PrivateKey, invoiceNumber: string): PublicKey {
+  deriveChild (privateKey: PrivateKey, invoiceNumber: string): PublicKey {
     const sharedSecret = this.deriveSharedSecret(privateKey)
     const invoiceNumberBin = toArray(invoiceNumber, 'utf8')
     const hmac = sha256hmac(sharedSecret.encode(true), invoiceNumberBin)
@@ -225,7 +225,7 @@ export default class PublicKey extends Point {
    * @example
    * const publicKey = Signature.fromMsgHashAndCompactSignature(msgHash, 'IMOl2mVKfDgsSsHT4uIYBNN4e...', 'base64');
    */
-  static fromMsgHashAndCompactSignature(msgHash: BigNumber, signature: number[] | string, enc?: 'hex' | 'base64'): PublicKey {
+  static fromMsgHashAndCompactSignature (msgHash: BigNumber, signature: number[] | string, enc?: 'hex' | 'base64'): PublicKey {
     const data = toArray(signature, enc)
     if (data.length !== 65) {
       throw new Error('Invalid Compact Signature')

package/src/transaction/Beef.ts

@@ -98,6 +98,26 @@ export class Beef {
     return this.txs.find(tx => tx.txid === txid)
   }
 
+  /**
+   * Replaces `BeefTx` for this txid with txidOnly.
+   *
+   * Replacement is done so that a `clone()` can be
+   * updated by this method without affecting the
+   * original.
+   *
+   * @param txid
+   * @returns undefined if txid is unknown.
+   */
+  makeTxidOnly (txid: string): BeefTx | undefined {
+    const i = this.txs.findIndex(tx => tx.txid === txid)
+    if (i === -1) return undefined
+    let btx = this.txs[i]
+    if (btx.isTxidOnly) { return btx }
+    this.txs.slice(i, i + 1)
+    btx = this.mergeTxidOnly(txid)
+    return btx
+  }
+
   /**
    * @returns `MerklePath` with level zero hash equal to txid or undefined.
    */
@@ -518,7 +538,7 @@ export class Beef {
 
   /**
      * Sort the `txs` by input txid dependency order:
-     * - Oldest Tx Anchored by Path
+     * - Oldest Tx Anchored by Path or txid only
      * - Newer Txs depending on Older parents
      * - Newest Tx
      *
@@ -553,7 +573,10 @@ export class Beef {
       if (tx.isValid) {
         validTxids[tx.txid] = true
         result.push(tx)
-      } else if (tx.isTxidOnly) { txidOnly.push(tx) } else { queue.push(tx) }
+      } else if (tx.isTxidOnly && tx.inputTxids.length === 0) {
+        validTxids[tx.txid] = true
+        txidOnly.push(tx)
+      } else { queue.push(tx) }
     }
 
     // Hashtable of unknown input txids used to fund transactions without their own proof.
@@ -564,17 +587,18 @@ export class Beef {
     const possiblyMissingInputs = queue
     queue = []
 
+    // all tx are isValid false, hasProof false.
+    // if isTxidOnly then has inputTxids
     for (const tx of possiblyMissingInputs) {
       let hasMissingInput = false
-      if (!tx.isValid) {
-        // For all the unproven transactions,
-        // link their inputs that exist in this beef,
-        // make a note of missing inputs.
-        for (const inputTxid of tx.inputTxids) {
-          if (!txidToTx[inputTxid]) {
-            missingInputs[inputTxid] = true
-            hasMissingInput = true
-          }
+
+      // For all the unproven transactions,
+      // link their inputs that exist in this beef,
+      // make a note of missing inputs.
+      for (const inputTxid of tx.inputTxids) {
+        if (!txidToTx[inputTxid]) {
+          missingInputs[inputTxid] = true
+          hasMissingInput = true
         }
       }
       if (hasMissingInput) { txsMissingInputs.push(tx) } else { queue.push(tx) }
@@ -584,6 +608,8 @@ export class Beef {
     while (queue.length > 0) {
       const oldQueue = queue
       queue = []
+      // all tx are isValid false, hasProof false.
+      // if isTxidOnly then has inputTxids
       for (const tx of oldQueue) {
         if (tx.inputTxids.every(txid => validTxids[txid])) {
           validTxids[tx.txid] = true
@@ -596,8 +622,8 @@ export class Beef {
     // transactions that don't have proofs and don't chain to proofs
     const txsNotValid = queue
 
-    // New order of txs is sorted, unsortable, txidOnly (no raw transaction)
-    this.txs = result.concat(queue).concat(txidOnly).concat(txsMissingInputs)
+    // New order of txs is unsortable (missing inputs or depends on missing inputs), txidOnly, sorted (so newest sorted is last)
+    this.txs = txsMissingInputs.concat(txsNotValid).concat(txidOnly).concat(result)
 
     return {
       missingInputs: Object.keys(missingInputs),

package/src/transaction/__tests/Beef.test.ts

@@ -305,6 +305,24 @@ describe('Beef tests', () => {
         expect(atomic).toEqual(beef2)
       }
     })
+    test('9_sortTxs', async () => {
+      {
+        const beef = new Beef()
+        beef.mergeTxidOnly('a')
+        const btx = beef.mergeTxidOnly('b')
+        btx.inputTxids = ['a']
+        beef.sortTxs()
+        expect(beef.txs[1].txid).toBe('b')
+      }
+      {
+        const beef = new Beef()
+        const atx = beef.mergeTxidOnly('a')
+        const btx = beef.mergeTxidOnly('b')
+        atx.inputTxids = ['b']
+        beef.sortTxs()
+        expect(beef.txs[1].txid).toBe('a')
+      }
+    })
 })
 
 const txs: string[] = [