@bsv/sdk 1.0.4 → 1.0.6

package/docs/examples/EXAMPLE_SCRIPT_TEMPLATES.md

@@ -0,0 +1,170 @@
+# Example: Creating the R-puzzle Script Template
+
+This guide will provide information about the structure and functionality of script templates within the BSV SDK. Script templates are a powerful abstraction layer designed to simplify the creation and management of the scripts used in Bitcoin transactions. By understanding how these templates work, developers can leverage them to build more sophisticated and efficient blockchain applications. By the end of this example, you'll understand how the R-puzzle script template (P2RPH) was created.
+
+### Understanding Script Templates
+
+A script template is essentially a blueprint for creating the locking and unlocking scripts that are crucial for securing and spending bitcoins. These templates encapsulate the logic needed to construct these scripts dynamically, based on the parameters passed to them. This approach allows for a modular and reusable codebase, where common scripting patterns can be defined once and then instantiated as needed across different transactions.
+
+#### Locking Script
+
+The locking script, or output script, specifies the conditions under which the bitcoins can be spent. In the BSV SDK, the `lock` function of a script template is responsible for generating this script. By abstracting the creation of locking scripts into a method that accepts parameters, developers can easily create diverse conditions for spending bitcoins without having to write the low-level script code each time.
+
+For example, a locking script might require the presentation of a public key that matches a certain hash or the fulfillment of a multi-signature condition. The flexibility of passing parameters to the `lock` function enables the creation of locking scripts tailored to specific requirements. This example will require a signature created with a particular ephemeral K-value, [an R-puzzle](https://wiki.bitcoinsv.io/index.php/R-Puzzles).
+
+#### Unlocking Script
+
+The unlocking script, or input script, provides the evidence needed to satisfy the conditions set by the locking script. The `unlock` method in a script template not only generates this script but also offers two key functionalities — it's a function that returns an object with two properties:
+
+1. **`estimateLength`**: Before a transaction is signed and broadcast to the network, it's crucial to estimate its size to calculate the required fee accurately. The `estimateLength` function predicts the length of the unlocking script once it will be created, allowing developers to make informed decisions about fee estimation.
+
+2. **`sign`**: This function generates an unlocking script that includes the necessary signatures or data required to unlock the bitcoins. By accepting a transaction and an input index as arguments, it ensures that the unlocking script is correctly associated with the specific transaction input it intends to fund, allowing signatures to be scoped accordingly.
+
+### Creating a Script Template
+
+To create a script template, developers define a class that adheres to the `ScriptTemplate` interface. This involves implementing the `lock` and `unlock` methods with the specific logic needed for their application.
+
+Now that you understand the necessary components, here's the code for the R-puzzle script template:
+
+```javascript
+import {
+  OP, ScriptTemplate, LockingScript, UnlockingScript, Transaction,
+  PrivateKey, TransactionSignature, sha256, ScriptChunk, BigNumber
+} from '@bsv/sdk'
+
+/**
+ * RPuzzle class implementing ScriptTemplate.
+ *
+ * This class provides methods to create R Puzzle and R Puzzle Hash locking and unlocking scripts, including the unlocking of UTXOs with the correct K value.
+ */
+export default class RPuzzle implements ScriptTemplate {
+  type: 'raw' | 'SHA1' | 'SHA256' | 'HASH256' | 'RIPEMD160' | 'HASH160' = 'raw'
+
+  /**
+   * @constructor
+   * Constructs an R Puzzle template instance for a given puzzle type
+   *
+   * @param {'raw'|'SHA1'|'SHA256'|'HASH256'|'RIPEMD160'|'HASH160'} type Denotes the type of puzzle to create
+   */
+  constructor (type: 'raw' | 'SHA1' | 'SHA256' | 'HASH256' | 'RIPEMD160' | 'HASH160' = 'raw') {
+    this.type = type
+  }
+
+  /**
+   * Creates an R puzzle locking script for a given R value or R value hash.
+   *
+   * @param {number[]} value - An array representing the R value or its hash.
+   * @returns {LockingScript} - An R puzzle locking script.
+   */
+  lock (value: number[]): LockingScript {
+    const chunks: ScriptChunk[] = [
+      { op: OP.OP_OVER },
+      { op: OP.OP_3 },
+      { op: OP.OP_SPLIT },
+      { op: OP.OP_NIP },
+      { op: OP.OP_1 },
+      { op: OP.OP_SPLIT },
+      { op: OP.OP_SWAP },
+      { op: OP.OP_SPLIT },
+      { op: OP.OP_DROP }
+    ]
+    if (this.type !== 'raw') {
+      chunks.push({
+        op: OP['OP_' + this.type]
+      })
+    }
+    chunks.push({ op: value.length, data: value })
+    chunks.push({ op: OP.OP_EQUALVERIFY })
+    chunks.push({ op: OP.OP_CHECKSIG })
+    return new LockingScript(chunks)
+  }
+
+  /**
+   * Creates a function that generates an R puzzle unlocking script along with its signature and length estimation.
+   *
+   * The returned object contains:
+   * 1. `sign` - A function that, when invoked with a transaction and an input index,
+   *    produces an unlocking script suitable for an R puzzle locked output.
+   * 2. `estimateLength` - A function that returns the estimated length of the unlocking script in bytes.
+   *
+   * @param {BigNumber} k — The K-value used to unlock the R-puzzle.
+   * @param {PrivateKey} privateKey - The private key used for signing the transaction. If not provided, a random key will be generated.
+   * @param {'all'|'none'|'single'} signOutputs - The signature scope for outputs.
+   * @param {boolean} anyoneCanPay - Flag indicating if the signature allows for other inputs to be added later.
+   * @returns {Object} - An object containing the `sign` and `estimateLength` functions.
+   */
+  unlock (
+    k: BigNumber,
+    privateKey: PrivateKey,
+    signOutputs: 'all' | 'none' | 'single' = 'all',
+    anyoneCanPay: boolean = false
+  ): {
+      sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>
+      estimateLength: () => Promise<106>
+    } {
+    return {
+      sign: async (tx: Transaction, inputIndex: number) => {
+        if (typeof privateKey === 'undefined') {
+          privateKey = PrivateKey.fromRandom()
+        }
+        let signatureScope = TransactionSignature.SIGHASH_FORKID
+        if (signOutputs === 'all') {
+          signatureScope |= TransactionSignature.SIGHASH_ALL
+        }
+        if (signOutputs === 'none') {
+          signatureScope |= TransactionSignature.SIGHASH_NONE
+        }
+        if (signOutputs === 'single') {
+          signatureScope |= TransactionSignature.SIGHASH_SINGLE
+        }
+        if (anyoneCanPay) {
+          signatureScope |= TransactionSignature.SIGHASH_ANYONECANPAY
+        }
+        const otherInputs = [...tx.inputs]
+        const [input] = otherInputs.splice(inputIndex, 1)
+        if (typeof input.sourceTransaction !== 'object') {
+          throw new Error(
+            'The source transaction is needed for transaction signing.'
+          )
+        }
+        const preimage = TransactionSignature.format({
+          sourceTXID: input.sourceTransaction.id('hex') as string,
+          sourceOutputIndex: input.sourceOutputIndex,
+          sourceSatoshis: input.sourceTransaction.outputs[input.sourceOutputIndex].satoshis,
+          transactionVersion: tx.version,
+          otherInputs,
+          inputIndex,
+          outputs: tx.outputs,
+          inputSequence: input.sequence,
+          subscript: input.sourceTransaction.outputs[input.sourceOutputIndex].lockingScript,
+          lockTime: tx.lockTime,
+          scope: signatureScope
+        })
+        const rawSignature = privateKey.sign(sha256(preimage), undefined, true, k)
+        const sig = new TransactionSignature(
+          rawSignature.r,
+          rawSignature.s,
+          signatureScope
+        )
+        const sigForScript = sig.toChecksigFormat()
+        const pubkeyForScript = privateKey.toPublicKey().encode(true) as number[]
+        return new UnlockingScript([
+          { op: sigForScript.length, data: sigForScript },
+          { op: pubkeyForScript.length, data: pubkeyForScript }
+        ])
+      },
+      estimateLength: async () => {
+        // public key (1+33) + signature (1+71)
+        // Note: We add 1 to each element's length because of the associated OP_PUSH
+        return 106
+      }
+    }
+  }
+}
+```
+
+In this example, `RPuzzle` defines custom logic for creating both locking and unlocking scripts. The opcodes, intermixed with the various template fields, enable end-users to implement R-puzzles into their applications without being concerned with these low-level details. Check out [this guide](./EXAMPLE_COMPLEX_TX.md) to see an example of this template used in a transaction.
+
+### Conclusion
+
+Script templates in the BSV SDK offer a structured and efficient way to handle the creation of locking and unlocking scripts in Bitcoin transactions. By encapsulating the logic for script generation and providing essential functionalities like signature creation and length estimation, script templates make it easier for developers to implement complex transactional logic. With these tools, template consumers can focus on the higher-level aspects of their blockchain applications, relying on the SDK to manage the intricacies of script handling.

package/docs/examples/EXAMPLE_SIMPLE_TX.md

@@ -0,0 +1,64 @@
+# Example: Creating a Simple Transaction
+
+This guide walks you through the steps of creating a simple Bitcoin transaction. To get started, let's explain some basic concepts around Bitcoin transactions.
+
+## Understanding and Creating Transactions
+
+Transactions in Bitcoin are mechanisms for transferring value and invoking smart contract logic. The `Transaction` class in the BSV SDK encapsulates the creation, signing, and broadcasting of transactions, also enabling the use of Bitcoin's scripting language for locking and unlocking coins.
+
+## Creating and Signing a Transaction
+
+Consider the scenario where you need to create a transaction. The process involves specifying inputs (where the bitcoins are coming from) and outputs (where they're going). Here's a simplified example:
+
+```typescript
+import { Transaction, PrivateKey, PublicKey, P2PKH, ARC } from '@bsv/sdk'
+
+const privKey = PrivateKey.fromWif('...') // Your P2PKH private key
+const changePrivKey = PrivateKey.fromWif('...') // Change private key (never re-use addresses)
+const recipientAddress = '1Fd5F7XR8LYHPmshLNs8cXSuVAAQzGp7Hc' // Address of the recipient
+
+const tx = new Transaction()
+
+// Add the input
+tx.addInput({
+  sourceTransaction: Transaction.fromHex('...'), // The source transaction where the output you are spending was created,
+  sourceOutputIndex: 0, // The output index in the source transaction
+  unlockingScriptTemplate: new P2PKH().unlock(privKey), // The script template you are using to unlock the output, in this case P2PKH
+})
+
+// Pay an output to a recipient using the P2PKH locking template
+tx.addOutput({
+  lockingScript: new P2PKH().lock(recipientAddress),
+  satoshis: 2500
+})
+
+// Send remainder back the change
+tx.addOutput({
+  lockingScript: new P2PKH().lock(changePrivKey.toPublicKey().toHash()),
+  change: true
+})
+
+// Now we can compute the fee and sign the transaction
+await tx.fee()
+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))
+```
+
+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).
+
+## Handling Hex Locking Scripts
+
+Moving beyond this basic example into more advanced use-cases enables you to start dealing with custom scripts. If you're provided with a hex-encoded locking script for an output, you can set it directly in the transaction's output as follows:
+
+```typescript
+transaction.addOutput({
+  lockingScript: Script.fromHex('76a9....88ac'), // Hex-encoded locking script
+  satoshis: 2500 // Number of satoshis
+})
+```
+
+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.

package/docs/examples/EXAMPLE_TYPE_42.md

@@ -0,0 +1,108 @@
+# Example: Using Type 42 Key Derivation for Bitcoin Wallet Management
+
+Welcome to this type-42 key derivation guide! We're glad you're here, especially if you're migrating from an older key derivation system. Type-42 is more private, more elegant and it's easy to understand.
+
+This guide will walk you through using type-42 keys in the context of a Bitcoin wallet.
+
+## Generating keys
+
+Generating type-42 keys with the SDK is identical to generating normal private keys. Secretly, every private key (and public key) in the SDK is already a type-42 key!
+
+```typescript
+import { PrivateKey } from '@bsv/sdk'
+
+const privateKey = PrivateKey.fromRandom()
+```
+
+Now, we can move on to key derivation.
+
+## Type 42 Key Derivation
+
+In type-42 systems, you provide a counterparty key when deriving, as well as your own. There is always one public key and one private key. It's either:
+
+- Your private key and the public key of your counterparty are used to derive one of your private keys, or
+- Your private key and the public key of your counterparty are used to derive one of their public keys
+
+When you and your counterparty use the same invoice number to derive keys, the public key you derive for them will correspond to the private key they derive for themselves. A private key that you derive for yourself will correspond to the public key they derived for you.
+
+Once you understand those concepts, we're ready to jump into some code!
+
+### Alice and Bob
+
+Let's consider the scenario of Alice and Bob, who want to exchange some Bitcoin. How can Alice send Bitcoins to Bob?
+
+1. Alice learns Bob's master public key, and they agree on the Bitcoin aount to exchange.
+2. They also agree on an invoice number.
+3. Alice uses Bob's master public key with her private key to derive the payment key she will use.
+4. Alice creates a Bitcoin transaction and pays Bob the money.
+5. Bob uses Alice's public key and his own private key to derive the corresponding private key, verifying it matches the transaction Alice sent him.
+
+Here's an example:
+
+```typescript
+// Alice and Bob have master private keys...
+const alice = PrivateKey.fromRandom()
+const bob = PrivateKey.fromRandom()
+alice.toString()
+'106674548343907642146062962636638307981249604845652704224160905817279514790351'
+bob.toString()
+'108446104340374144960104248963000752145648236191076545713737995455205583156408'
+
+// ... and master public keys
+const alicePub = alice.toPublicKey()
+const bobPub = bob.toPublicKey()
+alicePub.toString()
+'0260846fbaf8e950c1896d360954a716f26699252b879fea1743a9f78a0950d167'
+bobPub.toString()
+'0258bfa42bd832c4ab655295cac5e2f64daefb2b4cd9a2b72bdd3c3f9ba5076cb7'
+
+// To pay Alice, they agree on an invoice number and then Bob derives a key where he can pay Alice
+const paymentKey = alicePub.deriveChild(bob, 'AMZN-44-1191213')
+
+// The key can be converted to an address if desired
+paymentKey2.toAddress()
+'1HqfEfHNF9ji9p3AEC66mj8fhGA7sy2WYT'
+
+// To unlock the coins, Alice derives the private key with the same invoice number, using Bob's public key
+const paymentPriv = alice.deriveChild(bobPub, 'AMZN-44-1191213')
+
+// The key can be converted to WIF if desired
+paymentPriv.toWif()
+'L22stYh323a8DfBNunLvxrcrxudT2YXjdKxe1q9ecARYT9XfFGGc'
+
+// To check, Alice can convert the private key back into an address.
+paymentPriv.toPublicKey().toAddress()
+'1HqfEfHNF9ji9p3AEC66mj8fhGA7sy2WYT'
+```
+
+This provides privacy for Alice and Bob, even if eeryone in the world knows Alice and Bob's master public keys.
+
+## Going Further: Public Derivation
+
+Sometimes, there is a legitimate reason to do "public key derivation" from a key, so that anyone can link a master key to a child key, like in BIP32. To accomplish this, rather than creating a new algorithm, we just use a private key that everyone already knows: the number `1`.
+
+```typescript
+alicePub.deriveChild(new PrivateKey(1), '1').toString()
+'0391ff4958a6629be3176330bed0efd99d860f2b7630c21b2e33a42f3cd1740544'
+alicePub.deriveChild(new PrivateKey(1), '2').toString()
+'022ea65d6d66754dc7d94e197dab31a4a8854cdb28d57f216e765af7dfddb5322d'
+alicePub.deriveChild(new PrivateKey(1), 'Bitcoin SV').toString()
+'039e9bf79f4cf7accc061d570b1282bd24d2045be44584e8c6744cd3ff42e1758c'
+alicePub.deriveChild(new PrivateKey(1), '2-tempo-1').toString() // BRC-43 :)
+'02fd1e62689b7faaa718fabe9593da718fb2f966a9b391e5c48f25b1f9fbd4e770'
+```
+
+Because everyone knows the number `1`, everyone can derive Alice's public keys with these invoice numbers. But only Alice can derive the corresponding private keys:
+
+```typescript
+alice.deriveChild(new PrivateKey(1).toPublicKey(), '1').toString()
+'5097922263303694608415912843049723146488598519566487750842578489217455687866'
+alice.deriveChild(new PrivateKey(1).toPublicKey(), '2').toString()
+'30335387255051916743526252561695774618041865683431443265879198629898915116869'
+alice.deriveChild(new PrivateKey(1).toPublicKey(), 'Bitcoin SV').toString()
+'78577766545688955856149390014909118010252835780550951683873199149559002824861'
+alice.deriveChild(new PrivateKey(1).toPublicKey(), '2-tempo-1').toString() // BRC-43 :)
+'85481526811941870977151386860102277207605069038305420293413543998866547111586'
+```
+
+The type-42 system enables both public and private key derivation, all while providing a more flexible and open-ended invoice numbering scheme than BIP32.

package/docs/examples/EXAMPLE_VERIFYING_BEEF.md

@@ -0,0 +1,55 @@
+# Example: Verifying a BEEF Structure
+
+The BSV SDK comes with advanced capabilities around the SPV architecture. In Bitcoin, SPV refers to the process of creating, exchanging, and verifying transactions in a way that anchors them to the blockchain. One of the standard formats for representing the necessary SPV data is known as BEEF (background-evaluated extended format), representing a transaction and its parents together with needed merkle proofs. This example will show you how to verify the legitimacy of a BEEF-formatted SPV structure you've received, checking to ensure the target transaction and its ancestors are well-anchored to the blockchain based on the current chain of block headers. First we'll unpack these concepts, then we'll dive into the code.
+
+## Block Headers and Merkle Proofs
+
+In Bitcoin, miners create blocks. These blocks comprise merkle trees of the included transactions. The root of the merkle tree, together with other useful information, is collected together into a block header that can be used to verify the block's proof-of-work. This merkle tree structure enables anyone to keep track of the chain of block headers without keeping a copy of every Bitcoin transaction.
+
+Merkle proofs are simply a way for someone to prove the existence of a given transaction within a given merkle tree, and by extension, its inclusion by the miners in a particular block of the blockchain. This becomes extremely important and useful when we think about Simplified Payment Verification (SPV).
+
+## Simplified Payment Verification (SPV)
+
+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:
+
+```typescript
+import { Transaction } from '@bsv/sdk'
+
+// Replace with the BEEF structure you'd like to check
+const BEEFHex = '0100beef01fe636d0c0007021400fe507c0c7aa754cef1f7889d5fd395cf1f785dd7de98eed895dbedfe4e5bc70d1502ac4e164f5bc16746bb0868404292ac8318bbac3800e4aad13a014da427adce3e010b00bc4ff395efd11719b277694cface5aa50d085a0bb81f613f70313acd28cf4557010400574b2d9142b8d28b61d88e3b2c3f44d858411356b49a28a4643b6d1a6a092a5201030051a05fc84d531b5d250c23f4f886f6812f9fe3f402d61607f977b4ecd2701c19010000fd781529d58fc2523cf396a7f25440b409857e7e221766c57214b1d38c7b481f01010062f542f45ea3660f86c013ced80534cb5fd4c19d66c56e7e8c5d4bf2d40acc5e010100b121e91836fd7cd5102b654e9f72f3cf6fdbfd0b161c53a9c54b12c841126331020100000001cd4e4cac3c7b56920d1e7655e7e260d31f29d9a388d04910f1bbd72304a79029010000006b483045022100e75279a205a547c445719420aa3138bf14743e3f42618e5f86a19bde14bb95f7022064777d34776b05d816daf1699493fcdf2ef5a5ab1ad710d9c97bfb5b8f7cef3641210263e2dee22b1ddc5e11f6fab8bcd2378bdd19580d640501ea956ec0e786f93e76ffffffff013e660000000000001976a9146bfd5c7fbe21529d45803dbcf0c87dd3c71efbc288ac0000000001000100000001ac4e164f5bc16746bb0868404292ac8318bbac3800e4aad13a014da427adce3e000000006a47304402203a61a2e931612b4bda08d541cfb980885173b8dcf64a3471238ae7abcd368d6402204cbf24f04b9aa2256d8901f0ed97866603d2be8324c2bfb7a37bf8fc90edd5b441210263e2dee22b1ddc5e11f6fab8bcd2378bdd19580d640501ea956ec0e786f93e76ffffffff013c660000000000001976a9146bfd5c7fbe21529d45803dbcf0c87dd3c71efbc288ac0000000000'
+
+// You can create a Transaction from BEEF hex directly
+const tx = Transaction.fromHexBEEF(BEEFHex)
+
+// This ensures the BEEF structure is legitimate
+const verified = await tx.verify(gullibleHeadersClient)
+
+// 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.

package/docs/examples/EXAMPLE_VERIFYING_SPENDS.md

@@ -0,0 +1,69 @@
+# Example: Verifying Spends with Script Intrepreter
+
+The SDK comes with a script interpreter that allows you to verify the chain of spends within Bitcoin. When coins are spent from one transaction to another, the process is carried out between a particular output of the source transaction and a particular input of the spending transaction. The `Spend` class sets up the necessary contextual information for this process, and then evaluates the scripts to determine if the transfer is legitimate.
+
+This guide will walk you through the verification of a real spend, with real data. You can apply this code to your own transactions to ensure the transfer of coins from one state into the next is legitimate.
+
+## Pre-requisites
+
+We will need two transactions: a source transaction and a spending transaction, in order to set up the `Spend` context in which the transfer of coins occurs between them. When you construct an instance of the `Spend` class, you'll need to provide this information in the correct format. In a new file, let's set up som basic things we'll need:
+
+```typescript
+import { Spend, LockingScript, UnlockingScript } from '@bsv/sdk'
+
+const spend = new Spend({
+
+    // Replace with the TXID of the transaction where you are spending from
+    sourceTXID: '0000000000000000000000000000000000000000000000000000000000000000',
+
+    // Replace with the output index you are redeeming
+    sourceOutputIndex: 0,
+
+    // Replace with the number of satoshis in the output you are redeeming
+    sourceSatoshis: 1,
+
+    // Replace with the locking script you are spending
+    lockingScript: LockingScript.fromASM('OP_3 OP_ADD OP_7 OP_EQUAL'),
+
+    // Replace with the version of the new spending transaction
+    transactionVersion: 1,
+
+    // Other inputs from the spending transaction that are needed for verification.
+    // The SIGHASH flags used in signatures may not require this (if SIGHASH_ANYONECANPAY was used).
+    // This is an ordered array of TransactionInputs with the input whose script we're currently evaluating missing.
+    otherInputs: [],
+
+    // TransactionOutputs from the spending transaction that are needed for verification.
+    // The SIGHASH flags used in signatures may nnt require this (if SIGHASH_NONE was used).
+    // If SIGHASH_SINGLE is used, it's possible for this to be a sparse array, with only the index corresponding to
+    // the inputIndex populated.
+    outputs: [],
+
+    // This is the index of the input whose script we are currently evaluating.
+    inputIndex: 0,
+
+    // This is the unlocking script that we are evaluating, to see if it unlocks the source output.
+    unlockingScript: UnlockingScript.fromASM('OP_4'),
+
+    // This is the sequence number of the input whose script we are currently evaluating.
+    inputSequence: 0xffffffff,
+
+    // This is the lock time of the spending transaction.
+    lockTime: 0
+})
+```
+
+Once you've provided the context and constructed the Spend, you should have a new spend instance ready for verification.
+
+## Validating the Spend
+
+You can use the `validate()` method to run the scripts and validate the spend, as follows:
+
+```typescript
+const validated = spend.validate()
+// console.log(validated) => true
+```
+
+The result will be a boolean indicating the result of the script. If there is an error thrown, or if the boolean is false, the script is not valid. If the boolean is true, the spend is considered valid.
+
+Errors from the spend will contain useful information, such as the specific opcode and context in which the error occurred (in either the locking or unlocking script).

package/docs/examples/GETTING_STARTED_NODE_CJS.md

@@ -0,0 +1,73 @@
+# Getting Started with BSV SDK in NodeJS (CommonJS)
+
+Welcome to the BSV SDK! This guide is tailored for developers working in a NodeJS environment, specifically those who are using the CommonJS module system. We'll walk you through the installation process and show you how to get started with creating and signing a Bitcoin SV transaction using the SDK. Whether you're building on BSV for the first time or transitioning an existing project to use the SDK, this guide is for you.
+
+## Prerequisites
+
+Before we begin, make sure you have Node.js installed on your system. You can download and install Node.js from [nodejs.org](https://nodejs.org/). This guide assumes you have basic knowledge of JavaScript and the Node.js environment.
+
+## Installation
+
+First, you'll need to install the BSV SDK package in your project. Open your terminal, navigate to your project directory, and run the following command:
+
+```bash
+npm install @bsv/sdk
+```
+
+This command installs the BSV SDK in your project, making it ready for use. There are no external runtime dependencies.
+
+## Requiring the SDK
+
+To use the BSV SDK in a NodeJS project with CommonJS, you'll import modules using the `require` syntax. Here's how you set up a basic script to use the BSV SDK:
+
+1. Create a new JavaScript file in your project. For example, `index.js`.
+2. At the top of your file, require the SDK modules you plan to use. For instance:
+
+```javascript
+const { PrivateKey, P2PKH, Transaction, ARC } = require('@bsv/sdk');
+```
+
+## Creating and Signing a Transaction
+
+Now, let's create and sign a transaction. We'll follow the example provided in the README. This example demonstrates how to create a transaction from a source to a recipient, including calculating fees, signing the transaction, and broadcasting it to ARC.
+
+Copy and paste the following code into your `index.js` file below your `require` statement:
+
+```javascript
+const privKey = PrivateKey.fromWif('...')
+
+const sourceTransaction = Transaction.fromHex('...')
+
+const version = 1
+const input = {
+  sourceTransaction,
+  sourceOutputIndex: 0,
+  unlockingScriptTemplate: new P2PKH().unlock(privKey),
+}
+const output = {
+  lockingScript: new P2PKH().lock(privKey.toPublicKey().toHash()),
+  change: true
+}
+
+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))
+```
+
+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.
+
+## Running Your Script
+
+To run your script, simply execute the following command in your terminal:
+
+```bash
+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.

