@bsv/sdk 1.0.9 → 1.0.11

package/docs/low-level/TYPE_42.md

@@ -0,0 +1,53 @@
+# Type 42 Key Derivation
+
+The BSV SDK supports type-42 key derivation, which is a way for two people who have master keys to derive child keys from one another, given a specific string called an invoice number. They can then use these keys for message signing, message encryption or any other purpose.
+
+This guide will cover the process of type-42 derivation, the steps involved, and then demonstrate a simple example of using it for message signing. Finally, we will talk about the "anyone key" and why it can sometimes be useful within type-42 systems.
+
+## The Process
+
+The process starts with two users, who each generate a "master key" from which everything else will be based. Then, they share the associated public key with the other party.
+
+Next, they make use of [ECDH](./ECDH.md) to arrive at a shared secret between themselves. They agree on the "invoice number" they will be using to communicate. We call it an invoice number because type-42 has historically been used for Bitcoin payments. In reality, this is just the unique identifier for the keys to derive.
+
+Now, they compute an [HMAC](./USING_HASHES_AND_HMACS.md) over the invoice number, using the shared secret as the HMAC key. Because the shared secret is private, the HMAC hash function initialized with its value is only usable by the two parties. This means only these two people can hash the invoice number in this unique way.
+
+Finally, the output of the HMAC function over the invoice number is used for key derivation. If Alice wants to derive a key from Bob, she will add this HMAC output to Bob's master public key. Conversely, if Bob wants to derive his own private key to match, he can add the same vlue to his original master private key.
+
+Every invoice number leads to a unique, privately-derivable key in a "shared key universe" occupied only by Alice and Bob. Alice can derive public keys for Bob, and Bob can derive the corresponding private keys. Conversely, Bob can derive public keys for Alice, and Alice can derive the corresponding private keys. They just need to agree on the right invoice number to use, and know each other's master public keys.
+
+Because no one else can compute a shared secret between these two values, no one else can use the special HMAC function over the invoice numbers, and thus no one else can link the master keys of either party to any other party.
+
+## Practical Example
+
+Let's use the BSV SDK to create a practical example. Here, Alice and Bob will generate private keys. Then, Alice will sign a message privately for Bob to verify, using a specific invoice number. Finally, Bob will use the invoice number to deriv Alice's child signing public key, so he can verify the message that Alice signed for him:
+
+```ts
+import { PrivateKey, Utils } from '@bsv/sdk'
+
+const alice = PrivateKey.fromRandom()
+const alicePub = alice.toPublicKey()
+
+const bob = PrivateKey.fromRandom()
+const bobPub = bob.toPublicKey()
+
+// Both parties agree on an invoice number to use
+const invoiceNumber = '2-simple signing protocol-1'
+
+// Alice derives a child private key for signing
+const aliceSigningChild = alice.deriveChild(bobPub, invoiceNumber)
+
+// Alice signs a message for Bob
+const message = Utils.toArray('Hi Bob', 'utf8')
+const signature = aliceSigningChild.sign(message)
+
+// Bob derives Alice's correct signing public key from her master public key
+const aliceSigningPub = alicePub.deriveChild(bob, invoiceNumber)
+
+// Now, Bob can privately verify Alice's signature
+const verified = aliceSigningPub.verify(message, signature)
+console.log(verified)
+// true
+```
+
+This enables people to securely agree on which keys to use, and derive keys for one another privately.

package/docs/low-level/USING_ECDSA.md

@@ -1,19 +1,30 @@
 # Low-level: Making Use of ECDSA with Public and Private Keys
 
-In this tutorial, we will learn how to use ECDSA with asymmetric public and private key pairs. Note, this is a low-level tutorial and should only be used if you would like to add advanced features to your applications. 
+In this tutorial, we will learn how to use ECDSA with asymmetric public and private key pairs. Note, this is a low-level tutorial and should only be used if the SDK's higher-level [Message Signing Capabilities](../examples/EXAMPLE_MESSAGE_SIGNING.md) do not meet your needs.
 
 ## Getting Started
 
