ecash-lib 1.2.2-rc9 → 1.4.0

package/src/io/writerlength.ts

@@ -0,0 +1,44 @@
+// 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 { Endian } from './bytes.js';
+import { Int } from './int.js';
+import { Writer } from './writer.js';
+
+/**
+ * Writer implementation which only measures the length of the serialized
+ * output but doesn't actually store any byte data.
+ **/
+export class WriterLength implements Writer {
+    public length: number;
+
+    public constructor() {
+        this.length = 0;
+    }
+
+    /** Write a single byte */
+    public putU8(_value: Int): void {
+        this.length++;
+    }
+
+    /** Write a 2-byte little-endian integer (uint16_t) */
+    public putU16(_value: Int, _endian?: Endian): void {
+        this.length += 2;
+    }
+
+    /** Write a 4-byte little-endian integer (uint32_t) */
+    public putU32(_value: Int, _endian?: Endian): void {
+        this.length += 4;
+    }
+
+    /** Write an 8-byte little-endian integer (uint64_t) */
+    public putU64(_value: Int, _endian?: Endian): void {
+        this.length += 8;
+    }
+
+    /** Write the given bytes */
+    public putBytes(bytes: Uint8Array): void {
+        this.length += bytes.length;
+    }
+}

package/src/mnemonic.ts

@@ -0,0 +1,153 @@
+// Copyright (c) 2025 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { sha256, sha512Hasher } from './hash';
+import { strToBytes } from './indexNodeJs';
+import { pbkdf2 } from './pbkdf2';
+
+const BITS_PER_BYTE = 8;
+const BITS_PER_WORD = 11;
+const BITS_PER_CHECKSUM_BIT = 32;
+
+// Calculate how many bits there are in the mnemonic
+function calcNumChecksumBits(numEntropyBytes: number): number {
+    return (numEntropyBytes * BITS_PER_BYTE) / BITS_PER_CHECKSUM_BIT;
+}
+
+// Normalize according to unicode standard
+function normalize(str?: string): string {
+    return (str || '').normalize('NFKD');
+}
+
+// Turn the password into a salt for seed generation
+function salt(password?: string): string {
+    return 'mnemonic' + (password || '');
+}
+
+/** Word list to generate a seed phrase. */
+export interface WordList {
+    /** Word separator of the seed phrase (Japanese has \u3000 as space) */
+    separator: string;
+    /** Words in the word list to generate a mnemonic phrase */
+    words: string[];
+}
+
+/** Derive the mnemonic from entropy */
+export function entropyToMnemonic(
+    entropy: Uint8Array,
+    wordlist: WordList,
+): string {
+    if (entropy.length < 16 || entropy.length > 32) {
+        throw new TypeError('Entropy must be between 16 and 32 bytes long');
+    }
+    if (entropy.length % 4 !== 0) {
+        throw new TypeError('Entropy length must be divisible by 4');
+    }
+
+    const checksum = sha256(entropy);
+    const data = new Uint8Array(entropy.length + checksum.length);
+    data.set(entropy, 0);
+    data.set(checksum, entropy.length);
+
+    let nextBits = 0;
+    let numBits = 0;
+    let numLeftoverBits =
+        entropy.length * BITS_PER_BYTE + calcNumChecksumBits(entropy.length);
+    const words = [];
+    for (const byte of data) {
+        nextBits = (nextBits << BITS_PER_BYTE) | byte;
+        numBits += BITS_PER_BYTE;
+        if (numBits >= BITS_PER_WORD) {
+            const wordIdx = nextBits >> (numBits - BITS_PER_WORD);
+            words.push(wordlist.words[wordIdx]);
+            if (numLeftoverBits <= BITS_PER_WORD) {
+                break;
+            }
+            numBits -= BITS_PER_WORD;
+            numLeftoverBits -= BITS_PER_WORD;
+            nextBits &= 0x7ff >> (BITS_PER_WORD - numBits);
+        }
+    }
+
+    return words.join(wordlist.separator);
+}
+
+/** Recover the entropy from the mnemonic */
+export function mnemonicToEntropy(
+    phrase: string,
+    wordlist: string[],
+): Uint8Array {
+    const words = normalize(phrase).split(' ');
+    if (words.length < 12 || words.length > 24) {
+        throw new Error(
+            'Number of words in mnemonic phrase must be between 12 and 24',
+        );
+    }
+    if (words.length % 3 !== 0) {
+        throw new Error(
+            'Number of words in mnemonic phrase must be divisible by 3',
+        );
+    }
+
+    const wordIndices = words.map(word => {
+        const idx = wordlist.indexOf(word);
+        if (idx === -1) {
+            throw new Error('Invalid mnemonic phrase word: ' + word);
+        }
+        return idx;
+    });
+
+    const numEntropyBytes = (wordIndices.length / 3) * 4;
+    let nextBits = 0;
+    let numBits = 0;
+    let idx = 0;
+    const entropy = new Uint8Array(numEntropyBytes);
+    let checksum = 0;
+    for (const wordIdx of wordIndices) {
+        nextBits = (nextBits << BITS_PER_WORD) | wordIdx;
+        numBits += BITS_PER_WORD;
+        while (numBits >= BITS_PER_BYTE) {
+            const byte = nextBits >> (numBits - BITS_PER_BYTE);
+            if (idx < entropy.length) {
+                entropy[idx] = byte;
+            } else {
+                checksum = (checksum << BITS_PER_BYTE) | byte;
+            }
+            idx++;
+            numBits -= BITS_PER_BYTE;
+            nextBits &= 0xffff >> (16 - numBits);
+        }
+    }
+    if (numBits != 0) {
+        checksum = (checksum << BITS_PER_BYTE) | nextBits;
+    }
+
+    const entropyHash = sha256(entropy);
+    const numChecksumBits = calcNumChecksumBits(numEntropyBytes);
+    const expectedChecksum =
+        entropyHash[0] >> (BITS_PER_BYTE - numChecksumBits);
+
+    if (checksum != expectedChecksum) {
+        const expected = expectedChecksum.toString(16);
+        const actual = checksum.toString(16);
+        throw new Error(
+            `Invalid checksum: expected ${expected}, got ${actual}`,
+        );
+    }
+
+    return entropy;
+}
+
+/** Derive the seed bytes from the mnemonic */
+export function mnemonicToSeed(phrase: string, password?: string): Uint8Array {
+    return pbkdf2({
+        hashFactory: sha512Hasher,
+        password: strToBytes(normalize(phrase)),
+        salt: strToBytes(salt(normalize(password))),
+        blockLength: 128,
+        outputLength: 64,
+        dkLen: 64,
+        iterations: 2048,
+    });
+}

