@bsv/sdk 1.1.24 → 1.1.26

package/docs/transaction.md

@@ -449,6 +449,9 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | |
 | --- |
 | [ARC](#class-arc) |
+| [Beef](#class-beef) |
+| [BeefParty](#class-beefparty) |
+| [BeefTx](#class-beeftx) |
 | [FetchHttpClient](#class-fetchhttpclient) |
 | [MerklePath](#class-merklepath) |
 | [NodejsHttpClient](#class-nodejshttpclient) |
@@ -836,6 +839,319 @@ Argument Details
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+### Class: BeefTx
+
+A single bitcoin transaction associated with a `Beef` validity proof set.
+
+Simple case is transaction data included directly, either as raw bytes or fully parsed data, or both.
+
+Supports 'known' transactions which are represented by just their txid.
+It is assumed that intended consumer of this beef already has validity proof for such a transaction,
+which they can merge if necessary to create a valid beef.
+
+```ts
+export default class BeefTx {
+    _bumpIndex?: number;
+    _tx?: Transaction;
+    _rawTx?: number[];
+    _txid?: string;
+    inputTxids: string[] = [];
+    degree: number = 0;
+    get bumpIndex(): number | undefined 
+    set bumpIndex(v: number | undefined) 
+    get hasProof(): boolean 
+    get isTxidOnly(): boolean 
+    get txid() 
+    get tx() 
+    get rawTx() 
+    constructor(tx: Transaction | number[] | string, bumpIndex?: number) 
+    toWriter(writer: Writer): void 
+    static fromReader(br: Reader): BeefTx 
+}
+```
+
+<details>
+
+<summary>Class BeefTx Details</summary>
+
+#### Constructor
+
+```ts
+constructor(tx: Transaction | number[] | string, bumpIndex?: number) 
+```
+
+Argument Details
+
++ **tx**
+  + If string, must be a valid txid. If `number[]` must be a valid serialized transaction.
++ **bumpIndex**
+  + If transaction already has a proof in the beef to which it will be added.
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+### Class: Beef
+
+```ts
+export class Beef {
+    bumps: MerklePath[] = [];
+    txs: BeefTx[] = [];
+    constructor() 
+    get version(): number 
+    findTxid(txid: string): BeefTx | undefined 
+    mergeBump(bump: MerklePath): number 
+    mergeRawTx(rawTx: number[], bumpIndex?: number): BeefTx 
+    mergeTransaction(tx: Transaction): BeefTx 
+    removeExistingTxid(txid: string) 
+    mergeTxidOnly(txid: string): BeefTx 
+    mergeBeefTx(btx: BeefTx): BeefTx 
+    mergeBeef(beef: number[] | Beef) 
+    isValid(allowTxidOnly?: boolean): boolean 
+    async verify(chainTracker: ChainTracker, allowTxidOnly?: boolean): Promise<boolean> 
+    toBinary(): number[] 
+    toHex(): string 
+    static fromReader(br: Reader): Beef 
+    static fromBinary(bin: number[]): Beef 
+    static fromString(s: string, enc?: "hex" | "utf8" | "base64"): Beef 
+    sortTxs(): string[] 
+    clone(): Beef 
+    trimKnownTxids(knownTxids: string[]) 
+    toLogString(): string 
+}
+```
+
+<details>
+
+<summary>Class Beef Details</summary>
+
+#### Method clone
+
+```ts
+clone(): Beef 
+```
+
+Returns
+
+a shallow copy of this beef
+
+#### Method findTxid
+
+```ts
+findTxid(txid: string): BeefTx | undefined 
+```
+
+Returns
+
+`BeefTx` in `txs` with `txid`.
+
+Argument Details
+
++ **txid**
+  + of `beefTx` to find
+
+#### Method fromBinary
+
+Constructs an instance of the Beef class based on the provided binary array
+
+```ts
+static fromBinary(bin: number[]): Beef 
+```
+
+Returns
+
+An instance of the Beef class constructed from the binary data
+
+Argument Details
+
++ **bin**
+  + The binary array from which to construct BEEF
+
+#### Method fromString
+
+Constructs an instance of the Beef class based on the provided string
+
+```ts
+static fromString(s: string, enc?: "hex" | "utf8" | "base64"): Beef 
+```
+
+Returns
+
+An instance of the Beef class constructed from the string
+
+Argument Details
+
++ **s**
+  + The string value from which to construct BEEF
++ **enc**
+  + The encoding of the string value from which BEEF should be constructed
+
+#### Method isValid
+
+Sorts `txs` and checks structural validity of beef.
+
+Does NOT verify merkle roots.
+
+Validity requirements:
+1. No 'known' txids, unless `allowTxidOnly` is true.
+2. All transactions have bumps or their inputs chain back to bumps (or are known).
+3. Order of transactions satisfies dependencies before dependents.
+4. No transactions with duplicate txids.
+
+```ts
+isValid(allowTxidOnly?: boolean): boolean 
+```
+
+Argument Details
+
++ **allowTxidOnly**
+  + optional. If true, transaction txid only is assumed valid
+
+#### Method mergeBump
+
+Merge a MerklePath that is assumed to be fully valid.
+
+```ts
+mergeBump(bump: MerklePath): number 
+```
+
+Returns
+
+index of merged bump
+
+#### Method mergeRawTx
+
+Merge a serialized transaction.
+
+Checks that a transaction with the same txid hasn't already been merged.
+
+Replaces existing transaction with same txid.
+
+```ts
+mergeRawTx(rawTx: number[], bumpIndex?: number): BeefTx 
+```
+
+Returns
+
+txid of rawTx
+
+Argument Details
+
++ **bumpIndex**
+  + Optional. If a number, must be valid index into bumps array.
+
+#### Method mergeTransaction
+
+Merge a `Transaction` and any referenced `merklePath` and `sourceTransaction`, recursifely.
+
+Replaces existing transaction with same txid.
+
+Attempts to match an existing bump to the new transaction.
+
+```ts
+mergeTransaction(tx: Transaction): BeefTx 
+```
+
+Returns
+
+txid of tx
+
+#### Method removeExistingTxid
+
+Removes an existing transaction from the BEEF, given its TXID
+
+```ts
+removeExistingTxid(txid: string) 
+```
+
+Argument Details
+
++ **txid**
+  + TXID of the transaction to remove
+
+#### Method sortTxs
+
+Sort the `txs` by input txid dependency order.
+
+```ts
+sortTxs(): string[] 
+```
+
+Returns
+
+array of input txids of unproven transactions that aren't included in txs.
+
+#### Method toBinary
+
+Returns a binary array representing the serialized BEEF
+
+```ts
+toBinary(): number[] 
+```
+
+Returns
+
+A binary array representing the BEEF
+
+#### Method toHex
+
+Returns a hex string representing the serialized BEEF
+
+```ts
+toHex(): string 
+```
+
+Returns
+
+A hex string representing the BEEF
+
+#### Method toLogString
+
+```ts
+toLogString(): string 
+```
+
+Returns
+
+Summary of `Beef` contents as multi-line string.
+
+#### Method trimKnownTxids
+
+Ensure that all the txids in `knownTxids` are txidOnly
+
+```ts
+trimKnownTxids(knownTxids: string[]) 
+```
+
+#### Method verify
+
+Sorts `txs` and confirms validity of transaction data contained in beef
+by validating structure of this beef and confirming computed merkle roots
+using `chainTracker`.
+
+Validity requirements:
+1. No 'known' txids, unless `allowTxidOnly` is true.
+2. All transactions have bumps or their inputs chain back to bumps (or are known).
+3. Order of transactions satisfies dependencies before dependents.
+4. No transactions with duplicate txids.
+
+```ts
+async verify(chainTracker: ChainTracker, allowTxidOnly?: boolean): Promise<boolean> 
+```
+
+Argument Details
+
++ **chainTracker**
+  + Used to verify computed merkle path roots for all bump txids.
++ **allowTxidOnly**
+  + optional. If true, transaction txid is assumed valid
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ### Class: Transaction
 
@@ -863,7 +1179,8 @@ export default class Transaction {
     lockTime: number;
     metadata: Record<string, any>;
     merklePath?: MerklePath;
-    static fromBEEF(beef: number[]): Transaction 
+    static fromBEEF(beef: number[], txid?: string): Transaction 
+    static fromAtomicBEEF(beef: number[]): Transaction 
     static fromEF(ef: number[]): Transaction 
     static parseScriptOffsets(bin: number[]): {
         inputs: Array<{
@@ -881,7 +1198,7 @@ export default class Transaction {
     static fromBinary(bin: number[]): Transaction 
     static fromHex(hex: string): Transaction 
     static fromHexEF(hex: string): Transaction 
-    static fromHexBEEF(hex: string): Transaction 
+    static fromHexBEEF(hex: string, txid?: string): Transaction 
     constructor(version: number = 1, inputs: TransactionInput[] = [], outputs: TransactionOutput[] = [], lockTime: number = 0, metadata: Record<string, any> = {}, merklePath?: MerklePath) 
     addInput(input: TransactionInput): void 
     addOutput(output: TransactionOutput): void 
@@ -895,12 +1212,14 @@ export default class Transaction {
     toHexEF(): string 
     toHex(): string 
     toHexBEEF(): string 
+    toHexAtomicBEEF(): string 
     hash(enc?: "hex"): number[] | string 
     id(): number[];
     id(enc: "hex"): string;
     id(enc?: "hex"): number[] | string 
     async verify(chainTracker: ChainTracker | "scripts only" = defaultChainTracker(), feeModel?: FeeModel): Promise<boolean> 
     toBEEF(): number[] 
+    toAtomicBEEF(): number[] 
 }
 ```
 
@@ -975,12 +1294,35 @@ amongst the change outputs
 
 TODO: Benford's law change distribution.
 
+#### Method fromAtomicBEEF
+
+Creates a new transaction from an Atomic BEEF (BRC-95) structure.
+Extracts the subject transaction and ensures that all transactions within the BEEF data
+are part of the dependency graph of the subject transaction.
+Throws errors if the Atomic BEEF data does not strictly adhere to the BRC-95 specification.
+
+```ts
+static fromAtomicBEEF(beef: number[]): Transaction 
+```
+
+Returns
+
+The subject transaction, linked to its associated inputs populated with merkle paths.
+
+Argument Details
+
++ **beef**
+  + A binary representation of an Atomic BEEF structure.
+
 #### Method fromBEEF
 
 Creates a new transaction, linked to its inputs and their associated merkle paths, from a BEEF (BRC-62) structure.
+Optionally, you can provide a specific TXID to retrieve a particular transaction from the BEEF data.
+If the TXID is provided but not found in the BEEF data, an error will be thrown.
+If no TXID is provided, the last transaction in the BEEF data is returned.
 
 ```ts
-static fromBEEF(beef: number[]): Transaction 
+static fromBEEF(beef: number[], txid?: string): Transaction 
 ```
 
 Returns
@@ -990,7 +1332,9 @@ An anchored transaction, linked to its associated inputs populated with merkle p
 Argument Details
 
 + **beef**
-  + A binary representation of a transaction in BEEF format.
+  + A binary representation of transactions in BEEF format.
++ **txid**
+  + Optional TXID of the transaction to retrieve from the BEEF data.
 
 #### Method fromBinary
 
@@ -1046,9 +1390,12 @@ Argument Details
 #### Method fromHexBEEF
 
 Creates a Transaction instance from a hexadecimal string encoded BEEF.
+Optionally, you can provide a specific TXID to retrieve a particular transaction from the BEEF data.
+If the TXID is provided but not found in the BEEF data, an error will be thrown.
+If no TXID is provided, the last transaction in the BEEF data is returned.
 
 ```ts
-static fromHexBEEF(hex: string): Transaction 
+static fromHexBEEF(hex: string, txid?: string): Transaction 
 ```
 
 Returns
@@ -1059,6 +1406,8 @@ Argument Details
 
 + **hex**
   + The hexadecimal string representation of the transaction BEEF.
++ **txid**
+  + Optional TXID of the transaction to retrieve from the BEEF data.
 
 #### Method fromHexEF
 
@@ -1196,6 +1545,21 @@ Signs a transaction, hydrating all its unlocking scripts based on the provided s
 async sign(): Promise<void> 
 ```
 
+#### Method toAtomicBEEF
+
+Serializes this transaction and its inputs into the Atomic BEEF (BRC-95) format.
+The Atomic BEEF format starts with a 4-byte prefix `0x01010101`, followed by the TXID of the subject transaction,
+and then the BEEF data containing only the subject transaction and its dependencies.
+This format ensures that the BEEF structure is atomic and contains no unrelated transactions.
+
+```ts
+toAtomicBEEF(): number[] 
+```
+
+Returns
+
+- The serialized Atomic BEEF structure.
+
 #### 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.
@@ -1244,6 +1608,18 @@ Returns
 
 - The hexadecimal string representation of the transaction.
 
+#### Method toHexAtomicBEEF
+
+Converts the transaction to a hexadecimal string Atomic BEEF.
+
+```ts
+toHexAtomicBEEF(): string 
+```
+
+Returns
+
+- The hexadecimal string representation of the transaction Atomic BEEF.
+
 #### Method toHexBEEF
 
 Converts the transaction to a hexadecimal string BEEF.
@@ -1308,6 +1684,119 @@ tx.verify(new WhatsOnChain(), new SatoshisPerKilobyte(1))
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+### Class: BeefParty
+
+Extends `Beef` that is used to exchange transaction validity data with more than one external party.
+
+Use `addKnownTxidsForParty` to keep track of who knows what to reduce re-transmission of potentially large transactions.
+
+Use `getTrimmedBeefForParty` to obtain a `Beef` trimmed of transaction validity data known to a specific party.
+
+Typical usage scenario:
+
+1. Query a wallet storage provider for spendable outputs.
+2. The provider replies with a Beef validating the returned outputs.
+3. Construct a new transaction using some of the queried outputs as inputs, including Beef validating all the inputs.
+4. Receive new valid raw transaction after processing and Beef validating change outputs added to original inputs.
+5. Return to step 1, continuing to build on old and new spendable outputs.
+
+By default, each Beef is required to be complete and valid: All transactions appear as full serialized bitcoin transactions and
+each transaction either has a merkle path proof (it has been mined) or all of its input transactions are included.
+
+The size and redundancy of these Beefs becomes a problem when chained transaction creation out-paces the block mining rate.
+
+```ts
+export class BeefParty extends Beef {
+    knownTo: Record<string, Record<string, boolean>> = {};
+    constructor(parties?: string[]) 
+    isParty(party: string) 
+    addParty(party: string) 
+    getKnownTxidsForParty(party: string): string[] 
+    getTrimmedBeefForParty(party: string): Beef 
+    addKnownTxidsForParty(party: string, knownTxids: string[]) 
+}
+```
+
+<details>
+
+<summary>Class BeefParty Details</summary>
+
+#### Constructor
+
+```ts
+constructor(parties?: string[]) 
+```
+
+Argument Details
+
++ **parties**
+  + Optional array of initial unique party identifiers.
+
+#### Property knownTo
+
+keys are party identifiers.
+values are records of txids with truthy value for which the party already has validity proof.
+
+```ts
+knownTo: Record<string, Record<string, boolean>> = {}
+```
+
+#### Method addKnownTxidsForParty
+
+Make note of additional txids "known" to `party`.
+
+```ts
+addKnownTxidsForParty(party: string, knownTxids: string[]) 
+```
+
+Argument Details
+
++ **party**
+  + unique identifier, added if new.
+
+#### Method addParty
+
+Adds a new unique party identifier to this `BeefParty`.
+
+```ts
+addParty(party: string) 
+```
+
+#### Method getKnownTxidsForParty
+
+```ts
+getKnownTxidsForParty(party: string): string[] 
+```
+
+Returns
+
+Array of txids "known" to `party`.
+
+#### Method getTrimmedBeefForParty
+
+```ts
+getTrimmedBeefForParty(party: string): Beef 
+```
+
+Returns
+
+trimmed beef of unknown transactions and proofs for `party`
+
+#### Method isParty
+
+```ts
+isParty(party: string) 
+```
+
+Returns
+
+`true` if `party` has already beed added to this `BeefParty`.
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ## Functions
 
@@ -1423,3 +1912,40 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ## Variables
 
+| |
+| --- |
+| [BEEF_MAGIC](#variable-beef_magic) |
+| [BEEF_MAGIC_TXID_ONLY_EXTENSION](#variable-beef_magic_txid_only_extension) |
+| [BEEF_MAGIC_V2](#variable-beef_magic_v2) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+### Variable: BEEF_MAGIC
+
+```ts
+BEEF_MAGIC = 4022206465
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+### Variable: BEEF_MAGIC_V2
+
+```ts
+BEEF_MAGIC_V2 = 4022206466
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+### Variable: BEEF_MAGIC_TXID_ONLY_EXTENSION
+
+```ts
+BEEF_MAGIC_TXID_ONLY_EXTENSION = 4022206465
+```
+
+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.24",
+  "version": "1.1.26",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/totp/totp.ts

@@ -106,7 +106,7 @@ function generateHOTP (
   options: Required<TOTPOptions>
 ): string {
   const timePad = new BigNumber(counter).toArray('be', 8)
-  console.log({ timePad })
+  //console.log({ timePad })
   const hmac = calcHMAC(secret, timePad, options.algorithm)
   const signature = hmac.digest()