@bsv/sdk 1.0.17 → 1.0.19

package/docs/concepts/README.md

@@ -0,0 +1,14 @@
+# Conceptual Topics
+
+These documents cover high-level conceptual information that will augment developers' understanding of the code-level SDK documentation:
+
+- [What is BEEF and why is it useful?](BEEF.md)
+- [What is a Transaction Signature?](TX_SIG.md)
+- [What is Type-42 and How Does it Enable Private Signatures?](./42.md)
+- [What are Script Templates Used for?](TEMPLATES.md)
+- [How are Transactions Built with Inputs and Outputs?](HOW_TX.md)
+- [The Role of Chain Trackers within the SPV Ecosystem](CHAIN_SPV.md)
+- [How Does Transaction Fee Modeling Work?](FEE.md)
+- [How are Bitcoin Transactions Validated?](TX_VALID.md)
+- [Opcodes and Their Functionality Within Bitcoin Script](OP.md)
+- [What are Hashes and Why are they Important in Bitcoin?](HASHES.md)

package/docs/concepts/TEMPLATES.md

@@ -0,0 +1,42 @@
+# What are Script Templates Used for?
+
+Script templates play a critical role in facilitating the creation and management of scripts that control the locking and unlocking of UTXOs (transaction outputs or tokens in BSV). These scripts are integral to implementing the various transaction protocols on the blockchain, adhering to Bitcoin's original vision while enhancing security, scalability, and efficiency.
+
+## The Role of Scripts in BSV
+
+Scripts are pieces of code that define the conditions under which funds can be spent on the blockchain. Every transaction on the BSV network includes two kinds of scripts:
+- **Locking Scripts**: These scripts set conditions under which coins can be spent. They are included in the output of a transaction.
+- **Unlocking Scripts**: These scripts satisfy the conditions set by the locking scripts to spend the funds in a subsequent transaction. They are found in the input of a transaction.
+
+The purpose of these scripts is to ensure that only authorized parties can access and transact the funds by meeting predefined conditions, which may include providing a digital signature or solving a computational challenge. Any conceivable set of constraints can be programmed into a locking script.
+
+## Concept of Script Templates
+
+A script template is a predefined framework that simplifies the process of creating otherwise-potentially-complex locking and unlocking scripts. It abstracts away the underlying script construction details, allowing developers to create scripts without having to write low-level code for every new scenario. The template provides methods and properties to generate scripts dynamically based on the transaction context and the specific input parameters provided.
+
+### Components of a Script Template
+A script template generally includes the following:
+
+1. **Lock Method**: This method generates a locking script based on given parameters, such as a public key hash or other conditions defined by the transaction type (e.g., P2PKH—Pay to Public Key Hash).
+
+2. **Unlock Method**: This method creates an unlocking script, which usually involves generating a digital signature and potentially other data required to unlock the funds according to the locking script's conditions.
+
+3. **Estimate Length**: This utility provides an estimation of the unlocking script's length, which can be crucial for transaction fee calculation.
+
+## Importance of Script Templates
+
+### Simplification and Standardization
+Script templates standardize the creation of scripts, ensuring consistency and reducing errors in script generation. They provide a high-level interface for commonly used script patterns, like P2PKH, reducing the need for repetitive, error-prone coding.
+
+### Security Enhancements
+By abstracting the details of script creation, script templates help in minimizing security risks associated with manual script handling. Robust templates can ensure that scripts are generated in a secure manner, adhering to the necessary cryptographic standards and best practices. Templates can also be audited for increased security, which will benefit everyone who relies upon it.
+
+### Scalability and Efficiency
+Script templates enable developers to quickly implement and deploy blockchain solutions on a large scale. They reduce the complexity involved in script creation, allowing developers to focus on building applications rather than dealing with the intricacies of script coding.
+
+### Flexibility
+Templates are designed to be flexible and extensible, accommodating various transaction types and conditions without significant modifications to the underlying codebase. This flexibility is crucial for adapting to evolving use cases and requirements in the BSV ecosystem.
+
+## Conclusion
+
+Script templates are fundamental tools within the BSV SDK that streamline the development of on-chain use-cases by providing robust, secure, and efficient methods for handling transaction scripts. They encapsulate the complexity of script creation and ensure that developers can focus on higher-level application logic, thereby accelerating the development process and enhancing the capabilities of their implementations. To get started with script templates in the TypeScript SDK, [check out this tutorial!](../examples/EXAMPLE_SCRIPT_TEMPLATES.md)

