@bsv/sdk 1.0.4 → 1.0.6

package/docs/examples/EXAMPLE_ENCRYPT_DECRYPT_MESSAGE.md

@@ -0,0 +1,52 @@
+# Example: Message Encryption and Decryption
+
+This guide walks you through the steps of encrypting and decrypting messages.
+
+## Overview
+
+Understanding the ins-and-outs of message encryption and decryption is key to implementing secure communication. The implemented functions allow a sender to encrypt messages that only the intended recipient can decrypt, thus preserving the privacy of the message exchange.
+
+### Encrypting a Message
+ To get started, you will first want to import the required functions / classes.
+
+```ts
+import { PrivateKey, EncryptedMessage, Utils } from '@bsv/sdk'
+```
+
+Next, you will want to configure who the sender is, the recipient, and what message you would like to encrypt.
+
+```ts
+const sender = new PrivateKey(15)
+const recipient = new PrivateKey(21)
+const recipientPub = recipient.toPublicKey()
+const message: number[] = Utils.toArray('Did you receive the Bitcoin payment?', 'utf8')
+```
+
+Now you are ready to generate the ciphertext using the `encrypt` function. This function will return an array of bytes so you will need to convert it using `toUTF` if you would like it as a string of text. 
+
+```ts
+const encrypted: number[] = EncryptedMessage.encrypt(message, sender, recipientPub)
+const ciphertextMessage: string = Utils.toUTF8(encrypted)
+```
+
+### Decrypting a Message
+
+To get back your plaintext message, use the `decrypt` function and then transform it as needed.
+
+```ts
+const decrypted: number[] = EncryptedMessage.decrypt(encrypted, recipient)
+const plaintextMessage: string = Utils.toUTF8(decrypted)
+// console.log(plaintextMessage) -> 'Did you receive the Bitcoin payment?'
+```
+
+## Considerations
+
+As you leverage encryption and decryption in your applications, it's crucial to remember:
+
+- **Key management**: Private keys should always be kept safe and never exposed. This library insures that intermediate keys generated for message encryption always use random nonces to mitigate key-reuse attack vectors. 
+
+- **Key of recipient:** The decryption stage using the recipient's key is always done on the recipient's end. As such, the recipient key used is the public key provided by the recipient, and is just generated in the above example for testing purposes.
+
+- **Interpretation of decrypted data**: The decrypted byte array may need to be transformed back into a string, depending on the nature of the original message. There are several utility functions exported, such as toUTF8, that can be leveraged as needed.
+
+This is just a simple example of how encryption and decryption can be implemented for secure message exchange in your applications. The exact method of implementation might vary based on your application’s specifics.

package/docs/examples/EXAMPLE_FEE_MODELING.md

