@bitcoinerlab/descriptors 2.1.0 → 2.2.0

package/README.md

@@ -84,10 +84,10 @@ To call `updatePsbtAsInput()`, use the following syntax:
 ```javascript
 import { Psbt } from 'bitcoinjs-lib';
 const psbt = new Psbt();
-const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout });
+const inputFinalizer = output.updatePsbtAsInput({ psbt, txHex, vout, rbf });
 ```
 
-Here, `psbt` refers to an instance of the [bitcoinjs-lib Psbt class](https://github.com/bitcoinjs/bitcoinjs-lib). The parameter `txHex` denotes a hex string that serializes the previous transaction containing this output. Meanwhile, `vout` is an integer that marks the position of the output within that transaction.
+Here, `psbt` refers to an instance of the [bitcoinjs-lib Psbt class](https://github.com/bitcoinjs/bitcoinjs-lib). The parameter `txHex` denotes a hex string that serializes the previous transaction containing this output. Meanwhile, `vout` is an integer that marks the position of the output within that transaction. Finally, `rbf` is an optional parameter (defaulting to `true`) used to indicate whether the transaction uses Replace-By-Fee (RBF). When RBF is enabled, transactions can be replaced while they are in the mempool with others that have higher fees. Note that RBF is enabled for the entire transaction if at least one input signals it. Also, note that transactions using relative time locks inherently opt into RBF due to the `nSequence` range used.
 
 The method returns the `inputFinalizer()` function. This finalizer function completes a PSBT input by adding the unlocking script (`scriptWitness` or `scriptSig`) that satisfies the previous output's spending conditions. Bear in mind that both `scriptSig` and `scriptWitness` incorporate signatures. As such, you should complete all necessary signing operations before calling `inputFinalizer()`. Detailed [explanations on the `inputFinalizer` method](#signers-and-finalizers-finalize-psbt-input) can be found in the Signers and Finalizers section.
 

package/dist/descriptors.d.ts

@@ -158,6 +158,7 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
                 txId?: string;
                 value?: number;
                 vout: number;
+                rbf?: boolean;
             }): number;
             /**
              * Sets this output as an input of the provided `psbt` and updates the
@@ -176,6 +177,14 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
              *
              * When unsure, always use `txHex`, and skip `txId` and `value` for safety.
              *
+             * Use `rbf` to mark whether this tx can be replaced with another with
+             * higher fee while being in the mempool. Note that a tx will automatically
+             * be marked as replacable if a single input requests it.
+             * Note that any transaction using a relative timelock (nSequence < 0x80000000)
+             * also falls within the RBF range (nSequence < 0xFFFFFFFE), making it
+             * inherently replaceable. So don't set `rbf` to false if this is tx uses
+             * relative time locks.
+             *
              * @returns A finalizer function to be used after signing the `psbt`.
              * This function ensures that this input is properly finalized.
              * The finalizer has this signature:
@@ -183,12 +192,13 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
              * `( { psbt, validate = true } : { psbt: Psbt; validate: boolean | undefined } ) => void`
              *
              */
