@caravan/psbt 2.0.7 → 2.1.0

package/README.md

@@ -28,6 +28,7 @@ A set of utilities for working with PSBTs.
       - [`public addPartialSig`](#public-addpartialsig)
       - [`public removePartialSig`](#public-removepartialsig)
       - [`public setProprietaryValue`](#public-setproprietaryvalue)
+      - [`public combine`](#public-combine)
       - [`static PsbtV2.FromV0`](#static-psbtv2fromv0)
     - [`function getPsbtVersionNumber`](#function-getpsbtversionnumber)
 - [Concepts](#concepts)
@@ -197,6 +198,23 @@ Args:
 
 From the provided args, a key with the following format will be generated: `0xFC<compact uint identifier length><bytes identifier><bytes subtype><bytes subkeydata>`
 
+##### `public combine`
+
+Combines multiple PSBTs into this PsbtV2. This implements the Combiner role as defined in [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#user-content-Roles).
+
+Args:
+
+- `psbts` - An array of `PsbtV2` instances to combine into this PSBT.
+
+Before combining, this method validates that:
+1. This PsbtV2 is ready for the Combiner role (`isReadyForCombiner` returns `true`).
+2. Each PSBT in the provided array is also ready for the Combiner role.
+3. All PSBTs represent the same unsigned transaction. This is determined by comparing transaction IDs after setting all input sequence numbers to 0 (per [BIP 370](https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#unique-identification) unique identification rules).
+
+When combining, later PSBTs in the array take precedence over earlier ones. The combination merges all global, input, and output map key-value pairs. This operation is atomic—if any error occurs during combination, the original state is preserved.
+
+**Warning:** This method could potentially produce a PSBT in a bad state. For example, if a later PSBT has an input sequence without a signature, it could potentially invalidate signatures existing on this or earlier PSBTs in the list if the sequence numbers do not agree.
+
 ##### `static PsbtV2.FromV0`
 
 Attempts to return a `PsbtV2` by converting from a PSBTv0 string or Buffer

package/dist/index.d.ts

@@ -69,6 +69,21 @@ declare abstract class PsbtV2Maps {
     copy(to: PsbtV2Maps): void;
     private copyMaps;
     private copyMap;
+    /**
+     * For a given map, set the value to the given key if the value is not empty.
+     * This overrides the value at that key as long as the value will not be
+     * empty.
+     */
+    private combineValue;
+    private validateCombineMaps;
+    /**
+     * Combines the maps in the provided PsbtV2Maps object into this one. Using
+     * this without validation may produce a PSBT in an invalid state.
+     *
+     * This operation is atomic - if any error occurs, the original state is
+     * preserved.
+     */
+    protected combineMaps(from: PsbtV2Maps): void;
 }
 
 /**
@@ -408,6 +423,23 @@ declare class PsbtV2 extends PsbtV2Maps {
      * Updates the PSBT_GLOBAL_OUTPUT_COUNT field in the global map.
      */
     private updateGlobalOutputCount;
+    /**
+     * Validates this PsbtV2 and the one it's being combined with are ready for
+     * the Combiner role. Also, the calculated unsigned transaction IDs of the two
+     * must be the same.
+     */
+    private validateCombine;
+    /**
+     * Combines multiple PsbtV2 objects into this one with the latest index taking
+     * precedence over earlier indices of the provided list. This action is
+     * atomic.
+     *
+     * WARNING: This method could potentially produce a PSBT in an bad state. For
+     * example, if a later PSBT has an input sequence without a signature, it
+     * could potentially invalidate signatures existing on this or earlier PSBTs
+     * in the list if the sequence numbers do not agree.
+     */
+    combine(psbts: PsbtV2[]): void;
 }
 
 interface PsbtInput {

package/dist/index.js

@@ -295,6 +295,63 @@ var PsbtV2Maps = class {
   copyMap(from, to) {
     from.forEach((v, k) => to.set(k, Buffer.from(v)));
   }
+  /**
+   * For a given map, set the value to the given key if the value is not empty.
+   * This overrides the value at that key as long as the value will not be
+   * empty.
+   */
+  combineValue(map, value, toKey) {
+    if (value && value.length > 0) {
+      map.set(toKey, value);
+    }
+  }
+  validateCombineMaps(from) {
+    if (from.inputMaps.length !== this.inputMaps.length) {
+      throw new Error(
+        `Cannot combine PSBTs with different input counts: this has ${this.inputMaps.length}, other has ${from.inputMaps.length}`
+      );
+    }
+    if (from.outputMaps.length !== this.outputMaps.length) {
+      throw new Error(
+        `Cannot combine PSBTs with different output counts: this has ${this.outputMaps.length}, other has ${from.outputMaps.length}`
+      );
+    }
+  }
+  /**
+   * Combines the maps in the provided PsbtV2Maps object into this one. Using
+   * this without validation may produce a PSBT in an invalid state.
+   *
+   * This operation is atomic - if any error occurs, the original state is
+   * preserved.
+   */
+  combineMaps(from) {
+    this.validateCombineMaps(from);
+    const newGlobalMap = new Map(this.globalMap);
+    const newInputMaps = this.inputMaps.map((m) => new Map(m));
+    const newOutputMaps = this.outputMaps.map((m) => new Map(m));
+    for (const [key, value] of from.globalMap) {
+      this.combineValue(newGlobalMap, value, key);
+    }
+    for (let i = 0; i < from.inputMaps.length; i++) {
+      if (!newInputMaps[i]) {
+        newInputMaps[i] = /* @__PURE__ */ new Map();
+      }
+      for (const [key, value] of from.inputMaps[i]) {
+        this.combineValue(newInputMaps[i], value, key);
+      }
+    }
+    for (let i = 0; i < from.outputMaps.length; i++) {
+      if (!newOutputMaps[i]) {
+        newOutputMaps[i] = /* @__PURE__ */ new Map();
+      }
+      for (const [key, value] of from.outputMaps[i]) {
+        this.combineValue(newOutputMaps[i], value, key);
+      }
+    }
+    this.globalMap = newGlobalMap;
+    this.inputMaps = newInputMaps;
+    this.outputMaps = newOutputMaps;
+  }
 };
 var PsbtConversionMaps = class extends PsbtV2Maps {
   /**
@@ -375,6 +432,29 @@ var PsbtConversionMaps = class extends PsbtV2Maps {
       this.v0delete(outputMap, "04" /* PSBT_OUT_SCRIPT */);
     }
   };
+  getTransactionId() {
+    const txBuf = this.buildUnsignedTx();
+    try {
+      return import_bitcoinjs_lib_v6.Transaction.fromBuffer(txBuf).getId();
+    } catch (e) {
+      const numInputs = this.inputMaps.length;
+      const numOutputs = this.outputMaps.length;
+      if (numInputs === 0 && numOutputs === 1) {
+        console.error(
+          `Cannot compute transaction ID for PSBT with 0 inputs and 1 output. The serialized transaction (${txBuf.toString("hex")}) is ambiguous with SegWit format and cannot be parsed.`
+        );
+        throw new Error(
+          "Cannot compute transaction ID: PSBT has 0 inputs and 1 output, which produces an ambiguous transaction format. "
+        );
+      }
+      console.error(
+        `Failed to parse transaction buffer: ${txBuf.toString("hex")}`
+      );
+      throw new Error(
+        `Failed to compute transaction ID (${numInputs} inputs, ${numOutputs} outputs): ${e instanceof Error ? e.message : e}`
+      );
+    }
+  }
 };
 
 // src/psbtv2/psbtv2.ts
@@ -961,9 +1041,9 @@ var PsbtV2 = class _PsbtV2 extends PsbtV2Maps {
    *   https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki
    */
   setInputSequence(inputIndex, sequence) {
-    if (!this.isReadyForUpdater) {
+    if (!this.isReadyForUpdater && !this.isReadyForCombiner) {
       throw new Error(
-        "PSBT is not ready for the Updater role. Sequence cannot be changed."
+        "PSBT is not ready for the Updater or Combiner role. Sequence cannot be changed."
       );
     }
     if (inputIndex < 0 || inputIndex >= this.PSBT_GLOBAL_INPUT_COUNT) {
@@ -1454,6 +1534,67 @@ var PsbtV2 = class _PsbtV2 extends PsbtV2Maps {
     bw.writeU8(this.outputMaps.length);
     this.globalMap.set("05" /* PSBT_GLOBAL_OUTPUT_COUNT */, bw.render());
   }
+  /**
+   * Validates this PsbtV2 and the one it's being combined with are ready for
+   * the Combiner role. Also, the calculated unsigned transaction IDs of the two
+   * must be the same.
+   */
+  validateCombine(psbt) {
+    if (!this.isReadyForCombiner) {
+      throw Error("This PsbtV2 is not ready for Combiner role.");
+    }
+    if (!psbt.isReadyForCombiner) {
+      throw Error("Provided PsbtV2 is not ready for Combiner role.");
+    }
+    const tempThis = new _PsbtV2(this.serialize(), true);
+    const tempOther = new _PsbtV2(psbt.serialize(), true);
+    for (const [index, sequence] of tempThis.PSBT_IN_SEQUENCE.entries()) {
+      if (sequence !== 0) {
+        tempThis.setInputSequence(index, 0);
+      }
+    }
+    for (const [index, sequence] of tempOther.PSBT_IN_SEQUENCE.entries()) {
+      if (sequence !== 0) {
+        tempOther.setInputSequence(index, 0);
+      }
+    }
+    const checkThis = new PsbtConversionMaps(tempThis.serialize());
+    const checkOther = new PsbtConversionMaps(tempOther.serialize());
+    if (checkThis.getTransactionId() !== checkOther.getTransactionId()) {
+      throw Error("Cannot combine PSBTs for different unsigned transactions.");
+    }
+    for (const [index, sequence] of this.PSBT_IN_SEQUENCE.entries()) {
+      const otherSequence = psbt.PSBT_IN_SEQUENCE[index];
+      if (otherSequence !== sequence && this.PSBT_IN_PARTIAL_SIG[index].some((sig) => sig !== null)) {
+        console.warn(
+          `Combined PSBT updated sequence on signed input ${index}. This may invalidate the existing signature.`
+        );
+      }
+    }
+  }
+  /**
+   * Combines multiple PsbtV2 objects into this one with the latest index taking
+   * precedence over earlier indices of the provided list. This action is
+   * atomic.
+   *
+   * WARNING: This method could potentially produce a PSBT in an bad state. For
+   * example, if a later PSBT has an input sequence without a signature, it
+   * could potentially invalidate signatures existing on this or earlier PSBTs
+   * in the list if the sequence numbers do not agree.
+   */
+  combine(psbts) {
+    for (const psbt of psbts) {
+      this.validateCombine(psbt);
+    }
+    try {
+      for (const psbt of psbts) {
+        this.combineMaps(psbt);
+      }
+    } catch (error) {
+      console.error(error);
+      throw Error("Failed to combine PSBTs.");
+    }
+  }
 };
 
 // src/psbtv0/psbt.ts

package/dist/index.mjs

@@ -248,6 +248,63 @@ var PsbtV2Maps = class {
   copyMap(from, to) {
     from.forEach((v, k) => to.set(k, Buffer.from(v)));
   }
+  /**
+   * For a given map, set the value to the given key if the value is not empty.
+   * This overrides the value at that key as long as the value will not be
+   * empty.
+   */
+  combineValue(map, value, toKey) {
+    if (value && value.length > 0) {
+      map.set(toKey, value);
+    }
+  }
+  validateCombineMaps(from) {
+    if (from.inputMaps.length !== this.inputMaps.length) {
+      throw new Error(
+        `Cannot combine PSBTs with different input counts: this has ${this.inputMaps.length}, other has ${from.inputMaps.length}`
+      );
+    }
+    if (from.outputMaps.length !== this.outputMaps.length) {
+      throw new Error(
+        `Cannot combine PSBTs with different output counts: this has ${this.outputMaps.length}, other has ${from.outputMaps.length}`
+      );
+    }
+  }
+  /**
+   * Combines the maps in the provided PsbtV2Maps object into this one. Using
+   * this without validation may produce a PSBT in an invalid state.
+   *
+   * This operation is atomic - if any error occurs, the original state is
+   * preserved.
+   */
+  combineMaps(from) {
+    this.validateCombineMaps(from);
+    const newGlobalMap = new Map(this.globalMap);
+    const newInputMaps = this.inputMaps.map((m) => new Map(m));
+    const newOutputMaps = this.outputMaps.map((m) => new Map(m));
+    for (const [key, value] of from.globalMap) {
+      this.combineValue(newGlobalMap, value, key);
+    }
+    for (let i = 0; i < from.inputMaps.length; i++) {
+      if (!newInputMaps[i]) {
+        newInputMaps[i] = /* @__PURE__ */ new Map();
+      }
+      for (const [key, value] of from.inputMaps[i]) {
+        this.combineValue(newInputMaps[i], value, key);
+      }
+    }
+    for (let i = 0; i < from.outputMaps.length; i++) {
+      if (!newOutputMaps[i]) {
+        newOutputMaps[i] = /* @__PURE__ */ new Map();
+      }
+      for (const [key, value] of from.outputMaps[i]) {
+        this.combineValue(newOutputMaps[i], value, key);
+      }
+    }
+    this.globalMap = newGlobalMap;
+    this.inputMaps = newInputMaps;
+    this.outputMaps = newOutputMaps;
+  }
 };
 var PsbtConversionMaps = class extends PsbtV2Maps {
   /**
@@ -328,6 +385,29 @@ var PsbtConversionMaps = class extends PsbtV2Maps {
       this.v0delete(outputMap, "04" /* PSBT_OUT_SCRIPT */);
     }
   };
+  getTransactionId() {
+    const txBuf = this.buildUnsignedTx();
+    try {
+      return Transaction.fromBuffer(txBuf).getId();
+    } catch (e) {
+      const numInputs = this.inputMaps.length;
+      const numOutputs = this.outputMaps.length;
+      if (numInputs === 0 && numOutputs === 1) {
+        console.error(
+          `Cannot compute transaction ID for PSBT with 0 inputs and 1 output. The serialized transaction (${txBuf.toString("hex")}) is ambiguous with SegWit format and cannot be parsed.`
+        );
+        throw new Error(
+          "Cannot compute transaction ID: PSBT has 0 inputs and 1 output, which produces an ambiguous transaction format. "
+        );
+      }
+      console.error(
+        `Failed to parse transaction buffer: ${txBuf.toString("hex")}`
+      );
+      throw new Error(
+        `Failed to compute transaction ID (${numInputs} inputs, ${numOutputs} outputs): ${e instanceof Error ? e.message : e}`
+      );
+    }
+  }
 };
 
 // src/psbtv2/psbtv2.ts
@@ -914,9 +994,9 @@ var PsbtV2 = class _PsbtV2 extends PsbtV2Maps {
    *   https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki
    */
   setInputSequence(inputIndex, sequence) {
-    if (!this.isReadyForUpdater) {
+    if (!this.isReadyForUpdater && !this.isReadyForCombiner) {
       throw new Error(
-        "PSBT is not ready for the Updater role. Sequence cannot be changed."
+        "PSBT is not ready for the Updater or Combiner role. Sequence cannot be changed."
       );
     }
     if (inputIndex < 0 || inputIndex >= this.PSBT_GLOBAL_INPUT_COUNT) {
@@ -1407,6 +1487,67 @@ var PsbtV2 = class _PsbtV2 extends PsbtV2Maps {
     bw.writeU8(this.outputMaps.length);
     this.globalMap.set("05" /* PSBT_GLOBAL_OUTPUT_COUNT */, bw.render());
   }
+  /**
+   * Validates this PsbtV2 and the one it's being combined with are ready for
+   * the Combiner role. Also, the calculated unsigned transaction IDs of the two
+   * must be the same.
+   */
+  validateCombine(psbt) {
+    if (!this.isReadyForCombiner) {
+      throw Error("This PsbtV2 is not ready for Combiner role.");
+    }
+    if (!psbt.isReadyForCombiner) {
+      throw Error("Provided PsbtV2 is not ready for Combiner role.");
+    }
+    const tempThis = new _PsbtV2(this.serialize(), true);
+    const tempOther = new _PsbtV2(psbt.serialize(), true);
+    for (const [index, sequence] of tempThis.PSBT_IN_SEQUENCE.entries()) {
+      if (sequence !== 0) {
+        tempThis.setInputSequence(index, 0);
+      }
+    }
+    for (const [index, sequence] of tempOther.PSBT_IN_SEQUENCE.entries()) {
+      if (sequence !== 0) {
+        tempOther.setInputSequence(index, 0);
+      }
+    }
+    const checkThis = new PsbtConversionMaps(tempThis.serialize());
+    const checkOther = new PsbtConversionMaps(tempOther.serialize());
+    if (checkThis.getTransactionId() !== checkOther.getTransactionId()) {
+      throw Error("Cannot combine PSBTs for different unsigned transactions.");
+    }
+    for (const [index, sequence] of this.PSBT_IN_SEQUENCE.entries()) {
+      const otherSequence = psbt.PSBT_IN_SEQUENCE[index];
+      if (otherSequence !== sequence && this.PSBT_IN_PARTIAL_SIG[index].some((sig) => sig !== null)) {
+        console.warn(
+          `Combined PSBT updated sequence on signed input ${index}. This may invalidate the existing signature.`
+        );
+      }
+    }
+  }
+  /**
+   * Combines multiple PsbtV2 objects into this one with the latest index taking
+   * precedence over earlier indices of the provided list. This action is
+   * atomic.
+   *
+   * WARNING: This method could potentially produce a PSBT in an bad state. For
+   * example, if a later PSBT has an input sequence without a signature, it
+   * could potentially invalidate signatures existing on this or earlier PSBTs
+   * in the list if the sequence numbers do not agree.
+   */
+  combine(psbts) {
+    for (const psbt of psbts) {
+      this.validateCombine(psbt);
+    }
+    try {
+      for (const psbt of psbts) {
+        this.combineMaps(psbt);
+      }
+    } catch (error) {
+      console.error(error);
+      throw Error("Failed to combine PSBTs.");
+    }
+  }
 };
 
 // src/psbtv0/psbt.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caravan/psbt",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "typescript library for working with PSBTs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -66,6 +66,11 @@
     "typescript": "^5.3.3"
   },
   "peerDependencies": {
-    "@caravan/bitcoin": "0.4.4"
+    "@caravan/bitcoin": "0.4.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caravan-bitcoin/caravan",
+    "directory": "packages/caravan-psbt"
   }
 }