@scure/btc-signer 2.0.1 → 2.3.0

package/script.js

@@ -1,8 +1,27 @@
 import * as P from 'micro-packed';
-import { isBytes, reverseObject } from "./utils.js";
+import { aarray, abytes, isBytes, reverseObject, } from "./utils.js";
+/**
+ * Maximum byte size allowed for a single pushed script element.
+ * BIP 342 keeps this 520-byte stack-element limit even though tapscript removes
+ * the old 10,000-byte overall script-size cap.
+ */
 export const MAX_SCRIPT_BYTE_LENGTH = 520;
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
 // prettier-ignore
-export const OP = {
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _8n = /* @__PURE__ */ BigInt(8);
+const U8_MAX = /* @__PURE__ */ BigInt(0xff);
+const COMPACT_DIRECT_MAX = /* @__PURE__ */ BigInt(0xfc);
+// prettier-ignore
+/**
+ * Bitcoin Script opcode table.
+ * @example
+ * Use opcode numbers when you need the raw byte form instead of Script mnemonics.
+ * ```ts
+ * import { OP } from '@scure/btc-signer/script.js';
+ * new Uint8Array([OP.OP_1, OP.OP_2, OP.CHECKMULTISIG]);
+ * ```
+ */
+export const OP = /* @__PURE__ */ Object.freeze({
     OP_0: 0, PUSHDATA1: 76, PUSHDATA2: 77, PUSHDATA4: 78, '1NEGATE': 79,
     RESERVED: 80,
     OP_1: 81, OP_2: 82, OP_3: 83, OP_4: 84, OP_5: 85, OP_6: 86, OP_7: 87, OP_8: 88, OP_9: 89,
@@ -31,20 +50,43 @@ export const OP = {
     CHECKSIGADD: 186,
     // Invalid
     INVALID: 255,
-};
-export const OPNames = reverseObject(OP);
+});
+/**
+ * Reverse lookup map from opcode numbers back to names.
+ * @example
+ * Turn parsed opcode numbers back into their mnemonic names.
+ * ```ts
+ * import { OP, OPNames } from '@scure/btc-signer/script.js';
+ * OPNames[OP.CHECKSIG];
+ * ```
+ */
+export const OPNames = /* @__PURE__ */ (() => Object.freeze(reverseObject(OP)))();
 // We can encode almost any number as ScriptNum, however, parsing will be a problem
 // since we can't know if buffer is a number or something else.
+/**
+ * Coder for Bitcoin Script numbers.
+ * bytesLimit only constrains decode. encode still serializes any bigint in
+ * Script's signed-magnitude byte form so higher-level consumers can enforce
+ * opcode-specific 4-byte or 5-byte bounds separately.
+ * @param bytesLimit - maximum decoded length in bytes
+ * @param forceMinimal - whether to reject non-minimal encodings
+ * @returns Script number coder.
+ * @example
+ * Encode a small integer using Script number rules.
+ * ```ts
+ * ScriptNum().encode(1n);
+ * ```
+ */
 export function ScriptNum(bytesLimit = 6, forceMinimal = false) {
     return P.wrap({
         encodeStream: (w, value) => {
-            if (value === 0n)
+            if (value === _0n)
                 return;
             const neg = value < 0;
             const val = BigInt(value);
             const nums = [];
-            for (let abs = neg ? -val : val; abs; abs >>= 8n)
-                nums.push(Number(abs & 0xffn));
+            for (let abs = neg ? -val : val; abs; abs >>= _8n)
+                nums.push(Number(abs & U8_MAX));
             if (nums[nums.length - 1] >= 0x80)
                 nums.push(neg ? 0x80 : 0);
             else if (neg)
@@ -56,37 +98,52 @@ export function ScriptNum(bytesLimit = 6, forceMinimal = false) {
             if (len > bytesLimit)
                 throw new Error(`ScriptNum: number (${len}) bigger than limit=${bytesLimit}`);
             if (len === 0)
-                return 0n;
+                return _0n;
+            // Read the payload once instead of peeking for the minimality check and
+            // then re-reading it byte-by-byte through the Reader.
+            const data = r.bytes(len);
             if (forceMinimal) {
-                const data = r.bytes(len, true);
                 // MSB is zero (without sign bit) -> not minimally encoded
-                if ((data[data.length - 1] & 0x7f) === 0) {
+                if ((data[len - 1] & 0x7f) === 0) {
                     // exception
-                    if (len <= 1 || (data[data.length - 2] & 0x80) === 0)
+                    if (len <= 1 || (data[len - 2] & 0x80) === 0)
                         throw new Error('Non-minimally encoded ScriptNum');
                 }
             }
-            let last = 0;
-            let res = 0n;
-            for (let i = 0; i < len; ++i) {
-                last = r.byte();
-                res |= BigInt(last) << (8n * BigInt(i));
-            }
-            if (last >= 0x80) {
-                res &= (2n ** BigInt(len * 8) - 1n) >> 1n;
+            let res = _0n;
+            for (let i = 0; i < len; ++i)
+                res |= BigInt(data[i]) << (_8n * BigInt(i));
+            if (data[len - 1] >= 0x80) {
+                res &= (_2n ** BigInt(len * 8) - _1n) >> _1n;
                 res = -res;
             }
             return res;
         },
     });
 }
+/**
+ * Attempts to decode a numeric script element into a JavaScript number.
+ * Accepts decoded small integers already represented as JS numbers and pushed
+ * `ScriptNum` byte payloads, but does not interpret opcode mnemonics like `1NEGATE`.
+ * @param op - script element to decode
+ * @param bytesLimit - maximum encoded length in bytes
+ * @param forceMinimal - whether to enforce minimal `ScriptNum` encoding
+ * @returns Decoded number, or `undefined` when the element is not a JS number or valid `ScriptNum` bytes.
+ * @example
+ * Decode a script element back into a JavaScript number when possible.
+ * ```ts
+ * OpToNum(1);
+ * ```
+ */
 export function OpToNum(op, bytesLimit = 4, forceMinimal = true) {
     if (typeof op === 'number')
         return op;
     if (isBytes(op)) {
         try {
             const val = ScriptNum(bytesLimit, forceMinimal).decode(op);
-            if (val > Number.MAX_SAFE_INTEGER)
+            // Symmetric safe-integer bound: large negative values would otherwise
+            // coerce through Number() with silent precision loss.
+            if (val > Number.MAX_SAFE_INTEGER || val < -Number.MAX_SAFE_INTEGER)
                 return;
             return Number(val);
         }
@@ -96,6 +153,29 @@ export function OpToNum(op, bytesLimit = 4, forceMinimal = true) {
     }
     return;
 }
+// Shared raw pushdata-length parser. Keep this aligned with Script.decodeStream
+// so byte-preserving walkers can skip pushed data without semantic decode/re-encode.
+/**
+ * Returns the pushed-data length for a push opcode.
+ * @param op - opcode byte already read from the script stream
+ * @param read - callback that reads the following 1/2/4-byte little-endian length
+ * @returns Push length for data-carrying opcodes, or `undefined` for non-push opcodes.
+ * @throws If the opcode falls through the recognized push-opcode set unexpectedly.
+ * {@link Error}
+ */
+export const scriptPushLen = (op, read) => {
+    if (!(OP.OP_0 < op && op <= OP.PUSHDATA4))
+        return;
+    if (op < OP.PUSHDATA1)
+        return op;
+    if (op === OP.PUSHDATA1)
+        return read(1);
+    if (op === OP.PUSHDATA2)
+        return read(2);
+    if (op === OP.PUSHDATA4)
+        return read(4);
+    throw new Error('Should be not possible');
+};
 // Converts script bytes to parsed script
 // 5221030000000000000000000000000000000000000000000000000000000000000001210300000000000000000000000000000000000000000000000000000000000000022103000000000000000000000000000000000000000000000000000000000000000353ae
 // =>
@@ -105,13 +185,28 @@ export function OpToNum(op, bytesLimit = 4, forceMinimal = true) {
 //   030000000000000000000000000000000000000000000000000000000000000003
 //   OP_3
 //   CHECKMULTISIG
-export const Script = P.wrap({
+// This is a semantic AST codec, not a byte-preserving parser: encode
+// canonicalizes small integers to OP_n and chooses the shortest push opcode,
+// so decode(...)+encode(...) rewrites non-minimal push spellings.
+/**
+ * Bitcoin script coder.
+ * @example
+ * Encode a short script from opcode mnemonics and small integers.
+ * ```ts
+ * Script.encode(['OP_1', 'OP_2']);
+ * ```
+ */
+export const Script = /* @__PURE__ */ (() => Object.freeze(P.wrap({
     encodeStream: (w, value) => {
+        aarray(value, 'value');
         for (let o of value) {
             if (typeof o === 'string') {
-                if (OP[o] === undefined)
+                const op = OP[o];
+                // OP is a plain object, so inherited Object.prototype keys ('toString',
+                // 'constructor', ...) are not opcodes and must be rejected here too.
+                if (typeof op !== 'number')
                     throw new Error(`Unknown opcode=${o}`);
-                w.byte(OP[o]);
+                w.byte(op);
                 continue;
             }
             else if (typeof o === 'number') {
@@ -119,6 +214,12 @@ export const Script = P.wrap({
                     w.byte(0x00);
                     continue;
                 }
+                else if (o === -1) {
+                    // BIP62 minimal push / number rules spell numeric -1 as OP_1NEGATE
+                    // instead of a pushed ScriptNum payload 0x81.
+                    w.byte(OP['1NEGATE']);
+                    continue;
+                }
                 else if (1 <= o && o <= 16) {
                     w.byte(OP.OP_1 - 1 + o);
                     continue;
@@ -127,8 +228,7 @@ export const Script = P.wrap({
             // Encode big numbers
             if (typeof o === 'number')
                 o = ScriptNum().encode(BigInt(o));
-            if (!isBytes(o))
-                throw new Error(`Wrong Script OP=${o} (${typeof o})`);
+            abytes(o, undefined, 'value');
             // Bytes
             const len = o.length;
             if (len < OP.PUSHDATA1)
@@ -152,19 +252,14 @@ export const Script = P.wrap({
         const out = [];
         while (!r.isEnd()) {
             const cur = r.byte();
-            // if 0 < cur < 78
-            if (OP.OP_0 < cur && cur <= OP.PUSHDATA4) {
-                let len;
-                if (cur < OP.PUSHDATA1)
-                    len = cur;
-                else if (cur === OP.PUSHDATA1)
-                    len = P.U8.decodeStream(r);
-                else if (cur === OP.PUSHDATA2)
-                    len = P.U16LE.decodeStream(r);
-                else if (cur === OP.PUSHDATA4)
-                    len = P.U32LE.decodeStream(r);
-                else
-                    throw new Error('Should be not possible');
+            const len = scriptPushLen(cur, (bytes) => {
+                if (bytes === 1)
+                    return P.U8.decodeStream(r);
+                if (bytes === 2)
+                    return P.U16LE.decodeStream(r);
+                return P.U32LE.decodeStream(r);
+            });
+            if (len !== undefined) {
                 out.push(r.bytes(len));
             }
             else if (cur === 0x00) {
@@ -182,81 +277,209 @@ export const Script = P.wrap({
         }
         return out;
     },
-});
-// BTC specific variable length integer encoding
-// https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
-const CSLimits = {
-    0xfd: [0xfd, 2, 253n, 65535n],
-    0xfe: [0xfe, 4, 65536n, 4294967295n],
-    0xff: [0xff, 8, 4294967296n, 18446744073709551615n],
-};
-export const CompactSize = P.wrap({
-    encodeStream: (w, value) => {
-        if (typeof value === 'number')
-            value = BigInt(value);
-        if (0n <= value && value <= 252n)
-            return w.byte(Number(value));
-        for (const [flag, bytes, start, stop] of Object.values(CSLimits)) {
-            if (start > value || value > stop)
-                continue;
-            w.byte(flag);
+})))();
+/**
+ * Bitcoin CompactSize integer coder.
+ * @example
+ * Encode a CompactSize integer for wire serialization.
+ * ```ts
+ * CompactSize.encode(1n);
+ * ```
+ */
+export const CompactSize = /* @__PURE__ */ (() => {
+    // BTC specific variable length integer encoding
+    // https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer
+    const limits = {
+        0xfd: [0xfd, 2, BigInt(0xfd), BigInt(0xffff)],
+        0xfe: [0xfe, 4, BigInt(0x10000), BigInt(0xffffffff)],
+        0xff: [0xff, 8, BigInt(0x100000000), BigInt('0xffffffffffffffff')],
+    };
+    // Hoisted: Object.values() would otherwise allocate a fresh array on every encode.
+    const limitsList = Object.values(limits);
+    return Object.freeze(P.wrap({
+        encodeStream: (w, value) => {
+            if (typeof value === 'number')
+                value = BigInt(value);
+            if (_0n <= value && value <= COMPACT_DIRECT_MAX)
+                return w.byte(Number(value));
+            for (const [flag, bytes, start, stop] of limitsList) {
+                if (start > value || value > stop)
+                    continue;
+                w.byte(flag);
+                for (let i = 0; i < bytes; i++)
+                    w.byte(Number((value >> (_8n * BigInt(i))) & U8_MAX));
+                return;
+            }
+            throw w.err(`VarInt too big: ${value}`);
+        },
+        decodeStream: (r) => {
+            const b0 = r.byte();
+            if (b0 <= 0xfc)
+                return BigInt(b0);
+            const [_, bytes, start] = limits[b0];
+            let num = _0n;
             for (let i = 0; i < bytes; i++)
-                w.byte(Number((value >> (8n * BigInt(i))) & 0xffn));
-            return;
-        }
-        throw w.err(`VarInt too big: ${value}`);
-    },
-    decodeStream: (r) => {
-        const b0 = r.byte();
-        if (b0 <= 0xfc)
-            return BigInt(b0);
-        const [_, bytes, start] = CSLimits[b0];
-        let num = 0n;
-        for (let i = 0; i < bytes; i++)
-            num |= BigInt(r.byte()) << (8n * BigInt(i));
-        if (num < start)
-            throw r.err(`Wrong CompactSize(${8 * bytes})`);
-        return num;
-    },
-});
+                num |= BigInt(r.byte()) << (_8n * BigInt(i));
+            // BIP 152 / BIP 174: CompactSize fields must use the shortest encoding,
+            // so wider prefixes for smaller values are rejected here.
+            if (num < start)
+                throw r.err(`Wrong CompactSize(${8 * bytes})`);
+            return num;
+        },
+    }));
+})();
 // Same thing, but in number instead of bigint. Checks for safe integer inside
-export const CompactSizeLen = P.apply(CompactSize, P.coders.numberBigint);
+/**
+ * CompactSize coder that decodes into JavaScript numbers.
+ * @example
+ * Use the number-based CompactSize helper when the value fits a JS number.
+ * ```ts
+ * CompactSizeLen.encode(1);
+ * ```
+ */
+export const CompactSizeLen = /* @__PURE__ */ (() => Object.freeze(P.apply(CompactSize, P.coders.numberBigint)))();
 // ui8a of size <CompactSize>
-export const VarBytes = P.bytes(CompactSize);
+// Keep an unwrapped local coder for raw transaction structs. The exported VarBytes surface uses
+// TRet for declaration stability, but RawInput/RawOutput still need the old internal field shape.
+const _VarBytes = /* @__PURE__ */ (() => Object.freeze(P.bytes(CompactSize)))();
+/**
+ * Length-prefixed byte array coder.
+ * @example
+ * Prefix a byte array with its CompactSize length.
+ * ```ts
+ * VarBytes.encode(new Uint8Array([1, 2, 3]));
+ * ```
+ */
+export const VarBytes = _VarBytes;
 // SegWit v0 stack of witness buffers
-export const RawWitness = P.array(CompactSizeLen, VarBytes);
+// Raw witness serialization is reused across witness versions and PSBT
+// finalScriptWitness values; version-specific stack and element limits are
+// enforced by the spending rules, not by this byte codec.
+// Same split for raw witness stacks: export the wrapped surface, but keep the raw tx struct coder
+// on the unwrapped local alias so witness arrays inside RawTx keep their previous internal shape.
+const _RawWitness = /* @__PURE__ */ (() => Object.freeze(P.array(CompactSizeLen, _VarBytes)))();
+/**
+ * SegWit witness stack coder.
+ * @example
+ * Encode one witness stack for a SegWit input.
+ * ```ts
+ * RawWitness.encode([new Uint8Array([1])]);
+ * ```
+ */
+export const RawWitness = _RawWitness;
 // Array of size <CompactSize>
+/**
+ * Coder for CompactSize-prefixed arrays.
+ * @param t - element coder
+ * @returns Array coder.
+ * @example
+ * CompactSize-prefix a small list of fixed-width integers.
+ * ```ts
+ * import * as P from 'micro-packed';
+ * import { BTCArray } from '@scure/btc-signer/script.js';
+ * BTCArray(P.U8).encode([1, 2, 3]);
+ * ```
+ */
 export const BTCArray = (t) => P.array(CompactSize, t);
-export const RawInput = P.struct({
+/**
+ * Raw Bitcoin transaction input coder.
+ * @example
+ * Encode one transaction input exactly as it appears on the wire.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { RawInput } from '@scure/btc-signer/script.js';
+ * RawInput.encode({
+ *   txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *   index: 0,
+ *   finalScriptSig: new Uint8Array([0x51]),
+ *   sequence: 0xffffffff,
+ * });
+ * ```
+ */
+export const RawInput = /* @__PURE__ */ (() => Object.freeze(P.struct({
     txid: P.bytes(32, true), // hash(prev_tx),
     index: P.U32LE, // output number of previous tx
-    finalScriptSig: VarBytes, // btc merges input and output script, executes it. If ok = tx passes
+    finalScriptSig: _VarBytes, // btc merges input and output script, executes it. If ok = tx passes
     sequence: P.U32LE, // ?
-});
-export const RawOutput = P.struct({ amount: P.U64LE, script: VarBytes });
+})))();
+/**
+ * Raw Bitcoin transaction output coder.
+ * @example
+ * Encode one transaction output with amount and scriptPubKey.
+ * ```ts
+ * import { RawOutput } from '@scure/btc-signer/script.js';
+ * RawOutput.encode({ amount: 1n, script: new Uint8Array([0x51]) });
+ * ```
+ */
+export const RawOutput = /* @__PURE__ */ (() => Object.freeze(P.struct({ amount: P.U64LE, script: _VarBytes })))();
 // https://en.bitcoin.it/wiki/Protocol_documentation#tx
-const _RawTx = P.struct({
+const _RawTx = /* @__PURE__ */ (() => P.struct({
     version: P.I32LE,
     segwitFlag: P.flag(new Uint8Array([0x00, 0x01])),
     inputs: BTCArray(RawInput),
     outputs: BTCArray(RawOutput),
-    witnesses: P.flagged('segwitFlag', P.array('inputs/length', RawWitness)),
+    // BIP144 does not encode a witness-count field; one RawWitness entry is
+    // implied for each txin and follows the same order as inputs.
+    witnesses: P.flagged('segwitFlag', P.array('inputs/length', _RawWitness)),
     // < 500000000	Block number at which this transaction is unlocked
     // >= 500000000	UNIX timestamp at which this transaction is unlocked
     // Handled as part of PSBTv2
     lockTime: P.U32LE,
-});
+}))();
 function validateRawTx(tx) {
-    if (tx.segwitFlag && tx.witnesses && !tx.witnesses.length)
-        throw new Error('Segwit flag with empty witnesses array');
+    // BIP 144: if every per-input witness field is empty, callers must use the old
+    // serialization format instead of the marker/flag witness form.
+    if (tx.segwitFlag && tx.witnesses && tx.witnesses.every((w) => !w.length))
+        throw new Error('Segwit flag with only empty witness fields');
     return tx;
 }
-export const RawTx = P.validate(_RawTx, validateRawTx);
+/**
+ * Raw Bitcoin transaction coder.
+ * @example
+ * Encode a SegWit transaction with one input, one output, and one witness stack.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { RawTx } from '@scure/btc-signer/script.js';
+ * RawTx.encode({
+ *   version: 2,
+ *   segwitFlag: true,
+ *   inputs: [{
+ *     txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *     index: 0,
+ *     finalScriptSig: new Uint8Array(),
+ *     sequence: 0xffffffff,
+ *   }],
+ *   outputs: [{ amount: 1n, script: new Uint8Array([0x51]) }],
+ *   witnesses: [[new Uint8Array([1])]],
+ *   lockTime: 0,
+ * });
+ * ```
+ */
+export const RawTx = /* @__PURE__ */ (() => Object.freeze(P.validate(_RawTx, validateRawTx)))();
 // Pre-SegWit serialization format (for PSBTv0)
-export const RawOldTx = P.struct({
+/**
+ * Pre-SegWit transaction coder used by PSBTv0.
+ * @example
+ * Encode the legacy unsigned transaction format used inside PSBTv0 globals.
+ * ```ts
+ * import { hex } from '@scure/base';
+ * import { RawOldTx } from '@scure/btc-signer/script.js';
+ * RawOldTx.encode({
+ *   version: 2,
+ *   inputs: [{
+ *     txid: hex.decode('0000000000000000000000000000000000000000000000000000000000000001'),
+ *     index: 0,
+ *     finalScriptSig: new Uint8Array(),
+ *     sequence: 0xffffffff,
+ *   }],
+ *   outputs: [{ amount: 1n, script: new Uint8Array([0x51]) }],
+ *   lockTime: 0,
+ * });
+ * ```
+ */
+export const RawOldTx = /* @__PURE__ */ (() => Object.freeze(P.struct({
     version: P.I32LE,
     inputs: BTCArray(RawInput),
     outputs: BTCArray(RawOutput),
     lockTime: P.U32LE,
-});
-//# sourceMappingURL=script.js.map
+})))();

package/src/_type_test.ts

@@ -0,0 +1,69 @@
+import { secp256k1 as secp } from '@noble/curves/secp256k1.js';
+import { hex } from '@scure/base';
+import * as btc from './index.ts';
+
+const privKey1 = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
+const P1 = secp.getPublicKey(privKey1, true);
+
+const wpkh = btc.p2wpkh(P1);
+
+const tx = new btc.Transaction();
+
+// Basic input test
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  ...wpkh,
+  finalScriptSig: Uint8Array.of(),
+  sequence: 1,
+});
+
+// Doesn't force any fields on input addition (only on sign)
+tx.addInput({
+  sequence: 1,
+});
+
+tx.updateInput(0, {
+  sequence: 1,
+});
+
+const nonWitnessUtxo =
+  '0200000001aad73931018bd25f84ae400b68848be09db706eac2ac18298babee71ab656f8b0000000048473044022058f6fc7c6a33e1b31548d481c826c015bd30135aad42cd67790dab66d2ad243b02204a1ced2604c6735b6393e5b41691dd78b00f0c5942fb9f751856faa938157dba01feffffff0280f0fa020000000017a9140fb9463421696b82c833af241c78c17ddbde493487d0f20a270100000017a91429ca74f8a08f81999428185c97b5d852e4063f618765000000';
+const nonWitnessUtxoB = hex.decode(nonWitnessUtxo);
+
+tx.updateInput(0, { nonWitnessUtxo: nonWitnessUtxo });
+tx.updateInput(0, { nonWitnessUtxo: nonWitnessUtxoB });
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  nonWitnessUtxo: nonWitnessUtxo,
+});
+
+tx.addInput({
+  txid: hex.decode('0af50a00a22f74ece24c12cd667c290d3a35d48124a69f4082700589172a3aa2'),
+  index: 0,
+  nonWitnessUtxo: nonWitnessUtxoB,
+});
+
+// Should fail!
+// tx.updateInput(0, {
+//   nonWitnessUtxo: 1,
+// });
+// Outputs
+tx.addOutput({ amount: BigInt(123) });
+// should fail
+// tx.updateOutput(0, { amount: '1' });
+// tx.updateOutput(0, { amount: 1 });
+// should fail
+// tx.addOutput({ amount: '123' });
+// tx.addOutput({ amount: 123 });
+
+for (let i = 0; i < tx.inputsLength; i++) {
+  // @ts-ignore
+  console.log('I', tx.getInput(i));
+}
+
+for (let i = 0; i < tx.outputsLength; i++) {
+  // @ts-ignore
+  console.log('O', tx.getOutput(i));
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 /*! scure-btc-signer - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+import type { TArg, TRet } from './utils.ts';
 import {
   compareBytes,
   concatBytes,
@@ -25,16 +26,36 @@ export {
 export type { ScriptType } from './script.ts';
 export { getInputType, Transaction } from './transaction.ts';
 export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from './utils.ts';
+export type { TArg, TRet } from './utils.ts';
 export { selectUTXO } from './utxo.ts';
 
-export const utils = {
-  isBytes,
-  concatBytes,
-  compareBytes,
-  pubSchnorr,
-  randomPrivateKeyBytes,
-  taprootTweakPubkey,
-};
+/**
+ * Small collection of commonly used utility exports.
+ * @example
+ * Reach for the grouped helpers when you want the common byte and Taproot utilities.
+ * ```ts
+ * utils.compareBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
+// Convenience subset; import from `./utils.ts` when you need the full helper surface.
+export const utils: TRet<
+  Readonly<{
+    isBytes: (a: unknown) => a is Uint8Array;
+    concatBytes: (...arrays: TArg<Uint8Array[]>) => TRet<Uint8Array>;
+    compareBytes: typeof compareBytes;
+    pubSchnorr: (priv: TArg<Uint8Array>) => TRet<Uint8Array>;
+    randomPrivateKeyBytes: () => TRet<Uint8Array>;
+    taprootTweakPubkey: typeof taprootTweakPubkey;
+  }>
+> = /* @__PURE__ */ (() =>
+  Object.freeze({
+    isBytes,
+    concatBytes,
+    compareBytes,
+    pubSchnorr,
+    randomPrivateKeyBytes,
+    taprootTweakPubkey,
+  }))();
 
 export {
   _sortPubkeys,
@@ -45,9 +66,11 @@ export {
   sortedMultisig,
   taprootListToTree,
   WIF,
-} from './payment.ts'; // remove
+} from './payment.ts';
 // remove
 export type { CustomScript, OptScript } from './payment.ts';
-export { _DebugPSBT, TaprootControlBlock } from './psbt.ts'; // remove
-export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from './transaction.ts'; // remove
+// remove
+export { _DebugPSBT, TaprootControlBlock } from './psbt.ts';
+// remove
+export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from './transaction.ts';
 export { _cmpBig, _Estimator } from './utxo.ts';