@bsv/sdk 2.0.8 → 2.0.9

package/docs/reference/transaction.md

@@ -1673,10 +1673,11 @@ export default class Transaction {
     toAtomicBEEF(allowPartial?: boolean): number[] 
     toAtomicBEEFUint8Array(allowPartial?: boolean): Uint8Array 
     async completeWithWallet(wallet: WalletInterface, actionDescription?: DescriptionString5to50Bytes, originator?: string, options?: CreateActionOptions): Promise<void> 
+    preimage(inputIndex?: number, signatureScope?: number, subscript?: LockingScript): number[] 
 }
 ```
 
-See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Broadcaster](./transaction.md#interface-broadcaster), [ChainTracker](./transaction.md#interface-chaintracker), [CreateActionOptions](./wallet.md#interface-createactionoptions), [DescriptionString5to50Bytes](./wallet.md#type-descriptionstring5to50bytes), [FeeModel](./transaction.md#interface-feemodel), [LivePolicy](./transaction.md#class-livepolicy), [MerklePath](./transaction.md#class-merklepath), [Reader](./primitives.md#class-reader), [ReaderUint8Array](./primitives.md#class-readeruint8array), [TransactionInput](./transaction.md#interface-transactioninput), [TransactionOutput](./transaction.md#interface-transactionoutput), [WalletInterface](./wallet.md#interface-walletinterface), [Writer](./primitives.md#class-writer), [WriterUint8Array](./primitives.md#class-writeruint8array), [defaultBroadcaster](./transaction.md#function-defaultbroadcaster), [defaultChainTracker](./transaction.md#function-defaultchaintracker), [sign](./compat.md#variable-sign), [toHex](./primitives.md#variable-tohex), [toUint8Array](./primitives.md#variable-touint8array), [verify](./compat.md#variable-verify)
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Broadcaster](./transaction.md#interface-broadcaster), [ChainTracker](./transaction.md#interface-chaintracker), [CreateActionOptions](./wallet.md#interface-createactionoptions), [DescriptionString5to50Bytes](./wallet.md#type-descriptionstring5to50bytes), [FeeModel](./transaction.md#interface-feemodel), [LivePolicy](./transaction.md#class-livepolicy), [LockingScript](./script.md#class-lockingscript), [MerklePath](./transaction.md#class-merklepath), [Reader](./primitives.md#class-reader), [ReaderUint8Array](./primitives.md#class-readeruint8array), [TransactionInput](./transaction.md#interface-transactioninput), [TransactionOutput](./transaction.md#interface-transactionoutput), [WalletInterface](./wallet.md#interface-walletinterface), [Writer](./primitives.md#class-writer), [WriterUint8Array](./primitives.md#class-writeruint8array), [defaultBroadcaster](./transaction.md#function-defaultbroadcaster), [defaultChainTracker](./transaction.md#function-defaultchaintracker), [sign](./compat.md#variable-sign), [toHex](./primitives.md#variable-tohex), [toUint8Array](./primitives.md#variable-touint8array), [verify](./compat.md#variable-verify)
 
 #### Method addInput
 
@@ -2033,6 +2034,28 @@ Argument Details
 + **bin**
   + binary transaction data
 
+#### Method preimage
+
+Returns the formatted preimage of a transaction for the requested input index, signature scope (default SIGHASH_FORKID | SIGHASH_ALL), and optional subscript.
+
+```ts
+preimage(inputIndex?: number, signatureScope?: number, subscript?: LockingScript): number[] 
+```
+See also: [LockingScript](./script.md#class-lockingscript)
+
+Returns
+
+The formatted preimage
+
+Argument Details
+
++ **inputIndex**
+  + The index of the input to generate the preimage for
++ **signatureScope**
+  + The signature scope to use for the preimage
++ **subscript**
+  + The subscript to use for the preimage (optional)
+
 #### Method sign
 
 Signs a transaction, hydrating all its unlocking scripts based on the provided script templates where they are available.

package/package.json

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

package/src/primitives/index.ts

@@ -9,7 +9,7 @@ export * as ECDSA from './ECDSA.js'
 export * as Utils from './utils.js'
 export * as Hash from './Hash.js'
 export { default as Random } from './Random.js'
-export { default as TransactionSignature } from './TransactionSignature.js'
+export { default as TransactionSignature, type SignatureHashCache } from './TransactionSignature.js'
 export { default as Polynomial, PointInFiniteField } from './Polynomial.js'
 export { default as Schnorr } from './Schnorr.js'
 export { default as Secp256r1 } from './Secp256r1.js'

package/src/transaction/Transaction.ts

@@ -16,6 +16,7 @@ import { defaultChainTracker } from './chaintrackers/DefaultChainTracker.js'
 import { Beef, BEEF_V1 } from './Beef.js'
 import P2PKH from '../script/templates/P2PKH.js'
 import type { WalletInterface, DescriptionString5to50Bytes, CreateActionOptions } from '../wallet/Wallet.interfaces.js'
+import TransactionSignature from '../primitives/TransactionSignature.js'
 
 /**
  * Represents a complete Bitcoin transaction. This class encapsulates all the details
@@ -1292,4 +1293,49 @@ export default class Transaction {
       ...newTransaction.metadata
     }
   }
+
+  /**
+   * Returns the formatted preimage of a transaction for the requested input index, signature scope (default SIGHASH_FORKID | SIGHASH_ALL), and optional subscript.
+   * @param inputIndex - The index of the input to generate the preimage for
+   * @param signatureScope - The signature scope to use for the preimage
+   * @param subscript - The subscript to use for the preimage (optional)
+   * @returns The formatted preimage
+   */
+  preimage (inputIndex?: number, signatureScope?: number, subscript?: LockingScript): number[] {
+    inputIndex ??= 0
+    signatureScope ??= TransactionSignature.SIGHASH_FORKID | TransactionSignature.SIGHASH_ALL
+    if (inputIndex < 0 || inputIndex >= this.inputs.length) {
+      throw new Error('Invalid input index')
+    }
+    const flags = signatureScope & 0xf0
+    if (flags !== 224 && flags !== 192 && flags !== 64) {
+      throw new Error('FORKID must be set')
+    }
+    const coverage = signatureScope & 0x0f
+    if (coverage < 1 || coverage > 3) {
+      throw new Error('Invalid signature coverage, must be all, none or single')
+    }
+    const input = this.inputs[inputIndex]
+    if (input.sourceTransaction == null) {
+      throw new Error('Source transaction is required')
+    }
+    const output = input.sourceTransaction.outputs[input.sourceOutputIndex]
+    if (output == null) {
+      throw new Error(`Source transaction's output at index ${input.sourceOutputIndex} is required`)
+    }
+    const otherInputs = this.inputs.filter((_, index) => index !== inputIndex)
+    return TransactionSignature.format({
+      sourceTXID: input.sourceTXID ?? input.sourceTransaction.id('hex'),
+      sourceOutputIndex: input.sourceOutputIndex,
+      sourceSatoshis: output.satoshis,
+      transactionVersion: this.version,
+      otherInputs,
+      inputIndex,
+      outputs: this.outputs,
+      inputSequence: input.sequence ?? 0xffffffff,
+      subscript: subscript ?? output.lockingScript,
+      lockTime: this.lockTime,
+      scope: signatureScope
+    })
+  }
 }

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