@@ -0,0 +1,199 @@
+# Example: Creating a Custom Transaction Fee Model
+
+Bitcoin miners accept transactions into a block when they pay an appropriate fee. The transaction fee is simply the difference between the amounts used as input, and the amounts claimed by transaction outputs. This is to say, any amount of Bitcoins that are unclaimed (left over) after all transaction outputs have been fulfilled is given to the miner who solves the block in which the transaction is included.
+
+To date, fees have generally been measured in satoshis per kilobyte of block space used by the transaction. However, the SDK allows you to create custom fee models that take other factors into account. This guide will show you the default fee model, and discuss how it might be customized in the future. Note that you'll need to consult with various miners if considering an alternative fee model, to make sure your transactions would still be included in the blockchain.
+
+## Default Fee Model
+
+The `.fee()` method on a `Transaction` object takes a fee model as an optional parameter. The function of a fee model is to compute the number of satoshis that the transaction should pay in fees. Here's the interface all fee models need to follow:
+
+```typescript
+/**
+ * Represents the interface for a transaction fee model.
+ * This interface defines a standard method for computing a fee when given a transaction.
+ *
+ * @interface
+ * @property {function} computeFee - A function that takes a Transaction object and returns a BigNumber representing the number of satoshis the transaction should cost.
+ */
+export default interface FeeModel {
+  computeFee: (transaction: Transaction) => Promise<number>
+}
+
+```
+
+In short, a fee model is an object with a `computeFee` function that, when called with a `Transaction` as its first and only parameter, will return a `Promise` for a `number` of satoshis.
+
+The default fee model, used if no other model is provided, looks like this:
+
+```typescript
+/**
+ * Represents the "satoshis per kilobyte" transaction fee model.
+ */
+export default class SatoshisPerKilobyte implements FeeModel {
+  /**
+   * @property
+   * Denotes the number of satoshis paid per kilobyte of transaction size.
+   */
+  value: number
+
+  /**
+   * Constructs an instance of the sat/kb fee model.
+   *
+   * @param {number} value - The number of satoshis per kilobyte to charge as a fee.
+   */
+  constructor(value: number) {
+    this.value = value
+  }
+
+  /**
+   * Computes the fee for a given transaction.
+   *
+   * @param tx The transaction for which a fee is to be computed.
+   * @returns The fee in satoshis for the transaction, as a number.
+   */
+  async computeFee(tx: Transaction): Promise<number> {
+    const getVarIntSize = (i: number): number => {
+      if (i > 2 ** 32) {
+        return 9
+      } else if (i > 2 ** 16) {
+        return 5
+      } else if (i > 253) {
+        return 3
+      } else {
+        return 1
+      }
+    }
+    // Compute the (potentially estimated) size of the transaction
+    let size = 4 // version
+    size += getVarIntSize(tx.inputs.length) // number of inputs
+    for (let i = 0; i < tx.inputs.length; i++) {
+      const input = tx.inputs[i]
+      size += 40 // txid, output index, sequence number
+      let scriptLength: number
+      if (typeof input.unlockingScript === 'object') {
+        scriptLength = input.unlockingScript.toBinary().length
+      } else if (typeof input.unlockingScriptTemplate === 'object') {
+        scriptLength = await input.unlockingScriptTemplate.estimateLength(tx, i)
+      } else {
+        throw new Error('All inputs must have an unlocking script or an unlocking script template for sat/kb fee computation.')
+      }
+      size += getVarIntSize(scriptLength) // unlocking script length
+      size += scriptLength // unlocking script
+    }
+    size += getVarIntSize(tx.outputs.length) // number of outputs
+    for (const out of tx.outputs) {
+      size += 8 // satoshis
+      const length = out.lockingScript.toBinary().length
+      size += getVarIntSize(length) // script length
+      size += length // script
+    }
+    size += 4 // lock time
+    // We'll use Math.ceil to ensure the miners get the extra satoshi.
+    const fee = Math.ceil((size / 1000) * this.value)
+    return fee
+  }
+}
+```
+
+Here, you can see we're computing the size of the transaction in bytes, then computing the number of satoshis based on the number of kilobytes.
+
+## Making Adjustments
+
+Let's modify our fee model to check for a few custom cases, just as a purely theoretical example:
+
+- If the version of the transaction is 3301, the transaction is free.
+- If there are more than 3x as many inputs as there are outputs (the transaction is helping shrink the number of UTXOs), the transaction gets a 20% discount.
+- If there are more than 5x as many outputs as there are inputs, the transaction is 10% more expensive.
+- Other than that, the rules are the same as the Satoshis per Kilobyte fee model.
+
+With these rules in place, let's build a custom fee model!
+
+```typescript
+/**
+ * Represents the "example" transaction fee model.
+ */
+export default class Example implements FeeModel {
+  /**
+   * @property
+   * Denotes the base number of satoshis paid per kilobyte of transaction size.
+   */
+  value: number
+
+  /**
+   * Constructs an instance of the example fee model.
+   *
+   * @param {number} value - The base number of satoshis per kilobyte to charge as a fee.
+   */
+  constructor(value: number) {
+    this.value = value
+  }
+
+  /**
+   * Computes the fee for a given transaction.
+   *
+   * @param tx The transaction for which a fee is to be computed.
+   * @returns The fee in satoshis for the transaction, as a number.
+   */
+  async computeFee(tx: Transaction): Promise<number> {
+    const getVarIntSize = (i: number): number => {
+      if (i > 2 ** 32) {
+        return 9
+      } else if (i > 2 ** 16) {
+        return 5
+      } else if (i > 253) {
+        return 3
+      } else {
+        return 1
+      }
+    }
+
+    // Version 3301 transactions are free :)
+    if (tx.version === 3301) {
+        return 0
+    }
+
+    // Compute the (potentially estimated) size of the transaction
+    let size = 4 // version
+    size += getVarIntSize(tx.inputs.length) // number of inputs
+    for (let i = 0; i < tx.inputs.length; i++) {
+      const input = tx.inputs[i]
+      size += 40 // txid, output index, sequence number
+      let scriptLength: number
+      if (typeof input.unlockingScript === 'object') {
+        scriptLength = input.unlockingScript.toBinary().length
+      } else if (typeof input.unlockingScriptTemplate === 'object') {
+        scriptLength = await input.unlockingScriptTemplate.estimateLength(tx, i)
+      } else {
+        throw new Error('All inputs must have an unlocking script or an unlocking script template for sat/kb fee computation.')
+      }
+      size += getVarIntSize(scriptLength) // unlocking script length
+      size += scriptLength // unlocking script
+    }
+    size += getVarIntSize(tx.outputs.length) // number of outputs
+    for (const out of tx.outputs) {
+      size += 8 // satoshis
+      const length = out.lockingScript.toBinary().length
+      size += getVarIntSize(length) // script length
+      size += length // script
+    }
+    size += 4 // lock time
+    let fee = ((size / 1000) * this.value)
+
+    // Now we apply our input and output rules
+    // For the inputs incentive
+    if (tx.inputs.length / 3 >= tx.outputs.length) {
+        fee *= 0.8
+    }
+    // For the outputs penalty
+    if (tx.outputs.length / 5 >= tx.inputs.length) {
+        fee *= 1.1
+    }
+
+    // We'll use Math.ceil to ensure the miners get the extra satoshi.
+    return Math.ceil(fee)
+  }
+}
+```
+
+Now. when you create a new transaction and call the `.ee()` method with this fee model, it will follow the rules we have set above!

