@scure/btc-signer 2.0.1 → 2.3.0

package/script.d.ts

@@ -1,145 +1,282 @@
 import * as P from 'micro-packed';
-import { type ValueOf, type Bytes } from './utils.ts';
+import { type Bytes, type TArg, type TRet, type ValueOf } from './utils.ts';
+/**
+ * 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 declare const MAX_SCRIPT_BYTE_LENGTH = 520;
-export declare const OP: {
-    OP_0: number;
-    PUSHDATA1: number;
-    PUSHDATA2: number;
-    PUSHDATA4: number;
-    '1NEGATE': number;
-    RESERVED: number;
-    OP_1: number;
-    OP_2: number;
-    OP_3: number;
-    OP_4: number;
-    OP_5: number;
-    OP_6: number;
-    OP_7: number;
-    OP_8: number;
-    OP_9: number;
-    OP_10: number;
-    OP_11: number;
-    OP_12: number;
-    OP_13: number;
-    OP_14: number;
-    OP_15: number;
-    OP_16: number;
-    NOP: number;
-    VER: number;
-    IF: number;
-    NOTIF: number;
-    VERIF: number;
-    VERNOTIF: number;
-    ELSE: number;
-    ENDIF: number;
-    VERIFY: number;
-    RETURN: number;
-    TOALTSTACK: number;
-    FROMALTSTACK: number;
-    '2DROP': number;
-    '2DUP': number;
-    '3DUP': number;
-    '2OVER': number;
-    '2ROT': number;
-    '2SWAP': number;
-    IFDUP: number;
-    DEPTH: number;
-    DROP: number;
-    DUP: number;
-    NIP: number;
-    OVER: number;
-    PICK: number;
-    ROLL: number;
-    ROT: number;
-    SWAP: number;
-    TUCK: number;
-    CAT: number;
-    SUBSTR: number;
-    LEFT: number;
-    RIGHT: number;
-    SIZE: number;
-    INVERT: number;
-    AND: number;
-    OR: number;
-    XOR: number;
-    EQUAL: number;
-    EQUALVERIFY: number;
-    RESERVED1: number;
-    RESERVED2: number;
-    '1ADD': number;
-    '1SUB': number;
-    '2MUL': number;
-    '2DIV': number;
-    NEGATE: number;
-    ABS: number;
-    NOT: number;
-    '0NOTEQUAL': number;
-    ADD: number;
-    SUB: number;
-    MUL: number;
-    DIV: number;
-    MOD: number;
-    LSHIFT: number;
-    RSHIFT: number;
-    BOOLAND: number;
-    BOOLOR: number;
-    NUMEQUAL: number;
-    NUMEQUALVERIFY: number;
-    NUMNOTEQUAL: number;
-    LESSTHAN: number;
-    GREATERTHAN: number;
-    LESSTHANOREQUAL: number;
-    GREATERTHANOREQUAL: number;
-    MIN: number;
-    MAX: number;
-    WITHIN: number;
-    RIPEMD160: number;
-    SHA1: number;
-    SHA256: number;
-    HASH160: number;
-    HASH256: number;
-    CODESEPARATOR: number;
-    CHECKSIG: number;
-    CHECKSIGVERIFY: number;
-    CHECKMULTISIG: number;
-    CHECKMULTISIGVERIFY: number;
-    NOP1: number;
-    CHECKLOCKTIMEVERIFY: number;
-    CHECKSEQUENCEVERIFY: number;
-    NOP4: number;
-    NOP5: number;
-    NOP6: number;
-    NOP7: number;
-    NOP8: number;
-    NOP9: number;
-    NOP10: number;
-    CHECKSIGADD: number;
-    INVALID: number;
-};
-export declare const OPNames: {
-    [x: number]: "OP_0" | "PUSHDATA1" | "PUSHDATA2" | "PUSHDATA4" | "1NEGATE" | "RESERVED" | "OP_1" | "OP_2" | "OP_3" | "OP_4" | "OP_5" | "OP_6" | "OP_7" | "OP_8" | "OP_9" | "OP_10" | "OP_11" | "OP_12" | "OP_13" | "OP_14" | "OP_15" | "OP_16" | "NOP" | "VER" | "IF" | "NOTIF" | "VERIF" | "VERNOTIF" | "ELSE" | "ENDIF" | "VERIFY" | "RETURN" | "TOALTSTACK" | "FROMALTSTACK" | "2DROP" | "2DUP" | "3DUP" | "2OVER" | "2ROT" | "2SWAP" | "IFDUP" | "DEPTH" | "DROP" | "DUP" | "NIP" | "OVER" | "PICK" | "ROLL" | "ROT" | "SWAP" | "TUCK" | "CAT" | "SUBSTR" | "LEFT" | "RIGHT" | "SIZE" | "INVERT" | "AND" | "OR" | "XOR" | "EQUAL" | "EQUALVERIFY" | "RESERVED1" | "RESERVED2" | "1ADD" | "1SUB" | "2MUL" | "2DIV" | "NEGATE" | "ABS" | "NOT" | "0NOTEQUAL" | "ADD" | "SUB" | "MUL" | "DIV" | "MOD" | "LSHIFT" | "RSHIFT" | "BOOLAND" | "BOOLOR" | "NUMEQUAL" | "NUMEQUALVERIFY" | "NUMNOTEQUAL" | "LESSTHAN" | "GREATERTHAN" | "LESSTHANOREQUAL" | "GREATERTHANOREQUAL" | "MIN" | "MAX" | "WITHIN" | "RIPEMD160" | "SHA1" | "SHA256" | "HASH160" | "HASH256" | "CODESEPARATOR" | "CHECKSIG" | "CHECKSIGVERIFY" | "CHECKMULTISIG" | "CHECKMULTISIGVERIFY" | "NOP1" | "CHECKLOCKTIMEVERIFY" | "CHECKSEQUENCEVERIFY" | "NOP4" | "NOP5" | "NOP6" | "NOP7" | "NOP8" | "NOP9" | "NOP10" | "CHECKSIGADD" | "INVALID";
-};
+/**
+ * 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 declare const OP: Readonly<{
+    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;
+    OP_10: 90;
+    OP_11: 91;
+    OP_12: 92;
+    OP_13: 93;
+    OP_14: 94;
+    OP_15: 95;
+    OP_16: 96;
+    NOP: 97;
+    VER: 98;
+    IF: 99;
+    NOTIF: 100;
+    VERIF: 101;
+    VERNOTIF: 102;
+    ELSE: 103;
+    ENDIF: 104;
+    VERIFY: 105;
+    RETURN: 106;
+    TOALTSTACK: 107;
+    FROMALTSTACK: 108;
+    '2DROP': 109;
+    '2DUP': 110;
+    '3DUP': 111;
+    '2OVER': 112;
+    '2ROT': 113;
+    '2SWAP': 114;
+    IFDUP: 115;
+    DEPTH: 116;
+    DROP: 117;
+    DUP: 118;
+    NIP: 119;
+    OVER: 120;
+    PICK: 121;
+    ROLL: 122;
+    ROT: 123;
+    SWAP: 124;
+    TUCK: 125;
+    CAT: 126;
+    SUBSTR: 127;
+    LEFT: 128;
+    RIGHT: 129;
+    SIZE: 130;
+    INVERT: 131;
+    AND: 132;
+    OR: 133;
+    XOR: 134;
+    EQUAL: 135;
+    EQUALVERIFY: 136;
+    RESERVED1: 137;
+    RESERVED2: 138;
+    '1ADD': 139;
+    '1SUB': 140;
+    '2MUL': 141;
+    '2DIV': 142;
+    NEGATE: 143;
+    ABS: 144;
+    NOT: 145;
+    '0NOTEQUAL': 146;
+    ADD: 147;
+    SUB: 148;
+    MUL: 149;
+    DIV: 150;
+    MOD: 151;
+    LSHIFT: 152;
+    RSHIFT: 153;
+    BOOLAND: 154;
+    BOOLOR: 155;
+    NUMEQUAL: 156;
+    NUMEQUALVERIFY: 157;
+    NUMNOTEQUAL: 158;
+    LESSTHAN: 159;
+    GREATERTHAN: 160;
+    LESSTHANOREQUAL: 161;
+    GREATERTHANOREQUAL: 162;
+    MIN: 163;
+    MAX: 164;
+    WITHIN: 165;
+    RIPEMD160: 166;
+    SHA1: 167;
+    SHA256: 168;
+    HASH160: 169;
+    HASH256: 170;
+    CODESEPARATOR: 171;
+    CHECKSIG: 172;
+    CHECKSIGVERIFY: 173;
+    CHECKMULTISIG: 174;
+    CHECKMULTISIGVERIFY: 175;
+    NOP1: 176;
+    CHECKLOCKTIMEVERIFY: 177;
+    CHECKSEQUENCEVERIFY: 178;
+    NOP4: 179;
+    NOP5: 180;
+    NOP6: 181;
+    NOP7: 182;
+    NOP8: 183;
+    NOP9: 184;
+    NOP10: 185;
+    CHECKSIGADD: 186;
+    INVALID: 255;
+}>;
+/**
+ * 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 declare const OPNames: Record<number, keyof typeof OP>;
+/** Numeric opcode value from {@link OP}. */
 export type OP = ValueOf<typeof OP>;
