@caravan/psbt 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,40 +1,80 @@
 /**
- * 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);
     /**
      * Globals Getters/Setters
      */
-    get PSBT_GLOBAL_XPUB(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    get PSBT_GLOBAL_XPUB(): NonUniqueKeyTypeValue[];
     get PSBT_GLOBAL_TX_VERSION(): number;
     set PSBT_GLOBAL_TX_VERSION(version: number);
     get PSBT_GLOBAL_FALLBACK_LOCKTIME(): number | null;
@@ -47,7 +87,7 @@ declare class PsbtV2 extends PsbtV2Maps {
     set PSBT_GLOBAL_TX_MODIFIABLE(modifiable: PsbtGlobalTxModifiableBits[]);
     get PSBT_GLOBAL_VERSION(): number;
     set PSBT_GLOBAL_VERSION(version: number);
-    get PSBT_GLOBAL_PROPRIETARY(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    get PSBT_GLOBAL_PROPRIETARY(): NonUniqueKeyTypeValue[];
     /**
      * Input Getters/Setters
      */
@@ -57,23 +97,23 @@ declare class PsbtV2 extends PsbtV2Maps {
     get PSBT_IN_SIGHASH_TYPE(): (number | null)[];
     get PSBT_IN_REDEEM_SCRIPT(): (string | null)[];
     get PSBT_IN_WITNESS_SCRIPT(): (string | null)[];
-    get PSBT_IN_BIP32_DERIVATION(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    get PSBT_IN_BIP32_DERIVATION(): NonUniqueKeyTypeValue[][];
     get PSBT_IN_FINAL_SCRIPTSIG(): (string | null)[];
     get PSBT_IN_FINAL_SCRIPTWITNESS(): (string | null)[];
     get PSBT_IN_POR_COMMITMENT(): (string | null)[];
-    get PSBT_IN_RIPEMD160(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
-    get PSBT_IN_SHA256(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
-    get PSBT_IN_HASH160(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
-    get PSBT_IN_HASH256(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    get PSBT_IN_RIPEMD160(): NonUniqueKeyTypeValue[][];
+    get PSBT_IN_SHA256(): NonUniqueKeyTypeValue[][];
+    get PSBT_IN_HASH160(): NonUniqueKeyTypeValue[][];
+    get PSBT_IN_HASH256(): NonUniqueKeyTypeValue[][];
     get PSBT_IN_PREVIOUS_TXID(): string[];
     get PSBT_IN_OUTPUT_INDEX(): number[];
     get PSBT_IN_SEQUENCE(): (number | null)[];
     get PSBT_IN_REQUIRED_TIME_LOCKTIME(): (number | null)[];
     get PSBT_IN_REQUIRED_HEIGHT_LOCKTIME(): (number | null)[];
     get PSBT_IN_TAP_KEY_SIG(): (string | null)[];
-    get PSBT_IN_TAP_SCRIPT_SIG(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
-    get PSBT_IN_TAP_LEAF_SCRIPT(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
-    get PSBT_IN_TAP_BIP32_DERIVATION(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    get PSBT_IN_TAP_SCRIPT_SIG(): NonUniqueKeyTypeValue[][];
+    get PSBT_IN_TAP_LEAF_SCRIPT(): NonUniqueKeyTypeValue[][];
+    get PSBT_IN_TAP_BIP32_DERIVATION(): NonUniqueKeyTypeValue[][];
     get PSBT_IN_TAP_INTERNAL_KEY(): (string | null)[];
     get PSBT_IN_TAP_MERKLE_ROOT(): (string | null)[];
     get PSBT_IN_PROPRIETARY(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
@@ -89,15 +129,91 @@ declare class PsbtV2 extends PsbtV2Maps {
     get PSBT_OUT_TAP_TREE(): (string | null)[];
     get PSBT_OUT_TAP_BIP32_DERIVATION(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
     get PSBT_OUT_PROPRIETARY(): NonUniqueKeyTypeValue[] | NonUniqueKeyTypeValue[][];
+    /**
+     * Operator Role Validation Getters
+     */
+    /**
+     * Returns true if the PsbtV2 is ready for an operator taking the Constructor
+     * role.
+     *
+     * This check assumes that the Creator used this class's constructor method to
+     * initialize the PsbtV2 without passing a psbt (constructor  defaults were
+     * set).
+     */
+    get isReadyForConstructor(): boolean;
+    /**
+     * Returns true if the PsbtV2 is ready for an operator taking the Updater
+     * role.
+     *
+     * Before signatures are added, but after an input is added, a PsbtV2 is
+     * likely to be ready for Constructor, ready for Updater, and ready for Signer
+     * simultaneously.
+     *
+     * According to BIP370, the Updater can modify the sequence number, but it is
+     * unclear if the Updater retains permissions provided in psbtv0 (BIP174). It
+     * is likely not the case that the Updater has the same permissions as
+     * previously because it seems to now be the realm of the Constructor to add
+     * inputs and outputs.
+     */
+    get isReadyForUpdater(): boolean;
+    /**
+     * Returns true if the PsbtV2 is ready for an operator taking the Signer role.
+     */
+    get isReadyForSigner(): boolean;
+    /**
+     * Returns true if the PsbtV2 is ready for an operator taking the Combiner
+     * role.
+     */
+    get isReadyForCombiner(): boolean;
+    /**
+     * Unimplemented. Returns false.
+     */
+    get isReadyForInputFinalizer(): boolean;
+    /**
+     * Returns true if the PsbtV2 is ready for an operator taking the Transaction
+     * Extractor role.
+     *
+     * If all the inputs have been finalized, then the psbt is ready for the
+     * Transaction Extractor. According to BIP 174, it's the responsibility of the
+     * Input Finalizer to add scriptSigs or scriptWitnesses and then remove other
+     * details besides the UTXO. This getter checks that the Input Finalizer has
+     * finished its job.
+     */
+    get isReadyForTransactionExtractor(): boolean;
     /**
      * 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 +247,51 @@ 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 all 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.
+     *
+     * This method first starts with a fresh PsbtV2 having just been created. It
+     * then takes the PsbtV2 through its operator saga through the Signer role. In
+     * this sense validation for each operator role will be performed.
+     */
     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 };