ecash-lib 1.2.2-rc9 → 1.4.0

package/src/hdwallet.ts

@@ -0,0 +1,181 @@
+// 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 { Ecc } from './ecc.js';
+import { hmacSha512 } from './hmac.js';
+import { shaRmd160 } from './hash.js';
+import { Bytes } from './io/bytes.js';
+import { strToBytes } from './io/str.js';
+import { WriterBytes } from './io/writerbytes.js';
+
+const HIGHEST_BIT = 0x80000000;
+
+export class HdNode {
+    private _ecc: Ecc;
+    private _seckey: Uint8Array | undefined;
+    private _pubkey: Uint8Array;
+    private _chainCode: Uint8Array;
+    private _depth: number;
+    private _index: number;
+    private _parentFingerprint: number;
+
+    public constructor(params: {
+        ecc: Ecc;
+        seckey: Uint8Array | undefined;
+        pubkey: Uint8Array;
+        chainCode: Uint8Array;
+        depth: number;
+        index: number;
+        parentFingerprint: number;
+    }) {
+        this._ecc = params.ecc;
+        this._seckey = params.seckey;
+        this._pubkey = params.pubkey;
+        this._chainCode = params.chainCode;
+        this._depth = params.depth;
+        this._index = params.index;
+        this._parentFingerprint = params.parentFingerprint;
+    }
+
+    public seckey(): Uint8Array | undefined {
+        return this._seckey;
+    }
+
+    public pubkey(): Uint8Array {
+        return this._pubkey;
+    }
+
+    public pkh(): Uint8Array {
+        return shaRmd160(this._pubkey);
+    }
+
+    public fingerprint(): Uint8Array {
+        return this.pkh().slice(0, 4);
+    }
+
+    public index(): number {
+        return this._index;
+    }
+
+    public depth(): number {
+        return this._depth;
+    }
+
+    public parentFingerprint(): number {
+        return this._parentFingerprint;
+    }
+
+    public chainCode(): Uint8Array {
+        return this._chainCode;
+    }
+
+    public derive(index: number): HdNode {
+        const isHardened = index >= HIGHEST_BIT;
+        const data = new WriterBytes(1 + 32 + 4);
+        if (isHardened) {
+            if (this._seckey === undefined) {
+                throw new Error('Missing private key for hardened child key');
+            }
+            data.putU8(0);
+            data.putBytes(this._seckey);
+        } else {
+            data.putBytes(this._pubkey);
+        }
+        data.putU32(index, 'BE');
+        const hashed = hmacSha512(this._chainCode, data.data);
+        const hashedLeft = hashed.slice(0, 32);
+        const hashedRight = hashed.slice(32);
+
+        // In case the secret key doesn't lie on the curve, we proceed with the
+        // next index. This is astronomically unlikely but part of the specification.
+        if (!this._ecc.isValidSeckey(hashedLeft)) {
+            return this.derive(index + 1);
+        }
+
+        let seckey: Uint8Array | undefined;
+        let pubkey: Uint8Array;
+        if (this._seckey !== undefined) {
+            try {
+                seckey = this._ecc.seckeyAdd(this._seckey, hashedLeft);
+            } catch (ex) {
+                console.log('Skipping index', index, ':', ex);
+                return this.derive(index + 1);
+            }
+            pubkey = this._ecc.derivePubkey(seckey);
+        } else {
+            try {
+                pubkey = this._ecc.pubkeyAdd(this._pubkey, hashedLeft);
+            } catch (ex) {
+                console.log('Skipping index', index, ':', ex);
+                return this.derive(index + 1);
+            }
+            seckey = undefined;
+        }
+        return new HdNode({
+            ecc: this._ecc,
+            seckey: seckey,
+            pubkey: pubkey,
+            chainCode: hashedRight,
+            depth: this._depth + 1,
+            index,
+            parentFingerprint: new Bytes(this.fingerprint()).readU32('BE'),
+        });
+    }
+
+    public deriveHardened(index: number): HdNode {
+        if (index < 0 || index >= HIGHEST_BIT) {
+            throw new TypeError(
+                `index must be between 0 and ${HIGHEST_BIT}, got ${index}`,
+            );
+        }
+        return this.derive(index + HIGHEST_BIT);
+    }
+
+    public derivePath(path: string): HdNode {
+        let splitPath = path.split('/');
+        if (splitPath[0] === 'm') {
+            if (this._parentFingerprint) {
+                throw new TypeError('Expected master, got child');
+            }
+            splitPath = splitPath.slice(1);
+        }
+
+        let hd: HdNode = this;
+        for (const step of splitPath) {
+            if (step.slice(-1) === `'`) {
+                hd = hd.deriveHardened(parseInt(step.slice(0, -1), 10));
+            } else {
+                hd = hd.derive(parseInt(step, 10));
+            }
+        }
+
+        return hd;
+    }
+
+    public static fromPrivateKey(
+        ecc: Ecc,
+        seckey: Uint8Array,
+        chainCode: Uint8Array,
+    ): HdNode {
+        return new HdNode({
+            ecc,
+            seckey: seckey,
+            pubkey: ecc.derivePubkey(seckey),
+            chainCode,
+            depth: 0,
+            index: 0,
+            parentFingerprint: 0,
+        });
+    }
+
+    public static fromSeed(ecc: Ecc, seed: Uint8Array): HdNode {
+        if (seed.length < 16 || seed.length > 64) {
+            throw new TypeError('Seed must be between 16 and 64 bytes long');
+        }
+        const hashed = hmacSha512(strToBytes('Bitcoin seed'), seed);
+        const hashedLeft = hashed.slice(0, 32);
+        const hashedRight = hashed.slice(32);
+        return HdNode.fromPrivateKey(ecc, hashedLeft, hashedRight);
+    }
+}