package/docs/examples/EXAMPLE_HD_WALLETS.md

@@ -0,0 +1,71 @@
+# Example: BIP32 Key Derivation with HD Wallets
+
+For a long time, BIP32 was the standard way to structure a Bitcoin wallet. While [type-42](EXAMPLE_TYPE_42.md) has since taken over as the standard approach due to its increased privacy and open-ended invoice numbering scheme, it's sometimes still necessary to interact with legacy systems using BIP32 key derivation.
+
+This guide will show you how to generate keys, derive child keys, and convert them to WIF and Bitcoin address formats. At the end, we'll compare BIP32 to the [type-42 system and encourage you to adopt the new approach](EXAMPLE_TYPE_42.md) to key management.
+
+## Generating BIP32 keys
+
+You can generate a BIP32 seed with the SDK as follows:
+
+```typescript
+import { HD } from '@bsv/sdk'
+const randomKey = HD.fromRandom()
+
+// Convert your "xprv" key to a string
+console.log(randomKey.toString())
+
+// Example: xprv9s21ZrQH143K2vF2szsDFhrRehet4iHNCBPWprjymByU9mzN7n687qj3ULQ2YYXdNqFwhVSsKv9W9fM675whM9ATaYrmsLpykQSxMc6RN8V
+```
+
+You can also import an existing key as follows:
+
+```typescript
+const importedKey = new HD().fromString('xprv...')
+```
+
+Now that you've generated or imported your key, you're ready to derive child keys.
+
+## Deriving Child Keys
+
+BIP32 child keys can be derived from a key using the `.derive()` method. Here's a full example:
+
+```typescript
+const key = new bsv.HD().fromString('xprv9s21ZrQH143K2vF2szsDFhrRehet4iHNCBPWprjymByU9mzN7n687qj3ULQ2YYXdNqFwhVSsKv9W9fM675whM9ATaYrmsLpykQSxMc6RN8V')
+const child = key.derive('m/0/1/2')
+console.log(child.toString())
+// 'xprv9yGx5dNDfq8pt1DJ9SFCK3gNFhjrL3kTqEj98oDs6xvfaUAUs3nyvVakQzwHAEMrc6gg1c3iaNCDubUruhX75gNHC7HAnFxHuxeiMVgLEqS'
+```
+
+Any of the standard derivation paths can be passed into the `.derive()` method.
+
+## Converting Between Formats
+
+XPRIV keys can be converted to normal `PrivateKey` instances, and from there to WIF keys. XPUB keys can be converted to normal `PublicKey` instances, and from there to Bitcoin addresses. XPRIV keys can also be converted to XPUB keys:
+
+```typescript
+const key = new bsv.HD().fromString('xprv9s21ZrQH143K2vF2szsDFhrRehet4iHNCBPWprjymByU9mzN7n687qj3ULQ2YYXdNqFwhVSsKv9W9fM675whM9ATaYrmsLpykQSxMc6RN8V')
+
+// Convert XPRIV to XPUB
+const xpubKey = key.toPublic()
+console.log(xpubKey.toString());
+// xpub661MyMwAqRbcFQKVz2QDcqoACjVNUB1DZQK7dF9bKXWT2aKWfKQNfe3XKakZ1EnxeNP5E4MqZnZZw4P7179rPbeJEjhYbwF5ovkbGkeYPdF
+
+// Convert XPRIV to WIF
+console.log(key.privKey.toWif())
+// L1MZHeu2yMYRpDr45icTvjN7s3bBK1o7NgsRMkcfhzgRjLzewAhZ
+
+// Convert XPUB to public key
+console.log(xpubKey.pubKey.toString())
+// 022248d79bf217de60fa4afd4c7841e4f957b6459ed9a8c9c01b61e16cd4da3aae
+
+// Convert XPUB to address
+console.log(xpubKey.pubKey.toAddress())
+// 1CJXwGLb6GMCF46A721VYW59b21kkoRc5D
+```
+
+This guide has demonstrated how to use BIP32 for key derivation and format conversion. You can continue to use BIP32 within BSV wallet applications, but it's important to consider the disadvantages and risks of continued use, which are discussed below.
+
+## Disadvantages and Risks
+
+BIP32 allows anyone to derive child keys if they know an XPUB. The number of child keys per parent is limited to 2^31, and there's no support for custom invoice numbering schemes that can be used when deriving a child, only a simple integer. Finally, BIP32 has no support for private derivation, where two parties share a common key universe no one else can link to them, even while knowing the master public key. It's for these reasons that we recommend the use of type-42 over BIP32. You can read an equivalent guide [here](EXAMPLE_TYPE_42.md).

