@bsv/sdk 1.2.13 → 1.2.15

package/docs/transaction.md

@@ -1219,6 +1219,7 @@ export default class MerklePath {
     static fromHex(hex: string): MerklePath 
     static fromReader(reader: Reader): MerklePath 
     static fromBinary(bump: number[]): MerklePath 
+    static fromCoinbaseTxidAndHeight(txid: string, height: number): MerklePath 
     constructor(blockHeight: number, path: Array<Array<{
         offset: number;
         hash?: string;
@@ -1309,6 +1310,24 @@ Argument Details
 + **bump**
   + The binary array representation of the Merkle Path.
 
+#### Method fromCoinbaseTxidAndHeight
+
+```ts
+static fromCoinbaseTxidAndHeight(txid: string, height: number): MerklePath 
+```
+See also: [MerklePath](#class-merklepath)
+
+Returns
+
+- A new MerklePath instance which assumes the tx is in a block with no other transactions.
+
+Argument Details
+
++ **txid**
+  + The coinbase txid.
++ **height**
+  + The height of the block.
+
 #### Method fromHex
 
 Creates a MerklePath instance from a hexadecimal string.
@@ -1505,6 +1524,7 @@ export default class Transaction {
     constructor(version: number = 1, inputs: TransactionInput[] = [], outputs: TransactionOutput[] = [], lockTime: number = 0, metadata: Record<string, any> = {}, merklePath?: MerklePath) 
     addInput(input: TransactionInput): void 
     addOutput(output: TransactionOutput): void 
+    addP2PKHOutput(address: number[] | string, satoshis?: number): void 
     updateMetadata(metadata: Record<string, any>): void 
     async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(10), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
     getFee(): number 
@@ -1564,6 +1584,21 @@ Argument Details
 + **output**
   + The TransactionOutput object to add to the transaction.
 
+#### Method addP2PKHOutput
+
+Adds a new P2PKH output to the transaction.
+
+```ts
+addP2PKHOutput(address: number[] | string, satoshis?: number): void 
+```
+
+Argument Details
+
++ **address**
+  + The P2PKH address of the output.
++ **satoshis**
+  + The number of satoshis to send to the address - if not provided, the output is considered a change output.
+
 #### Method broadcast
 
 Broadcasts a transaction.

package/package.json

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

package/src/script/templates/P2PKH.ts

@@ -30,6 +30,7 @@ export default class P2PKH implements ScriptTemplate {
     } else {
       data = pubkeyhash
     }
+    if (data.length !== 20) throw new Error('P2PKH hash length must be 20 bytes')
     return new LockingScript([
       { op: OP.OP_DUP },
       { op: OP.OP_HASH160 },

package/src/transaction/MerklePath.ts

@@ -94,6 +94,21 @@ export default class MerklePath {
     return MerklePath.fromReader(reader)
   }
 
+  /**
+   *
+   * @static fromCoinbaseTxid
+   *
+   * Creates a MerklePath instance for a coinbase transaction in an empty block.
+   * This edge case is difficult to retrieve from standard APIs.
+   *
+   * @param {string} txid - The coinbase txid.
+   * @param {number} height - The height of the block.
+   * @returns {MerklePath} - A new MerklePath instance which assumes the tx is in a block with no other transactions.
+   */
+  static fromCoinbaseTxidAndHeight (txid: string, height: number): MerklePath {
+    return new MerklePath(height, [[{ offset: 0, hash: txid, txid: true }]])
+  }
+
   constructor (blockHeight: number, path: Array<Array<{
     offset: number
     hash?: string
@@ -127,8 +142,8 @@ export default class MerklePath {
       })
     })
 
-    let root: string
     // every txid must calculate to the same root.
+    let root: string
     this.path[0].map((leaf, idx) => {
       if (idx === 0) root = this.computeRoot(leaf.hash)
       if (root !== this.computeRoot(leaf.hash)) {
@@ -198,6 +213,10 @@ export default class MerklePath {
       hash256(toArray(m, 'hex').reverse())
     ).reverse())
     let workingHash = txid
+
+    // special case for blocks with only one transaction
+    if (this.path.length === 1 && this.path[0].length === 1) return workingHash
+
     for (let height = 0; height < this.path.length; height++) {
       const leaves = this.path[height]
       const offset = index >> height ^ 1

package/src/transaction/Transaction.ts

@@ -13,6 +13,7 @@ import ChainTracker from './ChainTracker.js'
 import { defaultBroadcaster } from './broadcasters/DefaultBroadcaster.js'
 import { defaultChainTracker } from './chaintrackers/DefaultChainTracker.js'
 import { ATOMIC_BEEF, BEEF_MAGIC } from './Beef.js'
+import P2PKH from '../script/templates/P2PKH.js'
 
 /**
  * Represents a complete Bitcoin transaction. This class encapsulates all the details
@@ -455,9 +456,30 @@ export default class Transaction {
    */
   addOutput (output: TransactionOutput): void {
     this.cachedHash = undefined
+    if (!output.change) {
+      if (typeof output.satoshis === 'undefined') throw new Error('either satoshis must be defined or change must be set to true')
+      if (output.satoshis <= 0) throw new Error('satoshis must be a positive integer or zero')
+    }
+    if (!output.lockingScript) throw new Error('lockingScript must be defined')
     this.outputs.push(output)
   }
 
+  /**
+   * Adds a new P2PKH output to the transaction.
+   *
+   * @param {number[] | string} address - The P2PKH address of the output.
+   * @param {number} [satoshis] - The number of satoshis to send to the address - if not provided, the output is considered a change output.
+   *
+   */
+  addP2PKHOutput (address: number[] | string, satoshis?: number): void {
+    const lockingScript = new P2PKH().lock(address)
+    if (typeof satoshis === 'undefined') { return this.addOutput({ lockingScript, change: true }) }
+    this.addOutput({
+      lockingScript,
+      satoshis
+    })
+  }
+
   /**
    * Updates the transaction's metadata.
    *

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

@@ -185,4 +185,11 @@ describe('MerklePath', () => {
       expect(() => MerklePath.fromHex(valid.bump)).not.toThrowError()
     }
   })
+  it('Validates a MerklePath for a block which only has 1 tx', () => {
+    const path = MerklePath.fromHex('fdd2040101000202ef57aa9f29c8141ae17935c88434457b2117890f23efba0d0e0cba7a7a37d5')
+    expect(path.computeRoot('d5377a7aba0c0e0dbaef230f8917217b453484c83579e11a14c8299faa57ef02')).toEqual('d5377a7aba0c0e0dbaef230f8917217b453484c83579e11a14c8299faa57ef02')
+  })
+  it('Creates a valid MerklePath from a txid', () => {
+    expect(() => MerklePath.fromCoinbaseTxidAndHeight('d5377a7aba0c0e0dbaef230f8917217b453484c83579e11a14c8299faa57ef02', 1)).not.toThrowError()
+  })
 })

package/src/transaction/__tests/Transaction.benchmarks.test.ts

@@ -42,7 +42,7 @@ describe('Transaction Verification Benchmark', () => {
         }
 
         // Build the chain
-        for (let i = 0; i < depth; i++) {
+        for (let i = 1; i < depth + 1; i++) {
             const newTx = new Transaction()
             newTx.addInput({
                 sourceTransaction: tx,
@@ -52,7 +52,7 @@ describe('Transaction Verification Benchmark', () => {
             })
             newTx.addOutput({
                 lockingScript: p2pkh.lock(publicKeyHash),
-                satoshis: 100000 - 1000 * (i + 1)
+                satoshis: 100000 - (i * 10)
             })
             await newTx.sign()
             tx = newTx

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

@@ -661,6 +661,15 @@ describe('Transaction', () => {
       const verified = await tx.verify("scripts only")
       expect(verified).toBe(true)
     })
+
+    it('Verifies tx scripts only when our input has no MerklePath.', async () => {
+      const sourceTransaction = Transaction.fromHex('01000000013834506e4af751dc3a0d73e9bdd067709ade5248860967fb3eb72854be6011dc020000006b4830450221008abf2ce1afbcc3c4895265b0966ac69e2275fb35a738f9873b5416cd3bb68cc102202c906f9771d2d6868f81a34d6a3af4cd7de070969286db7097c5e0f3a009b638412102f6a81c442dcd903c7808a75abde9217268bb70417ad538c18fb597b4c553c354ffffffff0301000000000000007c21039bf52152665699e24c1018bf5b48e575de316f844962a79db32b93b7e328bf71ac1062656e63686d61726b546f6b656e5f36463044022034ca3cc49163e4d5bc24f41c5ea4631efd4ae7c243f904c90e1db6e6a55e8f0e02206bb031baca2fc6d64da5ad722ce2e07137718e5e58092e5ecf54e52fcdd664ab6dc8000000000000001976a91470763a553d615a8144fa0889a0e1f93d1d8da8b088acaf430000000000001976a9145aa12f9be0121eee54e7331d8f995fe4dded72f588ac00000000')
+      const tx = Transaction.fromHex('01000000015c22e8d34a95a761a0685b8b5a99a0845e9f03d87d5716a7351d08939db5cd92020000006a47304402205101f2bdc40098cbde1a270071a5bfdd5a6fbefc8a38a8b4a1adaca0a6ff55e702200ec5c0a57cb65dfc6aa22e6856bb4c62b8987a7b9fa32cb601c94b579ba67d83412103c8be6b217fc55939851e28239fbbf731f997e026ad344aa9d4b739181fe96743ffffffff0301000000000000007c21039bf52152665699e24c1018bf5b48e575de316f844962a79db32b93b7e328bf71ac1062656e63686d61726b546f6b656e5f374630440220026808e9453f75ca1fc3c7bb0f7be1efaca5cea6b1eda96ab7db56c519b6793202207d1fa5e7d54254d2142256947f93a061781280a6ed2464052470633a7c888d1f6dc8000000000000001976a91428bb6f207ac8f4b7f6c1c5914e143a6165586b2488ace5420000000000001976a914197cbde77abbcb985ca60a85c2988b2ac32c541a88ac00000000')
+      sourceTransaction.merklePath = { assumeValid: true } // can be any object.
+      tx.inputs[0].sourceTransaction = sourceTransaction
+      const verified = await tx.verify('scripts only', undefined)
+      expect(verified).toBe(true)
+    })
   })
 
   describe('vectors: a 1mb transaction', () => {
@@ -964,4 +973,48 @@ describe('Transaction', () => {
       }).toThrowError('Transaction with TXID 0000000000000000000000000000000000000000000000000000000000000000 not found in BEEF data.')
     })
   })
+
+  describe('addP2PKHOutput', () => {
+    it('should create an output on the current transaction using an address hash or string', async () => {
+      const privateKey = PrivateKey.fromRandom()
+      const lockingScript = new P2PKH().lock(privateKey.toAddress())
+      const tx = new Transaction()
+      tx.addInput({
+        sourceTXID: '00'.repeat(32),
+        sourceOutputIndex: 0,
+        unlockingScriptTemplate: new P2PKH().unlock(privateKey),
+      })
+      tx.addP2PKHOutput(privateKey.toAddress(), 10000)
+      expect(tx.outputs.length).toEqual(1)
+      expect(tx.outputs[0].satoshis).toEqual(10000)
+      expect(tx.outputs[0].lockingScript.toHex() === lockingScript.toHex()).toBeTruthy()
+    })
+    it('should error is the address is non base58', async () => {
+      const tx = new Transaction()    
+      expect(() => tx.addP2PKHOutput('A small chicken', 10000)).toThrow("Invalid base58 character ")
+    })
+    it('should error if the address is incorrectly copied', async () => {
+      const tx = new Transaction()
+      expect(() => tx.addP2PKHOutput('14afWk1jLH9Uwi2mC9C5ehrsvcFxTLYDp', 10000)).toThrow("Invalid checksum")
+    })
+    it('should error if the address is a hash of wrong length', async () => {
+      const tx = new Transaction()
+      const address = [1,2,3,4,5]
+      expect(() => tx.addP2PKHOutput(address, 10000)).toThrow("P2PKH hash length must be 20 bytes")
+    })
+    it('should set the output to a change output if the satoshi value is not given', async () => {
+      const tx = new Transaction()
+      tx.addP2PKHOutput('18E63MgXH43KBb288ETM8u91J2cqdGNEmg')
+      expect(tx.outputs[0].change).toBeTruthy()
+      expect(tx.outputs[0].satoshis).toBeUndefined()
+    })
+    it('throw error when satoshi value is negative', async () => {
+      const tx = new Transaction()
+      expect(() => tx.addP2PKHOutput('18E63MgXH43KBb288ETM8u91J2cqdGNEmg', -1000)).toThrow('satoshis must be a positive integer or zero')
+    })
+    it('throw error when output does not set satoshi value', async () => {
+      const tx = new Transaction()
+      expect(() => tx.addOutput({ lockingScript: Script.fromASM('OP_TRUE') })).toThrow('either satoshis must be defined or change must be set to true')
+    })
+  })
 })