@caravan/psbt 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -1,34 +1,74 @@
 /**
- * The PsbtV2 class is intended to represent an easily modifiable and
- * serializable psbt of version 2 conforming to BIP0174. Getters exist for all
- * BIP-defined keytypes. Very few setters and modifier methods exist. As they
- * are added, they should enforce implied and documented rules and limitations.
- *
- * Defining BIPs:
- * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
- * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
+ * Hex encoded string containing `<keytype><keydata>`. A string is needed for
+ * Map.get() since it matches by identity. Most commonly, a `Key` only contains a
+ * keytype byte, however, some with keydata can allow for multiple unique keys
+ * of the same type.
  */
 type Key = string;
+/**
+ * Values can be of various different types or formats. Here we leave them as
+ * Buffers so that getters can decide how they should be formatted.
+ */
 type Value = Buffer;
 type NonUniqueKeyTypeValue = {
     key: string;
     value: string | null;
 };
+/**
+ * Provided to friendly-format the `PSBT_GLOBAL_TX_MODIFIABLE` bitmask from
+ * `PsbtV2.PSBT_GLOBAL_TX_MODIFIABLE` which returns
+ * `PsbtGlobalTxModifiableBits[]`.
+ */
 declare enum PsbtGlobalTxModifiableBits {
     INPUTS = "INPUTS",// 0b00000001
     OUTPUTS = "OUTPUTS",// 0b00000010
     SIGHASH_SINGLE = "SIGHASH_SINGLE"
 }
+
+/**
+ * Attempts to extract the version number as uint32LE from raw psbt regardless
+ * of psbt validity.
+ */
+declare function getPsbtVersionNumber(psbt: string | Buffer): number;
+
+/**
+ * This abstract class is provided for utility to allow for mapping, map
+ * copying, and serialization operations for psbts. This does almost no
+ * validation, so do not rely on it for ensuring a valid psbt.
+ */
 declare abstract class PsbtV2Maps {
     protected globalMap: Map<Key, Value>;
     protected inputMaps: Map<Key, Value>[];
     protected outputMaps: Map<Key, Value>[];
     constructor(psbt?: Buffer | string);
+    /**
+     * Return the current state of the psbt as a string in the specified format.
+     */
     serialize(format?: "base64" | "hex"): string;
+    /**
+     * Copies the maps in this PsbtV2 object to another PsbtV2 object.
+     *
+     * NOTE: This copy method is made available to achieve parity with the PSBT
+     * api required by `ledger-bitcoin` for creating merklized PSBTs. HOWEVER, it
+     * is not recommended to use this when avoidable as copying maps bypasses the
+     * validation defined in the constructor, so it could create a psbtv2 in an
+     * invalid psbt state. PsbtV2.serialize is preferable whenever possible.
+     */
     copy(to: PsbtV2): void;
     private copyMaps;
     private copyMap;
 }
