@bsv/sdk 1.1.29 → 1.1.32

package/docs/primitives.md

@@ -8,15 +8,16 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | | | |
 | --- | --- | --- |
-| [BasePoint](#class-basepoint) | [Point](#class-point) | [SHA1HMAC](#class-sha1hmac) |
-| [BigNumber](#class-bignumber) | [PointInFiniteField](#class-pointinfinitefield) | [SHA256](#class-sha256) |
-| [Curve](#class-curve) | [Polynomial](#class-polynomial) | [SHA256HMAC](#class-sha256hmac) |
-| [DRBG](#class-drbg) | [PrivateKey](#class-privatekey) | [SHA512](#class-sha512) |
-| [JacobianPoint](#class-jacobianpoint) | [PublicKey](#class-publickey) | [SHA512HMAC](#class-sha512hmac) |
-| [K256](#class-k256) | [RIPEMD160](#class-ripemd160) | [Signature](#class-signature) |
-| [KeyShares](#class-keyshares) | [Reader](#class-reader) | [SymmetricKey](#class-symmetrickey) |
-| [Mersenne](#class-mersenne) | [ReductionContext](#class-reductioncontext) | [TransactionSignature](#class-transactionsignature) |
-| [MontgomoryMethod](#class-montgomorymethod) | [SHA1](#class-sha1) | [Writer](#class-writer) |
+| [BasePoint](#class-basepoint) | [PointInFiniteField](#class-pointinfinitefield) | [SHA256HMAC](#class-sha256hmac) |
+| [BigNumber](#class-bignumber) | [Polynomial](#class-polynomial) | [SHA512](#class-sha512) |
+| [Curve](#class-curve) | [PrivateKey](#class-privatekey) | [SHA512HMAC](#class-sha512hmac) |
+| [DRBG](#class-drbg) | [PublicKey](#class-publickey) | [Schnorr](#class-schnorr) |
+| [JacobianPoint](#class-jacobianpoint) | [RIPEMD160](#class-ripemd160) | [Signature](#class-signature) |
+| [K256](#class-k256) | [Reader](#class-reader) | [SymmetricKey](#class-symmetrickey) |
+| [KeyShares](#class-keyshares) | [ReductionContext](#class-reductioncontext) | [TransactionSignature](#class-transactionsignature) |
+| [Mersenne](#class-mersenne) | [SHA1](#class-sha1) | [Writer](#class-writer) |
+| [MontgomoryMethod](#class-montgomorymethod) | [SHA1HMAC](#class-sha1hmac) |  |
+| [Point](#class-point) | [SHA256](#class-sha256) |  |
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
@@ -7349,6 +7350,116 @@ public hasLowS(): boolean
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+### Class: Schnorr
+
+Class representing the Schnorr Zero-Knowledge Proof (ZKP) protocol.
+
+This class provides methods to generate and verify proofs that demonstrate knowledge of a secret without revealing it.
+Specifically, it allows one party to prove to another that they know the private key corresponding to a public key
+and have correctly computed a shared secret, without disclosing the private key itself.
+
+The protocol involves two main methods:
+- `generateProof`: Generates a proof linking a public key `A` and a shared secret `S`, proving knowledge of the corresponding private key `a`.
+- `verifyProof`: Verifies the provided proof, ensuring its validity without revealing any secret information.
+
+The class utilizes elliptic curve cryptography (ECC) and the SHA-256 hash function to compute challenges within the proof.
+
+Example
+
+```typescript
+const schnorr = new Schnorr();
+const a = PrivateKey.fromRandom(); // Prover's private key
+const A = a.toPublicKey();         // Prover's public key
+const b = PrivateKey.fromRandom(); // Other party's private key
+const B = b.toPublicKey();         // Other party's public key
+const S = B.mul(a);                // Shared secret
+
+// Prover generates the proof
+const proof = schnorr.generateProof(a, A, B, S);
+
+// Verifier verifies the proof
+const isValid = schnorr.verifyProof(A.point, B.point, S.point, proof);
+console.log(`Proof is valid: ${isValid}`);
+```
+```ts
+export default class Schnorr {
+    constructor() 
+    generateProof(aArg: PrivateKey, AArg: PublicKey, BArg: PublicKey, S: Point): {
+        R: Point;
+        SPrime: Point;
+        z: BigNumber;
+    } 
+    verifyProof(A: Point, B: Point, S: Point, proof: {
+        R: Point;
+        SPrime: Point;
+        z: BigNumber;
+    }): boolean 
+}
+```
+
+<details>
+
+<summary>Class Schnorr Details</summary>
+
+#### Method generateProof
+
+Generates a proof that demonstrates the link between public key A and shared secret S
+
+```ts
+generateProof(aArg: PrivateKey, AArg: PublicKey, BArg: PublicKey, S: Point): {
+    R: Point;
+    SPrime: Point;
+    z: BigNumber;
+} 
+```
+
+Returns
+
+Proof (R, S', z)
+
+Argument Details
+
++ **a**
+  + Private key corresponding to public key A
++ **A**
+  + Public key
++ **B**
+  + Other party's public key
++ **S**
+  + Shared secret
+
+#### Method verifyProof
+
+Verifies the proof of the link between public key A and shared secret S
+
+```ts
+verifyProof(A: Point, B: Point, S: Point, proof: {
+    R: Point;
+    SPrime: Point;
+    z: BigNumber;
+}): boolean 
+```
+
+Returns
+
+True if the proof is valid, false otherwise
+
+Argument Details
+
++ **A**
+  + Public key
++ **B**
+  + Other party's public key
++ **S**
+  + Shared secret
++ **proof**
+  + Proof (R, S', z)
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ## Functions
 

package/docs/transaction.md

@@ -857,7 +857,7 @@ export default class BeefTx {
     _rawTx?: number[];
     _txid?: string;
     inputTxids: string[] = [];
-    degree: number = 0;
+    isValid?: boolean = undefined;
     get bumpIndex(): number | undefined 
     set bumpIndex(v: number | undefined) 
     get hasProof(): boolean 
@@ -888,6 +888,16 @@ Argument Details
 + **bumpIndex**
   + If transaction already has a proof in the beef to which it will be added.
 
+#### Property isValid
+
+true if `hasProof` or all inputs chain to `hasProof`.
+
+Typically set by sorting transactions by proven dependency chains.
+
+```ts
+isValid?: boolean = undefined
+```
+
 </details>
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -900,9 +910,13 @@ export class Beef {
     bumps: MerklePath[] = [];
     txs: BeefTx[] = [];
     version: BeefVersion = undefined;
+    atomicTxid: string | undefined = undefined;
     constructor(version?: BeefVersion) 
     get magic(): number 
     findTxid(txid: string): BeefTx | undefined 
+    findBump(txid: string): MerklePath | undefined 
+    findTransactionForSigning(txid: string): Transaction | undefined 
+    findAtomicTransaction(txid: string): Transaction | undefined 
     mergeBump(bump: MerklePath): number 
     mergeRawTx(rawTx: number[], bumpIndex?: number): BeefTx 
     mergeTransaction(tx: Transaction): BeefTx 
@@ -917,9 +931,16 @@ export class Beef {
     static fromReader(br: Reader): Beef 
     static fromBinary(bin: number[]): Beef 
     static fromString(s: string, enc?: "hex" | "utf8" | "base64"): Beef 
-    sortTxs(): string[] 
+    sortTxs(): {
+        missingInputs: string[];
+        notValid: string[];
+        valid: string[];
+        withMissingInputs: string[];
+        txidOnly: string[];
+    } 
     clone(): Beef 
     trimKnownTxids(knownTxids: string[]) 
+    getValidTxids(): string[] 
     toLogString(): string 
 }
 ```
@@ -938,6 +959,55 @@ Returns
 
 a shallow copy of this beef
 
+#### Method findAtomicTransaction
+
+Builds the proof tree rooted at a specific `Transaction`.
+
+To succeed, the Beef must contain all the required transaction and merkle path data.
+
+```ts
+findAtomicTransaction(txid: string): Transaction | undefined 
+```
+
+Returns
+
+Transaction with input `SourceTransaction` and `MerklePath` populated from this Beef.
+
+Argument Details
+
++ **txid**
+  + The id of the target transaction.
+
+#### Method findBump
+
+```ts
+findBump(txid: string): MerklePath | undefined 
+```
+
+Returns
+
+`MerklePath` with level zero hash equal to txid or undefined.
+
+#### Method findTransactionForSigning
+
+Finds a Transaction in this `Beef`
+and adds any missing input SourceTransactions from this `Beef`.
+
+The result is suitable for signing.
+
+```ts
+findTransactionForSigning(txid: string): Transaction | undefined 
+```
+
+Returns
+
+Transaction with all available input `SourceTransaction`s from this Beef.
+
+Argument Details
+
++ **txid**
+  + The id of the target transaction.
+
 #### Method findTxid
 
 ```ts
@@ -989,6 +1059,16 @@ Argument Details
 + **enc**
   + The encoding of the string value from which BEEF should be constructed
 
+#### Method getValidTxids
+
+```ts
+getValidTxids(): string[] 
+```
+
+Returns
+
+array of transaction txids that either have a proof or whose inputs chain back to a proven transaction.
+
 #### Method isValid
 
 Sorts `txs` and checks structural validity of beef.
@@ -1074,15 +1154,26 @@ Argument Details
 
 #### Method sortTxs
 
-Sort the `txs` by input txid dependency order.
+Sort the `txs` by input txid dependency order:
+- Oldest Tx Anchored by Path
+- Newer Txs depending on Older parents
+- Newest Tx
+
+with proof (MerklePath) last, longest chain of dependencies first
 
 ```ts
-sortTxs(): string[] 
+sortTxs(): {
+    missingInputs: string[];
+    notValid: string[];
+    valid: string[];
+    withMissingInputs: string[];
+    txidOnly: string[];
+} 
 ```
 
 Returns
 
-array of input txids of unproven transactions that aren't included in txs.
+`{ missingInputs, notValid, valid, withMissingInputs }`
 
 #### Method toBinary
 
@@ -1219,8 +1310,8 @@ export default class Transaction {
     id(enc: "hex"): string;
     id(enc?: "hex"): number[] | string 
     async verify(chainTracker: ChainTracker | "scripts only" = defaultChainTracker(), feeModel?: FeeModel): Promise<boolean> 
-    toBEEF(): number[] 
-    toAtomicBEEF(): number[] 
+    toBEEF(allowPartial?: boolean): number[] 
+    toAtomicBEEF(allowPartial?: boolean): number[] 
 }
 ```
 
@@ -1554,25 +1645,43 @@ and then the BEEF data containing only the subject transaction and its dependenc
 This format ensures that the BEEF structure is atomic and contains no unrelated transactions.
 
 ```ts
-toAtomicBEEF(): number[] 
+toAtomicBEEF(allowPartial?: boolean): number[] 
 ```
 
 Returns
 
 - The serialized Atomic BEEF structure.
 
+Argument Details
+
++ **allowPartial**
+  + If true, error will not be thrown if there are any missing sourceTransactions.
+
+Throws
+
+Error if there are any missing sourceTransactions unless `allowPartial` is true.
+
 #### Method toBEEF
 
 Serializes this transaction, together with its inputs and the respective merkle proofs, into the BEEF (BRC-62) format. This enables efficient verification of its compliance with the rules of SPV.
 
 ```ts
-toBEEF(): number[] 
+toBEEF(allowPartial?: boolean): number[] 
 ```
 
 Returns
 
 The serialized BEEF structure
 
+Argument Details
+
++ **allowPartial**
+  + If true, error will not be thrown if there are any missing sourceTransactions.
+
+Throws
+
+Error if there are any missing sourceTransactions unless `allowPartial` is true.
+
 #### Method toBinary
 
 Converts the transaction to a binary array format.
@@ -1716,6 +1825,7 @@ export class BeefParty extends Beef {
     getKnownTxidsForParty(party: string): string[] 
     getTrimmedBeefForParty(party: string): Beef 
     addKnownTxidsForParty(party: string, knownTxids: string[]) 
+    mergeBeefFromParty(party: string, beef: number[] | Beef) 
 }
 ```
 
@@ -1794,6 +1904,18 @@ Returns
 
 `true` if `party` has already beed added to this `BeefParty`.
 
+#### Method mergeBeefFromParty
+
+Merge a `beef` received from a specific `party`.
+
+Updates this `BeefParty` to track all the txids
+corresponding to transactions for which `party`
+has raw transaction and validity proof data.
+
+```ts
+mergeBeefFromParty(party: string, beef: number[] | Beef) 
+```
+
 </details>
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -1925,6 +2047,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [ATOMIC_BEEF](#variable-atomic_beef) |
 | [BEEF_MAGIC](#variable-beef_magic) |
 | [BEEF_MAGIC_TXID_ONLY_EXTENSION](#variable-beef_magic_txid_only_extension) |
 | [BEEF_MAGIC_V2](#variable-beef_magic_v2) |
@@ -1960,3 +2083,12 @@ BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
+### Variable: ATOMIC_BEEF
+
+```ts
+ATOMIC_BEEF = 16843009
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---

package/package.json

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

package/src/primitives/Schnorr.ts

@@ -0,0 +1,95 @@
+import BigNumber from './BigNumber.js'
+import Curve from './Curve.js'
+import Point from './Point.js'
+import { sha256 } from './Hash.js'
+import { PrivateKey, PublicKey } from './index.js'
+
+/**
+ * Class representing the Schnorr Zero-Knowledge Proof (ZKP) protocol.
+ *
+ * This class provides methods to generate and verify proofs that demonstrate knowledge of a secret without revealing it.
+ * Specifically, it allows one party to prove to another that they know the private key corresponding to a public key
+ * and have correctly computed a shared secret, without disclosing the private key itself.
+ *
+ * The protocol involves two main methods:
+ * - `generateProof`: Generates a proof linking a public key `A` and a shared secret `S`, proving knowledge of the corresponding private key `a`.
+ * - `verifyProof`: Verifies the provided proof, ensuring its validity without revealing any secret information.
+ *
+ * The class utilizes elliptic curve cryptography (ECC) and the SHA-256 hash function to compute challenges within the proof.
+ *
+ * @example
+ * ```typescript
+ * const schnorr = new Schnorr();
+ * const a = PrivateKey.fromRandom(); // Prover's private key
+ * const A = a.toPublicKey();         // Prover's public key
+ * const b = PrivateKey.fromRandom(); // Other party's private key
+ * const B = b.toPublicKey();         // Other party's public key
+ * const S = B.mul(a);                // Shared secret
+ *
+ * // Prover generates the proof
+ * const proof = schnorr.generateProof(a, A, B, S);
+ *
+ * // Verifier verifies the proof
+ * const isValid = schnorr.verifyProof(A.point, B.point, S.point, proof);
+ * console.log(`Proof is valid: ${isValid}`);
+ * ```
+ */
+export default class Schnorr {
+  private readonly curve: Curve
+
+  constructor () {
+    this.curve = new Curve()
+  }
+
+  /**
+     * Generates a proof that demonstrates the link between public key A and shared secret S
+     * @param a Private key corresponding to public key A
+     * @param A Public key
+     * @param B Other party's public key
+     * @param S Shared secret
+     * @returns Proof (R, S', z)
+     */
+  generateProof (aArg: PrivateKey, AArg: PublicKey, BArg: PublicKey, S: Point): { R: Point, SPrime: Point, z: BigNumber } {
+    const r = PrivateKey.fromRandom()
+    const R = r.toPublicKey()
+    const SPrime = BArg.mul(r)
+    const e = this.computeChallenge(AArg, BArg, S, SPrime, R)
+    const z = r.add(e.mul(aArg)).umod(this.curve.n)
+    return { R, SPrime, z }
+  }
+
+  /**
+     * Verifies the proof of the link between public key A and shared secret S
+     * @param A Public key
+     * @param B Other party's public key
+     * @param S Shared secret
+     * @param proof Proof (R, S', z)
+     * @returns True if the proof is valid, false otherwise
+     */
+  verifyProof (A: Point, B: Point, S: Point, proof: { R: Point, SPrime: Point, z: BigNumber }): boolean {
+    const { R, SPrime, z } = proof
+    const e = this.computeChallenge(A, B, S, SPrime, R)
+
+    // Check zG = R + eA
+    const zG = this.curve.g.mul(z)
+    const RpluseA = R.add(A.mul(e))
+    if (!zG.eq(RpluseA)) {
+      return false
+    }
+
+    // Check zB = S' + eS
+    const zB = B.mul(z)
+    const SprimeeS = SPrime.add(S.mul(e))
+    if (!zB.eq(SprimeeS)) {
+      return false
+    }
+
+    return true
+  }
+
+  private computeChallenge (A: Point, B: Point, S: Point, SPrime: Point, R: Point): BigNumber {
+    const message = [...A.encode(true), ...B.encode(true), ...S.encode(true), ...SPrime.encode(true), ...R.encode(true)] as number[]
+    const hash = sha256(message)
+    return new BigNumber(hash).umod(this.curve.n)
+  }
+}