package/src/op.ts

@@ -0,0 +1,162 @@
+// 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 { Bytes } from './io/bytes.js';
+import { Writer } from './io/writer.js';
+import {
+    OP_0,
+    OP_1NEGATE,
+    OP_PUSHDATA1,
+    OP_PUSHDATA2,
+    OP_PUSHDATA4,
+    Opcode,
+} from './opcode.js';
+
+/**
+ * A single operation in Bitcoin script, either a singular non-pushop code or
+ * a `PushOp` with an opcode and data attached.
+ **/
+export type Op = Opcode | PushOp;
+
+/**
+ * An Op that pushes some data onto the stack, will use `opcode` to push the
+ * data
+ **/
+export interface PushOp {
+    opcode: Opcode;
+    data: Uint8Array;
+}
+
+/** Returns true if the given object is a `PushOp` */
+export function isPushOp(op: any): op is PushOp {
+    if (!op || typeof op !== 'object') {
+        return false;
+    }
+    if (!op.hasOwnProperty('opcode') || !op.hasOwnProperty('data')) {
+        return false;
+    }
+    return typeof op.opcode === 'number' && op.data instanceof Uint8Array;
+}
+
+/** Read a single Script operation from the bytes */
+export function readOp(bytes: Bytes): Op {
+    const opcode = bytes.readU8();
+    let numBytes: number;
+    switch (opcode) {
+        case OP_PUSHDATA1:
+            numBytes = bytes.readU8();
+            break;
+        case OP_PUSHDATA2:
+            numBytes = bytes.readU16();
+            break;
+        case OP_PUSHDATA4:
+            numBytes = bytes.readU32();
+            break;
+        default:
+            if (opcode < 0x01 || opcode > 0x4b) {
+                // Non-push opcode
+                return opcode;
+            }
+            numBytes = opcode;
+    }
+    const data = bytes.readBytes(numBytes);
+    return { opcode, data };
+}
+
+/** Write a Script operation to the writer */
+export function writeOp(op: Op, writer: Writer) {
+    if (typeof op == 'number') {
+        writer.putU8(op);
+        return;
+    }
+    if (!isPushOp(op)) {
+        throw `Unexpected op: ${op}`;
+    }
+    writer.putU8(op.opcode);
+    switch (op.opcode) {
+        case OP_PUSHDATA1:
+            writer.putU8(op.data.length);
+            break;
+        case OP_PUSHDATA2:
+            writer.putU16(op.data.length);
+            break;
+        case OP_PUSHDATA4:
+            writer.putU32(op.data.length);
+            break;
+        default:
+            if (op.opcode < 0 || op.opcode > 0x4b) {
+                throw `Not a pushop opcode: 0x${op.opcode.toString(16)}`;
+            }
+            if (op.opcode != op.data.length) {
+                throw (
+                    `Inconsistent PushOp, claims to push ${op.opcode} bytes ` +
+                    `but actually has ${op.data.length} bytes attached`
+                );
+            }
+    }
+    writer.putBytes(op.data);
+}
+
+/** Return an Op that minimally pushes the given bytes onto the stack */
+export function pushBytesOp(data: Uint8Array): Op {
+    if (data.length == 0) {
+        return OP_0;
+    } else if (data.length == 1) {
+        if (data[0] >= 1 && data[0] <= 16) {
+            return data[0] + 0x50;
+        } else if (data[0] == 0x81) {
+            return OP_1NEGATE;
+        }
+    }
+    let opcode: Opcode;
+    if (data.length >= 0x01 && data.length <= 0x4b) {
+        opcode = data.length;
+    } else if (data.length >= 0x4c && data.length <= 0xff) {
+        opcode = OP_PUSHDATA1;
+    } else if (data.length >= 0x100 && data.length <= 0xffff) {
+        opcode = OP_PUSHDATA2;
+    } else if (data.length >= 0x10000 && data.length <= 0xffffffff) {
+        opcode = OP_PUSHDATA4;
+    } else {
+        throw 'Bytes way too large';
+    }
+    return { opcode, data };
+}
+
+/**
+ * Returns an Op that pushes the minimally encoded byte representation of a
+ * number to the stack. The bytes pushed to the stack can be used directly
+ * without the need for OP_BIN2NUM.
+ */
+export function pushNumberOp(value: number | bigint): Op {
+    if (value == 0) {
+        return OP_0;
+    }
+
+    // Prepare number for encoding. The algorithm below replicates the one used
+    // in `src/script/script.h` intentionally to avoid discrepancies.
+    const auxValue = BigInt(value);
+    let bytes: number[] = [];
+    let negative = auxValue < 0;
+    let absvalue = negative ? ~auxValue + 1n : auxValue;
+
+    // Encode value in little endian byte order by iteratively pushing the
+    // least significant byte until shifting right 1 more byte produces 0
+    while (absvalue) {
+        bytes.push(Number(absvalue & 0xffn));
+        absvalue >>= 8n;
+    }
+
+    // The MSB will encode the sign which means that, if the previous encoding
+    // of the absolute value uses that bit, a new byte must be added to encode
+    // the sign. If bit is not set, then it must be set for negative numbers.
+    let last = bytes[bytes.length - 1];
+    if (last & 0x80) {
+        bytes.push(negative ? 0x80 : 0x00);
+    } else if (negative) {
+        bytes[bytes.length - 1] = last | 0x80;
+    }
+
+    return pushBytesOp(Uint8Array.from(bytes));
+}