@@ -2054,4 +2054,174 @@ describe('Transaction', () => {
       await expect(tx.verify('scripts only', new SatoshisPerKilobyte(1), 35)).resolves.toBe(true)
     })
   })
+
+  describe('#preimage', () => {
+    let sourceTx: Transaction
+    let spendTx: Transaction
+    let privateKey: PrivateKey
+    let publicKey: any
+    let publicKeyHash: number[]
+    let p2pkh: P2PKH
+
+    beforeEach(() => {
+      privateKey = new PrivateKey(1)
+      publicKey = new Curve().g.mul(privateKey)
+      publicKeyHash = hash160(publicKey.encode(true))
+      p2pkh = new P2PKH()
+      sourceTx = new Transaction(
+        1,
+        [],
+        [
+          {
+            lockingScript: p2pkh.lock(publicKeyHash),
+            satoshis: 4000
+          }
+        ],
+        0
+      )
+      spendTx = new Transaction(
+        1,
+        [
+          {
+            sourceTransaction: sourceTx,
+            sourceOutputIndex: 0,
+            unlockingScript: new UnlockingScript(),
+            sequence: 0xffffffff
+          }
+        ],
+        [
+          {
+            satoshis: 1000,
+            lockingScript: p2pkh.lock(publicKeyHash)
+          },
+          {
+            lockingScript: p2pkh.lock(publicKeyHash),
+            change: true
+          }
+        ],
+        0
+      )
+    })
+
+    it('should generate preimage with default parameters', () => {
+      const preimage = spendTx.preimage()
+      expect(Array.isArray(preimage)).toBe(true)
+      expect(preimage.length).toBeGreaterThan(0)
+      expect(typeof preimage[0]).toBe('number')
+    })
+
+    it('should generate preimage with custom inputIndex', () => {
+      // Add another input to test inputIndex > 0
+      const sourceTx2 = new Transaction(
+        1,
+        [],
+        [
+          {
+            lockingScript: p2pkh.lock(publicKeyHash),
+            satoshis: 2000
+          }
+        ],
+        0
+      )
+      spendTx.addInput({
+        sourceTransaction: sourceTx2,
+        sourceOutputIndex: 0,
+        unlockingScript: new UnlockingScript(),
+        sequence: 0xffffffff
+      })
+
+      const preimage0 = spendTx.preimage(0)
+      const preimage1 = spendTx.preimage(1)
+      expect(Array.isArray(preimage0)).toBe(true)
+      expect(Array.isArray(preimage1)).toBe(true)
+      expect(preimage0).not.toEqual(preimage1)
+    })
+
+    it('should generate preimage with custom signatureScope', () => {
+      const defaultPreimage = spendTx.preimage()
+      const customPreimage = spendTx.preimage(0, TransactionSignature.SIGHASH_FORKID | TransactionSignature.SIGHASH_NONE)
+      expect(Array.isArray(customPreimage)).toBe(true)
+      expect(customPreimage).not.toEqual(defaultPreimage)
+    })
+
+    it('should generate preimage with custom subscript', () => {
+      const customScript = LockingScript.fromASM(
+        'OP_CHECKSIG'
+      )
+      const preimage = spendTx.preimage(0, undefined, customScript)
+      expect(Array.isArray(preimage)).toBe(true)
+    })
+
+    it('should throw error for invalid input index (negative)', () => {
+      expect(() => {
+        spendTx.preimage(-1)
+      }).toThrow('Invalid input index')
+    })
+
+    it('should throw error for invalid input index (out of bounds)', () => {
+      expect(() => {
+        spendTx.preimage(1)
+      }).toThrow('Invalid input index')
+    })
+
+    it('should throw error when sourceTransaction is missing', () => {
+      const txWithoutSource = new Transaction(
+        1,
+        [
+          {
+            sourceTXID: '00'.repeat(32),
+            sourceOutputIndex: 0,
+            unlockingScript: new UnlockingScript(),
+            sequence: 0xffffffff
+          }
+        ],
+        [
+          {
+            satoshis: 1000,
+            lockingScript: p2pkh.lock(publicKeyHash)
+          }
+        ],
+        0
+      )
+      expect(() => {
+        txWithoutSource.preimage()
+      }).toThrow('Source transaction is required')
+    })
+
+    it('should throw error when source transaction output is missing', () => {
+      const tx = new Transaction(
+        1,
+        [
+          {
+            sourceTransaction: new Transaction(1, [], [], 0), // No outputs
+            sourceOutputIndex: 0,
+            unlockingScript: new UnlockingScript(),
+            sequence: 0xffffffff
+          }
+        ],
+        [
+          {
+            satoshis: 1000,
+            lockingScript: p2pkh.lock(publicKeyHash)
+          }
+        ],
+        0
+      )
+      expect(() => {
+        tx.preimage()
+      }).toThrow('Source transaction\'s output at index 0 is required')
+    })
+
+    it('should throw error when FORKID is not set in signatureScope', () => {
+      expect(() => {
+        spendTx.preimage(0, TransactionSignature.SIGHASH_ALL)
+      }).toThrow('FORKID must be set')
+    })
+
+    it('should throw error for invalid signature coverage', () => {
+      expect(() => {
+        spendTx.preimage(0, TransactionSignature.SIGHASH_FORKID | 0x04) // Invalid coverage
+      }).toThrow('Invalid signature coverage, must be all, none or single')
+    })
+  })
 })