@bsv/sdk 1.0.33 → 1.0.36

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).
@@ -63,17 +63,36 @@ 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.
 
-## Configuring the ARC with http client
+## 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 as an argument to the ARC constructor:
+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, {fetch})
+const arc = new ARC('https://api.taal.com/arc', apiKey, new FetchHttpClient(mockFetch))
 ```
 
 ### https
@@ -94,7 +113,27 @@ Although the SDK is not providing adapters for axios, it can be easily used with
 You can make your own "adapter" for axios as follows:
 
 ```typescript
-const axiosHttpClient = { fetch: (url, options) => axios(url, {...options, data: options.body})}
+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) 
 ```

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.