+/** Single script element accepted by the script encoder. */
 export type ScriptOP = keyof typeof OP | Uint8Array | number;
+/** Parsed Bitcoin script as a list of script elements. */
 export type ScriptType = ScriptOP[];
+/**
+ * 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 declare function ScriptNum(bytesLimit?: number, forceMinimal?: boolean): P.CoderType<bigint>;
-export declare function OpToNum(op: ScriptOP, bytesLimit?: number, forceMinimal?: boolean): number | undefined;
-export declare const Script: P.CoderType<ScriptType>;
+/**
+ * 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 declare function OpToNum(op: TArg<ScriptOP>, bytesLimit?: number, forceMinimal?: boolean): number | undefined;
+/**
+ * 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 declare const scriptPushLen: (op: number, read: (bytes: 1 | 2 | 4) => number) => number | undefined;
+/**
+ * Bitcoin script coder.
+ * @example
+ * Encode a short script from opcode mnemonics and small integers.
+ * ```ts
+ * Script.encode(['OP_1', 'OP_2']);
+ * ```
+ */
+export declare const Script: TRet<P.CoderType<ScriptType>>;
+/**
+ * Bitcoin CompactSize integer coder.
+ * @example
+ * Encode a CompactSize integer for wire serialization.
+ * ```ts
+ * CompactSize.encode(1n);
+ * ```
+ */
 export declare const CompactSize: P.CoderType<bigint>;
