ecash-lib 1.2.2-rc9 → 1.4.0

package/src/txBuilder.ts

@@ -0,0 +1,262 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { Ecc, EccDummy } from './ecc.js';
+import { sha256d } from './hash.js';
+import { WriterBytes } from './io/writerbytes.js';
+import { pushBytesOp } from './op.js';
+import { Script } from './script.js';
+import { SigHashType, SigHashTypeVariant } from './sigHashType.js';
+import {
+    DEFAULT_TX_VERSION,
+    Tx,
+    TxInput,
+    TxOutput,
+    copyTxInput,
+    copyTxOutput,
+} from './tx.js';
+import { UnsignedTx, UnsignedTxInput } from './unsignedTx.js';
+
+/**
+ * Function that contains all the required data to sign a given `input` and
+ * return the scriptSig.
+ *
+ * Use it by attaching a `Signatory` to a TxBuilderInput, e.g. like this for a
+ * P2PKH input:
+ * ```ts
+ * new TxBuilder({
+ *     inputs: [{
+ *         input: { prevOut: ... },
+ *         signatory: P2PKHSignatory(sk, pk, ALL_BIP143),
+ *     }],
+ *     ...
+ * })
+ * ```
+ **/
+export type Signatory = (ecc: Ecc, input: UnsignedTxInput) => Script;
+
+/** Builder input that bundles all the data required to sign a TxInput */
+export interface TxBuilderInput {
+    input: TxInput;
+    signatory?: Signatory;
+}
+
+/**
+ * Output that can either be:
+ * - `TxOutput`: A full output with a fixed sats amount
+ * - `Script`: A Script which will receive the leftover sats after fees.
+ *   Leftover usually is the change the sender gets back from providing more
+ *   sats than needed.
+ */
+export type TxBuilderOutput = TxOutput | Script;
+
+/** Class that can be used to build and sign txs. */
+export class TxBuilder {
+    /** nVersion of the resulting Tx */
+    public version: number;
+    /** Inputs that will be signed by the buider */
+    public inputs: TxBuilderInput[];
+    /**
+     * Outputs of the tx, can specify a single leftover (i.e. change) output as
+     * a Script.
+     **/
+    public outputs: TxBuilderOutput[];
+    /** nLockTime of the resulting Tx */
+    public locktime: number;
+
+    public constructor(params?: {
+        version?: number;
+        inputs?: TxBuilderInput[];
+        outputs?: TxBuilderOutput[];
+        locktime?: number;
+    }) {
+        this.version = params?.version ?? DEFAULT_TX_VERSION;
+        this.inputs = params?.inputs ?? [];
+        this.outputs = params?.outputs ?? [];
+        this.locktime = params?.locktime ?? 0;
+    }
+
+    /** Calculte sum of all sats coming in, or `undefined` if some unknown. */
+    private inputSum(): bigint | undefined {
+        let inputSum = 0n;
+        for (const input of this.inputs) {
+            if (input.input.signData === undefined) {
+                return undefined;
+            }
+            inputSum += BigInt(input.input.signData.value);
+        }
+        return inputSum;
+    }
+
+    private prepareOutputs(): {
+        fixedOutputSum: bigint;
+        leftoverIdx: number | undefined;
+        outputs: TxOutput[];
+    } {
+        let fixedOutputSum = 0n;
+        let leftoverIdx: number | undefined = undefined;
+        let outputs: TxOutput[] = new Array(this.outputs.length);
+        for (let idx = 0; idx < this.outputs.length; ++idx) {
+            const builderOutput = this.outputs[idx];
+            if ('bytecode' in builderOutput) {
+                // If builderOutput instanceof Script
+                // Note that the "builderOutput instanceof Script" check may fail due
+                // to discrepancies between nodejs and browser environments
+                if (leftoverIdx !== undefined) {
+                    throw 'Multiple leftover outputs, can at most use one';
+                }
+                leftoverIdx = idx;
+                outputs[idx] = {
+                    value: 0, // placeholder
+                    script: builderOutput.copy(),
+                };
+            } else {
+                fixedOutputSum += BigInt(builderOutput.value);
+                outputs[idx] = copyTxOutput(builderOutput);
+            }
+        }
+        return { fixedOutputSum, leftoverIdx, outputs };
+    }
+
+    /** Sign the tx built by this builder and return a Tx */
+    public sign(ecc: Ecc, feePerKb?: number, dustLimit?: number): Tx {
+        const { fixedOutputSum, leftoverIdx, outputs } = this.prepareOutputs();
+        const inputs = this.inputs.map(input => copyTxInput(input.input));
+        const updateSignatories = (ecc: Ecc, unsignedTx: UnsignedTx) => {
+            for (let idx = 0; idx < this.inputs.length; ++idx) {
+                const signatory = this.inputs[idx].signatory;
+                const input = inputs[idx];
+                if (signatory !== undefined) {
+                    input.script = signatory(
+                        ecc,
+                        new UnsignedTxInput({
+                            inputIdx: idx,
+                            unsignedTx,
+                        }),
+                    );
+                }
+            }
+        };
+        if (leftoverIdx !== undefined) {
+            const inputSum = this.inputSum();
+            if (inputSum === undefined) {
+                throw new Error(
+                    'Using a leftover output requires setting SignData.value for all inputs',
+                );
+            }
+            if (feePerKb === undefined) {
+                throw new Error(
+                    'Using a leftover output requires setting feePerKb',
+                );
+            }
+            if (!Number.isInteger(feePerKb)) {
+                throw new Error('feePerKb must be an integer');
+            }
+            if (dustLimit === undefined) {
+                throw new Error(
+                    'Using a leftover output requires setting dustLimit',
+                );
+            }
+            const dummyUnsignedTx = UnsignedTx.dummyFromTx(
+                new Tx({
+                    version: this.version,
+                    inputs,
+                    outputs,
+                    locktime: this.locktime,
+                }),
+            );
+            // Must use dummy here because ECDSA sigs could be too small for fee calc
+            updateSignatories(new EccDummy(), dummyUnsignedTx);
+            let txSize = dummyUnsignedTx.tx.serSize();
+            let txFee = calcTxFee(txSize, feePerKb);
+            const leftoverValue = inputSum - (fixedOutputSum + txFee);
+            if (leftoverValue < dustLimit) {
+                // inputs cannot pay for a dust leftover -> remove & recalc
+                outputs.splice(leftoverIdx, 1);
+                dummyUnsignedTx.tx.outputs = outputs;
+                // Must update signatories again as they might depend on outputs
+                updateSignatories(new EccDummy(), dummyUnsignedTx);
+                txSize = dummyUnsignedTx.tx.serSize();
+                txFee = calcTxFee(txSize, feePerKb);
+            } else {
+                outputs[leftoverIdx].value = leftoverValue;
+            }
+            if (inputSum < fixedOutputSum + txFee) {
+                throw new Error(
+                    `Insufficient input value (${inputSum}): Can only pay for ${
+                        inputSum - fixedOutputSum
+                    } fees, but ${txFee} required`,
+                );
+            }
+        }
+        const unsignedTx = UnsignedTx.fromTx(
+            new Tx({
+                version: this.version,
+                inputs,
+                outputs,
+                locktime: this.locktime,
+            }),
+        );
+        updateSignatories(ecc, unsignedTx);
+        return unsignedTx.tx;
+    }
+}
+
+/** Calculate the required tx fee for the given txSize and feePerKb,
+ *  rounding up */
+export function calcTxFee(txSize: number, feePerKb: number): bigint {
+    return (BigInt(txSize) * BigInt(feePerKb) + 999n) / 1000n;
+}
+
+/** Append the sighash flags to the signature */
+export function flagSignature(
+    sig: Uint8Array,
+    sigHashFlags: SigHashType,
+): Uint8Array {
+    const writer = new WriterBytes(sig.length + 1);
+    writer.putBytes(sig);
+    writer.putU8(sigHashFlags.toInt() & 0xff);
+    return writer.data;
+}
+
+/**
+ * Sign the sighash using Schnorr for BIP143 signatures and ECDSA for Legacy
+ * signatures, and then flags the signature correctly
+ **/
+export function signWithSigHash(
+    ecc: Ecc,
+    sk: Uint8Array,
+    sigHash: Uint8Array,
+    sigHashType: SigHashType,
+): Uint8Array {
+    const sig =
+        sigHashType.variant == SigHashTypeVariant.LEGACY
+            ? ecc.ecdsaSign(sk, sigHash)
+            : ecc.schnorrSign(sk, sigHash);
+    return flagSignature(sig, sigHashType);
+}
+
+/** Signatory for a P2PKH input. Always uses Schnorr signatures */
+export const P2PKHSignatory = (
+    sk: Uint8Array,
+    pk: Uint8Array,
+    sigHashType: SigHashType,
+) => {
+    return (ecc: Ecc, input: UnsignedTxInput): Script => {
+        const preimage = input.sigHashPreimage(sigHashType);
+        const sighash = sha256d(preimage.bytes);
+        const sigFlagged = signWithSigHash(ecc, sk, sighash, sigHashType);
+        return Script.p2pkhSpend(pk, sigFlagged);
+    };
+};
+
+/** Signatory for a P2PK input. Always uses Schnorr signatures */
+export const P2PKSignatory = (sk: Uint8Array, sigHashType: SigHashType) => {
+    return (ecc: Ecc, input: UnsignedTxInput): Script => {
+        const preimage = input.sigHashPreimage(sigHashType);
+        const sighash = sha256d(preimage.bytes);
+        const sigFlagged = signWithSigHash(ecc, sk, sighash, sigHashType);
+        return Script.fromOps([pushBytesOp(sigFlagged)]);
+    };
+};