package/src/opcode.ts

@@ -0,0 +1,154 @@
+// 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.
+
+// Script opcodes, from /src/script/script.h
+
+export type Opcode = number;
+
+// push value
+export const OP_0 = 0x00;
+export const OP_FALSE = OP_0;
+export const OP_PUSHDATA1 = 0x4c;
+export const OP_PUSHDATA2 = 0x4d;
+export const OP_PUSHDATA4 = 0x4e;
+export const OP_1NEGATE = 0x4f;
+export const OP_RESERVED = 0x50;
+export const OP_1 = 0x51;
+export const OP_TRUE = OP_1;
+export const OP_2 = 0x52;
+export const OP_3 = 0x53;
+export const OP_4 = 0x54;
+export const OP_5 = 0x55;
+export const OP_6 = 0x56;
+export const OP_7 = 0x57;
+export const OP_8 = 0x58;
+export const OP_9 = 0x59;
+export const OP_10 = 0x5a;
+export const OP_11 = 0x5b;
+export const OP_12 = 0x5c;
+export const OP_13 = 0x5d;
+export const OP_14 = 0x5e;
+export const OP_15 = 0x5f;
+export const OP_16 = 0x60;
+
+// control
+export const OP_NOP = 0x61;
+export const OP_VER = 0x62;
+export const OP_IF = 0x63;
+export const OP_NOTIF = 0x64;
+export const OP_VERIF = 0x65;
+export const OP_VERNOTIF = 0x66;
+export const OP_ELSE = 0x67;
+export const OP_ENDIF = 0x68;
+export const OP_VERIFY = 0x69;
+export const OP_RETURN = 0x6a;
+
+// stack ops
+export const OP_TOALTSTACK = 0x6b;
+export const OP_FROMALTSTACK = 0x6c;
+export const OP_2DROP = 0x6d;
+export const OP_2DUP = 0x6e;
+export const OP_3DUP = 0x6f;
+export const OP_2OVER = 0x70;
+export const OP_2ROT = 0x71;
+export const OP_2SWAP = 0x72;
+export const OP_IFDUP = 0x73;
+export const OP_DEPTH = 0x74;
+export const OP_DROP = 0x75;
+export const OP_DUP = 0x76;
+export const OP_NIP = 0x77;
+export const OP_OVER = 0x78;
+export const OP_PICK = 0x79;
+export const OP_ROLL = 0x7a;
+export const OP_ROT = 0x7b;
+export const OP_SWAP = 0x7c;
+export const OP_TUCK = 0x7d;
+
+// splice ops
+export const OP_CAT = 0x7e;
+export const OP_SPLIT = 0x7f; // after monolith upgrade (May 2018)
+export const OP_NUM2BIN = 0x80; // after monolith upgrade (May 2018)
+export const OP_BIN2NUM = 0x81; // after monolith upgrade (May 2018)
+export const OP_SIZE = 0x82;
+
+// bit logic
+export const OP_INVERT = 0x83;
+export const OP_AND = 0x84;
+export const OP_OR = 0x85;
+export const OP_XOR = 0x86;
+export const OP_EQUAL = 0x87;
+export const OP_EQUALVERIFY = 0x88;
+export const OP_RESERVED1 = 0x89;
+export const OP_RESERVED2 = 0x8a;
+
+// numeric
+export const OP_1ADD = 0x8b;
+export const OP_1SUB = 0x8c;
+export const OP_2MUL = 0x8d;
+export const OP_2DIV = 0x8e;
+export const OP_NEGATE = 0x8f;
+export const OP_ABS = 0x90;
+export const OP_NOT = 0x91;
+export const OP_0NOTEQUAL = 0x92;
+
+export const OP_ADD = 0x93;
+export const OP_SUB = 0x94;
+export const OP_MUL = 0x95;
+export const OP_DIV = 0x96;
+export const OP_MOD = 0x97;
+export const OP_LSHIFT = 0x98;
+export const OP_RSHIFT = 0x99;
+
+export const OP_BOOLAND = 0x9a;
+export const OP_BOOLOR = 0x9b;
+export const OP_NUMEQUAL = 0x9c;
+export const OP_NUMEQUALVERIFY = 0x9d;
+export const OP_NUMNOTEQUAL = 0x9e;
+export const OP_LESSTHAN = 0x9f;
+export const OP_GREATERTHAN = 0xa0;
+export const OP_LESSTHANOREQUAL = 0xa1;
+export const OP_GREATERTHANOREQUAL = 0xa2;
+export const OP_MIN = 0xa3;
+export const OP_MAX = 0xa4;
+
+export const OP_WITHIN = 0xa5;
+
+// crypto
+export const OP_RIPEMD160 = 0xa6;
+export const OP_SHA1 = 0xa7;
+export const OP_SHA256 = 0xa8;
+export const OP_HASH160 = 0xa9;
+export const OP_HASH256 = 0xaa;
+export const OP_CODESEPARATOR = 0xab;
+export const OP_CHECKSIG = 0xac;
+export const OP_CHECKSIGVERIFY = 0xad;
+export const OP_CHECKMULTISIG = 0xae;
+export const OP_CHECKMULTISIGVERIFY = 0xaf;
+
+// expansion
+export const OP_NOP1 = 0xb0;
+export const OP_CHECKLOCKTIMEVERIFY = 0xb1;
+export const OP_NOP2 = OP_CHECKLOCKTIMEVERIFY;
+export const OP_CHECKSEQUENCEVERIFY = 0xb2;
+export const OP_NOP3 = OP_CHECKSEQUENCEVERIFY;
+export const OP_NOP4 = 0xb3;
+export const OP_NOP5 = 0xb4;
+export const OP_NOP6 = 0xb5;
+export const OP_NOP7 = 0xb6;
+export const OP_NOP8 = 0xb7;
+export const OP_NOP9 = 0xb8;
+export const OP_NOP10 = 0xb9;
+
+// More crypto
+export const OP_CHECKDATASIG = 0xba;
+export const OP_CHECKDATASIGVERIFY = 0xbb;
+
+// additional byte string operations
+export const OP_REVERSEBYTES = 0xbc;
+
+// multi-byte opcodes
+export const OP_PREFIX_BEGIN = 0xf0;
+export const OP_PREFIX_END = 0xf7;
+
+export const OP_INVALIDOPCODE = 0xff;

