@bsv/sdk 1.0.32 → 1.0.34

package/docs/examples/EXAMPLE_SIMPLE_TX.md

@@ -45,7 +45,7 @@ await tx.sign()
 // Finally, we broadcast it with ARC.
 // get your api key from https://console.taal.com
 const apiKey = 'mainnet_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' // replace
-await tx.broadcast(new ARC('https://api.taal.com/arc', apiKey))
+await tx.broadcast()
 ```
 
 This code snippet demonstrates creating a transaction, adding an input and an output, setting a change script, configuring the fee, signing the transaction, and broadcasting with the ARC broadcaster. It uses the P2PKH Template, which is a specific type of Bitcoin locking program. To learn more about templates, check out this example (link to be provided once cmpplete).
@@ -61,4 +61,85 @@ transaction.addOutput({
 })
 ```
 
-The `Transaction` class abstracts the complexity of Bitcoin's transaction structure. It handles inputs, outputs, scripts, and serialization, offering methods to easily modify and interrogate the transaction. Check out the full code-level documentation, refer to other examples, or reach out to the community to learn more.
+The `Transaction` class abstracts the complexity of Bitcoin's transaction structure. It handles inputs, outputs, scripts, and serialization, offering methods to easily modify and interrogate the transaction. Check out the full code-level documentation, refer to other examples, or reach out to the community to learn more.
+
+## Choosing broadcasting target (ARC or WhatsOnChain)
+
+### ARC
+
+You can broadcast via selected ARC by providing ARC instance to the `broadcast` method.
+
+```typescript
+await tx.broadcast(new ARC('https://api.taal.com/arc', apiKey))
+```
+
+### WhatsOnChain
+
+You can broadcast via What's On Chain by providing WhatsOnChainBroadcaster instance to the `broadcast` method.
+
+```typescript
+const network = 'main' // or 'test'
+await tx.broadcast(new WhatsOnChainBroadcaster(network))
+```
+
+## Use custom http client for broadcasting
+
+The ARC broadcaster requires an HTTP client to broadcast transactions. By default, the SDK will try to search for `window.fetch` in browser or `https` module on Node.js. 
+If you want to use a custom (or preconfigured) HTTP client, you can pass it with use of the adapter the ARC constructor:
+
+### fetch
+
+```typescript
+// In this example we're assuming you have variable fetch holding the fetch function`
+
+const arc = new ARC('https://api.taal.com/arc', apiKey, new FetchHttpClient(mockFetch))
+```
+
+### https
+
+Because ARC is assuming concrete interface of the http client, we're providing an adapter for https module. 
+You can use it as follows:
+
+```typescript
+// In this example we're assuming you have variable https holding the https module loaded for example with `require('https')`
+
+const arc = new ARC('https://api.taal.com/arc', apiKey, new NodejsHttpClient(https))
+
+```
+
+### axios
+
+Although the SDK is not providing adapters for axios, it can be easily used with the ARC broadcaster. 
+You can make your own "adapter" for axios as follows:
+
+```typescript
+const axiosHttpClient =   const httpClient: HttpClient = {
+  request: async (...args) => {
+    let res;
+    try {
+      res = await axios(...args);
+    } catch (e: unknown) {
+      if (axios.isAxiosError(e)) {
+        res = e.response;
+      } else {
+        throw e;
+      }
+    }
+    if (!res) {
+      throw new Error('No response');
+    }
+    return {
+      ok: res.status >= 200 && res.status <= 299,
+      ...res
+    };
+  },
+};
+
+new ARC('https://api.taal.com/arc', apiKey, axiosHttpClient) 
+```
+
+### other libraries
+
+Although the SDK is not providing adapters for other libraries, 
+you can easily create your own adapter by implementing the `HttpClient` interface.
+Please look at the example for axios above to see how easy it can be done.

package/docs/examples/EXAMPLE_VERIFYING_BEEF.md

@@ -12,26 +12,6 @@ Merkle proofs are simply a way for someone to prove the existence of a given tra
 
 The process for SPV is detailed in [BRC-67](https://github.com/bitcoin-sv/BRCs/blob/master/transactions/0067.md), but the main idea is that when a sender sends a transaction, they include merkle proofs on all of the input transactions. This allows anyone with a copy of the Bitcoin block headers to check that the input transactions are included in the blockchain. Verifiers then check that all the input and output scripts correctly transfer value from one party to the next, ensuring an unbroken chain of spends. The [BEEF data structure](https://github.com/bitcoin-sv/BRCs/blob/master/transactions/0062.md) provides a compact and efficient way for people to represent the data required to perform SPV. 
 
-## Block Headers Client
-
-To verify BEEF structures with the BSV SDK, you'll need to provide a block headers client that, given a merkle root, will indicate to the library whether the merkle root is correct for the block that's in the active chain at the given block height.
-
-For simplicity in this example, we are going to use a mock headers client that always indicates every merkle root as valid no matter what. However, in any real project, **you MUST always use an actual block headers client or attackers will be able to easily fool you with fraudulent transactions!**
-
-The TypeScript BSV SDK does not ship with a block headers client, but check out this example (link to be provided once complete) for setting up Pulse.
-
-Here is the gullible block headers client we will be using:
-
-```typescript
-const gullibleHeadersClient = {
-    // DO NOT USE IN A REAL PROJECT due to security risks of accepting any merkle root as valid without verification
-    isValidRootForHeight: async (merkleRoot, height) => {
-      console.log({ merkleRoot, height })
-      return true
-    }
-}
-```
-
 ## Verifying a BEEF Structure
 
 Now that you have access to a block headers client (either Pulse on a real project or the above code for a toy example), we can proceed to verifying the BEEF structure with the following code:
@@ -46,10 +26,37 @@ const BEEFHex = '0100beef01fe636d0c0007021400fe507c0c7aa754cef1f7889d5fd395cf1f7
 const tx = Transaction.fromHexBEEF(BEEFHex)
 
 // This ensures the BEEF structure is legitimate
-const verified = await tx.verify(gullibleHeadersClient)
+const verified = await tx.verify()
 
 // Print the results
 console.log(verified)
 ```
 