package/src/hmac.ts

@@ -0,0 +1,74 @@
+// 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, sha256Hasher, sha512Hasher } from './hash';
+
+export class Hmac {
+    oHash: Hasher;
+    iHash: Hasher;
+
+    constructor(
+        hashFactory: () => Hasher,
+        blockLength: number,
+        key: Uint8Array,
+    ) {
+        this.oHash = hashFactory();
+        this.iHash = hashFactory();
+        const pad = new Uint8Array(blockLength);
+        if (key.length > blockLength) {
+            const hasher = hashFactory();
+            hasher.update(key);
+            key = hasher.finalize();
+        }
+        pad.set(key, 0);
+
+        for (let i = 0; i < pad.length; i++) {
+            pad[i] ^= 0x36;
+        }
+        this.iHash.update(pad);
+
+        for (let i = 0; i < pad.length; i++) {
+            pad[i] ^= 0x36 ^ 0x5c;
+        }
+        this.oHash.update(pad);
+
+        pad.fill(0);
+    }
+
+    update(data: Uint8Array) {
+        this.iHash.update(data);
+    }
+
+    digest(): Uint8Array {
+        this.oHash.update(this.iHash.finalize());
+        const hash = this.oHash.finalize();
+        this.iHash.free();
+        this.oHash.free();
+        return hash;
+    }
+
+    clone(): Hmac {
+        const clone: Hmac = Object.create(Object.getPrototypeOf(this), {});
+        clone.oHash = this.oHash.clone();
+        clone.iHash = this.iHash.clone();
+        return clone;
+    }
+
+    free() {
+        this.iHash.free();
+        this.oHash.free();
+    }
+}
+
+export function hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array {
+    const hmac = new Hmac(sha256Hasher, 64, key);
+    hmac.update(data);
+    return hmac.digest();
+}
+
+export function hmacSha512(key: Uint8Array, data: Uint8Array): Uint8Array {
+    const hmac = new Hmac(sha512Hasher, 128, key);
+    hmac.update(data);
+    return hmac.digest();
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// 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.
+
+export * from './consts.js';
+export * from './ecc.js';
+export * from './hash.js';
+export * from './op.js';
+export * from './opcode.js';
+export * from './script.js';
+export * from './mnemonic.js';
+export * from './hdwallet.js';
+export * from './address/address.js';
+export * from './sigHashType.js';
+export * from './tx.js';
+export * from './txBuilder.js';
+export * from './unsignedTx.js';
+export * from './io/bytes.js';
+export * from './io/hex.js';
+export * from './io/int.js';
+export * from './io/str.js';
+export * from './io/varsize.js';
+export * from './io/writer.js';
+export * from './io/writerbytes.js';
+export * from './io/writerlength.js';
+export * from './token/alp.js';
+export * from './token/common.js';
+export * from './token/empp.js';
+export * from './token/slp.js';

package/src/indexBrowser.ts

@@ -0,0 +1,6 @@
+// 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.
+
+export * from './index.js';
+export * from './initBrowser.js';

package/src/indexNodeJs.ts

@@ -0,0 +1,6 @@
+// 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.
+
+export * from './index.js';
+export * from './initNodeJs.js';

package/src/initBrowser.ts

@@ -0,0 +1,21 @@
+// 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 { __setEcc } from './ecc.js';
+import __wbg_init, * as ffi from './ffi/ecash_lib_wasm_browser.js';
+import { __setHashes } from './hash.js';
+
+/** Load and initialize the WASM module for Web */
+export async function initWasm() {
+    await __wbg_init();
+    __setEcc(ffi.Ecc);
+    __setHashes({
+        sha256: ffi.sha256,
+        sha256d: ffi.sha256d,
+        shaRmd160: ffi.shaRmd160,
+        sha512: ffi.sha512,
+        Sha256H: ffi.Sha256H,
+        Sha512H: ffi.Sha512H,
+    });
+}

package/src/initNodeJs.ts

@@ -0,0 +1,20 @@
+// 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 { __setEcc } from './ecc.js';
+import * as ffi from './ffi/ecash_lib_wasm_nodejs.js';
+import { __setHashes } from './hash.js';
+
+/** Load and initialize the WASM module for NodeJS */
+export async function initWasm() {
+    __setEcc(ffi.Ecc);
+    __setHashes({
+        sha256: ffi.sha256,
+        sha256d: ffi.sha256d,
+        shaRmd160: ffi.shaRmd160,
+        sha512: ffi.sha512,
+        Sha256H: ffi.Sha256H,
+        Sha512H: ffi.Sha512H,
+    });
+}

package/src/io/bytes.ts

@@ -0,0 +1,80 @@
+// 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.
+
+export type Endian = 'LE' | 'BE';
+
+export function endianToBool(endian?: Endian): boolean {
+    if (!endian) {
+        // By default, little endian
+        return true;
+    }
+    return endian === 'LE';
+}
+
+/** Reads ints/bytes from a Uint8Array. All integers are little-endian. */
+export class Bytes {
+    public data: Uint8Array;
+    public view: DataView;
+    public idx: number;
+
+    /** Create a new Bytes that reads from the given data */
+    public constructor(data: Uint8Array) {
+        this.data = data;
+        this.view = new DataView(
+            this.data.buffer,
+            this.data.byteOffset,
+            this.data.byteLength,
+        );
+        this.idx = 0;
+    }
+
+    /** Read a single byte */
+    public readU8(): number {
+        this.ensureSize(1);
+        const result = this.data[this.idx];
+        this.idx++;
+        return result;
+    }
+
+    /** Read 2-byte little-endian integer (uint16_t) */
+    public readU16(endian?: Endian): number {
+        this.ensureSize(2);
+        const result = this.view.getUint16(this.idx, endianToBool(endian));
+        this.idx += 2;
+        return result;
+    }
+
+    /** Read 4-byte little-endian integer (uint32_t) */
+    public readU32(endian?: Endian): number {
+        this.ensureSize(4);
+        const result = this.view.getUint32(this.idx, endianToBool(endian));
+        this.idx += 4;
+        return result;
+    }
+
+    /** Read 8-byte little-endian integer (uint64_t) */
+    public readU64(endian?: Endian): bigint {
+        this.ensureSize(8);
+        const result = this.view.getBigUint64(this.idx, endianToBool(endian));
+        this.idx += 8;
+        return result;
+    }
+
+    /** Read the given number of bytes as array */
+    public readBytes(numBytes: number): Uint8Array {
+        this.ensureSize(numBytes);
+        const result = this.data.slice(this.idx, this.idx + numBytes);
+        this.idx += numBytes;
+        return result;
+    }
+
+    private ensureSize(extraBytes: number) {
+        if (this.data.length < this.idx + extraBytes) {
+            throw (
+                `Not enough bytes: Tried reading ${extraBytes} byte(s), but ` +
+                `there are only ${this.data.length - this.idx} byte(s) left`
+            );
+        }
+    }
+}

package/src/io/hex.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2023-2024 The Bitcoin developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+const LUT_HEX_4b = [
+    '0',
+    '1',
+    '2',
+    '3',
+    '4',
+    '5',
+    '6',
+    '7',
+    '8',
+    '9',
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+];
+const LUT_HEX_8b = new Array(0x100);
+const LUT_BIN_8b: { [key: string]: number } = {};
+for (let n = 0; n < 0x100; n++) {
+    const hex = `${LUT_HEX_4b[(n >>> 4) & 0xf]}${LUT_HEX_4b[n & 0xf]}`;
+    LUT_HEX_8b[n] = hex;
+    LUT_BIN_8b[hex] = n;
+}
+// End Pre-Init
+
+export function toHex(buffer: Uint8Array): string {
+    let out = '';
+    for (let idx = 0, edx = buffer.length; idx < edx; ++idx) {
+        out += LUT_HEX_8b[buffer[idx]];
+    }
+    return out;
+}
+
+export function toHexRev(buffer: Uint8Array): string {
+    let out = '';
+    for (let idx = buffer.length - 1; idx >= 0; --idx) {
+        out += LUT_HEX_8b[buffer[idx]];
+    }
+    return out;
+}
+
+export function fromHex(str: string): Uint8Array {
+    if ((str.length & 1) != 0) {
+        throw new Error(`Odd hex length: ${str}`);
+    }
+    const nBytes = str.length >> 1;
+    const array = new Uint8Array(nBytes);
+    for (let idx = 0; idx < str.length; idx += 2) {
+        const pair = str.substring(idx, idx + 2);
+        const byte = LUT_BIN_8b[pair];
+        if (byte === undefined) {
+            throw new Error(`Invalid hex pair: ${pair}, at index ${idx}`);
+        }
+        array[idx >> 1] = byte;
+    }
+    return array;
+}
+
+export function fromHexRev(str: string): Uint8Array {
+    const array = fromHex(str);
+    array.reverse();
+    return array;
+}

package/src/io/int.ts

@@ -0,0 +1,6 @@
+// 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.
+
+/** Union type which can either be a normal JS Number or a BigInt. */
+export type Int = number | bigint;

package/src/io/str.ts

@@ -0,0 +1,16 @@
+// 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.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Turn a UTF-8 encoded string into a Uint8Array */
+export function strToBytes(str: string): Uint8Array {
+    return encoder.encode(str);
+}
+
+/** Turn a Uint8Array into a UTF-8 encoded string */
+export function bytesToStr(bytes: Uint8Array): string {
+    return decoder.decode(bytes);
+}

package/src/io/varsize.ts

@@ -0,0 +1,49 @@
+// 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 './bytes.js';
+import { Writer } from './writer.js';
+import { Int } from './int.js';
+
+/**
+ * Read a VARINT, which encodes a size in the Bitcoin protocol, see:
+ * https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+ */
+export function readVarSize(bytes: Bytes): Int {
+    const firstByte = bytes.readU8();
+    if (firstByte <= 0xfc) {
+        return firstByte;
+    } else if (firstByte == 0xfd) {
+        return bytes.readU16();
+    } else if (firstByte == 0xfe) {
+        return bytes.readU32();
+    } else if (firstByte == 0xff) {
+        return bytes.readU64();
+    } else {
+        throw 'Unreachable';
+    }
+}
+
+/**
+ * Write a VARINT, which encodes a size in the Bitcoin protocol, see:
+ * https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+ * @param size Size integer to write
+ * @param writer Writer to write the size to
+ */
+export function writeVarSize(size: Int, writer: Writer) {
+    if (size <= 0xfc) {
+        writer.putU8(size);
+    } else if (size <= 0xffff) {
+        writer.putU8(0xfd);
+        writer.putU16(size);
+    } else if (size <= 0xffffffff) {
+        writer.putU8(0xfe);
+        writer.putU32(size);
+    } else if (size <= 0xffffffffffffffffn) {
+        writer.putU8(0xff);
+        writer.putU64(size);
+    } else {
+        throw 'Integer too big for VarSize';
+    }
+}

package/src/io/writer.ts

@@ -0,0 +1,20 @@
+// 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';
+
+/** Writer interface to abstract over writing Bitcoin objects */
+export interface Writer {
+    /** Write a single byte */
+    putU8(value: Int): void;
+    /** Write a 2-byte little-endian integer (uint16_t) */
+    putU16(value: Int, endian?: Endian): void;
+    /** Write a 4-byte little-endian integer (uint32_t) */
+    putU32(value: Int, endian?: Endian): void;
+    /** Write an 8-byte little-endian integer (uint64_t) */
+    putU64(value: Int, endian?: Endian): void;
+    /** Write the given bytes */
+    putBytes(bytes: Uint8Array): void;
+}

package/src/io/writerbytes.ts

@@ -0,0 +1,87 @@
+// 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, endianToBool } from './bytes.js';
+import { Int } from './int.js';
+import { Writer } from './writer.js';
+
+/**
+ * Implementation of `Writer` which writes to an array of pre-allocated size.
+ * It's intended to be used in unison with `WriterLength`, which first finds
+ * out the length of the serialized object and then the actual data is written
+ * using this class.
+ **/
+export class WriterBytes implements Writer {
+    public data: Uint8Array;
+    public view: DataView;
+    public idx: number;
+
+    /** Create a new WriterBytes with the given pre-allocated size */
+    public constructor(length: number) {
+        this.data = new Uint8Array(length);
+        this.view = new DataView(
+            this.data.buffer,
+            this.data.byteOffset,
+            this.data.byteLength,
+        );
+        this.idx = 0;
+    }
+
+    /** Write a single byte */
+    public putU8(value: Int): void {
+        if (value < 0 || value > 0xff) {
+            throw new Error(`Cannot fit ${value} into a u8`);
+        }
+        this.ensureSize(1);
+        this.data[this.idx] = Number(value);
+        this.idx++;
+    }
+
+    /** Write a 2-byte little-endian integer (uint16_t) */
+    public putU16(value: Int, endian?: Endian): void {
+        if (value < 0 || value > 0xffff) {
+            throw new Error(`Cannot fit ${value} into a u16`);
+        }
+        this.ensureSize(2);
+        this.view.setUint16(this.idx, Number(value), endianToBool(endian));
+        this.idx += 2;
+    }
+
+    /** Write a 4-byte little-endian integer (uint32_t) */
+    public putU32(value: Int, endian?: Endian): void {
+        if (value < 0 || value > 0xffffffff) {
+            throw new Error(`Cannot fit ${value} into a u32`);
+        }
+        this.ensureSize(4);
+        this.view.setUint32(this.idx, Number(value), endianToBool(endian));
+        this.idx += 4;
+    }
+
+    /** Write an 8-byte little-endian integer (uint64_t) */
+    public putU64(value: Int, endian?: Endian): void {
+        if (value < 0 || value > 0xffffffffffffffffn) {
+            throw new Error(`Cannot fit ${value} into a u64`);
+        }
+        this.ensureSize(8);
+        this.view.setBigUint64(this.idx, BigInt(value), endianToBool(endian));
+        this.idx += 8;
+    }
+
+    /** Write the given bytes */
+    public putBytes(bytes: Uint8Array): void {
+        this.ensureSize(bytes.length);
+        this.data.set(bytes, this.idx);
+        this.idx += bytes.length;
+    }
+
+    private ensureSize(extraBytes: number) {
+        if (this.data.length < this.idx + extraBytes) {
+            throw new Error(
+                `Not enough bytes: Tried writing ${extraBytes} byte(s), but ` +
+                    `only ${this.data.length - this.idx} byte(s) have been ` +
+                    `pre-allocated`,
+            );
+        }
+    }
+}