package/docs/concepts/TX_SIG.md

@@ -0,0 +1,34 @@
+# What are Transaction Signatures?
+
+Transaction signatures play a crucial role in securing transactions and establishing trust between parties. These digital signatures serve as a powerful tool for validating the authenticity and integrity of spends on the blockchain. This document delves into the concept of transaction signatures, breaking down their components, functionality, and significance in a way that's (hopefully) accessible to a fairly broad audience.
+
+## Introduction to Digital Signatures
+
+Before diving into transaction signatures, it's essential to understand the basics of digital signatures. A digital signature is akin to a fingerprint; it is a unique mark that an individual can use to sign digital documents or transactions. Just as a handwritten signature authenticates the identity of the signer and their consent to the document's terms, a digital signature ensures that a digital document or transaction is authentic and hasn't been tampered with after the signature was made.
+
+## Components of Transaction Signatures
+
+Transaction signatures in BSV are a special type of digital signature. They consist of several key components:
+
+- **r and s values**: These two values constitute the core of the ECDSA (Elliptic Curve Digital Signature Algorithm) signature. They are derived from the private key of the sender and the transaction data. Together, they verify that the owner of the corresponding public key has authorized the transaction.
+- **SIGHASH flags**: Transaction signatures also include SIGHASH flags, which specify how much of the transaction data is covered by the signature. These flags allow signers to control which parts of the transaction they are committing to when they sign it, and which ones might be updated later.
+
+## Understanding SIGHASH Flags
+
+SIGHASH flags provide flexibility in how transactions are signed, offering several options:
+
+- **SIGHASH_ALL**: This is the default mode, where the signature covers all the inputs and outputs of the transaction. It indicates the signer's commitment to the exact details of the transaction, including the amount and script associated with each output.
+- **SIGHASH_NONE**: With this flag, the signature covers all inputs but no outputs, allowing others to add or modify outputs. This could be used in scenarios where the signer is indifferent to where the funds are going.
+- **SIGHASH_SINGLE**: This mode signs only one input and one output, the one with the same index as the signed input. It is useful for transactions with multiple participants, allowing each to sign only for their part.
+- **SIGHASH_ANYONECANPAY**: This flag can be combined with the others and indicates that the signature covers only the current input, allowing others to add more inputs to the transaction.
+
+## The Role of Transaction Signatures
+
+Transaction signatures serve two primary purposes on the BSV network:
+
+1. **Authentication**: By signing a transaction with their private key, the sender proves they hold the private keys needed by the locking script that secures the funds they're attempting to spend.
+2. **Integrity**: Once a transaction is signed, any alteration to the parts that were signed would invalidate the signature. This property ensures that once a transaction is broadcasted to the network, it cannot be tampered with or altered by malicious actors.
+
+## Conclusion
+
+Transaction signatures are at the heart of the security and trust model of blockchain technology. They enable the secure transfer of digital assets between parties without the need for a central authority. By understanding the components and functionality of transaction signatures, users and developers can better appreciate the sophisticated mechanisms that keep the BSV network secure and trustworthy. You can learn more about how transaction signatures work within the TypeScript BSV SDK [here](../low-level/TX_SIG.md).

package/docs/concepts/TX_VALID.md