-            updatePsbtAsInput({ psbt, txHex, txId, value, vout }: {
+            updatePsbtAsInput({ psbt, txHex, txId, value, vout, rbf }: {
                 psbt: Psbt;
                 txHex?: string;
                 txId?: string;
                 value?: number;
                 vout: number;
+                rbf?: boolean;
             }): ({ psbt, validate }: {
                 psbt: Psbt;
                 /** Runs further test on the validity of the signatures.
@@ -440,6 +450,7 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
                 txId?: string;
                 value?: number;
                 vout: number;
+                rbf?: boolean;
             }): number;
             /**
              * Sets this output as an input of the provided `psbt` and updates the
@@ -458,6 +469,14 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
              *
              * When unsure, always use `txHex`, and skip `txId` and `value` for safety.
              *
+             * Use `rbf` to mark whether this tx can be replaced with another with
+             * higher fee while being in the mempool. Note that a tx will automatically
+             * be marked as replacable if a single input requests it.
+             * Note that any transaction using a relative timelock (nSequence < 0x80000000)
+             * also falls within the RBF range (nSequence < 0xFFFFFFFE), making it
+             * inherently replaceable. So don't set `rbf` to false if this is tx uses
+             * relative time locks.
+             *
              * @returns A finalizer function to be used after signing the `psbt`.
              * This function ensures that this input is properly finalized.
              * The finalizer has this signature:
@@ -465,12 +484,13 @@ export declare function DescriptorsFactory(ecc: TinySecp256k1Interface): {
              * `( { psbt, validate = true } : { psbt: Psbt; validate: boolean | undefined } ) => void`
              *
              */
-            updatePsbtAsInput({ psbt, txHex, txId, value, vout }: {
+            updatePsbtAsInput({ psbt, txHex, txId, value, vout, rbf }: {
                 psbt: Psbt;
                 txHex?: string;
                 txId?: string;
                 value?: number;
                 vout: number;
+                rbf?: boolean;
             }): ({ psbt, validate }: {
                 psbt: Psbt;
                 /** Runs further test on the validity of the signatures.

package/dist/descriptors.js

@@ -905,6 +905,14 @@ function DescriptorsFactory(ecc) {
          *
          * When unsure, always use `txHex`, and skip `txId` and `value` for safety.
          *
+         * Use `rbf` to mark whether this tx can be replaced with another with
+         * higher fee while being in the mempool. Note that a tx will automatically
+         * be marked as replacable if a single input requests it.
+         * Note that any transaction using a relative timelock (nSequence < 0x80000000)
+         * also falls within the RBF range (nSequence < 0xFFFFFFFE), making it
+         * inherently replaceable. So don't set `rbf` to false if this is tx uses
+         * relative time locks.
+         *
          * @returns A finalizer function to be used after signing the `psbt`.
          * This function ensures that this input is properly finalized.
          * The finalizer has this signature:
@@ -912,8 +920,8 @@ function DescriptorsFactory(ecc) {
          * `( { psbt, validate = true } : { psbt: Psbt; validate: boolean | undefined } ) => void`
          *
          */
-        updatePsbtAsInput({ psbt, txHex, txId, value, vout //vector output index
-         }) {
+        updatePsbtAsInput({ psbt, txHex, txId, value, vout, //vector output index
+        rbf = true }) {
             if (txHex === undefined) {
                 console.warn(`Warning: missing txHex may allow fee attacks`);
             }
@@ -934,7 +942,8 @@ function DescriptorsFactory(ecc) {
                 scriptPubKey: this.getScriptPubKey(),
                 isSegwit,
                 witnessScript: this.getWitnessScript(),
-                redeemScript: this.getRedeemScript()
+                redeemScript: this.getRedeemScript(),
+                rbf
             });
             const finalizer = ({ psbt, validate = true }) => this.finalizePsbtInput({ index, psbt, validate });
             return finalizer;
@@ -1072,16 +1081,20 @@ function DescriptorsFactory(ecc) {
             scriptPubKey = out.script;
         }
         const locktime = this.getLockTime() || 0;
-        let sequence = this.getSequence();
-        if (sequence === undefined && locktime !== 0)
-            sequence = 0xfffffffe;
-        if (sequence === undefined && locktime === 0)
-            sequence = 0xffffffff;
+        const sequence = this.getSequence();
+        //We don't know whether the user opted for RBF or not. So check that
+        //at least one of the 2 sequences matches.
+        const sequenceNoRBF = sequence !== undefined
+            ? sequence
+            : locktime === 0
+                ? 0xffffffff
+                : 0xfffffffe;
+        const sequenceRBF = sequence !== undefined ? sequence : 0xfffffffd;
         const eqBuffers = (buf1, buf2) => buf1 instanceof Buffer && buf2 instanceof Buffer
             ? Buffer.compare(buf1, buf2) === 0
             : buf1 === buf2;
         if (Buffer.compare(scriptPubKey, this.getScriptPubKey()) !== 0 ||
-            sequence !== inputSequence ||
+            (sequenceRBF !== inputSequence && sequenceNoRBF !== inputSequence) ||
             locktime !== psbt.locktime ||
             !eqBuffers(this.getWitnessScript(), input.witnessScript) ||
             !eqBuffers(this.getRedeemScript(), input.redeemScript)) {

package/dist/psbt.d.ts

@@ -21,7 +21,7 @@ export declare function finalScriptsFuncFactory(scriptSatisfaction: Buffer, netw
 /**
  * Important: Read comments on descriptor.updatePsbt regarding not passing txHex
  */
-export declare function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysInfo, scriptPubKey, isSegwit, witnessScript, redeemScript }: {
+export declare function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysInfo, scriptPubKey, isSegwit, witnessScript, redeemScript, rbf }: {
     psbt: Psbt;
     vout: number;
     txHex?: string;
@@ -34,5 +34,6 @@ export declare function updatePsbt({ psbt, vout, txHex, txId, value, sequence, l
     isSegwit: boolean;
     witnessScript: Buffer | undefined;
     redeemScript: Buffer | undefined;
+    rbf: boolean;
 }): number;
 export {};

package/dist/psbt.js

@@ -86,8 +86,10 @@ exports.finalScriptsFuncFactory = finalScriptsFuncFactory;
 /**
  * Important: Read comments on descriptor.updatePsbt regarding not passing txHex
  */
-function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysInfo, scriptPubKey, isSegwit, witnessScript, redeemScript }) {
+function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysInfo, scriptPubKey, isSegwit, witnessScript, redeemScript, rbf }) {
     //Some data-sanity checks:
+    if (sequence !== undefined && rbf && sequence > 0xfffffffd)
+        throw new Error(`Error: incompatible sequence and rbf settings`);
     if (!isSegwit && txHex === undefined)
         throw new Error(`Error: txHex is mandatory for Non-Segwit inputs`);
     if (isSegwit &&
@@ -129,13 +131,23 @@ function updatePsbt({ psbt, vout, txHex, txId, value, sequence, locktime, keysIn
         // this input's sequence < 0xffffffff
         if (sequence === undefined) {
             //NOTE: if sequence is undefined, bitcoinjs-lib uses 0xffffffff as default
-            sequence = 0xfffffffe;
+            sequence = rbf ? 0xfffffffd : 0xfffffffe;
         }
         else if (sequence > 0xfffffffe) {
             throw new Error(`Error: incompatible sequence: ${sequence} and locktime: ${locktime}`);
         }
+        if (sequence === undefined && rbf)
+            sequence = 0xfffffffd;
         psbt.setLocktime(locktime);
     }
+    else {
+        if (sequence === undefined) {
+            if (rbf)
+                sequence = 0xfffffffd;
+            else
+                sequence = 0xffffffff;
+        }
+    }
     const input = {
         hash: reverseBuffer(Buffer.from(txId, 'hex')),
         index: vout

package/package.json

@@ -2,7 +2,7 @@
   "name": "@bitcoinerlab/descriptors",
   "description": "This library parses and creates Bitcoin Miniscript Descriptors and generates Partially Signed Bitcoin Transactions (PSBTs). It provides PSBT finalizers and signers for single-signature, BIP32 and Hardware Wallets.",
   "homepage": "https://github.com/bitcoinerlab/descriptors",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": "Jose-Luis Landabaso",
   "license": "MIT",
   "repository": {
@@ -67,8 +67,8 @@
     "yargs": "^17.7.2"
   },
   "dependencies": {
-    "@bitcoinerlab/miniscript": "^1.2.1",
-    "@bitcoinerlab/secp256k1": "^1.0.5",
+    "@bitcoinerlab/miniscript": "^1.4.0",
+    "@bitcoinerlab/secp256k1": "^1.1.1",
     "bip32": "^4.0.0",
     "bitcoinjs-lib": "^6.1.3",
     "ecpair": "^2.1.0",