package/docs/examples/GETTING_STARTED_REACT.md

@@ -0,0 +1,121 @@
+Getting Started with BSV SDK using React and TypeScript
+=======================================================
+
+Welcome to the guide! This guide is designed for developers working in a React environment using TypeScript. We'll walk through the installation process and show you how to create and broadcast a Bitcoin SV transaction using the BSV SDK. Whether you're freshly starting on BSV or transitioning an existing project to use the SDK, this would be your go-to guide.
+
+Prerequisites
+-------------
+
+Ensure that you have Node.js installed on your system. You can download and install Node.js from [nodejs.org](https://nodejs.org/). Basic knowledge of JavaScript, React and TypeScript is recommended for this guide.
+
+Setting Up
+----------
+
+Begin by creating a new project using Create React App with the TypeScript template:
+
+```bash
+npx create-react-app my-bsv-app --template typescript
+cd my-bsv-app
+```
+
+Next, install the BSV SDK package in your project:
+
+```bash
+npm install @bsv/sdk
+```
+
+Writing the Component
+---------------------
+
+Let's now create a Button component that builds and broadcasts a transaction when clicked.
+
+1.  Create a new file in your project, such as `src/components/BsvButton.tsx`.
+2.  At the top of your component file, import the necessary modules from the BSV SDK:
+
+```
+import React from 'react';
+import { PrivateKey, Transaction, ARC, P2PKH } from '@bsv/sdk';
+```
+
+3.  Define a new component function, `BsvButton`, that handles the creation and broadcast of a transaction upon a button click:
+
+```typescript
+const BsvButton: React.FC = () => {
+  const handleClick = async () => {
+    const privKey = PrivateKey.fromWif('...')
+    const sourceTransaction = Transaction.fromHex('...') // your source transaction goes here
+
+    const version = 1
+    const input = {
+      sourceTransaction,
+      sourceOutputIndex: 0,
+      unlockingScriptTemplate: new P2PKH().unlock(privKey),
+    }
+    const output = {
+      lockingScript: new P2PKH().lock(privKey.toPublicKey().toHash()),
+      change: true
+    }
+
+    const tx = new Transaction(version, [input], [output])
+    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))
+  }
+
+  return (
+    <button onClick={handleClick}>
+      Create Transaction
+    </button>
+  );
+}
+```
+
+4.  Finally, export the `BsvButton` component:
+
+```typescript
+export default BsvButton;
+```
+
+Integrating into Application
+----------------------------
+
+Now, let's integrate our `BsvButton` component into our app:
+
+1.  Open `src/App.tsx`.
+2.  Delete all of its content and replace it with the following:
+
+```typescript
+import React from 'react';
+import BsvButton from './components/BsvButton';
+
+function App() {
+  return (
+    <div className="App">
+      <header className="App-header">
+        <BsvButton />
+      </header>
+    </div>
+  );
+}
+
+export default App;
+```
+
+Running the App
+---------------
+
+To run your application, just type the following command in your terminal:
+
+```bash
+npm run start
+```
+
+Now when you click the button, a transaction will be created, signed, and broadcast to the BSV network.
+
+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.