@@ -0,0 +1,35 @@
+# How are Bitcoin Transactions Validated?
+
+Understanding the intricacies of Bitcoin transaction validation is crucial for developers building systems that receive and process them within the ecosystem. This document will delve into the foundational concepts surrounding Bitcoin transactions, peer-to-peer exchange, and Simplified Payment Verification (SPV), as well as the critical validation processes that underpin the BSV network's scaling model.
+
+## Introduction
+
+Bitcoin transactions are the lifeblood of the network, enabling the transfer of value between participants without the need for central intermediaries. Each transaction on the Bitcoin SV blockchain is verified through a series of cryptographic checks and balances that ensure its authenticity and compliance with network rules.
+
+### Key Concepts
+
+- **Transactions:** These are data structures that encode the transfer of value between participants in the network.
+- **Peer-to-Peer Exchange:** Direct interaction between participants' wallets without the need for a central authority, in which transactions and associated merkle proofs are sent back and forth.
+- **SPV (Simplified Payment Verification):** A method for validating transactions that does not require downloading the entire blockchain, facilitating more scalable applications.
+
+## The Transaction Validation Process
+
+Validating a Bitcoin transaction involves several critical steps that confirm its legitimacy and adherence to the rules set by the network. Here's a breakdown of the validation process:
+
+1. **Script Execution:**
+   - Each input in a transaction has an unlocking script that must successfully execute and validate against the locking script of the output it is spending.
+   - The result of this script execution must be true, indicating that the conditions to spend the output are met.
+
+2. **Transaction Outputs vs. Inputs:**
+   - The total value of outputs must not exceed the total value of inputs, ensuring that no new money is created out of thin air, except for the coinbase transaction, which includes the block reward.
+   - Check that the transaction includes enough fee to be included in a block, as miners prioritize transactions with higher fees.
+
+3. **Merkle Path Verifications:**
+   - Each input must be traceable back to a transaction included in a block, verified through a Merkle path.
+   - This ensures that each input used is legitimate and recognized by the network as having been previously confirmed.
+
+4. **Checking Locktime and Sequence:**
+   - Transactions may include locktime and sequence numbers that impose conditions on the earliest time or block height at which a transaction can be added to the blockchain.
+   - Proper handling of these parameters ensures that transactions are processed in a timely and orderly manner.
+
+You can check out an example using the TypeScript SDK where a transaction is verified according to these rules [here](../examples/EXAMPLE_VERIFYING_BEEF.md).

package/docs/script.md

@@ -31,7 +31,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export default interface ScriptTemplate {
-    lock: (...params: any) => LockingScript;
+    lock: (...params: any) => LockingScript | Promise<LockingScript>;
     unlock: (...params: any) => {
         sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
         estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>;
@@ -48,7 +48,7 @@ export default interface ScriptTemplate {
 Creates a locking script with the given parameters.
 
 ```ts
-lock: (...params: any) => LockingScript
+lock: (...params: any) => LockingScript | Promise<LockingScript>
 ```
 
 #### Property unlock

package/package.json

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

package/src/primitives/Signature.ts

@@ -282,8 +282,8 @@ export default class Signature {
       compactByte += 4
     }
     let arr = [compactByte]
-    arr = arr.concat(this.r.toArray())
-    arr = arr.concat(this.s.toArray())
+    arr = arr.concat(this.r.toArray('be', 32))
+    arr = arr.concat(this.s.toArray('be', 32))
     if (enc === 'hex') {
       return toHex(arr)
     } else if (enc === 'base64') {

package/src/script/ScriptTemplate.ts

@@ -13,9 +13,9 @@ export default interface ScriptTemplate {
    * Creates a locking script with the given parameters.
    *
    * @param {...any} params - The parameters required to create the locking script.
-   * @returns {LockingScript} - An instance of LockingScript.
+   * @returns {LockingScript} - An instance of LockingScript, or a Promise for one.
    */
-  lock: (...params: any) => LockingScript
+  lock: (...params: any) => LockingScript | Promise<LockingScript>
 
   /**
    * Creates a function that generates an unlocking script along with its signature and length estimation.
@@ -28,9 +28,9 @@ export default interface ScriptTemplate {
    * @returns {Object} - An object containing the `sign` and `estimateLength` functions.
    */
   unlock: (...params: any) =>
-  {
-    sign: (tx: Transaction, inputIndex: number) =>
-    Promise<UnlockingScript>
-    estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
-  }
+    {
+      sign: (tx: Transaction, inputIndex: number) =>
+        Promise<UnlockingScript>
+      estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>
+    }
 }