+
+/**
+ * The PsbtV2 class is intended to represent an easily modifiable and
+ * serializable psbt of version 2 conforming to BIP0174. Getters exist for all
+ * BIP-defined keytypes. Very few setters and modifier methods exist. As they
+ * are added, they should enforce implied and documented rules and limitations.
+ *
+ * Defining BIPs:
+ * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
+ * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
+ */
 declare class PsbtV2 extends PsbtV2Maps {
     constructor(psbt?: Buffer | string);
     /**
@@ -92,12 +132,37 @@ declare class PsbtV2 extends PsbtV2Maps {
     /**
      * Other Getters/Setters
      */
+    /**
+     * Returns the `nLockTime` field for the psbt as if it were a bitcoin
+     * transaction.
+     */
     get nLockTime(): number | null;
     /**
      * Creator/Constructor Methods
      */
+    /**
+     * Ensures that global fields have initial values required by a PsbtV2
+     * Creator. It is called by the constructor if constructed without a psbt.
+     */
     private create;
+    /**
+     * Checks initial construction of any valid PsbtV2. It is called when a psbt
+     * is passed to the constructor or when a new psbt is being created. If
+     * constructed with a psbt, this method acts outside of the Creator role to
+     * validate the current state of the psbt.
+     */
     private validate;
+    /**
+     * This method is provided for compatibility issues and probably shouldn't be
+     * used since a PsbtV2 with PSBT_GLOBAL_TX_VERSION = 1 is BIP0370
+     * non-compliant. No guarantees can be made here that a serialized PsbtV2
+     * which used this method will be compatible with outside consumers.
+     *
+     * One may wish to instance this class from a partially signed PSBTv0 with a
+     * txn version 1 by using the static PsbtV2.FromV0. This method provides a way
+     * to override validation logic for the txn version and roles lifecycle
+     * defined for PsbtV2.
+     */
     dangerouslySetGlobalTxVersion1(): void;
     addGlobalXpub(xpub: Buffer, fingerprint: Buffer, path: string): void;
     addInput({ previousTxId, outputIndex, sequence, nonWitnessUtxo, witnessUtxo, redeemScript, witnessScript, bip32Derivation, }: {
@@ -131,20 +196,47 @@ declare class PsbtV2 extends PsbtV2Maps {
     /**
      * Updater/Signer Methods
      */
+    /**
+     * Removes an input-map from inputMaps.
+     */
     deleteInput(index: number): void;
+    /**
+     * Removes an output-map from outputMaps.
+     */
     deleteOutput(index: number): void;
+    /**
+     * Checks that provided flags are present in PSBT_GLOBAL_TX_MODIFIABLE.
+     */
     private isModifiable;
+    /**
+     * Adds a signature for an input. Validates that the input is mapped and does
+     * not already have a signature for the pubkey. Also validates for sighash.
+     * Other validation is incomplete. Also validates for required args in case
+     * typescript is not being used to call the method.
+     *
+     * The Signer, when it creates a signature, must add the partial sig keypair
+     * to the psbt for the input which it is signing. In the case that a
+     * particular signer does not, this method can be used to add a signature to
+     * the psbt. This method assumes the Signer did the validation outlined in
+     * BIP0174 before creating a signature.
+     * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#signer
+     */
     addPartialSig(inputIndex: number, pubkey: Buffer, sig: Buffer): void;
+    /**
+     * Removes all sigs for an input unless a pubkey is specified. Validates that
+     * the input exists. When providing a pubkey, this validates that a sig for
+     * the pubkey exists.
+     */
     removePartialSig(inputIndex: number, pubkey?: Buffer): void;
+    /**
+     * Ensures the PSBT is in the proper state when adding a partial sig keypair.
+     * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#signer
+     */
     private handleSighashType;
+    /**
+     * Attempts to return a PsbtV2 by converting from a PsbtV0 string or Buffer
+     */
     static FromV0(psbt: string | Buffer, allowTxnVersion1?: boolean): PsbtV2;
 }
-/**
- * Attempts to extract the version number as uint32LE from raw psbt regardless
- * of psbt validity.
- * @param {string | Buffer} psbt - hex, base64 or buffer of psbt
- * @returns {number} version number
- */
-declare function getPsbtVersionNumber(psbt: string | Buffer): number;
 
 export { PsbtV2, getPsbtVersionNumber };

package/dist/index.d.ts

@@ -1,34 +1,74 @@
 /**
- * The PsbtV2 class is intended to represent an easily modifiable and
- * serializable psbt of version 2 conforming to BIP0174. Getters exist for all
- * BIP-defined keytypes. Very few setters and modifier methods exist. As they
- * are added, they should enforce implied and documented rules and limitations.
- *
- * Defining BIPs:
- * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
- * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
+ * Hex encoded string containing `<keytype><keydata>`. A string is needed for
+ * Map.get() since it matches by identity. Most commonly, a `Key` only contains a
+ * keytype byte, however, some with keydata can allow for multiple unique keys
+ * of the same type.
  */
 type Key = string;
+/**
+ * Values can be of various different types or formats. Here we leave them as
+ * Buffers so that getters can decide how they should be formatted.
+ */
 type Value = Buffer;
 type NonUniqueKeyTypeValue = {
     key: string;
     value: string | null;
 };
+/**
+ * Provided to friendly-format the `PSBT_GLOBAL_TX_MODIFIABLE` bitmask from
+ * `PsbtV2.PSBT_GLOBAL_TX_MODIFIABLE` which returns
+ * `PsbtGlobalTxModifiableBits[]`.
+ */
 declare enum PsbtGlobalTxModifiableBits {
     INPUTS = "INPUTS",// 0b00000001
     OUTPUTS = "OUTPUTS",// 0b00000010
     SIGHASH_SINGLE = "SIGHASH_SINGLE"
 }
+
+/**
+ * Attempts to extract the version number as uint32LE from raw psbt regardless
+ * of psbt validity.
+ */
+declare function getPsbtVersionNumber(psbt: string | Buffer): number;
+
+/**
+ * This abstract class is provided for utility to allow for mapping, map
+ * copying, and serialization operations for psbts. This does almost no
+ * validation, so do not rely on it for ensuring a valid psbt.
+ */
 declare abstract class PsbtV2Maps {
     protected globalMap: Map<Key, Value>;
     protected inputMaps: Map<Key, Value>[];
     protected outputMaps: Map<Key, Value>[];
     constructor(psbt?: Buffer | string);
+    /**
+     * Return the current state of the psbt as a string in the specified format.
+     */
     serialize(format?: "base64" | "hex"): string;
+    /**
+     * Copies the maps in this PsbtV2 object to another PsbtV2 object.
+     *
+     * NOTE: This copy method is made available to achieve parity with the PSBT
+     * api required by `ledger-bitcoin` for creating merklized PSBTs. HOWEVER, it
+     * is not recommended to use this when avoidable as copying maps bypasses the
+     * validation defined in the constructor, so it could create a psbtv2 in an
+     * invalid psbt state. PsbtV2.serialize is preferable whenever possible.
+     */
     copy(to: PsbtV2): void;
     private copyMaps;
     private copyMap;
 }
+
+/**
+ * The PsbtV2 class is intended to represent an easily modifiable and
+ * serializable psbt of version 2 conforming to BIP0174. Getters exist for all
+ * BIP-defined keytypes. Very few setters and modifier methods exist. As they
+ * are added, they should enforce implied and documented rules and limitations.
+ *
+ * Defining BIPs:
+ * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
+ * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
+ */
 declare class PsbtV2 extends PsbtV2Maps {
     constructor(psbt?: Buffer | string);
     /**
@@ -92,12 +132,37 @@ declare class PsbtV2 extends PsbtV2Maps {
     /**
      * Other Getters/Setters
      */
+    /**
+     * Returns the `nLockTime` field for the psbt as if it were a bitcoin
+     * transaction.
+     */
     get nLockTime(): number | null;
     /**
      * Creator/Constructor Methods
      */
+    /**
+     * Ensures that global fields have initial values required by a PsbtV2
+     * Creator. It is called by the constructor if constructed without a psbt.
+     */
     private create;
+    /**
+     * Checks initial construction of any valid PsbtV2. It is called when a psbt
+     * is passed to the constructor or when a new psbt is being created. If
+     * constructed with a psbt, this method acts outside of the Creator role to
+     * validate the current state of the psbt.
+     */
     private validate;
+    /**
+     * This method is provided for compatibility issues and probably shouldn't be
+     * used since a PsbtV2 with PSBT_GLOBAL_TX_VERSION = 1 is BIP0370
+     * non-compliant. No guarantees can be made here that a serialized PsbtV2
+     * which used this method will be compatible with outside consumers.
+     *
+     * One may wish to instance this class from a partially signed PSBTv0 with a
+     * txn version 1 by using the static PsbtV2.FromV0. This method provides a way
+     * to override validation logic for the txn version and roles lifecycle
+     * defined for PsbtV2.
+     */
     dangerouslySetGlobalTxVersion1(): void;
     addGlobalXpub(xpub: Buffer, fingerprint: Buffer, path: string): void;
     addInput({ previousTxId, outputIndex, sequence, nonWitnessUtxo, witnessUtxo, redeemScript, witnessScript, bip32Derivation, }: {
@@ -131,20 +196,47 @@ declare class PsbtV2 extends PsbtV2Maps {
     /**
      * Updater/Signer Methods
      */
+    /**
+     * Removes an input-map from inputMaps.
+     */
     deleteInput(index: number): void;
+    /**
+     * Removes an output-map from outputMaps.
+     */
     deleteOutput(index: number): void;
+    /**
+     * Checks that provided flags are present in PSBT_GLOBAL_TX_MODIFIABLE.
+     */
     private isModifiable;
+    /**
+     * Adds a signature for an input. Validates that the input is mapped and does
+     * not already have a signature for the pubkey. Also validates for sighash.
+     * Other validation is incomplete. Also validates for required args in case
+     * typescript is not being used to call the method.
+     *
+     * The Signer, when it creates a signature, must add the partial sig keypair
+     * to the psbt for the input which it is signing. In the case that a
+     * particular signer does not, this method can be used to add a signature to
+     * the psbt. This method assumes the Signer did the validation outlined in
+     * BIP0174 before creating a signature.
+     * https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#signer
+     */
     addPartialSig(inputIndex: number, pubkey: Buffer, sig: Buffer): void;
+    /**
+     * Removes all sigs for an input unless a pubkey is specified. Validates that
+     * the input exists. When providing a pubkey, this validates that a sig for
+     * the pubkey exists.
+     */
     removePartialSig(inputIndex: number, pubkey?: Buffer): void;
+    /**
+     * Ensures the PSBT is in the proper state when adding a partial sig keypair.
+     * https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#signer
+     */
     private handleSighashType;
+    /**
+     * Attempts to return a PsbtV2 by converting from a PsbtV0 string or Buffer
+     */
     static FromV0(psbt: string | Buffer, allowTxnVersion1?: boolean): PsbtV2;
 }
-/**
- * Attempts to extract the version number as uint32LE from raw psbt regardless
- * of psbt validity.
- * @param {string | Buffer} psbt - hex, base64 or buffer of psbt
- * @returns {number} version number
- */
-declare function getPsbtVersionNumber(psbt: string | Buffer): number;
 
 export { PsbtV2, getPsbtVersionNumber };