@caravan/psbt 1.1.0 → 1.3.0

package/README.md

@@ -2,22 +2,15 @@
 
 A set of utilities for working with PSBTs.
 
-## Table of contents
-
-- [PSBTv0](#psbtv0)
-  - [Exports](#psbtv0-exports)
+# Table of contents
+- [Constants](#constants)
+  - [Exports](#exports)
     - [`const PSBT_MAGIC_HEX`](#const-psbt_magic_hex)
     - [`const PSBT_MAGIC_B64`](#const-psbt_magic_b64)
     - [`const PSBT_MAGIC_BYTES`](#const-psbt_magic_bytes)
-    - [`function autoLoadPSBT`](#function-autoloadpsbt)
-    - [`function psbtInputFormatter`](#function-psbtinputformatter)
-    - [`function psbtOutputFormatter`](#function-psbtoutputformatter)
-    - [`function translatePSBT`](#function-translatepsbt)
-    - [`function addSignaturesToPSBT`](#function-addsignaturestopsbt)
-    - [`function parseSignaturesFromPSBT`](#function-parsesignaturesfrompsbt)
-    - [`function parseSignatureArrayFromPSBT`](#function-parsesignaturearrayfrompsbt)
+- [PSBTv0](#psbtv0)
 - [PSBTv2](#psbtv2)
-  - [Exports](#psbtv2-exports)
+  - [Exports](#exports-1)
     - [`class PsbtV2`](#class-psbtv2)
       - [`get isReadyForConstructor`](#get-isreadyforconstructor)
       - [`get isReadyForUpdater`](#get-isreadyforupdater)
@@ -34,16 +27,19 @@ A set of utilities for working with PSBTs.
       - [`public deleteOutput`](#public-deleteoutput)
       - [`public addPartialSig`](#public-addpartialsig)
       - [`public removePartialSig`](#public-removepartialsig)
+      - [`public setProprietaryValue`](#public-setproprietaryvalue)
       - [`static PsbtV2.FromV0`](#static-psbtv2fromv0)
     - [`function getPsbtVersionNumber`](#function-getpsbtversionnumber)
 - [Concepts](#concepts)
   - [The operator role saga](#the-operator-role-saga)
 - [TODO](#todo)
+  - [PsbtV2](#psbtv2-1)
+    - [Operator role validation](#operator-role-validation)
+    - [Class constructor](#class-constructor)
+    - [Add input timelocks](#add-input-timelocks)
+    - [Add input sighash\_single](#add-input-sighash_single)
 
-## PSBTv0
-
-[BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)
-
+## Constants
 ### Exports
 
 #### `const PSBT_MAGIC_HEX`
@@ -58,43 +54,13 @@ A utility constant for base64 encoded psbt magic bytes equal to `"cHNidP8"`.
 
 A utility constant for `Buffer` instance of psbt magic bytes.
 
-#### `function autoLoadPSBT`
-
-Given a string, try to create a Psbt object based on MAGIC (hex or Base64).
-
-#### `function psbtInputFormatter`
-
-Take a `MultisigTransactionInput` and turn it into a `MultisigTransactionPSBTInput`.
-
-#### `function psbtOutputFormatter`
-
-Take a `MultisigTransactionOutput` and turn it into a `MultisigTransactionPSBTOutput`.
 
-#### `function translatePSBT`
-
-Translates a PSBT into inputs/outputs consumable by supported non-PSBT devices in the `@caravan/wallets` library.
-
-#### `function addSignaturesToPSBT`
-
-Given an unsigned PSBT, an array of signing public key(s) (one per input), an array of signature(s) (one per input) in the same order as the pubkey(s), adds partial signature object(s) to each input and returns the PSBT with partial signature(s) included.
-
-#### `function parseSignaturesFromPSBT`
-
-Extracts the signature(s) from a PSBT.
-
-NOTE: there should be one signature per input, per signer.
-
-ADDITIONAL NOTE: because of the restrictions we place on braids to march their multisig addresses (slices) forward at the _same_ index across each chain of the braid, we do not run into a possible collision with this data structure. BUT - to have this method accommodate the _most_ general form of signature parsing, it would be wise to wrap this one level deeper like:
+## PSBTv0
 
-```
-address: [pubkey : [signature(s)]]
-```
+[BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)
 
-that way if your braid only advanced one chain's (member's) index so that a pubkey could be used in more than one address, everything would still function properly.
 
-#### `function parseSignatureArrayFromPSBT`
 
-Extracts signatures in order of inputs and returns as array (or array of arrays if multiple signature sets).
 
 ## PSBTv2
 
@@ -217,6 +183,20 @@ The Signer, when it creates a signature, must add the partial sig keypair to the
 
 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.
 
+##### `public setProprietaryValue`
+
+Sets values on the proprietary keytype for a global, input, or output map. BIP 174 allows for proprietary values to be set on all maps with the keytype `0xFC`. This method sets byte data to key values defined by the args.
+
+Args:
+
+- `mapSelector` selects which map to set the proprietary value. If this value is not `"global"`, then a tuple must be provided with `"inputs"` or `"outputs"` as the first element and the index `number` on the second element representing which input or output map to set the value to. An example looks like `["inputs", 0]`. If the map name doesn't match, the values will be set to the global map. If the index is missing on `"inputs"` or `"outputs"`, then it will throw.
+- `identifier` should be the bytes identifier for the set of proprietary keytypes.
+- `subkeyType` accepts bytes proprietary keytype.
+- `subkeyData` accepts bytes proprietary keydata.
+- `valueData` accepts bytes which will be written as the proprietary value.
+
+From the provided args, a key with the following format will be generated: `0xFC<compact uint identifier length><bytes identifier><bytes subtype><bytes subkeydata>`
+
 ##### `static PsbtV2.FromV0`
 
 Attempts to return a `PsbtV2` by converting from a PSBTv0 string or Buffer
@@ -231,22 +211,80 @@ Attempts to extract the version number as uint32LE from raw psbt regardless of p
 
 The PSBT is a resource which may be passed between several operators or services. It's best to look at the operator roles as stages of a saga. The next valid operator role(s) can be determined by the state of the PSBT. The actions allowed for a PSBT are determined by which operator role the PSBT can be now and which role it could be next. See the following blog article at Unchained for a more detailed illustration: [Operator roles: Life stages in the saga of a PSBT](https://unchained.com/blog/operator-roles-life-stages-in-the-saga-of-a-psbt/)
 
-### TODO
+## TODO
 
-#### PsbtV2
+### PsbtV2
 
-##### Operator role validation
+#### Operator role validation
 
 Work remains for determining readiness for operator roles Input Finalizer and Transaction Extractor. The getters responsible for these checks are `isReadyForInputFinalizer` and `isReadyForTransactionExtractor`. Work also remains to expand the PsbtV2 method functionality beyond the Signer role. A huge benefit might be gained from building methods aimed at the Combiner role.
 
-##### Class constructor
+#### Class constructor
 
 The constructor must be able to handle values which the Creator role is responsible for. Currently, the constructor can only accept an optional psbt which it parses to configure itself. It would be ideal if a fresh PsbtV2 instance could be initialized with minimal arguments for which the Creator role is responsible. See `private create()`.
 
-##### Add input timelocks
+#### Add input timelocks
 
 The `public addInput` must be able to properly handle input locktimes which interact with the global value.
 
-##### Add input sighash_single
+#### Add input sighash_single
 
 The `public addInput` must be able to properly handle new inputs when the psbt has a `SIGHASH_SINGLE` flag on `PSBT_GLOBAL_TX_MODIFIABLE`.
+
+## Troubleshooting and FAQ
+### What's with the vendor version of tiny-secp256k1?
+In v6 of bitcoinjs-lib, which @caravan/psbt upgraded to use relative v5 in the older psbt code in @caravan/bitcoin,
+some functions of the library require an elliptic curve library to be initialized w/ bitcoinjs-lib (see [this issue](https://github.com/bitcoinjs/bitcoinjs-lib/issues/1889#issuecomment-1443792692)), e.g. for taproot functionality.
+For some reason, the recommended library `tiny-secp256k1` fails on initialization saying the library is invalid. The cause
+seems to be a comparison of a Buffer with Uint8Array (see [this issue](https://github.com/bitcoinjs/tiny-secp256k1/issues/136) for more info).
+
+A proposed fix is pending review and approval [here](https://github.com/bitcoinjs/tiny-secp256k1/pull/137). Unfortunately, since there
+is a special build requirement to get the package code, the easiest way to get bitcoinjs initialized was to include patched vendor code in
+the caravan codebase for now.
+
+If a fork needs to be maintained and updated, to build and update the code, you can fork the repo, and run the docker build steps:
+
+```
+% docker build -t tiny-secp256k1 .
+% docker run -it --rm -v `pwd`:/tiny-secp256k1 -w /tiny-secp256k1 tiny-secp256k1
+# make build
+```
+Then copy the resulting built code (ends up in the lib directory) into the vendor/tiny-secp256k1. Currently
+we just use the asmjs build to avoid wasm complications in
+the build system.
+
+### Experimental VM Modules
+This is related to the tiny-secp256k1 library which has difficulties importing in different environments.
+
+Note that the jest configs and the special prefix in the npm test scripts were needed
+to let jest understand the esmodule imports from the tiny-secp256k1 library.
+
+The npm script prefix in particular may result in a console warning when running tests:
+
+```
+ExperimentalWarning: VM Modules is an experimental feature and might change at any time
+```
+
+This can be safely ignored. See the [documentation in jest](https://jestjs.io/docs/ecmascript-modules)
+for more information on running with `--experimental-vm-modules`.
+
+
+### What's with the `bitcoinjs-lib-v6` dependency?
+
+npm workspaces and maybe vite have issues with nested dependencies with
+mismatched versions. `@caravan/psbt` requires v6 of bitcoinjs-lib but in order
+to avoid making massive breaking changes, other libraries like `@caravan/bitcoin` are
+still using bitcoinjs-lib v5. Unfortunately when being built altogether, it's possible
+that the wrong version takes precedence, causing the build to break.
+
+Because npm lacks a `nohoist` option for workspaces, the workaround is to use a kind
+of alias in the package.json. So we add `"bitcoinjs-lib-v6": "npm:bitcoinjs-lib@^6.1.5",`
+to say that we want to use v6.1.5 from npm whenever use the alias `bitcoinjs-lib-v6`
+in imports in our code. This forces build systems to look for this reference and
+the correct version of the package and avoid using a mismatch. Unfortunately
+this was the only workaround that worked. `overrides` for example was not being
+respected.
+
+Learn more [here](https://github.com/vitejs/vite/issues/4245),
+[here](https://github.com/zackerydev/noist?tab=readme-ov-file), and
+[here](https://github.com/prisma/prisma/issues/9649).

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { Network } from '@caravan/bitcoin';
+import { Psbt } from 'bitcoinjs-lib-v6';
+import { MultisigWalletConfig } from '@caravan/multisig';
+
 /**
  * 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
@@ -24,6 +28,8 @@ declare enum PsbtGlobalTxModifiableBits {
     OUTPUTS = "OUTPUTS",// 0b00000010
     SIGHASH_SINGLE = "SIGHASH_SINGLE"
 }
+type InputOutputIndexType = number;
+type MapSelectorType = "global" | ["inputs", InputOutputIndexType] | ["outputs", InputOutputIndexType];
 
 /**
  * Attempts to extract the version number as uint32LE from raw psbt regardless
@@ -279,6 +285,31 @@ declare class PsbtV2 extends PsbtV2Maps {
      * the pubkey exists.
      */
     removePartialSig(inputIndex: number, pubkey?: Buffer): void;
+    /**
+     * Sets values on the proprietary keytype for a global, input, or output map.
+     * BIP 174 allows for proprietary values to be set on all maps with the
+     * keytype `0xFC`. This method sets byte data to key values defined by the
+     * args.
+     *
+     * Args:
+     * - `mapSelector` selects which map to set the proprietary value. If this
+     *   value is not `"global"`, then a tuple must be provided with `"inputs"` or
+     *   `"outputs"` as the first element and the index `number` on the second
+     *   element representing which input or output map to set the value to. An
+     *   example looks like `["inputs", 0]`. If the map name doesn't match, the
+     *   values will be set to the global map. If the index is missing on
+     *   `"inputs"` or `"outputs"`, then it will throw.
+     * - `identifier` should be the bytes identifier for the set of proprietary
+     *   keytypes.
+     * - `subkeyType` accepts bytes proprietary keytype.
+     * - `subkeyData` accepts bytes proprietary keydata.
+     * - `valueData` accepts bytes which will be written as the proprietary value.
+     *
+     * From the provided args, a key with the following format will be generated:
+     * `0xFC<compact uint identifier length><bytes identifier><bytes
+     * subtype><bytes subkeydata>`
+     */
+    setProprietaryValue(mapSelector: MapSelectorType, identifier: Buffer, subkeyType: Buffer, subkeyData: Buffer, valueData: 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
@@ -294,4 +325,103 @@ declare class PsbtV2 extends PsbtV2Maps {
     static FromV0(psbt: string | Buffer, allowTxnVersion1?: boolean): PsbtV2;
 }
 
-export { PsbtV2, getPsbtVersionNumber };
+interface PsbtInput {
+    hash: string | Buffer;
+    index: number;
+    transactionHex: string;
+    redeemScript?: Buffer;
+    witnessScript?: Buffer;
+    bip32Derivation?: {
+        masterFingerprint: Buffer;
+        path: string;
+        pubkey: Buffer;
+    }[];
+    spendingWallet: MultisigWalletConfig;
+}
+interface PsbtOutput {
+    address: string;
+    value: number;
+    bip32Derivation?: {
+        masterFingerprint: Buffer;
+        path: string;
+        pubkey: Buffer;
+    }[];
+    redeemScript?: Buffer;
+    witnessScript?: Buffer;
+}
+/**
+ * This function seeks to be an updated version of the legacy `unsignedMultisigPSBT` function
+ * from @caravan/bitcoin.
+ * It takes the network and a set of inputs and outputs which it creates a PSBT from.
+ * This combines several operator roles of the PSBT saga into one function, getting a PSBT
+ * ready to be signed. It optionally can also add the global xpubs to the PSBT.
+ */
+declare const getUnsignedMultisigPsbtV0: ({ network, inputs, outputs, includeGlobalXpubs, }: {
+    network: Network;
+    inputs: PsbtInput[];
+    outputs: PsbtOutput[];
+    includeGlobalXpubs?: boolean | undefined;
+}) => Psbt;
+declare const addGlobalXpubs: (psbt: Psbt, inputs: PsbtInput[], network: Network) => void;
+/**
+ * Validate the signature on a psbt for a given input. Returns false if no
+ * valid signature is found otherwise returns the public key that was signed for.
+ *
+ * This is a port of the validateMultisigSignature function from @caravan/bitcoin
+ * to support a newer API and be more PSBT-native.
+ */
+declare const validateMultisigPsbtSignature: (raw: string | Buffer, inputIndex: number, inputSignature: Buffer, inputAmount?: string) => boolean | string;
+
+/**
+ * @file This file primarily contains utility functions migrated from the
+ * legacy psbt module in @caravan/bitcoin. With the new @caravan/psbt
+ * module, the goal is to make a more modular and legible API. But in order
+ * to make migrations easier from the old API, we need to provide conversion functions
+ * for converting the deeply nested objects in the legacy API.
+ */
+
+interface LegacyMultisig {
+    /**
+     * JSON stringified object with the following properties:
+     * braidDetails: {
+     *   network: Network;
+     *   addressType: number;
+     *   extendedPublicKeys: string[];
+     *   requiredSigners: number;
+     *   index: string;
+     * };
+     */
+    braidDetails: string;
+    bip32Derivation?: {
+        masterFingerprint: string;
+        path: string;
+        pubkey: Buffer;
+    }[];
+}
+interface LegacyInput {
+    txid: string;
+    index: number;
+    transactionHex: string;
+    amountSats: number | string;
+    multisig: LegacyMultisig;
+}
+interface LegacyOutput {
+    address: string;
+    amountSats: number | string;
+    bip32Derivation?: {
+        masterFingerprint: string;
+        path: string;
+        pubkey: Buffer;
+    }[];
+    witnessScript?: Buffer;
+    redeemScript?: Buffer;
+    multisig?: LegacyMultisig;
+}
+declare const convertLegacyInput: (input: LegacyInput) => PsbtInput;
+declare const convertLegacyOutput: (output: LegacyOutput) => PsbtOutput;
+
+declare const PSBT_MAGIC_HEX = "70736274ff";
+declare const PSBT_MAGIC_B64 = "cHNidP8";
+declare const PSBT_MAGIC_BYTES: Buffer;
+
+export { LegacyInput, LegacyMultisig, LegacyOutput, PSBT_MAGIC_B64, PSBT_MAGIC_BYTES, PSBT_MAGIC_HEX, PsbtInput, PsbtOutput, PsbtV2, addGlobalXpubs, convertLegacyInput, convertLegacyOutput, getPsbtVersionNumber, getUnsignedMultisigPsbtV0, validateMultisigPsbtSignature };