package/src/unsignedTx.ts

@@ -0,0 +1,359 @@
+// Copyright (c) 2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { sha256d } from './hash.js';
+import { Writer } from './io/writer.js';
+import { WriterBytes } from './io/writerbytes.js';
+import { WriterLength } from './io/writerlength.js';
+import { writeVarSize } from './io/varsize.js';
+import { isPushOp, Op } from './op.js';
+import { OP_CODESEPARATOR } from './opcode.js';
+import { Script } from './script.js';
+import {
+    SigHashType,
+    SigHashTypeInputs,
+    SigHashTypeOutputs,
+    SigHashTypeVariant,
+} from './sigHashType.js';
+import {
+    DEFAULT_SEQUENCE,
+    SignData,
+    Tx,
+    TxInput,
+    writeOutPoint,
+    writeTxOutput,
+} from './tx.js';
+
+/** An unsigned tx, which helps us build the sighash preimage we need to sign */
+export class UnsignedTx {
+    tx: Tx;
+    prevoutsHash: Uint8Array;
+    sequencesHash: Uint8Array;
+    outputsHash: Uint8Array;
+
+    private constructor(params: {
+        tx: Tx;
+        prevoutsHash: Uint8Array;
+        sequencesHash: Uint8Array;
+        outputsHash: Uint8Array;
+    }) {
+        this.tx = params.tx;
+        this.prevoutsHash = params.prevoutsHash;
+        this.sequencesHash = params.sequencesHash;
+        this.outputsHash = params.outputsHash;
+    }
+
+    /**
+     * Make an UnsignedTx from a Tx, will precompute the fields required to
+     * sign the tx
+     **/
+    public static fromTx(tx: Tx): UnsignedTx {
+        return new UnsignedTx({
+            tx,
+            prevoutsHash: txWriterHash(tx, writePrevouts),
+            sequencesHash: txWriterHash(tx, writeSequences),
+            outputsHash: txWriterHash(tx, writeOutputs),
+        });
+    }
+
+    /**
+     * Make a dummy UnsignedTx from a Tx, will set dummy values for the fields
+     * required to sign the tx. Useful for tx size estimation.
+     **/
+    public static dummyFromTx(tx: Tx): UnsignedTx {
+        return new UnsignedTx({
+            tx,
+            prevoutsHash: new Uint8Array(32),
+            sequencesHash: new Uint8Array(32),
+            outputsHash: new Uint8Array(32),
+        });
+    }
+
+    /** Return the unsigned tx input at the given input index */
+    public inputAt(inputIdx: number): UnsignedTxInput {
+        return new UnsignedTxInput({ inputIdx, unsignedTx: this });
+    }
+}
+
+/** A preimage of a sighash for an input's scriptSig ready to be signed */
+export interface SighashPreimage {
+    /** Bytes of the serialized sighash preimage */
+    bytes: Uint8Array;
+    /** Script code of the preimage, with OP_CODESEPARATOR cut out */
+    scriptCode: Script;
+    /** Redeem script, with no modifications */
+    redeemScript: Script;
+}
+
+// Write the legacy preimage used pre-UAHF.
+// It's modeled closely after SignatureHash in interpreter.cpp.
+function writeLegacyPreimage(
+    writer: Writer,
+    tx: Tx,
+    scriptCode: Script,
+    inputIdx: number,
+    sigHashType: SigHashType,
+) {
+    const hasAnyoneCanPay =
+        sigHashType.inputType === SigHashTypeInputs.ANYONECANPAY;
+
+    const writeLegacyScriptCode = () => {
+        const ops = scriptCode.ops();
+        let nextOp: Op | undefined = undefined;
+        const newOps = [];
+        // Filter out all code separators
+        while ((nextOp = ops.next()) !== undefined) {
+            if (isPushOp(nextOp) || nextOp != OP_CODESEPARATOR) {
+                newOps.push(nextOp);
+            }
+        }
+        Script.fromOps(newOps).writeWithSize(writer);
+    };
+
+    const writeLegacyInput = (idx: number) => {
+        // In case of SIGHASH_ANYONECANPAY, only the input being signed is
+        // serialized
+        if (hasAnyoneCanPay) {
+            idx = inputIdx;
+        }
+        const input = tx.inputs[idx];
+        // Serialize the prevout
+        writeOutPoint(input.prevOut, writer);
+        // Serialize the script
+        if (idx != inputIdx) {
+            // Blank out other inputs' signatures
+            new Script().writeWithSize(writer);
+        } else {
+            writeLegacyScriptCode();
+        }
+        // Serialize the nSequence
+        if (
+            idx != inputIdx &&
+            (sigHashType.outputType === SigHashTypeOutputs.SINGLE ||
+                sigHashType.outputType === SigHashTypeOutputs.NONE)
+        ) {
+            // let the others update at will
+            writer.putU32(0);
+        } else {
+            writer.putU32(input.sequence ?? DEFAULT_SEQUENCE);
+        }
+    };
+
+    const writeLegacyOutput = (idx: number) => {
+        if (
+            sigHashType.outputType === SigHashTypeOutputs.SINGLE &&
+            idx != inputIdx
+        ) {
+            // Do not lock-in the txout payee at other indices as txin
+            writeTxOutput({ value: 0, script: new Script() }, writer);
+        } else {
+            writeTxOutput(tx.outputs[idx], writer);
+        }
+    };
+
+    writer.putU32(tx.version);
+    const numInputs = hasAnyoneCanPay ? 1 : tx.inputs.length;
+    writeVarSize(numInputs, writer);
+    for (let inputIdx = 0; inputIdx < numInputs; ++inputIdx) {
+        writeLegacyInput(inputIdx);
+    }
+
+    // Serialize vout
+    const numOutputs = (() => {
+        switch (sigHashType.outputType) {
+            case SigHashTypeOutputs.NONE:
+                return 0;
+            case SigHashTypeOutputs.SINGLE:
+                return inputIdx + 1;
+            default:
+                return tx.outputs.length;
+        }
+    })();
+    writeVarSize(numOutputs, writer);
+    for (let outputIdx = 0; outputIdx < numOutputs; outputIdx++) {
+        writeLegacyOutput(outputIdx);
+    }
+
+    // Serialize nLockTime
+    writer.putU32(tx.locktime);
+
+    // Serialize sigHashType
+    writer.putU32(sigHashType.toInt());
+}
+
+/**
+ * An unsigned tx input, can be used to build a sighash preimage ready to be
+ * signed
+ **/
+export class UnsignedTxInput {
+    inputIdx: number;
+    unsignedTx: UnsignedTx;
+
+    public constructor(params: { inputIdx: number; unsignedTx: UnsignedTx }) {
+        this.inputIdx = params.inputIdx;
+        this.unsignedTx = params.unsignedTx;
+    }
+
+    /**
+     * Build the sigHashPreimage for this input, with the given sigHashType
+     * and OP_CODESEPARATOR index
+     **/
+    public sigHashPreimage(
+        sigHashType: SigHashType,
+        nCodesep?: number,
+    ): SighashPreimage {
+        const tx = this.unsignedTx.tx;
+        const input = tx.inputs[this.inputIdx];
+        if (input.signData === undefined) {
+            throw new Error('Input must have signData set');
+        }
+        const signData = input.signData;
+        const redeemScript = signDataScriptCode(input.signData);
+        const scriptCode =
+            nCodesep === undefined
+                ? redeemScript
+                : redeemScript.cutOutCodesep(nCodesep);
+
+        // Sign LEGACY signatures that don't use SIGHASH_FORKID
+        if (sigHashType.variant === SigHashTypeVariant.LEGACY) {
+            if (
+                sigHashType.outputType == SigHashTypeOutputs.SINGLE &&
+                this.inputIdx >= tx.outputs.length
+            ) {
+                throw new Error(
+                    'Invalid usage of SINGLE, input has no corresponding output',
+                );
+            }
+
+            const writePreimage = (writer: Writer) => {
+                writeLegacyPreimage(
+                    writer,
+                    this.unsignedTx.tx,
+                    scriptCode,
+                    this.inputIdx,
+                    sigHashType,
+                );
+            };
+            const preimageWriterLen = new WriterLength();
+            writePreimage(preimageWriterLen);
+            const preimageWriter = new WriterBytes(preimageWriterLen.length);
+            writePreimage(preimageWriter);
+
+            return {
+                bytes: preimageWriter.data,
+                scriptCode,
+                redeemScript,
+            };
+        }
+
+        let hashOutputs: Uint8Array;
+        switch (sigHashType.outputType) {
+            case SigHashTypeOutputs.ALL:
+                hashOutputs = this.unsignedTx.outputsHash;
+                break;
+            case SigHashTypeOutputs.NONE:
+                hashOutputs = new Uint8Array(32);
+                break;
+            case SigHashTypeOutputs.SINGLE:
+                if (this.inputIdx < tx.outputs.length) {
+                    const output = tx.outputs[this.inputIdx];
+                    const writerOutputLength = new WriterLength();
+                    writeTxOutput(output, writerOutputLength);
+                    const writerOutput = new WriterBytes(
+                        writerOutputLength.length,
+                    );
+                    writeTxOutput(output, writerOutput);
+                    hashOutputs = sha256d(writerOutput.data);
+                } else {
+                    hashOutputs = new Uint8Array(32);
+                }
+                break;
+        }
+
+        const writePreimage = (writer: Writer) => {
+            writer.putU32(tx.version);
+            if (sigHashType.inputType == SigHashTypeInputs.FIXED) {
+                writer.putBytes(this.unsignedTx.prevoutsHash);
+            } else {
+                writer.putBytes(new Uint8Array(32));
+            }
+            if (
+                sigHashType.inputType == SigHashTypeInputs.FIXED &&
+                sigHashType.outputType == SigHashTypeOutputs.ALL
+            ) {
+                writer.putBytes(this.unsignedTx.sequencesHash);
+            } else {
+                writer.putBytes(new Uint8Array(32));
+            }
+            writeOutPoint(input.prevOut, writer);
+            scriptCode.writeWithSize(writer);
+            writer.putU64(signData.value);
+            writer.putU32(input.sequence ?? DEFAULT_SEQUENCE);
+            writer.putBytes(hashOutputs);
+            writer.putU32(tx.locktime);
+            writer.putU32(sigHashType.toInt());
+        };
+
+        const preimageWriterLen = new WriterLength();
+        writePreimage(preimageWriterLen);
+        const preimageWriter = new WriterBytes(preimageWriterLen.length);
+        writePreimage(preimageWriter);
+
+        return {
+            bytes: preimageWriter.data,
+            scriptCode,
+            redeemScript,
+        };
+    }
+
+    /** Return the TxInput of this UnsignedTxInput */
+    public txInput(): TxInput {
+        return this.unsignedTx.tx.inputs[this.inputIdx];
+    }
+}
+
+/** Find the scriptCode that should be signed */
+function signDataScriptCode(signData: SignData): Script {
+    if (signData.outputScript !== undefined) {
+        if (signData.outputScript.isP2sh()) {
+            throw new Error(
+                'P2SH requires redeemScript to be set, not outputScript',
+            );
+        }
+        return signData.outputScript;
+    }
+    if (signData.redeemScript === undefined) {
+        throw new Error('Must either set outputScript or redeemScript');
+    }
+    return signData.redeemScript;
+}
+
+function txWriterHash(
+    tx: Tx,
+    fn: (tx: Tx, writer: Writer) => void,
+): Uint8Array {
+    const writerLength = new WriterLength();
+    fn(tx, writerLength);
+    const writer = new WriterBytes(writerLength.length);
+    fn(tx, writer);
+    return sha256d(writer.data);
+}
+
+function writePrevouts(tx: Tx, writer: Writer) {
+    for (const input of tx.inputs) {
+        writeOutPoint(input.prevOut, writer);
+    }
+}
+
+function writeSequences(tx: Tx, writer: Writer) {
+    for (const input of tx.inputs) {
+        writer.putU32(input.sequence ?? DEFAULT_SEQUENCE);
+    }
+}
+
+function writeOutputs(tx: Tx, writer: Writer) {
+    for (const output of tx.outputs) {
+        writeTxOutput(output, writer);
+    }
+}

package/tsconfig.json

@@ -11,8 +11,9 @@
         /* Interop Constraints */
         "esModuleInterop": true,
         "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
         /* Type Checking */
         "strict": true
     },
-    "include": ["src/**/*", "tests/**/*", "global.d.ts"]
+    "include": ["src/**/*", "tests/**/*"]
 }