package/docs/examples/EXAMPLE_MESSAGE_SIGNING.md

@@ -0,0 +1,63 @@
+# Example: Message Signing
+
+This guide walks through the necessary steps for both public and private message signing.
+
+## Overview
+
+Message signing is a mechanism that preserves the integrity of secure communications, enabling entities to verify the authenticity of a message's origin. This document emphasizes two primary types of message signing: private and public.
+
+Private message signing is used when a message needs to be verified by a *specific recipient*. In this scenario, the sender creates a unique signature using their private key combined with the recipient's public key. The recipient, using their private key, can then verify the signature and thereby the message's authenticity.
+
+On the other hand, public message signing creates a signature that can be verified by *anyone*, without the need for any specific private key. This is achieved by the sender using only their private key to create the signature.
+
+The choice between private and public message signing hinges on the specific requirements of the communication. For applications that require secure communication where authentication is paramount, private message signing proves most effective. Conversely, when the authenticity of a message needs to be transparent to all parties, public message signing is the go-to approach. Understanding these differences will enable developers to apply the correct method of message signing depending on their specific use case.
+
+### 1. Example Code - Private Message Signing
+ To get started, you will first want to import the required functions / classes.
+
+```ts
+import { PrivateKey, SignedMessage, Utils } from '@bsv/sdk'
+```
+
+Next, you will want to configure who the sender is, the recipient, and what message you would like to sign.
+
+```ts
+const sender = new PrivateKey(15)
+const recipient = new PrivateKey(21)
+const recipientPub = recipient.toPublicKey()
+const message: number[] = Utils.toArray('I like big blocks and I cannot lie', 'utf8')
+```
+
+Now we can sign the message and generate a signature that can only be verified by our specified recipient.
+
+```ts
+const signature = SignedMessage.sign(message, sender, recipientPub)
+const verified = SignedMessage.verify(message, signature, recipient)
+// console.log(verified) -> true
+```
+
+### 2. Example Code - Public Message Signing
+To create a signature that anyone can verify, the code is very similar to the first example, just without a specified recipient. This will allow anyone to verify the signature generated without requiring them to know a specific private key.
+
+```ts
+import { PrivateKey, SignedMessage, Utils } from '@bsv/sdk'
+
+const sender = new PrivateKey(15)
+const message: number[] = Utils.toArray('I like big blocks and I cannot lie', 'utf8')
+
+const signature = SignedMessage.sign(message, sender)
+const verified = SignedMessage.verify(message, signature)
+// console.log(verified) -> true
+```
+
+## Considerations
+
+While these private signing functions are built on industry standards and well-tested code, there are considerations to keep in mind when integrating them into your applications.
+
+- **Private Key Security**: Private keys must be stored securely to prevent unauthorized access, as they can be used to sign fraudulent messages.
+
+- **Use Case Analysis**: As stated in the overview, you should carefully evaluate whether you need a private or publicly verifiable signature based on your use case.
+
+- **Implications of Signature Verifiability**: When creating signatures that anyone can verify, consider the implications. While transparency is achieved, sensitive messages should only be verifiable by intended recipients.
+
+By understanding and applying these considerations, you can ensure a secure implementation of private signing within your applications.