-The above code allows you to ensure that a given BEEF structure is valid according to the rules of SPV.
+The above code allows you to ensure that a given BEEF structure is valid according to the rules of SPV.
+
+## Chain tracker
+
+To verify BEEF structures with the BSV SDK, you'll need to provide a block headers client that, given a merkle root, will indicate to the library whether the merkle root is correct for the block that's in the active chain at the given block height.
+
+The TypeScript BSV SDK does provides default implementation of the chain tracker that use What's On Chain API. 
+
+### What's On Chain configuration
+
+#### BSV network
+
+The default network for the chain tracker is `main`. You can change it to other network by providing the instance of WhatsOnChain ChainTracker configured for other network to `.verify()` method.
+
+```typescript
+tx.verify(new WhatsOnChain())
+```
+
+#### Api Key
+
+It is possible to use WhatsOnChain ChainTracker with obtained API KEY of [WhatsOnChain](https://docs.taal.com/core-products/whatsonchain). 
+To do so, you need to provide to `.verify()` method the custom instance of WhatsOnChain ChainTracker with the API KEY.
+
+```typescript
+import { Transaction, WhatsOnChain } from '@bsv/sdk'
+
+tx.verify(new WhatsOnChain('main', {apiKey: 'YOUR_API_KEY'}))
+```

package/docs/examples/EXAMPLE_VERIFYING_ROOTS.md

@@ -1,6 +1,6 @@
 # Example: Building a Pulse Block Headers Client
 
-When [verifying BEEF structures](EXAMPLE_VERIFYING_BEEF.md), it's necessary to ensure that all transactions are well-anchored: this is to say, that they come from inputs in the honest chain. The SDK doesn't ship with a headers client, but this guide shows an example of how to use it with [Pulse](https://github.com/bitcoin-sv/block-headers-service): a popular client suitable for a wide range of use-cases.
+When [verifying BEEF structures](EXAMPLE_VERIFYING_BEEF.md), it's necessary to ensure that all transactions are well-anchored: this is to say, that they come from inputs in the honest chain. The SDK doesn't ship with a headers client, but this guide shows an example of how to use it with [block-headers-service](https://github.com/bitcoin-sv/block-headers-service): a popular client suitable for a wide range of use-cases.
 
 ## Pre-requisites
 
@@ -41,59 +41,13 @@ export default interface ChainTracker {
 
 ```
 
-We will hide the complexities of making an https request from browsers/node.js in an separate function, which you could then import into the files you need otherwise.
-
-```typescript
-// httpsClient.ts
-async function nodeFetch (https, url, requestOptions): Promise<any> {
-    return await new Promise((resolve, reject) => {
-      const req = https.request(url, requestOptions, res => {
-        let data = ''
-        res.on('data', (chunk: string) => {
-          data += chunk
-        })
-        res.on('end', () => {
-          resolve(data)
-        })
-      })
-
-      req.on('error', error => {
-        reject(error)
-      })
-
-      if (requestOptions.body as boolean) {
-        req.write(requestOptions.body)
-      }
-      req.end()
-    })
-  }
-}
-
-export async function httpsClient (url: string, options: any) : Promise<any> {
-  let response
-  let data: any = {}
-  if (typeof window !== 'undefined' && typeof window.fetch === 'function') {
-    // Use fetch in a browser environment
-    response = await window.fetch(url, options)
-    data = await response.json()
-    return data
-  }
-  if (typeof require === 'undefined') throw new Error('No method available to perform HTTP request')
-  // Use Node.js https module
-  // eslint-disable-next-line
-  const https = require('https')
-  response = await nodeFetch(https, url, requestOptions)
-  data = JSON.parse(response)
-  return data
-}
-```
-
-
 Given an array of merkle roots and corresponding block heights, we return a boolean indicating whether they're all valid.
 
 We can plug in the Block Header Service API with appropriate HTTP handling logic as follows:
 
 ```typescript
+import {defaultHttpClient} from "@bsv/sdk";
+
 /**
  * Represents a Block Headers Client.
  */
@@ -107,9 +61,10 @@ export default class BlockHeadersClient implements ChainTracker {
    * @param {string} URL - The URL endpoint for the Pulse API.
    * @param {string} apiKey - The API key used for authorization with the Pulse API.
    */
-  constructor (URL: string, apiKey: string) {
+  constructor(URL: string, apiKey: string) {
     this.URL = URL
     this.apiKey = apiKey
+    this.httpClient = defaultHttpClient()
   }
 
   /**
@@ -119,19 +74,19 @@ export default class BlockHeadersClient implements ChainTracker {
    * @param height: number - The corresponding height
    * @returns {Promise<boolean>} A promise that resolves to either a success or failure response (true or false).
    */
-  async isValidRootForHeight (root: string, height: number): Promise<boolean> {
-    try {
-      const data = await httpsClient(`${this.URL}/api/v1/chain/merkleroot/verify`, {
-        method: 'POST',
-        body: JSON.stringify([{ merkleRoot: root, blockHeight: height }]),
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${this.apiKey}`
-        }
-      })
-      return data?.confirmationState === 'CONFIRMED'
-    } catch (error) {
-      return false
+  async isValidRootForHeight(root: string, height: number): Promise<boolean> {
+    const response = await httpsClient(`${this.URL}/api/v1/chain/merkleroot/verify`, {
+      method: 'POST',
+      body: [{merkleRoot: root, blockHeight: height}],
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`
+      }
+    })
+    if (response.ok) {
+      return response.data?.confirmationState === 'CONFIRMED'
+    } else {
+      throw new Error(`Failed to verify root at height ${height} with response ${response.status}`)
     }
   }
 }

package/docs/examples/GETTING_STARTED_NODE_CJS.md

@@ -53,9 +53,7 @@ const tx = new Transaction(version, [input], [output])
 await tx.fee()
 await tx.sign()
 
-// get your api key from https://console.taal.com
-const apiKey = 'mainnet_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' // replace
-await tx.broadcast(new ARC('https://api.taal.com/arc', apiKey))
+await tx.broadcast()
 ```
 
 This script demonstrates the entire process of creating a transaction, from initializing keys to signing and broadcast. When you run this script using Node.js (replacing the source transaction, private key, and ARC credentials), the spend will be signed and broadcast to the BSV network.
@@ -70,4 +68,4 @@ node index.js
 
 ## Conclusion
 
-Congratulations! You've successfully installed the BSV SDK in your NodeJS project and created a signed transaction. This guide covered the basics to get you started, but the BSV SDK is capable of much more. Explore the SDK documentation for detailed information on all the features and functionalities available to build scalable applications with the BSV blockchain.
+Congratulations! You've successfully installed the BSV SDK in your NodeJS project and created a signed transaction. This guide covered the basics to get you started, but the BSV SDK is capable of much more. Explore the SDK documentation for detailed information on all the features and functionalities available to build scalable applications with the BSV blockchain.

package/docs/examples/GETTING_STARTED_REACT.md

@@ -60,9 +60,7 @@ const BsvButton: React.FC = () => {
     await tx.fee()
     await tx.sign()
 
-    // grab your api key from https://console.taal.com
-    const apiKey = 'mainnet_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' // replace
-    await tx.broadcast(new ARC('https://api.taal.com/arc', apiKey))
+    await tx.broadcast()
   }
 
   return (
@@ -118,4 +116,4 @@ Now when you click the button, a transaction will be created, signed, and broadc
 Conclusion
 ----------
 
-Congratulations! You've successfully integrated the BSV SDK into your TypeScript & React application and created a button which broadcasts a bitcoin transaction on click. This guide covered the basic steps needed to get you started, but the BSV SDK can do a lot more. Explore the SDK documentation to dive deep into all the features and functionalities available to build scalable applications on the BSV blockchain.
+Congratulations! You've successfully integrated the BSV SDK into your TypeScript & React application and created a button which broadcasts a bitcoin transaction on click. This guide covered the basic steps needed to get you started, but the BSV SDK can do a lot more. Explore the SDK documentation to dive deep into all the features and functionalities available to build scalable applications on the BSV blockchain.

package/docs/primitives.md

@@ -6178,9 +6178,9 @@ const publicKey = signature.RecoverPublicKey(0, msgHash);
 Takes an array of numbers or a string and returns a new Signature instance.
 This method will throw an error if the Compact encoding is invalid.
 If a string is provided, it is assumed to represent a hexadecimal sequence.
-compactByte value 27-31 means compressed public key.
-32-35 means uncompressed public key.
-The range represents the recovery param which can be 0,1,2,3,4.
+compactByte value 27-30 means uncompressed public key.
+31-34 means compressed public key.
+The range represents the recovery param which can be 0,1,2,3.
 We could support recovery functions in future if there's demand.
 
 ```ts
@@ -6704,6 +6704,7 @@ export default class PublicKey extends Point {
     toHash(enc?: "hex"): number[] | string 
     toAddress(prefix: number[] = [0]): string 
     deriveChild(privateKey: PrivateKey, invoiceNumber: string): PublicKey 
+    static fromMsgHashAndCompactSignature(msgHash: BigNumber, signature: number[] | string, enc?: "hex" | "base64"): PublicKey 
 }
 ```
 
@@ -6781,6 +6782,38 @@ const myPrivKey = new PrivateKey(...)
 const sharedSecret = myPubKey.deriveSharedSecret(myPrivKey)
 ```
 
+#### Method fromMsgHashAndCompactSignature
+
+Takes an array of numbers or a string and returns a new PublicKey instance.
+This method will throw an error if the Compact encoding is invalid.
+If a string is provided, it is assumed to represent a hexadecimal sequence.
+compactByte value 27-30 means uncompressed public key.
+31-34 means compressed public key.
+The range represents the recovery param which can be 0,1,2,3.
+
+```ts
+static fromMsgHashAndCompactSignature(msgHash: BigNumber, signature: number[] | string, enc?: "hex" | "base64"): PublicKey 
+```
+
+Returns
+
+A PublicKey instance derived from the message hash and compact signature.
+
+Argument Details
+
++ **msgHash**
+  + The message hash which was signed.
++ **signature**
+  + The signature in compact format.
++ **enc**
+  + The encoding of the signature string.
+
+Example
+
+```ts
+const publicKey = Signature.fromMsgHashAndCompactSignature(msgHash, 'IMOl2mVKfDgsSsHT4uIYBNN4e...', 'base64');
+```
+
 #### Method fromPrivateKey
 
 Static factory method to derive a public key from a private key.

package/docs/transaction.md

@@ -426,6 +426,18 @@ export default class Transaction {
     metadata: Record<string, any>;
     merklePath?: MerklePath;
     static fromBEEF(beef: number[]): Transaction 
+    static parseScriptOffsets(bin: number[]): {
+        inputs: {
+            vin: number;
+            offset: number;
+            length: number;
+        }[];
+        outputs: {
+            vout: number;
+            offset: number;
+            length: number;
+        }[];
+    } 
     static fromBinary(bin: number[]): Transaction 
     static fromHex(hex: string): Transaction 
     static fromHexBEEF(hex: string): Transaction 
@@ -651,6 +663,42 @@ Argument Details
 + **enc**
   + The encoding to use for the ID. If 'hex', returns a hexadecimal string; otherwise returns a binary array.
 
+#### Method parseScriptOffsets
+
+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.
+Since the transaction data includes the output script data, saving a second copy of potentially
+large scripts can bloat application storage requirements.
+
+This function efficiently parses binary transaction data to determine the offsets and lengths of each script.
+This supports the efficient retreival of script data from transaction data.
+
+```ts
+static parseScriptOffsets(bin: number[]): {
+    inputs: {
+        vin: number;
+        offset: number;
+        length: number;
+    }[];
+    outputs: {
+        vout: number;
+        offset: number;
+        length: number;
+    }[];
+} 
+```
+
+Returns
+
+inputs: { vin: number, offset: number, length: number }[]
+outputs: { vout: number, offset: number, length: number }[]
+}
+
+Argument Details
+
++ **bin**
+  + binary transaction data
+
 #### Method sign
 
 Signs a transaction, hydrating all its unlocking scripts based on the provided script templates where they are available.

package/mod.ts

@@ -4,5 +4,6 @@ export * from "./src/script/templates/index.js"
 export * from "./src/transaction/index.js"
 export * from "./src/transaction/fee-models/index.js"
 export * from "./src/transaction/broadcasters/index.js"
+export * from "./src/transaction/http/index.js"
 export * from "./src/messages/index.js"
-export * from "./src/compat/index.js"
+export * from "./src/compat/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",
@@ -74,6 +74,26 @@
       "require": "./dist/cjs/src/transaction/broadcaster/*.js",
       "types": "./dist/types/src/transaction/broadcaster/*.d.ts"
     },
+    "./transaction/chaintrackers": {
+      "import": "./dist/esm/src/transaction/chaintrackers/index.js",
+      "require": "./dist/cjs/src/transaction/chaintrackers/index.js",
+      "types": "./dist/types/src/transaction/chaintrackers/index.d.ts"
+    },
+    "./transaction/chaintrackers/*": {
+      "import": "./dist/esm/src/transaction/chaintrackers/*.js",
+      "require": "./dist/cjs/src/transaction/chaintrackers/*.js",
+      "types": "./dist/types/src/transaction/chaintrackers/*.d.ts"
+    },
+    "./transaction/http": {
+      "import": "./dist/esm/src/transaction/http/index.js",
+      "require": "./dist/cjs/src/transaction/http/index.js",
+      "types": "./dist/types/src/transaction/http/index.d.ts"
+    },
+    "./transaction/http/*": {
+      "import": "./dist/esm/src/transaction/http/*.js",
+      "require": "./dist/cjs/src/transaction/http/*.js",
+      "types": "./dist/types/src/transaction/http/*.d.ts"
+    },
     "./transaction/fee-model": {
       "import": "./dist/esm/src/transaction/fee-model/index.js",
       "require": "./dist/cjs/src/transaction/fee-model/index.js",

package/src/primitives/PublicKey.ts

@@ -172,4 +172,43 @@ export default class PublicKey extends Point {
     const finalPoint = this.add(point)
     return new PublicKey(finalPoint.x, finalPoint.y)
   }
+
+  /**
+   * Takes an array of numbers or a string and returns a new PublicKey instance.
+   * This method will throw an error if the Compact encoding is invalid.
+   * If a string is provided, it is assumed to represent a hexadecimal sequence.
+   * compactByte value 27-30 means uncompressed public key.
+   * 31-34 means compressed public key.
+   * The range represents the recovery param which can be 0,1,2,3.
+   *
+   * @static
+   * @method fromMsgHashAndCompactSignature
+   * @param msgHash - The message hash which was signed.
+   * @param signature - The signature in compact format.
+   * @param enc - The encoding of the signature string.
+   * @returns A PublicKey instance derived from the message hash and compact signature.
+   * @example
+   * const publicKey = Signature.fromMsgHashAndCompactSignature(msgHash, 'IMOl2mVKfDgsSsHT4uIYBNN4e...', 'base64');
+   */
+  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')
+    }
+    const compactByte = data[0]
+    if (compactByte < 27 || compactByte >= 35) {
+      throw new Error('Invalid Compact Byte')
+    }
+    let r = data[0] - 27
+    let compressed = false // we don't really use this in the modern era, always use compressed.
+    if (r > 3) {
+      compressed = true
+      r -= 4
+    }
+    const s = new Signature(
+      new BigNumber(data.slice(1, 33)),
+      new BigNumber(data.slice(33, 65))
+    )
+    return s.RecoverPublicKey(r, msgHash)
+  }
 }

package/src/primitives/Signature.ts

@@ -106,9 +106,9 @@ export default class Signature {
    * Takes an array of numbers or a string and returns a new Signature instance.
    * This method will throw an error if the Compact encoding is invalid.
    * If a string is provided, it is assumed to represent a hexadecimal sequence.
-   * compactByte value 27-31 means compressed public key.
-   * 32-35 means uncompressed public key.
-   * The range represents the recovery param which can be 0,1,2,3,4.
+   * compactByte value 27-30 means uncompressed public key.
+   * 31-34 means compressed public key.
+   * The range represents the recovery param which can be 0,1,2,3.
    * We could support recovery functions in future if there's demand.
    *
    * @static
@@ -339,9 +339,9 @@ export default class Signature {
     const rInv = r.invm(n)
 
     // const Q = R.multiplyTwo(s, G, eNeg).mul(rInv)
-    const Q = R.mul(s)
-      .add(G.mul(eNeg))
-      .mul(rInv)
+    const srInv = rInv.mul(s).umod(n)
+    const eInvrInv = rInv.mul(eNeg).umod(n)
+    const Q = G.mul(eInvrInv).add(R.mul(srInv))
 
     const pubKey = new PublicKey(Q)
     pubKey.validate()