package/src/pbkdf2.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2025 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import { Hasher } from './hash';
+import { Hmac } from './hmac';
+
+export function pbkdf2(params: {
+    hashFactory: () => Hasher;
+    password: Uint8Array;
+    salt: Uint8Array;
+    blockLength: number;
+    outputLength: number;
+    dkLen: number;
+    iterations: number;
+}): Uint8Array {
+    const arr = new Uint8Array(4);
+    const view = new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
+    const result = new Uint8Array(params.dkLen);
+    const prf = new Hmac(
+        params.hashFactory,
+        params.blockLength,
+        params.password,
+    );
+    const prfSalt = prf.clone();
+    prfSalt.update(params.salt);
+
+    for (
+        let idx = 1, pos = 0;
+        pos < params.dkLen;
+        idx++, pos += params.outputLength
+    ) {
+        const ti = result.subarray(pos, pos + params.outputLength);
+        view.setInt32(0, idx, false);
+        const prfSaltClone = prfSalt.clone();
+        prfSaltClone.update(arr);
+        let u = prfSaltClone.digest();
+        ti.set(u.subarray(0, ti.length));
+        for (let ui = 1; ui < params.iterations; ui++) {
+            const prfClone = prf.clone();
+            prfClone.update(u);
+            u = prfClone.digest();
+            for (let i = 0; i < ti.length; i++) {
+                ti[i] ^= u[i];
+            }
+        }
+    }
+
+    prf.free();
+    prfSalt.free();
+    return result;
+}