package/docs/examples/EXAMPLE_PULSE_HEADERS.md

@@ -0,0 +1,140 @@
+# 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.
+
+## Pre-requisites
+
+As stated in the README, you will need to be running a Pulse instance. Get it up and running, and configure a level of authentication appropriate for your use-case:
+
+```sh
+docker pull bsvb/block-headers-service
+docker run bsvb/block-headers-service:latest
+```
+
+## Building our Client
+
+The SDK's `ChainTracker` interface defines the required structure for our implementation, as follows:
+
+```typescript
+/**
+ * The Chain Tracker is responsible for verifying the validity of a given Merkle root
+ * for a specific block height within the blockchain.
+ *
+ * Chain Trackers ensure the integrity of the blockchain by
+ * validating new headers against the chain's history. They use accumulated
+ * proof-of-work and protocol adherence as metrics to assess the legitimacy of blocks.
+ *
+ * @interface ChainTracker
+ * @function isValidRootForHeight - A method to verify the validity of a Merkle root
+ *          for a given block height.
+ *
+ * @example
+ * const chainTracker = {
+ *   isValidRootForHeight: async (root, height) => {
+ *     // Implementation to check if the Merkle root is valid for the specified block height.
+ *   }
+ * };
+ */
+export default interface ChainTracker {
+  isValidRootForHeight: (root: string, height: number) => Promise<boolean>
+}
+```
+
+Given a merkle root and block height, we return a boolean indicating whether it's valid.
+
+We can plug in the Pulse API with appropriate HTTP handling logic as follows:
+
+```typescript
+/**
+ * Represents a Pulse headers client.
+ */
+export default class PulseClient implements ChainTracker {
+  URL: string
+  apiKey: string
+
+  /**
+   * Constructs an instance of the Pulse chain tracker.
+   *
+   * @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) {
+    this.URL = URL
+    this.apiKey = apiKey
+  }
+
+  /**
+   * Checks a merkle root for a height.
+   *
+   * @param {string} root - The merkle root to check.
+   * @param {number} height — The height at which to check.
+   * @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> {
+    const requestOptions = {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`
+      }
+    }
+
+    try {
+      let response
+      let data: any = {}
+
+      if (typeof window !== 'undefined' && typeof window.fetch === 'function') {
+        // Use fetch in a browser environment
+        response = await window.fetch(`${this.URL}/api/v1/chain/header/byHeight?height=${height}&count=1`, requestOptions)
+        data = await response.json()
+      } else if (typeof require !== 'undefined') {
+        // Use Node.js https module
+        // eslint-disable-next-line
+        const https = require('https')
+        response = await this.nodeFetch(https, requestOptions)
+        data = JSON.parse(response)
+      } else {
+        throw new Error('No method available to perform HTTP request')
+      }
+
+      if (data.txid as boolean || response.ok as boolean || response.statusCode === 200) {
+        // Root must match
+        return data[0].merkleRoot === root
+      } else {
+        return false
+      }
+    } catch (error) {
+        // Handle error
+        return false
+    }
+  }
+
+  /** Helper function for Node.js HTTPS requests */
+  private async nodeFetch (https, requestOptions, height): Promise<any> {
+    return await new Promise((resolve, reject) => {
+      const req = https.request(`${this.URL}/api/v1/chain/header/byHeight?height=${height}&count=1`, 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()
+    })
+  }
+}
+```
+
+Now, we can use our `PulseClient` as a `ChainTracker` when calling the `Transaction` object's `.verify()` method. You can see an example in the [BEEF verification guide](EXAMPLE_VERIFYING_BEEF.md).
+
+This provides the ability to ensure that a transaction is well-anchored.