@bsv/sdk 1.0.38 → 1.1.0

package/docs/transaction.md

@@ -47,7 +47,6 @@ export default interface TransactionInput {
     sourceTransaction?: Transaction;
     sourceTXID?: string;
     sourceOutputIndex: number;
-    sourceSatoshis?: number;
     unlockingScript?: UnlockingScript;
     unlockingScriptTemplate?: {
         sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
@@ -348,8 +347,10 @@ Configuration options for the ARC broadcaster.
 ```ts
 export interface ArcConfig {
     apiKey?: string;
-    deploymentId?: string;
     httpClient?: HttpClient;
+    deploymentId?: string;
+    callbackUrl?: string;
+    callbackToken?: string;
     headers?: Record<string, string>;
 }
 ```
@@ -366,6 +367,22 @@ Authentication token for the ARC API
 apiKey?: string
 ```
 
+#### Property callbackToken
+
+default access token for notification callback endpoint. It will be used as a Authorization header for the http callback
+
+```ts
+callbackToken?: string
+```
+
+#### Property callbackUrl
+
+notification callback endpoint for proofs and double spend notification
+
+```ts
+callbackUrl?: string
+```
+
 #### Property deploymentId
 
 Deployment id used annotating api calls in XDeployment-ID header - this value will be randomly generated if not set
@@ -376,7 +393,7 @@ deploymentId?: string
 
 #### Property headers
 
-The headers to be attached to all tx submissions.
+additional headers to be attached to all tx submissions.
 
 ```ts
 headers?: Record<string, string>
@@ -699,6 +716,8 @@ export default class ARC implements Broadcaster {
     readonly URL: string;
     readonly apiKey: string | undefined;
     readonly deploymentId: string;
+    readonly callbackUrl: string | undefined;
+    readonly callbackToken: string | undefined;
     readonly headers: Record<string, string> | undefined;
     constructor(URL: string, config?: ArcConfig);
     constructor(URL: string, apiKey?: string);
@@ -827,6 +846,7 @@ export default class Transaction {
     metadata: Record<string, any>;
     merklePath?: MerklePath;
     static fromBEEF(beef: number[]): Transaction 
+    static fromEF(ef: number[]): Transaction 
     static parseScriptOffsets(bin: number[]): {
         inputs: Array<{
             vin: number;
@@ -841,6 +861,7 @@ export default class Transaction {
     } 
     static fromBinary(bin: number[]): Transaction 
     static fromHex(hex: string): Transaction 
+    static fromHexEF(hex: string): Transaction 
     static fromHexBEEF(hex: string): Transaction 
     constructor(version: number = 1, inputs: TransactionInput[] = [], outputs: TransactionOutput[] = [], lockTime: number = 0, metadata: Record<string, any> = {}, merklePath?: MerklePath) 
     addInput(input: TransactionInput): void 
@@ -969,6 +990,23 @@ Argument Details
 + **bin**
   + The binary array representation of the transaction.
 
+#### Method fromEF
+
+Creates a new transaction, linked to its inputs and their associated merkle paths, from a EF (BRC-30) structure.
+
+```ts
+static fromEF(ef: number[]): Transaction 
+```
+
+Returns
+
+An extended transaction, linked to its associated inputs by locking script and satoshis amounts only.
+
+Argument Details
+
++ **ef**
+  + A binary representation of a transaction in EF format.
+
 #### Method fromHex
 
 Creates a Transaction instance from a hexadecimal string.
@@ -1003,6 +1041,23 @@ Argument Details
 + **hex**
   + The hexadecimal string representation of the transaction BEEF.
 
+#### Method fromHexEF
+
+Creates a Transaction instance from a hexadecimal string encoded EF.
+
+```ts
+static fromHexEF(hex: string): Transaction 
+```
+
+Returns
+
+- A new Transaction instance.
+
+Argument Details
+
++ **hex**
+  + The hexadecimal string representation of the transaction EF.
+
 #### Method getFee
 
 Utility method that returns the current fee based on inputs and outputs
@@ -1236,11 +1291,35 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | [defaultBroadcaster](#function-defaultbroadcaster) |
 | [defaultChainTracker](#function-defaultchaintracker) |
 | [defaultHttpClient](#function-defaulthttpclient) |
+| [isBroadcastFailure](#function-isbroadcastfailure) |
+| [isBroadcastResponse](#function-isbroadcastresponse) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+### Function: isBroadcastResponse
+
+Convenience type guard for response from `Broadcaster.broadcast`
+
+```ts
+export function isBroadcastResponse(r: BroadcastResponse | BroadcastFailure): r is BroadcastResponse 
+```
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
+### Function: isBroadcastFailure
+
+Convenience type guard for response from `Broadcaster.broadcast`
 
+```ts
+export function isBroadcastFailure(r: BroadcastResponse | BroadcastFailure): r is BroadcastFailure 
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
 ### Function: defaultHttpClient
 
 Returns a default HttpClient implementation based on the environment that it is run on.

package/package.json

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

package/src/compat/Utxo.ts

@@ -0,0 +1,55 @@
+import Transaction from '../transaction/Transaction.js'
+import TransactionInput from '../transaction/TransactionInput.js'
+import LockingScript from '../script/LockingScript.js'
+import UnlockingScript from '../script/UnlockingScript.js'
+
+type jsonUtxo = {
+    txid: string
+    vout: number
+    satoshis: number
+    script: string
+}
+/**
+ * @method fromUtxo
+ * 
+ * @description
+ * This function creates a transaction input from a utxo json object
+ * The idea being old code that uses utxos rather than sourceTranactions can convert using this.
+ * 
+ * @deprecated
+ * This approach is made available for compatibility only. It is deprecated in favor of using sourceTransactions 
+ * directly. It's recommended that wallets general keep transactions which store unspent outputs in their entirety, 
+ * along with corresonding Merkle paths. The reason you would keep the whole transaction is such that you can prove 
+ * the txid, and therefore its inclusion within a specific block.
+ * 
+ * @example
+ * const i = fromUtxo({
+ *   txid: '434555433eaca96dff6e71a4d02febd0dd3832e5ca4e5734623ca914522e17d5',
+ *   vout: 0,
+ *   script: '51',
+ *   satoshis: 1234
+ * }, new P2PKH().unlock(p))
+ * 
+ * tx.addInput(i)
+ * 
+ * @param utxo: jsonUtxo
+ * @param unlockingScriptTemplate: { sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>, estimateLength: (tx: Transaction, inputIndex: number) => Promise<number> }
+ * @returns 
+ */
+export default function fromUtxo(utxo: jsonUtxo, unlockingScriptTemplate: {
+    sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
+    estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
+  }): TransactionInput {
+    const sourceTransaction = new Transaction(0, [], [], 0)
+    sourceTransaction.outputs = Array(utxo.vout + 1).fill(null)
+    sourceTransaction.outputs[utxo.vout] = {
+        satoshis: utxo.satoshis,
+        lockingScript: LockingScript.fromHex(utxo.script)
+    }
+    return {
+        sourceTransaction,
+        sourceOutputIndex: utxo.vout,
+        unlockingScriptTemplate,
+        sequence: 0xFFFFFFFF
+    }
+}

package/src/compat/index.ts

@@ -2,3 +2,4 @@ export * as BSM from './BSM.js'
 export { default as HD } from './HD.js'
 export { default as Mnemonic } from './Mnemonic.js'
 export { default as ECIES } from './ECIES.js'
+export { default as fromUtxo } from './Utxo.js'

package/src/primitives/AESGCM.ts

@@ -180,15 +180,15 @@ export function AES (input: number[], key: number[]): number[] {
 
   // Since the BigNumber representation of keys ignores big endian zeroes,
   // extend incoming key arrays with zeros to the smallest standard key size.
-  let ekey = Array.from(key)
+  const ekey = Array.from(key)
   if (ekey.length <= 16) {
-    while (ekey.length < 16) ekey.unshift(0) 
+    while (ekey.length < 16) ekey.unshift(0)
     roundLimit = 11
   } else if (ekey.length <= 24) {
-    while (ekey.length < 24) ekey.unshift(0) 
+    while (ekey.length < 24) ekey.unshift(0)
     roundLimit = 13
   } else if (key.length <= 32) {
-    while (ekey.length < 32) ekey.unshift(0) 
+    while (ekey.length < 32) ekey.unshift(0)
     roundLimit = 15
   } else {
     throw new Error('Illegal key length: ' + String(key.length))

package/src/script/templates/P2PKH.ts

@@ -91,7 +91,6 @@ export default class P2PKH implements ScriptTemplate {
           )
         }
         sourceSatoshis ||= input.sourceTransaction?.outputs[input.sourceOutputIndex].satoshis
-        sourceSatoshis ||= input.sourceSatoshis
         if (!sourceSatoshis) {
           throw new Error(
             'The sourceSatoshis or input sourceTransaction is required for transaction signing.'

package/src/transaction/Broadcaster.ts

@@ -40,3 +40,17 @@ export interface Broadcaster {
   broadcast: (transaction: Transaction) =>
   Promise<BroadcastResponse | BroadcastFailure>
 }
+
+/**
+ * Convenience type guard for response from `Broadcaster.broadcast`
+ */
+export function isBroadcastResponse (r: BroadcastResponse | BroadcastFailure): r is BroadcastResponse {
+  return r.status === 'success'
+}
+
+/**
+ * Convenience type guard for response from `Broadcaster.broadcast`
+ */
+export function isBroadcastFailure (r: BroadcastResponse | BroadcastFailure): r is BroadcastFailure {
+  return r.status === 'error'
+}

package/src/transaction/Transaction.ts

@@ -122,6 +122,59 @@ export default class Transaction {
     return transactions[lastTXID].tx
   }
 
+
+  /**
+   * Creates a new transaction, linked to its inputs and their associated merkle paths, from a EF (BRC-30) structure.
+   * @param ef A binary representation of a transaction in EF format.
+   * @returns An extended transaction, linked to its associated inputs by locking script and satoshis amounts only.
+   */
+  static fromEF (ef: number[]): Transaction {
+    const br = new Reader(ef)
+    const version = br.readUInt32LE()
+    if (toHex(br.read(6)) !== '0000000000ef') throw new Error('Invalid EF marker')
+    const inputsLength = br.readVarIntNum()
+    const inputs: TransactionInput[] = []
+    for (let i = 0; i < inputsLength; i++) {
+      const sourceTXID = toHex(br.readReverse(32))
+      const sourceOutputIndex = br.readUInt32LE()
+      const scriptLength = br.readVarIntNum()
+      const scriptBin = br.read(scriptLength)
+      const unlockingScript = UnlockingScript.fromBinary(scriptBin)
+      const sequence = br.readUInt32LE()
+      const satoshis = br.readUInt64LEBn().toNumber()
+      const lockingScriptLength = br.readVarIntNum()
+      const lockingScriptBin = br.read(lockingScriptLength)
+      const lockingScript = LockingScript.fromBinary(lockingScriptBin)
+      const sourceTransaction = new Transaction(null, [], [], null)
+      sourceTransaction.outputs = Array(sourceOutputIndex + 1).fill(null)
+      sourceTransaction.outputs[sourceOutputIndex] = {
+        satoshis,
+        lockingScript
+      }
+      inputs.push({
+        sourceTransaction,
+        sourceTXID,
+        sourceOutputIndex,
+        unlockingScript,
+        sequence
+      })
+    }
+    const outputsLength = br.readVarIntNum()
+    const outputs: TransactionOutput[] = []
+    for (let i = 0; i < outputsLength; i++) {
+      const satoshis = br.readUInt64LEBn().toNumber()
+      const scriptLength = br.readVarIntNum()
+      const scriptBin = br.read(scriptLength)
+      const lockingScript = LockingScript.fromBinary(scriptBin)
+      outputs.push({
+        satoshis,
+        lockingScript
+      })
+    }
+    const lockTime = br.readUInt32LE()
+    return new Transaction(version, inputs, outputs, lockTime)
+  }
+
   /**
    * Since the validation of blockchain data is atomically transaction data validation,
    * any application seeking to validate data in output scripts must store the entire transaction as well.
@@ -220,6 +273,17 @@ export default class Transaction {
     return Transaction.fromBinary(toArray(hex, 'hex'))
   }
 
+  /**
+   * Creates a Transaction instance from a hexadecimal string encoded EF.
+   *
+   * @static
+   * @param {string} hex - The hexadecimal string representation of the transaction EF.
+   * @returns {Transaction} - A new Transaction instance.
+   */
+  static fromHexEF (hex: string): Transaction {
+    return Transaction.fromEF(toArray(hex, 'hex'))
+  }
+
   /**
    * Creates a Transaction instance from a hexadecimal string encoded BEEF.
    *
@@ -316,12 +380,10 @@ export default class Transaction {
     // change = inputs - fee - non-change outputs
     let change = 0
     for (const input of this.inputs) {
-      if (typeof input.sourceTransaction !== 'object' && typeof input.sourceSatoshis !== 'number') {
-        throw new Error('Source transactions or sourceSatoshis are required for all inputs during fee computation')
+      if (typeof input.sourceTransaction !== 'object') {
+        throw new Error('Source transactions are required for all inputs during fee computation')
       }
-      change += input.sourceTransaction
-        ? input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis
-        : input.sourceSatoshis
+      change += input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis
     }
     change -= fee
     let changeCount = 0
@@ -367,12 +429,10 @@ export default class Transaction {
   getFee (): number {
     let totalIn = 0
     for (const input of this.inputs) {
-      if (typeof input.sourceTransaction !== 'object' && typeof input.sourceSatoshis !== 'number') {
+      if (typeof input.sourceTransaction !== 'object') {
         throw new Error('Source transactions or sourceSatoshis are required for all inputs to calculate fee')
       }
-      totalIn += input.sourceTransaction
-        ? input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis
-        : input.sourceSatoshis || 0
+      totalIn += input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis
     }
     let totalOut = 0
     for (const output of this.outputs) {
@@ -465,7 +525,11 @@ export default class Transaction {
       if (typeof i.sourceTransaction === 'undefined') {
         throw new Error('All inputs must have source transactions when serializing to EF format')
       }
-      writer.write(i.sourceTransaction.hash() as number[])
+      if (typeof i.sourceTXID === 'undefined') {
+        writer.write(i.sourceTransaction.hash() as number[])
+      } else {
+        writer.write(toArray(i.sourceTXID, 'hex').reverse() as number[])
+      }
       writer.writeUInt32LE(i.sourceOutputIndex)
       const scriptBin = i.unlockingScript.toBinary()
       writer.writeVarIntNum(scriptBin.length)

package/src/transaction/TransactionInput.ts

@@ -16,9 +16,6 @@ import Transaction from './Transaction.js'
  * @property {number} sourceOutputIndex - The index of the output in the source transaction
  *           that this input is spending. It is zero-based, indicating the position of the
  *           output in the array of outputs of the source transaction.
- * @property {number} [sourceSatoshis] - The amount of satoshis of the source transaction
- *           output that this input is spending, used for fee calculation and signing when
- *           source transaction is not present
  * @property {UnlockingScript} [unlockingScript] - Optional. The script that 'unlocks' the
  *           source output for spending. This script typically contains signatures and
  *           public keys that evidence the ownership of the output.
@@ -57,7 +54,6 @@ export default interface TransactionInput {
   sourceTransaction?: Transaction
   sourceTXID?: string
   sourceOutputIndex: number
-  sourceSatoshis?: number
   unlockingScript?: UnlockingScript
   unlockingScriptTemplate?: {
     sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>

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

@@ -9,6 +9,7 @@ import { hash256, hash160 } from '../../../dist/cjs/src/primitives/Hash'
 import PrivateKey from '../../../dist/cjs/src/primitives/PrivateKey'
 import Curve from '../../../dist/cjs/src/primitives/Curve'
 import P2PKH from '../../../dist/cjs/src/script/templates/P2PKH'
+import fromUtxo from '../../../dist/cjs/src/compat/Utxo'
 
 import sighashVectors from '../../primitives/__tests/sighash.vectors'
 import invalidTransactions from './tx.invalid.vectors'
@@ -396,14 +397,13 @@ describe('Transaction', () => {
       const priv = PrivateKey.fromRandom()
       const tx = new Transaction()
       utxos.forEach(utxo => {
-        const script = new P2PKH().lock(priv.toPublicKey().toHash())
-        tx.addInput({
-          sourceTXID: utxo.tx_hash,
-          sourceOutputIndex: utxo.tx_pos,
-          sourceSatoshis: utxo.value,
-          unlockingScriptTemplate: new P2PKH()
-            .unlock(priv, 'all', false, utxo.value, script)
-        })
+        const u = {
+          txid: utxo.tx_hash,
+          vout: utxo.tx_pos,
+          script: new P2PKH().lock(priv.toPublicKey().toHash()).toHex(),
+          satoshis: utxo.value
+        }
+        tx.addInput(fromUtxo(u, new P2PKH().unlock(priv)))
       })
       tx.addOutput({
         lockingScript: new P2PKH().lock(priv.toAddress()),

package/src/transaction/broadcasters/ARC.ts

@@ -9,11 +9,15 @@ import {toHex} from "../../primitives/utils.js";
 export interface ArcConfig {
   /** Authentication token for the ARC API */
   apiKey?: string
-  /** Deployment id used annotating api calls in XDeployment-ID header - this value will be randomly generated if not set */
-  deploymentId?: string
   /** The HTTP client used to make requests to the ARC API. */
   httpClient?: HttpClient
-  /** The headers to be attached to all tx submissions. */
+  /** Deployment id used annotating api calls in XDeployment-ID header - this value will be randomly generated if not set */
+  deploymentId?: string
+  /** notification callback endpoint for proofs and double spend notification */
+  callbackUrl?: string
+  /** default access token for notification callback endpoint. It will be used as a Authorization header for the http callback */
+  callbackToken?: string
+  /** additional headers to be attached to all tx submissions. */
   headers?: Record<string, string>
 }
 
@@ -29,6 +33,8 @@ export default class ARC implements Broadcaster {
   readonly URL: string
   readonly apiKey: string | undefined
   readonly deploymentId: string
+  readonly callbackUrl: string | undefined
+  readonly callbackToken: string | undefined
   readonly headers: Record<string, string> | undefined
   private readonly httpClient: HttpClient;
 
@@ -52,11 +58,16 @@ export default class ARC implements Broadcaster {
     if (typeof config === 'string') {
       this.apiKey = config
       this.httpClient = defaultHttpClient()
+      this.deploymentId = defaultDeploymentId()
+      this.callbackToken = undefined
+      this.callbackUrl = undefined
     } else {
-      const {apiKey, deploymentId, headers, httpClient} = config ?? {} as ArcConfig
+      const {apiKey, deploymentId, httpClient, callbackToken, callbackUrl, headers } = config ?? {} as ArcConfig
+      this.apiKey = apiKey
       this.httpClient = httpClient ?? defaultHttpClient()
       this.deploymentId = deploymentId ?? defaultDeploymentId()
-      this.apiKey = apiKey
+      this.callbackToken = callbackToken
+      this.callbackUrl = callbackUrl
       this.headers = headers
     }
   }
@@ -95,11 +106,20 @@ export default class ARC implements Broadcaster {
           message: `${txStatus} ${extraInfo}`
         }
       } else {
-        return {
+        const r: BroadcastFailure = {
           status: 'error',
           code: response.status.toString() ?? 'ERR_UNKNOWN',
-          description: response.data?.detail ?? 'Unknown error'
+          description: 'Unknown error'
+        }
+        if (typeof response.data === 'string') {
+          try {
+            const data = JSON.parse(response.data)
+            if (typeof data.detail === 'string') {
+              r.description = data.detail
+            }
+          } catch {}
         }
+        return r
       }
     } catch (error) {
       return {
@@ -122,6 +142,14 @@ export default class ARC implements Broadcaster {
       headers['Authorization'] = `Bearer ${this.apiKey}`
     }
 
+    if (this.callbackUrl) {
+      headers['X-CallbackUrl'] = this.callbackUrl
+    }
+
+    if (this.callbackToken) {
+      headers['X-CallbackToken'] = this.callbackToken
+    }
+
     if (!!this.headers) {
       for (const key in this.headers) {
         headers[key] = this.headers[key]

package/src/transaction/broadcasters/__tests/ARC.test.ts

@@ -165,9 +165,9 @@ describe('ARC Broadcaster', () => {
   it('should handle non-200 responses', async () => {
     const mockFetch = mockedFetch({
       status: '400',
-      data: {
+      data: JSON.stringify({
         detail: 'Bad request'
-      }
+      })
     })
 
     const broadcaster = new ARC(URL, {httpClient: new FetchHttpClient(mockFetch)})

package/src/transaction/index.ts

@@ -2,5 +2,6 @@ export { default as Transaction } from './Transaction.js'
 export { default as MerklePath } from './MerklePath.js'
 export type { default as TransactionInput } from './TransactionInput.js'
 export type { default as TransactionOutput } from './TransactionOutput.js'
-export type * as Broadcaster from './Broadcaster.js'
+export type { Broadcaster, BroadcastFailure, BroadcastResponse } from './Broadcaster.js'
+export { isBroadcastResponse, isBroadcastFailure } from './Broadcaster.js'
 export type { default as ChainTracker } from './ChainTracker.js'