-First, you will want to make sure you have installed the required dependencies.
+First, you'll need to import the `PrivateKey` function. We'll also import `utils` so we can represent our messages in human-readable formats.
 
 ```ts
 import { PrivateKey, Utils } from '@bsv/sdk'
 ```
 
+Now, let's generate a random private key and sign a message with it.
+
 ```ts
 const privateKey = PrivateKey.fromRandom()
 const message = Utils.toArray('Message to sign!')
+
+// The .sign() method creates an ECDSA digital signature for the message from the private key.
 const signature = privateKey.sign(message)
-const valid = privateKey.verify(message, signature)
+
+// Anyone with the corresponding public key can now verify the message.
+const publicKey = privateKey.toPublicKey()
+
+// The .verify() method is used for message verification
+const valid = publicKey.verify(message, signature)
 // console.log(valid) --> true
-```
+```
+
+Anyone who knows the public key can verify the message, even if they don't have the private key. You can sign Bitcoin transactions, documents, or any other type of information with ECDSA. Changing the message will invalidate the signature.

package/docs/low-level/USING_HASHES_AND_HMACS.md

@@ -0,0 +1,79 @@
+# Using Hashes and HMACs
+
+Hashes allow you to check the integrity of a message, by providing a deterministic one-way function that ransforms the input data. Hashes are widely useful, especially within Bitcoin. The BSV SDK provides first-class support for the hashing functions used within Bitcoin and its scripting language.
+
+In this tutorial, we will learn how to use hashes and HMACs (Hash-based Message Authentication Codes) to verify the integrity of information, ensuring it has not been changed.
+
+## Setting Up
+
+First, install the `@bsv/sdk` package into your project. We will be using two SDK modules for this exercise:
+
+- **Hash** - contains the hash and HMAC functions we will be using.
+- **Utils** - the SDK provides several helpful utility functions such as `toArray` and and `toUTF8` which allow you to encode and transform data as needed.
+
+```ts
+import { Hash, Utils } from '@bsv/sdk'
+```
+
+## Creating a Hash
+
+The following code performs a straightforward SHA256 hash of a message with the resulting hash returned as a hex string. 
+
+This is a one-way process where the input message is transformed into a fixed-size string (the hash), which acts as a unique representation of the input data. It's primarily used for verifying data integrity.
+
+```ts
+  let sha256Hasher = new Hash.SHA256()
+  sha256Hasher.update('Message to hash')
+  let hashedMessage = sha256Hasher.digestHex()
+  // console.log(hashedMessage)
+  // -> f1aa45b0f5f6703468f9b9bc2b9874d4fa6b001a170d0f132aa5a26d00d0c7e5
+```
+
+A binary hash can also be produced by using the `digest` function instead of `digestHex`.
+
+```ts
+  let hmacMessage = hmacHasher.digest()
+```
+
+Other hashing algorithms are also supported including the following:
+- `Hash.RIPEMD160`
+- `Hash.SHA1`
+- `Hash.SHA512`
+
+There are also shorthand helpers, which will construct the hashesr and digest the message automatically. For example, we can use the `hash.sha256` function as follows:
+
+```ts
+const result = Hash.sha256(toArray('hello, world', 'utf8'))
+```
+
+In addition to simple hashes, the library also support HMAC functions.
+
+## Creating an HMAC
+
+In comparison to standard hashing, the following code introduces HMAC which combines a secret key with the hashing process to provide both data integrity and authentication. 
+
+A key is involved in the hashing process, making the output hash specific not just to the message but also to the key. This means the same message hashed with a different key would produce a different result, adding a layer of security.
+
+```ts
+  let hmacHasher = new Hash.SHA256HMAC('key')
+  hmacHasher.update('Message to hash')
+  let hmacMessageHex = hmacHasher.digestHex()
+  // console.log
+  // -> 41495ec4a050f4059f20c8722b6308efe6e0a90a6a4886b02a31d22180db367c
+```
+
+Just as with hashes, a binary hmac message can also be produced by using the `digest` function instead of `digestHex`.
+
+```ts
+  let hmacMessage = hmacHasher.digest()
+```
+
+In addition to SHA256 based HMACs, `Hash.SHA512HMAC` is also supported which uses the SHA-512 cryptographic hash function.
+
+Just as with hashes, there are also shorthand helpers available for HMACs:
+
+```ts
+const result = Hash.sha256hmac('key', 'message')
+```
+
+This guide has explored the core concepts and practical applications of hashing and HMACs using the BSV SDK. Whether you're verifying the integrity of data, securing communications, or implementing authentication protocols, these tools will serve you well in your development journey.

package/docs/low-level/USING_PRIVATE_PUBLIC_KEYS.md

@@ -0,0 +1,70 @@
+# Generating, Serializing, and Deserializing Private and Public Keys
+
+Private keys protect Bitcoins, enable secure message signing, among other vital roles in the BSV ecosystem. Public keys enable ownership tracking, message attestation, and attribution for signed messages, among other use-cases. In this low-level tutorial, we will learn how to generate, serialize and deserialize public and private keys using the functions provided by the SDK.
+
+## Getting Set Up
+
+We'll be making use of two SDK modules in this guide. Make sure you've installed the `@bsv/sdk` package in your project, then import the modules we'll be using:
+
+- **PrivateKey** - this class will enable to you create a new PrivateKey from various sources such as random, hex string, and WIP. It can also transform a private key into a public key.
+- **Utils** - the SDK provides several helpful utility functions such as `toArray` and and `toUTF8` which allow you to serialize and deserialize data as needed.
+
+```ts
+import { PrivateKey, Utils } from '@bsv/sdk'
+```
+
+## Generating and Deserializing Keys
+First, we will learn how to generate new cryptographic keys to be used within your applications. Unless generating a new private key from random, this will most often involve deserializing a key from various types the most common being such as hex, WIF, and binary.
+
+Here is an example of how this can be done:
+
+```ts
+  const privKeyRandom = PrivateKey.fromRandom()
+  const privKeyFromHex = PrivateKey.fromHex('08dcced21ebf831cb1b1d320c5de2dee690ebea9b4930a7f1af9b7bde8f7858a')
+  const privKeyFromHex2 = PrivateKey.fromString('08dcced21ebf831cb1b1d320c5de2dee690ebea9b4930a7f1af9b7bde8f7858a', 'hex')
+  const privKeyFromWif = PrivateKey.fromWif('L3dyA911FSFwSpgzRFhncUTRPk57aNTHkEhRtXoi4W7fz63bR45W')
+  const privKeyFromBinary = new PrivateKey(Utils.toArray('e0f6f9084f02a59cdc0aa9498b28fe8e20d0d4eeeb19af629761099210990894', 'hex'))
+```
+
+We can then transform these to find the corresponding public key  as follows:
+
+```ts
+  const privKeyRandom = PrivateKey.fromRandom()
+  // Get the corresponding public key
+  let pubKey = privKeyRandom.toPublicKey()
+```
+
+## Serializing Keys
+
+Sometimes you will want to convert private / public keys into a format that can be more easily transported in your applications such as hex or binary.
+
+Let's explore the available functions the SDK provides.
+
+### Private Keys
+Serialize a private key into hex and binary:
+```ts
+  // Starting private key
+  const privKey = PrivateKey.fromRandom()
+
+  // Serialized formats
+  const privKeyHex = privKey.toHex()
+  const privKeyBinary = privKey.toArray()
+  const privKeyWif = privKey.toWif()
+```
+
+### Public Keys
+Public keys can be serialized as well, and include helper functions to serialize into common formats such as an address or DER.
+
+```ts
+  
+  const privateKey = PrivateKey.fromRandom()
+  const publicKey = privateKey.toPublicKey()
+  const publicKeyHex = publicKey.toString()
+  const publicKeyAddress = publicKey.toAddress()
+  const publicKeyDER = publicKey.toDER()
+
+  // Serialize a public key using function chaining
+  const publicKey = PrivateKey.fromRandom().toPublicKey().toString()
+```
+
+Now you should be able to manage cryptographic keys with the SDK, including generating, serializing, and deserializing both private and public keys. These skills are important for using low-level cryptographic keys, ensuring you have the necessary tools to leverage the security benefits they offer and to implement advanced cryptographic functions within your applications.

package/docs/low-level/USING_SCRIPTS.md

@@ -0,0 +1,71 @@
+# Serializing and Deserializing Bitcoin Scripts
+
+Bitcoin scripts are the mechanism by which coins are locked and unlocked. They define the constraints and rules that govern transfers, and are therefore instrumental in the functionality of Bitcoin.
+
+In this low-level tutorial, we will learn how to serialize and deserialize Bitcoin scripts within your applications using the functions provided by the SDK.
+
+First, you will want to make sure you have installed the `@bsv/sdk` library and imported the necessary modules for this tutorial:
+
+- **Script** - this class will enable to you create a Bitcoin Script from various sources.
+- **PrivateKey** - Used in the demo of creating a P2PKH locking script.
+- **P2PKH** - This class provides methods to create Pay To Public Key Hash locking and unlocking scripts.
+- **OP** - Bitcoin opcode map used in example scripts. 
+
+```ts
+import { Script, PrivateKey, P2PKH, OP } from '@bsv/sdk'
+```
+
+## Generating and Deserializing Scripts
+First, we will learn how to generate new Bitcoin scripts. This will usually involve deserializing a script from various types the most common being as hex, ASM, and binary.
+
+Here is an example of how this can be done:
+
+```ts
+  // From Hex
+  const buf: number[] = [OP.OP_TRUE]
+  const scriptFromHex = Script.fromHex(Utils.toHex([OP.OP_TRUE]))
+
+  // From ASM
+  const scriptFromASM = Script.fromASM('OP_DUP OP_HASH160 1451baa3aad777144a0759998a03538018dd7b4b OP_EQUALVERIFY OP_CHECKSIG')
+
+  // From Binary
+  const buf2 = [OP.OP_PUSHDATA1, 3, 1, 2, 3]
+  const scriptFromBinary = Script.fromBinary(buf)
+```
+
+For a more advanced example, the P2PKH class can be used to creating a locking script to a Public Key Hash as follows:
+
+```ts
+  const priv = PrivateKey.fromRandom()
+  const publicKeyHash = priv.toPublicKey().toHash()
+  const lockingScript = new P2PKH().lock(publicKeyHash).toASM()
+  // console.log(lockingScript)
+  // -> 'OP_DUP OP_HASH160 99829df6ad0df41a759811add7f233e268501ea9 OP_EQUALVERIFY OP_CHECKSIG'
+
+```
+
+## Serializing Scripts
+
+Sometimes you will want to convert Scripts into a format that can be more easily transported in your applications such as hex or binary.
+
+Let's explore the available functions the SDK provides.
+
+```ts
+  // Create initial script
+  const script = Script.fromASM('OP_DUP OP_HASH160 1451baa3aad777144a0759998a03538018dd7b4b OP_EQUALVERIFY OP_CHECKSIG')
+
+  // Serialize script
+  const scriptAsHex = script.toHex()
+  // console.log(scriptAsHex)
+  // -> 76a9141451baa3aad777144a0759998a03538018dd7b4b88ac
+
+  const scriptAsASM = script.toASM()
+  // console.log(scriptAsASM)
+  // -> 'OP_DUP OP_HASH160 1451baa3aad777144a0759998a03538018dd7b4b OP_EQUALVERIFY OP_CHECKSIG'
+
+  const scriptAsBinary = script.toBinary()
+  // console.log(scriptAsBinary)
+  // -> [118, 169, 20, ..., 172]
+```
+
+We've covered how to interpret scripts from formats like hex, ASM, and binary, as well as how to convert them back for efficient transmission or storage. You should now be equipped to manage Bitcoin scripts efficiently in your journey to develop Bitcoin-powered applications.

package/package.json

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

package/src/primitives/BigNumber.ts

@@ -552,15 +552,15 @@ export default class BigNumber {
   }
 
   /**
-   * The copy method creates and returns a separate identical copy of the BigNumber.
+   * The copy method copies the state of this BigNumber into an exsiting `dest` BigNumber.
    *
    * @method copy
-   * @param dest - The BigNumber instance that will be made into a copy.
+   * @param dest - The BigNumber instance that will be updated to become a copy.
    *
    * @example
    * const bn1 = new BigNumber('123456', 10, 'be');
    * const bn2 = new BigNumber();
-   * bn1.cop(bn2);
+   * bn1.copy(bn2);
    * // bn2 is now a BigNumber representing 123456
    */
   copy (dest: BigNumber): void {

package/src/primitives/PrivateKey.ts

@@ -75,6 +75,8 @@ export default class PrivateKey extends BigNumber {
    * @param base - The base of number provided. By default is 10. Ignored if number is BigNumber.
    *
    * @param endian - The endianness provided. By default is 'big endian'. Ignored if number is BigNumber.
+   * 
+   * @param modN - Optional. Default 'apply. If 'apply', apply modN to input to guarantee a valid PrivateKey. If 'error', if input is out of field throw Error('Input is out of field'). If 'nocheck', assumes input is in field.
    *
    * @example
    * import PrivateKey from './PrivateKey';
@@ -84,7 +86,8 @@ export default class PrivateKey extends BigNumber {
   constructor (
     number: BigNumber | number | string | number[] = 0,
     base: number | 'be' | 'le' | 'hex' = 10,
-    endian: 'be' | 'le' = 'be'
+    endian: 'be' | 'le' = 'be',
+    modN: 'apply' | 'nocheck' | 'error' = 'apply'
   ) {
     if (number instanceof BigNumber) {
       super()
@@ -92,6 +95,35 @@ export default class PrivateKey extends BigNumber {
     } else {
       super(number, base, endian)
     }
+
+    if (modN !== 'nocheck') {
+      const check = this.checkInField()
+      if (!check.inField) {
+        if (modN === 'error') {
+          throw new Error('Input is out of field') 
+        }
+        // Force the PrivateKey BigNumber value to lie in the field limited by curve.n
+        BigNumber.move(this, check.modN)
+      }
+    }
+  }
+
+  /**
+   * A utility function to check that the value of this PrivateKey lies in the field limited by curve.n
+   * @returns { inField, modN } where modN is this PrivateKey's current BigNumber value mod curve.n, and inField is true only if modN equals current BigNumber value.
+   */
+  checkInField() : { inField: boolean, modN: BigNumber } {
+    const curve = new Curve()
+    const modN = this.mod(curve.n)
+    const inField = this.cmp(modN) === 0
+    return { inField, modN }
+  }
+
+  /**
+   * @returns true if the PrivateKey's current BigNumber value lies in the field limited by curve.n
+   */
+  isValid() : boolean {
+    return this.checkInField().inField
   }
 
   /**
@@ -161,13 +193,17 @@ export default class PrivateKey extends BigNumber {
    * 
    * @param prefix defaults to [0x80] for mainnet, set it to [0xef] for testnet.
    * 
+   * @throws Error('Value is out of field') if current BigNumber value is out of field limited by curve.n
+   * 
    * @example
    * const privateKey = PrivateKey.fromRandom();
    * const wif = privateKey.toWif();
    * const testnetWif = privateKey.toWif([0xef]);
    */
   toWif (prefix : number[] = [0x80]): string {
-    return toBase58Check([...this.toArray(), 1], prefix)
+    if (!this.isValid())
+      throw new Error('Value is out of field')
+    return toBase58Check([...this.toArray("be", 32), 1], prefix)
   }
 
   /**

package/src/primitives/__tests/bug-31.test.ts

@@ -0,0 +1,33 @@
+//import { PrivateKey, PublicKey, Curve, Hash, BigNumber } from '..';
+import PublicKey from '../../../dist/cjs/src/primitives/PublicKey'
+//import { PrivateKey } from '..';
+import PrivateKey from '../../../dist/cjs/src/primitives/PrivateKey'
+import Curve from '../../../dist/cjs/src/primitives/Curve'
+import BigNumber from '../../../dist/cjs/src/primitives/BigNumber'
+
+describe("bug-31 tests", () => {
+
+    test("0", () => {
+        const c = new Curve()
+        const G = c.g
+        //const bn = new BigNumber(c.n + 12)
+        const bn = c.n.addn(12)
+        const sn = new BigNumber(12)
+        {
+            expect(() => new PrivateKey(bn.toHex(), 'hex', 'be', 'error')).toThrow("Input is out of field")
+        }
+        const o = PrivateKey.fromString(bn.toHex(), 'hex')
+        const os = PrivateKey.fromString(sn.toHex(), 'hex')
+        expect(o.cmp(os)).toBe(0)
+        const os2 = new PrivateKey(bn.toHex(), 'hex', 'be', 'nocheck')
+        expect(o.cmp(os2)).not.toBe(0)
+
+        const oWif = o.toWif()
+        expect(oWif).toBe('KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU79MFFcB1G')
+        const osWif = os.toWif()
+        expect(osWif).toBe('KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU79MFFcB1G')
+
+        expect(() => os2.toWif()).toThrow("Value is out of field")
+
+    })
+})

package/src/primitives/utils.ts

@@ -321,9 +321,12 @@ export class Writer {
   }
 
   toArray(): number[] {
-    const ret = []
+    let ret = []
     for (const x of this.bufs) {
-      ret.push(...x)
+      if (x.length < 65536)
+        ret.push(...x)
+      else
+        ret = ret.concat(x)
     }
     return ret
   }

package/docs/low-level/AES_SYMMETRIC_ENCRYPTION

@@ -1,44 +0,0 @@
-# Low-Level: Using AES for the Symmetric Encryption of Data
-
-The goal of this tutorial is to explore symmetric encryption of data using public and private keys with the Advanced Encryption Standard (AES). We will make use of the functions provided by this library in order to encrypt data with user held keys. 
-
-<img src="./images/symmetric_encryption_diagram.png" width="600" alt=""/>
-
-If you would like to learn more about AES encryption, here are some general resources that may help:
-
-- [AES - Wiki](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
-- [GCM - Wiki](https://en.wikipedia.org/wiki/Galois/Counter_Mode)
-
-
-Let's get started!
-
-## Getting Started
-
-First, you will want to make sure you have installed the required dependencies.
-
-```ts
-import { SymmetricKey, Utils } from '@bsv/sdk'
-```
-
-Next, we wil define the keys to be used and the data to encrypt. They encrypt function expects a parameter of type `number[]` so we will use the Utils `toArray` function to convert the UTF8 message to the correct type.
-
-```ts
-  const symmetricKey = SymmetricKey.fromRandom()
-  const messageToEncrypt: number[] = Utils.toArray('Hello Alice, this is Bob!', 'utf8')
-```
-
-### Encrypting and Decrypting
-
-When you encrypt a message, an initialization vector is prepended to the message to prevent potential key-reuse attacks. Conversely, when decrypting, the initialization vector that was initially added is spliced out and used in the AES-GSM decryption processes.
-
-We will use the `encrypt` and `decrypt` functions of the SymmetricKey class to transform the message.
-
-To parse out the text as a UTF8 string from a number array, we will use the Utils `toUTF8` function.
-```ts
-  const encryptedMessage = SymmetricKey.encrypt(messageToEncrypt)
-  const plaintext = SymmetricKey.decrypt(encryptedMessage) as number[]
-  const plaintextMessage = Utils.toUTF8(plaintext)
-  // console.log(plaintextMessage) --> 'Hello Alice, this is Bob!'
-```
-
-This is just a basic demonstration of symmetric encryption/decryption using the @bsv/sdk library, however the possibilities of what you can do are endless once you understand these fundamentals.