+/**
+ * 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 declare const CompactSizeLen: P.CoderType<number>;
-export declare const VarBytes: P.CoderType<Bytes>;
-export declare const RawWitness: P.CoderType<Bytes[]>;
+/**
+ * Length-prefixed byte array coder.
+ * @example
+ * Prefix a byte array with its CompactSize length.
+ * ```ts
+ * VarBytes.encode(new Uint8Array([1, 2, 3]));
+ * ```
+ */
+export declare const VarBytes: TRet<P.CoderType<Bytes>>;
+/**
+ * SegWit witness stack coder.
+ * @example
+ * Encode one witness stack for a SegWit input.
+ * ```ts
+ * RawWitness.encode([new Uint8Array([1])]);
+ * ```
+ */
+export declare const RawWitness: TRet<P.CoderType<Bytes[]>>;
+/**
+ * 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 declare const BTCArray: <T>(t: P.CoderType<T>) => P.CoderType<T[]>;
-export declare const RawInput: P.CoderType<P.StructInput<{
+/**
+ * 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 declare const RawInput: Readonly<P.CoderType<P.StructInput<{
     txid: P.Bytes;
     index: number;
-    finalScriptSig: Bytes;
+    finalScriptSig: P.Bytes;
     sequence: number;
-}>>;
-export declare const RawOutput: P.CoderType<P.StructInput<{
+}>>>;
+/**
+ * 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 declare const RawOutput: Readonly<P.CoderType<P.StructInput<{
     amount: bigint;
-    script: Bytes;
-}>>;
+    script: P.Bytes;
+}>>>;
 declare const _RawTx: P.CoderType<P.StructInput<{
     version: number;
     segwitFlag: boolean | undefined;
@@ -153,11 +290,53 @@ declare const _RawTx: P.CoderType<P.StructInput<{
         amount: /*elided*/ any;
         script: /*elided*/ any;
     }>[];
-    witnesses: P.Option<Bytes[][]>;
+    witnesses: P.Option<P.Bytes[][]>;
     lockTime: number;
 }>>;
+/**
+ * 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 declare const RawTx: typeof _RawTx;
-export declare const RawOldTx: P.CoderType<P.StructInput<{
+/**
+ * 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 declare const RawOldTx: Readonly<P.CoderType<P.StructInput<{
     version: number;
     inputs: P.StructInput<{
         txid: /*elided*/ any;
@@ -170,6 +349,5 @@ export declare const RawOldTx: P.CoderType<P.StructInput<{
         script: /*elided*/ any;
     }>[];
     lockTime: number;
-}>>;
+}>>>;
 export {};
-//# sourceMappingURL=script.d.ts.map