dcr-ts 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,955 @@
+/**
+ * Typed errors.
+ *
+ * Everything this library throws is a {@link DcrError} carrying a stable
+ * {@link DcrErrorCode}. Without one, the only way to tell a mistyped address from
+ * a right-address-wrong-network paste is to match on prose — which is not part of
+ * any API, breaks the moment a message is reworded, and cannot express the cases
+ * that share wording. The tests in this repository had exactly that problem.
+ *
+ * ```ts
+ * try {
+ *   addressToScript(pasted, mainnet);
+ * } catch (e) {
+ *   if (hasErrorCode(e, "bad-checksum")) showTypoHelp();
+ *   else if (hasErrorCode(e, "wrong-network")) showWrongNetworkHelp();
+ *   else throw e;
+ * }
+ * ```
+ *
+ * Codes are the stable part; messages are for humans and may be reworded.
+ */
+/**
+ * What went wrong, as a value rather than a sentence.
+ *
+ * Grouped by concern. New codes may be added in a minor release, so treat an
+ * unrecognised one as a generic failure rather than assuming the set is closed.
+ */
+type DcrErrorCode = 
+/** A character outside the base58 alphabet. */
+"invalid-base58"
+/** base58check or WIF checksum did not match. Usually a typo. */
+ | "bad-checksum"
+/** Input longer than the format allows; rejected before the quadratic decode. */
+ | "input-too-long"
+/** A field or payload was not the required size. */
+ | "bad-length"
+/** A varint that could have been encoded in fewer bytes (dcrd's ErrNonCanonicalVarInt). */
+ | "non-canonical-varint"
+/** Ran off the end of the input while reading. */
+ | "unexpected-end"
+/** Input parsed, but bytes remained after it. */
+ | "trailing-bytes"
+/** Not a valid private scalar (zero, or out of range for the suite's group order). */
+ | "invalid-private-key"
+/** Wrong length or prefix, or not a point on the curve. */
+ | "invalid-public-key"
+/** The two-byte version prefix belongs to no known network and kind. */
+ | "unknown-prefix"
+/** Well-formed, but for a different network than the one required. */
+ | "wrong-network"
+/** A signature-suite identifier this library does not support. */
+ | "unsupported-signature-type"
+/** Cannot derive a hardened child from a public key. */
+ | "hardened-from-public"
+/** The derived child is invalid; retry the next index (BIP32 says this is ~2^-127). */
+ | "invalid-child"
+/** Refused to derive past the depth a single byte can serialize. */
+ | "max-depth"
+/** A derivation path that does not parse. */
+ | "invalid-path"
+/** A private-key operation was asked of a public (neutered) key. */
+ | "not-a-private-key"
+/** Extended-key version bytes matching no known network. */
+ | "unknown-version"
+/** Mnemonic failed its checksum, or used a word outside the wordlist. */
+ | "invalid-mnemonic"
+/** A script whose data pushes do not tokenize (dcrd's checkScriptParses). */
+ | "malformed-script"
+/** A signature hash type dcrd would not accept, or one wider than a byte. */
+ | "invalid-hash-type"
+/** A push above MaxScriptElementSize, which dcrd can never execute. */
+ | "element-too-large"
+/** A numeric argument outside its permitted range. */
+ | "out-of-range"
+/** A numeric argument that was not an integer (includes NaN and Infinity). */
+ | "not-an-integer"
+/** A malformed or unrepresentable amount. */
+ | "invalid-amount"
+/** A required argument was missing or of the wrong shape. */
+ | "invalid-argument";
+/** Every error this library throws. */
+declare class DcrError extends Error {
+    /** Stable, machine-readable. Branch on this, not on {@link message}. */
+    readonly code: DcrErrorCode;
+    readonly name = "DcrError";
+    constructor(
+    /** Stable, machine-readable. Branch on this, not on {@link message}. */
+    code: DcrErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * True when `e` is a {@link DcrError}, including one thrown by another copy of
+ * this package loaded into the same process.
+ */
+declare function isDcrError(e: unknown): e is DcrError;
+/**
+ * True when `e` is a {@link DcrError} with this code.
+ *
+ * Safe on an `unknown` from a `catch`, so it needs no type guard at the call site.
+ */
+declare function hasErrorCode(e: unknown, code: DcrErrorCode): boolean;
+
+/** The BLAKE-256 digest length in bytes. */
+declare const BLAKE256_DIGEST_LENGTH = 32;
+/** The BLAKE-256 block length in bytes. */
+declare const BLAKE256_BLOCK_LENGTH = 64;
+/** Incremental BLAKE-256 hasher. */
+declare class Blake256 {
+    private readonly h;
+    private readonly buf;
+    private buflen;
+    /** Total message bytes fed in (used for the final length encoding). */
+    private total;
+    /** Message bytes already absorbed by the compression function. */
+    private compressed;
+    private finished;
+    update(data: Uint8Array): this;
+    digest(): Uint8Array;
+}
+/** One-shot BLAKE-256. Returns the 32-byte digest. */
+declare function blake256(data: Uint8Array): Uint8Array;
+
+/** Double BLAKE-256: `blake256(blake256(data))`. */
+declare function hash256(data: Uint8Array): Uint8Array;
+/** RIPEMD-160 of BLAKE-256: `ripemd160(blake256(data))`. The address hash. */
+declare function hash160(data: Uint8Array): Uint8Array;
+
+/** Encode raw bytes as base58 (no checksum). */
+declare function base58Encode(bytes: Uint8Array): string;
+/**
+ * Longest base58 string that can decode to `decodedLen` bytes.
+ *
+ * base58 expands by at most log_58(256) ≈ 1.37 bytes of output per input byte,
+ * which is how dcrd derives its own bounds (`stdaddr.DecodeAddressV0`'s
+ * `maxV0AddrLen`, `hdkeychain.NewKeyFromString`'s `maxKeyLen`). Callers must cap
+ * untrusted input *before* decoding: {@link base58Decode} accumulates one BigInt
+ * digit at a time and is therefore quadratic, so an unbounded string is a cheap
+ * way to stall the event loop.
+ */
+declare function maxBase58Length(decodedLen: number): number;
+/**
+ * Decode a base58 string to raw bytes. Throws on invalid characters.
+ *
+ * Cost is **quadratic** in the length of `str`. There is deliberately no length
+ * cap here, because the function is general-purpose; every decoder in this
+ * library bounds its input first via {@link maxBase58Length}, and anything
+ * calling this directly on untrusted input must do the same.
+ */
+declare function base58Decode(str: string): Uint8Array;
+/** base58check-encode: append the 4-byte double-BLAKE-256 checksum. */
+declare function checkEncode(data: Uint8Array): string;
+/**
+ * base58check-decode and verify the checksum, returning the payload without the
+ * trailing 4 checksum bytes. Throws if the checksum does not match.
+ *
+ * Inherits {@link base58Decode}'s **quadratic** cost and its lack of a length
+ * cap, and the checksum does not change that: the whole string is decoded before
+ * there is anything to check. Cap untrusted input with {@link maxBase58Length}
+ * first, exactly as `decodeAddress`, `decodeWif` and `ExtendedKey.fromString`
+ * do before they call this — the bound is in each of those callers, not in here.
+ */
+declare function checkDecode(str: string): Uint8Array;
+
+/**
+ * Copy `n` bytes out of `src` starting at `off`, always into a fresh buffer.
+ *
+ * Deliberately not `src.slice(off, off + n)`. `Uint8Array.prototype.slice`
+ * copies, but Node's `Buffer` overrides it to return a *view* over the same
+ * memory (deprecated, still the behaviour). Since `Buffer` is what
+ * `fs.readFileSync`, `Buffer.from(hex, "hex")`, sockets and database drivers all
+ * hand back, a `slice()` here would silently alias the caller's memory for the
+ * most common input type: reusing or zeroing that buffer afterwards would mutate
+ * an already-parsed transaction or key.
+ */
+declare function copyOf(src: Uint8Array, off: number, n: number): Uint8Array;
+/** Growable little-endian byte writer. */
+declare class Writer {
+    private buf;
+    private view;
+    private len;
+    private ensure;
+    u8(v: number): this;
+    u16(v: number): this;
+    u32(v: number): this;
+    u64(v: bigint): this;
+    /** Signed 64-bit little-endian (two's complement). Used for atom amounts. */
+    i64(v: bigint): this;
+    bytes(b: Uint8Array): this;
+    /** Compact-size varint. */
+    varInt(v: number | bigint): this;
+    /** A varint length prefix followed by the bytes themselves. */
+    varBytes(b: Uint8Array): this;
+    finish(): Uint8Array;
+}
+/** Little-endian byte reader. */
+declare class Reader {
+    private readonly data;
+    private off;
+    private readonly view;
+    constructor(data: Uint8Array);
+    get offset(): number;
+    get remaining(): number;
+    private need;
+    u8(): number;
+    u16(): number;
+    u32(): number;
+    u64(): bigint;
+    /** Signed 64-bit little-endian (two's complement). */
+    i64(): bigint;
+    bytes(n: number): Uint8Array;
+    /**
+     * Compact-size varint. Rejects non-canonical encodings (a value that could
+     * have been encoded in fewer bytes), matching dcrd's `ErrNonCanonicalVarInt`.
+     * Without this check two distinct byte strings could parse to the same
+     * transaction while hashing to different ids.
+     */
+    varInt(): number;
+    varBytes(): Uint8Array;
+}
+
+/**
+ * Decred network parameters.
+ *
+ * The magic prefix bytes, private-key IDs, extended-key version bytes and coin
+ * types are taken verbatim from dcrd's `chaincfg` package for the four
+ * networks. They are what make an address human-readable as `Ds…`/`Ts…`/`Ss…`
+ * and what bind a key to a specific network.
+ */
+/** Two-byte address version prefixes and related per-network identifiers. */
+interface Network {
+    /** Human name, e.g. "mainnet". */
+    readonly name: string;
+    /** Network magic (wire protocol identifier). */
+    readonly net: number;
+    /** Leading character(s) of every address on this network (informational). */
+    readonly addressPrefix: string;
+    /** Version prefix for pay-to-pubkey (secp256k1 ECDSA) addresses. */
+    readonly pubKeyAddrId: readonly [number, number];
+    /** Version prefix for pay-to-pubkey-hash (secp256k1 ECDSA) addresses. */
+    readonly pubKeyHashAddrId: readonly [number, number];
+    /** Version prefix for pay-to-pubkey-hash (Ed25519) addresses. */
+    readonly pubKeyHashEdwardsAddrId: readonly [number, number];
+    /** Version prefix for pay-to-pubkey-hash (secp256k1 Schnorr) addresses. */
+    readonly pubKeyHashSchnorrAddrId: readonly [number, number];
+    /** Version prefix for pay-to-script-hash addresses. */
+    readonly scriptHashAddrId: readonly [number, number];
+    /** Version prefix for WIF private keys. */
+    readonly privateKeyId: readonly [number, number];
+    /** BIP32 extended private key version bytes (`dprv`/`tprv`/…). */
+    readonly hdPrivateKeyId: readonly [number, number, number, number];
+    /** BIP32 extended public key version bytes (`dpub`/`tpub`/…). */
+    readonly hdPublicKeyId: readonly [number, number, number, number];
+    /** SLIP-0044 registered coin type used in BIP44 derivation paths. */
+    readonly slip44: number;
+}
+declare const mainnet: Network;
+declare const testnet3: Network;
+declare const simnet: Network;
+declare const regnet: Network;
+/** All networks keyed by name. */
+declare const networks: {
+    readonly mainnet: Network;
+    readonly testnet3: Network;
+    readonly simnet: Network;
+    readonly regnet: Network;
+};
+type NetworkName = keyof typeof networks;
+
+/** The secp256k1 group order. */
+declare const CURVE_ORDER: bigint;
+/** True when `key` is a valid secp256k1 private scalar (0 < key < n). */
+declare function isValidPrivateKey(key: Uint8Array): boolean;
+/**
+ * Throw unless `key` is a usable secp256k1 private scalar.
+ *
+ * Everything that signs, or turns a private key into a public one, goes through
+ * this. `@noble` checks the same two conditions itself but throws its own plain
+ * `Error`, which escapes the typed-error contract — a caller branching on
+ * `hasErrorCode` cannot classify a zeroed or wrong-length key buffer, which is
+ * exactly the mistake worth classifying.
+ *
+ * Deliberately stricter than dcrd, which cannot express this failure at all:
+ * `secp256k1.PrivKeyFromBytes` reduces mod n and left-pads a short slice, so a
+ * zero key there signs under an all-zero-X public key and a 31-byte key is
+ * silently padded. Rejecting is the safer contract for a signing API.
+ */
+declare function assertPrivateKey(key: Uint8Array, who: string): void;
+/** Compressed (33-byte) public key for a private key. */
+declare function publicKeyFromPrivate(privateKey: Uint8Array, compressed?: boolean): Uint8Array;
+/** True when `key` is a valid serialized secp256k1 point (compressed or not). */
+declare function isValidPublicKey(key: Uint8Array): boolean;
+/**
+ * True when `key` is a valid 32-byte Ed25519 public key.
+ *
+ * Decred's alternative signature suites are recognised on decode even though this
+ * library cannot sign for them, and an address whose key is not on the curve is
+ * unspendable — so it should not decode as valid. Ed25519 comes from the same
+ * `@noble/curves` package already in use, so this adds no dependency.
+ */
+declare function isValidEd25519PublicKey(key: Uint8Array): boolean;
+/**
+ * Throw unless `key` is a 33-byte compressed secp256k1 point.
+ *
+ * Anything that turns a public key into an address or an output script must go
+ * through this. Length alone is not enough, and length is not even checked in the
+ * common mistake: passing a 32-byte private key where the public key was meant
+ * type-checks fine, since both are `Uint8Array`. The resulting address or script
+ * is well-formed and permanently unspendable, because no key hashes to it.
+ */
+declare function assertCompressedPubKey(key: Uint8Array, who: string): void;
+/**
+ * Throw unless `key` is a serialized secp256k1 point — 33-byte compressed or
+ * 65-byte uncompressed.
+ *
+ * For hashing a key into a P2PKH address, where both serializations are
+ * legitimate and produce *different* addresses (dcrd hashes whichever form the
+ * caller holds; see `dcrutil/util.go`). Use {@link assertCompressedPubKey}
+ * wherever the format itself requires 33 bytes, such as the pay-to-pubkey address
+ * payload or a bare-P2PK script.
+ */
+declare function assertPubKey(key: Uint8Array, who: string): void;
+
+type AddressKind = "pubkeyhash-ecdsa" | "pubkeyhash-ed25519" | "pubkeyhash-schnorr" | "scripthash" | "pubkey-ecdsa" | "pubkey-ed25519" | "pubkey-schnorr";
+/** The hash-based address kinds, which carry a 20-byte `hash`. */
+type HashAddressKind = "pubkeyhash-ecdsa" | "pubkeyhash-ed25519" | "pubkeyhash-schnorr" | "scripthash";
+/** The pay-to-pubkey kinds, which carry a serialized `pubKey`. */
+type PubKeyAddressKind = "pubkey-ecdsa" | "pubkey-ed25519" | "pubkey-schnorr";
+/**
+ * A decoded address.
+ *
+ * A discriminated union on `kind`, so `hash` and `pubKey` are present exactly
+ * where they exist — narrowing on `kind` (or on `"hash" in decoded`) replaces
+ * what would otherwise be a non-null assertion at every use.
+ */
+type DecodedAddress = {
+    readonly network: Network;
+    readonly kind: HashAddressKind;
+    /** 20-byte hash. */
+    readonly hash: Uint8Array;
+    /** The original address string. */
+    readonly address: string;
+} | {
+    readonly network: Network;
+    readonly kind: PubKeyAddressKind;
+    /**
+     * The serialized public key: 33-byte compressed secp256k1 for
+     * `pubkey-ecdsa` and `pubkey-schnorr`, 32-byte Ed25519 for
+     * `pubkey-ed25519`.
+     */
+    readonly pubKey: Uint8Array;
+    readonly address: string;
+};
+/**
+ * Longest a version-0 address can be: a 33-byte payload (the pay-to-pubkey kind)
+ * plus a 2-byte version prefix and a 4-byte checksum. Matches dcrd's
+ * `maxV0AddrLen`.
+ */
+declare const MAX_ADDRESS_LENGTH: number;
+/** Encode a 20-byte pubkey hash as a P2PKH (secp256k1 ECDSA) address. */
+declare function pubKeyHashAddress(hash: Uint8Array, network: Network): string;
+/** Encode a 20-byte script hash as a P2SH address. */
+declare function scriptHashAddress(hash: Uint8Array, network: Network): string;
+/** Encode a 20-byte pubkey hash as a P2PKH (Ed25519) address. */
+declare function pubKeyHashEd25519Address(hash: Uint8Array, network: Network): string;
+/** Encode a 20-byte pubkey hash as a P2PKH (secp256k1 Schnorr) address. */
+declare function pubKeyHashSchnorrAddress(hash: Uint8Array, network: Network): string;
+/** Encode a compressed public key as a pay-to-pubkey (secp256k1 ECDSA) address. */
+declare function pubKeyAddress(compressedPubKey: Uint8Array, network: Network): string;
+/** Encode a 32-byte Ed25519 public key as a pay-to-pubkey address. */
+declare function pubKeyEd25519Address(pubKey: Uint8Array, network: Network): string;
+/** Encode a compressed public key as a pay-to-pubkey (secp256k1 Schnorr) address. */
+declare function pubKeySchnorrAddress(compressedPubKey: Uint8Array, network: Network): string;
+/**
+ * Derive the standard P2PKH address for a public key (`hash160` of the key).
+ *
+ * Accepts **either** serialization: 33-byte compressed or 65-byte uncompressed.
+ * They hash to different addresses, and both are legitimate — dcrd hashes
+ * whichever form the caller holds — so refusing the uncompressed form would break
+ * the only address a signature script built with
+ * `signatureScript(..., compressed = false)` can ever satisfy.
+ *
+ * The key is validated as a real curve point. Without that, any byte string
+ * hashes to something and produces a well-formed, valid-checksum address that no
+ * key can ever spend from — and the way to hit it is mundane: passing
+ * `privateKeyBytes()` where `publicKey()` was meant type-checks silently, because
+ * both are `Uint8Array`, and 32 vs 33 bytes is invisible at the call site.
+ */
+declare function addressFromPubKey(pubKey: Uint8Array, network: Network): string;
+/** Derive the P2SH address that pays to `redeemScript`. */
+declare function addressFromScript(redeemScript: Uint8Array, network: Network): string;
+/**
+ * Decode and validate an address. When `network` is given the address must
+ * belong to it; otherwise the network is inferred from the version prefix.
+ */
+declare function decodeAddress(address: string, network?: Network): DecodedAddress;
+/** True when `address` is a well-formed address (optionally for `network`). */
+declare function isValidAddress(address: string, network?: Network): boolean;
+/**
+ * Build the pkScript that pays to `address`.
+ *
+ * `network` is **required**, and deliberately so. A payment script commits only
+ * to the 20-byte hash, not to the network, so `addressToScript` on a testnet
+ * address produces bytes byte-identical to the mainnet address for the same hash
+ * — a pasted testnet address would quietly pay whoever controls that hash on
+ * mainnet. Naming the expected network here is the only thing that catches it.
+ *
+ * Use {@link decodeAddress} without a network when you genuinely want to inspect
+ * an address of unknown origin; it returns the network it found.
+ */
+declare function addressToScript(address: string, network: Network): Uint8Array;
+
+/** Decred signature suites, matching dcrd's `dcrec.SignatureType`. */
+declare enum SignatureType {
+    Ecdsa = 0,
+    Ed25519 = 1,
+    SchnorrSecp256k1 = 2
+}
+interface DecodedWif {
+    readonly privateKey: Uint8Array;
+    readonly network: Network;
+    readonly signatureType: SignatureType;
+}
+/** Encode a 32-byte private key as WIF. */
+declare function encodeWif(privateKey: Uint8Array, network: Network, signatureType?: SignatureType): string;
+/**
+ * Longest a WIF string can be: 2 prefix + 1 suite + 32 key + 4 checksum bytes.
+ */
+declare const MAX_WIF_LENGTH: number;
+/** Decode and validate a WIF string. */
+declare function decodeWif(wif: string): DecodedWif;
+
+declare const OP: {
+    readonly OP_0: 0;
+    readonly DATA_20: 20;
+    readonly DATA_32: 32;
+    readonly DATA_33: 33;
+    readonly PUSHDATA1: 76;
+    readonly PUSHDATA2: 77;
+    readonly PUSHDATA4: 78;
+    readonly OP_1NEGATE: 79;
+    readonly OP_1: 81;
+    readonly OP_2: 82;
+    readonly OP_16: 96;
+    readonly DUP: 118;
+    readonly EQUAL: 135;
+    readonly EQUALVERIFY: 136;
+    readonly HASH160: 169;
+    readonly CHECKSIG: 172;
+    readonly CHECKSIGALT: 190;
+};
+/**
+ * Largest a single stack element may be (dcrd `txscript.MaxScriptElementSize`).
+ * dcrd rejects a bigger push both when building and at execution, so anything
+ * over this can never run.
+ */
+declare const MAX_SCRIPT_ELEMENT_SIZE = 2048;
+/**
+ * Encode a canonical data push — the smallest valid encoding for `data`.
+ *
+ * "Smallest" includes the small-integer opcodes, which is a consensus rule and
+ * not a policy one: dcrd's script engine applies `checkMinimalDataPush` to every
+ * executed push with no verification flag gating it, so `OP_DATA_1 0x05` fails
+ * where `OP_5` succeeds. A script built with a non-minimal push is unspendable.
+ */
+declare function pushData(data: Uint8Array): Uint8Array;
+/**
+ * True when `script` tokenizes cleanly as a version-0 script — i.e. every data
+ * push declares a length that actually fits.
+ *
+ * The equivalent of dcrd's `checkScriptParses`, which its exported
+ * `CalcSignatureHash` runs before hashing. Signing against a script that does
+ * not parse produces a signature over a message dcrd would refuse to compute,
+ * so the resulting transaction can never be spent.
+ *
+ * This is a structural check only, not an execution one: it says nothing about
+ * whether the opcodes are valid or the script would succeed.
+ */
+declare function scriptParses(script: Uint8Array): boolean;
+/** Build a P2PKH script: `OP_DUP OP_HASH160 <20-byte hash> OP_EQUALVERIFY OP_CHECKSIG`. */
+declare function payToPubKeyHashScript(hash160: Uint8Array): Uint8Array;
+/**
+ * Build a P2PKH script for an alternative signature suite (Ed25519 = 1,
+ * secp256k1 Schnorr = 2): `OP_DUP OP_HASH160 <20-byte hash> OP_EQUALVERIFY
+ * <OP_1|OP_2> OP_CHECKSIGALT`. The signature type is pushed as a small integer.
+ */
+declare function payToPubKeyHashAltScript(hash160: Uint8Array, sigType: 1 | 2): Uint8Array;
+/** Build a P2SH script: `OP_HASH160 <20-byte hash> OP_EQUAL`. */
+declare function payToScriptHashScript(hash160: Uint8Array): Uint8Array;
+/**
+ * Build a bare P2PK script: `<33-byte compressed pubkey> OP_CHECKSIG`.
+ *
+ * The key is validated as an actual curve point, not just measured. This is an
+ * *output* script: paying to one built around arbitrary 33 bytes burns the coins,
+ * because no signature can ever satisfy an `OP_CHECKSIG` whose key does not
+ * parse. dcrd cannot express this — its constructor takes a parsed public key.
+ */
+declare function payToPubKeyScript(compressedPubKey: Uint8Array): Uint8Array;
+/**
+ * Build a pay-to-pubkey script for an alternative signature suite.
+ *
+ * Ed25519 takes a 32-byte key: `<32-byte pubkey> OP_1 OP_CHECKSIGALT`.
+ * secp256k1 Schnorr takes a 33-byte compressed key:
+ * `<33-byte pubkey> OP_2 OP_CHECKSIGALT`.
+ *
+ * The suite is pushed as a small integer, exactly as in
+ * {@link payToPubKeyHashAltScript}.
+ */
+declare function payToPubKeyAltScript(pubKey: Uint8Array, sigType: 1 | 2): Uint8Array;
+/** True when `script` is a canonical version-0 P2PKH template. */
+declare function isPayToPubKeyHash(script: Uint8Array): boolean;
+/** True when `script` is a canonical version-0 P2SH template. */
+declare function isPayToScriptHash(script: Uint8Array): boolean;
+/**
+ * Extract the 20-byte hash from a P2PKH or P2SH script, or `null`.
+ *
+ * Note this deliberately loses *which* template matched, and the two need
+ * different addresses — use {@link classifyScript} when that matters, or the
+ * hash will be encoded as the wrong address kind.
+ */
+declare function extractHash160(script: Uint8Array): Uint8Array | null;
+/** What {@link classifyScript} recognises. */
+type ScriptKind = "pubkeyhash-ecdsa" | "pubkeyhash-ed25519" | "pubkeyhash-schnorr" | "scripthash";
+/**
+ * Classify a version-0 payment script and return its 20-byte hash.
+ *
+ * {@link extractHash160} returns a bare hash for either the P2PKH or the P2SH
+ * template, so a caller labelling outputs by address has no way to tell which
+ * encoder to use — and picking wrong produces a completely different, valid
+ * address for the same script. This keeps the kind attached. Also recognises the
+ * two `OP_CHECKSIGALT` templates the library can build, which nothing could
+ * classify before.
+ */
+declare function classifyScript(script: Uint8Array): {
+    kind: ScriptKind;
+    hash: Uint8Array;
+} | null;
+
+/** Index of the first hardened child (2^31). */
+declare const HARDENED_OFFSET = 2147483648;
+/**
+ * Longest a `dprv`/`dpub` string can be: the 78-byte serialization plus a 4-byte
+ * checksum. Matches dcrd's `maxKeyLen` in `NewKeyFromString`.
+ */
+declare const MAX_EXTENDED_KEY_LENGTH: number;
+/**
+ * Mark a BIP44 child index as hardened.
+ *
+ * Rejects anything outside `0..2^31-1`: adding the offset to an already-hardened
+ * or out-of-range index wraps, and the result would be a *non*-hardened index
+ * silently derived from the wrong branch.
+ */
+declare function hardened(index: number): number;
+/** A BIP32 extended key with Decred version bytes. */
+declare class ExtendedKey {
+    readonly network: Network;
+    readonly isPrivate: boolean;
+    /** 32-byte private scalar, or `null` for a public (neutered) key. */
+    private readonly privateKey;
+    /** 33-byte compressed public key. */
+    private readonly compressedPublicKey;
+    private readonly chainCodeBytes;
+    readonly depth: number;
+    private readonly parentFingerprintBytes;
+    readonly childNumber: number;
+    /**
+     * Whether dcrd would be holding this scalar with its leading zero bytes
+     * stripped, which changes the hardened HMAC input of its children (see the
+     * module docs). True only for keys produced by {@link derive} — dcrd strips
+     * in `child` alone, so a master key from `fromSeed` and a key parsed by
+     * `fromSerialized` are both held at full width, exactly as `NewMaster` and
+     * `NewKeyFromString` do. The scalar itself is always stored padded to 32
+     * bytes here; only the HMAC input is narrowed.
+     */
+    private readonly scalarStripped;
+    private constructor();
+    /** Memoized hash160 of the public key; see {@link identifier}. */
+    private cachedIdentifier;
+    /**
+     * Memoized decompression of {@link compressedPublicKey}, so deriving a chain of
+     * public children does the modular square root once instead of per step. Only
+     * populated on the public-derivation path.
+     */
+    private cachedPoint;
+    /** Derive a master key from a BIP32 seed (16–64 bytes). */
+    static fromSeed(seed: Uint8Array, network: Network): ExtendedKey;
+    /** The compressed public key (33 bytes). */
+    publicKey(): Uint8Array;
+    /** The 32-byte private scalar. Throws for a public key. */
+    privateKeyBytes(): Uint8Array;
+    /**
+     * The 32-byte chain code. A copy: the key's own derivation reads the internal
+     * bytes, so handing out a live view would let a caller change what this key
+     * derives.
+     */
+    get chainCode(): Uint8Array;
+    /** The parent's 4-byte fingerprint, or four zero bytes for a master key. A copy. */
+    get parentFingerprint(): Uint8Array;
+    /**
+     * Identifier = hash160(compressed pubkey); the fingerprint is its first 4 bytes.
+     *
+     * Memoized, because `derive` needs the parent fingerprint for every child and
+     * would otherwise recompute a BLAKE-256 plus a RIPEMD-160 of the same key at
+     * every step. Both accessors return copies: the memo turned what used to be a
+     * per-call throwaway digest into long-lived shared state, so handing out a view
+     * would let one caller's write corrupt the cache, this key's own fingerprint,
+     * every sibling's `parentFingerprint` and every child derived afterwards.
+     */
+    identifier(): Uint8Array;
+    fingerprint(): Uint8Array;
+    /** The memoized digest itself. Never escapes this class. */
+    private identifierBytes;
+    /**
+     * Derive a child key by index, the **Decred way** — the equivalent of dcrd
+     * `hdkeychain.Child`, and what dcrwallet and Decrediton derive with for the
+     * whole wallet path. Use {@link hardened} for hardened indices.
+     *
+     * This is the default because it is what the Decred ecosystem derives; see
+     * {@link deriveBip32Std} for the strict form and the module docs for why they
+     * differ.
+     */
+    derive(index: number): ExtendedKey;
+    /**
+     * Derive a child key by **strict BIP32** — the equivalent of dcrd
+     * `hdkeychain.ChildBIP32Std`, retaining the leading zero bytes of the parent
+     * private key that {@link derive} strips.
+     *
+     * Produces different hardened children from {@link derive} for any parent
+     * scalar with a leading zero byte, which is about 1 key in 256 at each
+     * hardened step. Use it only when strict BIP32 is what you want; anything that
+     * has to agree with a dcrwallet or Decrediton seed must not.
+     */
+    deriveBip32Std(index: number): ExtendedKey;
+    private deriveInner;
+    /**
+     * Derive along a path like `m/44'/42'/0'/0/0`, the **Decred way** (see
+     * {@link derive}). An apostrophe or `h` marks a hardened index.
+     */
+    derivePath(path: string): ExtendedKey;
+    /**
+     * Derive along a path using **strict BIP32** (see {@link deriveBip32Std}).
+     * Diverges from {@link derivePath} below any hardened step whose parent scalar
+     * has a leading zero byte, so do not use it to reproduce a wallet seed.
+     */
+    derivePathBip32Std(path: string): ExtendedKey;
+    private derivePathInner;
+    /** Return the public (watch-only) version of this key. */
+    neuter(): ExtendedKey;
+    /** The standard P2PKH address for this key on its network. */
+    address(network?: Network): string;
+    /** Serialize to the 78-byte BIP32 form (without the base58check checksum). */
+    serialize(): Uint8Array;
+    /** Encode as a `dprv`/`dpub` (or per-network) base58check string. */
+    toString(): string;
+    /** Parse an extended key string, validating the checksum and version. */
+    static fromString(str: string): ExtendedKey;
+    /**
+     * Parse a raw 78-byte serialization (checksum already verified/absent).
+     *
+     * Every field is copied out of `data`, so the returned key does not alias the
+     * caller's buffer — which matters most here, because a caller doing the right
+     * thing and wiping the serialization after parsing would otherwise destroy the
+     * key it just parsed. See {@link copyOf}.
+     */
+    static fromSerialized(data: Uint8Array): ExtendedKey;
+}
+
+/** A BIP39 wordlist: 2048 words. Defaults to English throughout this module. */
+type Wordlist = readonly string[];
+/** The English BIP39 wordlist, used wherever `wordlist` is omitted. */
+declare const englishWordlist: Wordlist;
+/** Generate a new mnemonic. `strength` is entropy bits (128–256, default 128). */
+declare function generateMnemonic(strength?: number, wordlist?: Wordlist): string;
+/** Validate a mnemonic's checksum and wordlist membership. */
+declare function validateMnemonic(mnemonic: string, wordlist?: Wordlist): boolean;
+/** Recover the raw entropy behind a mnemonic. */
+declare function mnemonicToEntropy(mnemonic: string, wordlist?: Wordlist): Uint8Array;
+/** Encode entropy (16–32 bytes, multiple of 4) as a mnemonic. */
+declare function entropyToMnemonic(entropy: Uint8Array, wordlist?: Wordlist): string;
+/**
+ * Expand a mnemonic (with optional passphrase) into the 64-byte BIP39 seed.
+ *
+ * Checksum-unchecked, by design: derivation does not consult a wordlist, so any
+ * phrase of a legal length expands whether or not its words are in a list and
+ * whether or not its checksum holds. Use {@link mnemonicToMasterKey} to get the
+ * checksum verified first. The word count *is* enforced: BIP39 is defined only
+ * for 12, 15, 18, 21 or 24 words.
+ *
+ * Both failures are checked here rather than caught from `@scure`, and the two
+ * checks are exhaustive: `mnemonicToSeedSync` reaches the caller's input only
+ * through `nfkd`, which rejects a non-string, and `normalize`, which rejects a
+ * word count outside the five. Its salt is `"mnemonic" + passphrase`, a
+ * concatenation that always yields a string, and its PBKDF2 parameters are
+ * constants — so nothing else in it can throw. Catching instead would report
+ * `invalid-mnemonic` for a future `@scure` failure that has nothing to do with
+ * the mnemonic, which is the one direction that wastes the most debugging time.
+ */
+declare function mnemonicToSeed(mnemonic: string, passphrase?: string): Uint8Array;
+/**
+ * Expand a mnemonic straight into a Decred master {@link ExtendedKey}.
+ *
+ * The mnemonic's checksum is verified first, against `wordlist` (English by
+ * default). Because seed derivation consults no wordlist, a typo'd or
+ * mis-transcribed phrase of the right length would otherwise expand happily into
+ * a different, valid-looking wallet — one of the classic ways to lose funds while
+ * every operation appears to succeed.
+ *
+ * Pass the matching `wordlist` for a non-English phrase; validating a Spanish
+ * mnemonic against the English list would reject a perfectly good one. Use
+ * {@link mnemonicToSeed} directly if you specifically want the unchecked
+ * primitive.
+ */
+declare function mnemonicToMasterKey(mnemonic: string, network: Network, passphrase?: string, wordlist?: Wordlist): ExtendedKey;
+
+/** Transaction serialization selectors (encoded in the version word). */
+declare enum TxSerializeType {
+    Full = 0,
+    NoWitness = 1,
+    OnlyWitness = 2
+}
+/** Output tree: regular spends vs. the stake tree. */
+declare enum TxTree {
+    Regular = 0,
+    Stake = 1
+}
+declare const DEFAULT_TX_VERSION = 1;
+declare const MAX_SEQUENCE = 4294967295;
+/**
+ * Sentinel "unknown" input amount / block position used for unsigned inputs,
+ * matching dcrd's `wire.NullValueIn` / `NullBlockHeight` / `NullBlockIndex`.
+ *
+ * Note the asymmetry, which is dcrd's and not a typo here: the null block
+ * *height* is `0` ("it references the genesis block") while the null block
+ * *index* is `0xffffffff`.
+ */
+declare const NULL_VALUE_IN = -1n;
+declare const NULL_BLOCK_HEIGHT = 0;
+declare const NULL_BLOCK_INDEX = 4294967295;
+interface OutPoint {
+    /** 32-byte transaction hash in internal (serialized) byte order. */
+    hash: Uint8Array;
+    index: number;
+    tree: number;
+}
+interface TxInput {
+    previousOutPoint: OutPoint;
+    sequence: number;
+    valueIn: bigint;
+    blockHeight: number;
+    blockIndex: number;
+    signatureScript: Uint8Array;
+}
+interface TxOutput {
+    value: bigint;
+    version: number;
+    pkScript: Uint8Array;
+}
+/** A mutable Decred transaction. */
+declare class Transaction {
+    version: number;
+    inputs: TxInput[];
+    outputs: TxOutput[];
+    lockTime: number;
+    expiry: number;
+    /**
+     * Add an input. Witness fields default to the "unsigned/unknown" sentinels.
+     *
+     * The outpoint and signature script are copied, so a caller that reuses or
+     * scrubs its own buffers afterwards cannot silently rewrite this transaction's
+     * bytes — which would change its txid and invalidate every signature already
+     * computed over it, with nothing to detect the change.
+     */
+    addInput(previousOutPoint: OutPoint, opts?: Partial<Omit<TxInput, "previousOutPoint">>): this;
+    /** Add an output. The script is copied; see {@link addInput}. */
+    addOutput(value: bigint, pkScript: Uint8Array, version?: number): this;
+    private writeVersion;
+    private writePrefixBody;
+    private writeWitnessBody;
+    /** Serialize as prefix ‖ witness (the full form). */
+    serialize(): Uint8Array;
+    /** Serialize the prefix only (no witness). This is what the txid hashes. */
+    serializePrefix(): Uint8Array;
+    /** Serialize the witness only. */
+    serializeWitness(): Uint8Array;
+    /** Raw 32-byte prefix hash (internal byte order). */
+    hash(): Uint8Array;
+    /** The transaction id (reversed-hex display form of the prefix hash). */
+    txid(): string;
+    /** The witness hash id (display form). */
+    witnessTxid(): string;
+    /** The full hash id: `blake256(prefixHash ‖ witnessHash)`, display form. */
+    fullTxid(): string;
+    /**
+     * Parse a full (prefix ‖ witness) serialization.
+     *
+     * The declared input and output counts are deliberately **not** capped, where
+     * dcrd's `decodePrefix` and `decodeWitness` reject anything above
+     * `maxTxInPerMessage` (780336) or `maxTxOutPerMessage` (3728271) — the counts
+     * that could fit a 32 MiB `MaxMessagePayload`. Those bounds exist because dcrd
+     * decodes from an `io.Reader` of unknown length and sizes `make([]TxIn, count)`
+     * from the count *before* reading an input; here the argument is a `Uint8Array`
+     * whose length is already the bound, and nothing is sized from a count —
+     * `Reader` checks every read against the bytes that remain, so an inflated
+     * count fails at the first short read having allocated nothing. The only
+     * observable difference is that a blob of ~43 MiB or larger declaring more than
+     * 780336 inputs parses here and does not in dcrd; such a transaction is neither
+     * relayable (over `MaxMessagePayload`) nor valid (mainnet `MaxTxSize` is 393216
+     * bytes, 115x smaller). On a *truncated* blob both reject, only with different
+     * errors: dcrd's `ErrTooManyTxs` against this library's `unexpected-end`.
+     *
+     * Cost is still linear in `bytes.length`, so cap the size of untrusted input at
+     * the call site. dcrd's count limits would not help with that: 32 MiB holds
+     * 818400 minimal prefix inputs and the cap is 780336, so a buffer at the wire
+     * maximum stays under it.
+     */
+    static fromBytes(bytes: Uint8Array): Transaction;
+}
+/** Build an OutPoint from a txid *string* (reverses to internal byte order). */
+declare function outPointFromTxid(txid: string, index: number, tree?: TxTree): OutPoint;
+
+declare enum SigHashType {
+    All = 1,
+    None = 2,
+    Single = 3,
+    AnyOneCanPay = 128
+}
+/**
+ * True when `hashType` is one dcrd's script engine will accept, i.e. the six
+ * values `CheckHashTypeEncoding` permits: All/None/Single, each optionally
+ * OR'ed with AnyOneCanPay.
+ *
+ * Note {@link calcSignatureHash} deliberately still computes a hash for other
+ * byte values, because dcrd's `calcSignatureHash` does — undefined types hash as
+ * if they were All. Validation belongs at the point a signature is *produced*,
+ * which is where {@link assertSignableSigHashType} is applied.
+ */
+declare function isSignableSigHashType(hashType: number): boolean;
+/** Throw unless `hashType` is one dcrd's engine accepts. */
+declare function assertSignableSigHashType(hashType: number): void;
+/**
+ * The reusable prefix hash for `SigHashAll` without `AnyOneCanPay`.
+ *
+ * Under that hash type the prefix half of the signature hash does not depend on
+ * which input is being signed, and its serialization is byte-identical to the
+ * transaction's own prefix serialization — `SigHashSerializePrefix` and
+ * `TxSerializeNoWitness` are both `1`, and the bodies are the same. So this is
+ * exactly `tx.hash()`, and passing it to {@link calcSignatureHash} as
+ * `cachedPrefix` removes the dominant per-input cost when signing.
+ *
+ * It does **not** make signing linear. The witness half still walks every input
+ * on each call (one varint apiece), so signing N inputs stays O(N²) — but the
+ * prefix half is the expensive one, since it re-serializes every outpoint and
+ * every output script, so the constant drops by more than an order of magnitude.
+ * Measured on the hashing alone: 12x at 50 inputs, 26x at 500.
+ *
+ * This is what dcrd's `cachedPrefix` parameter exists for.
+ */
+declare function sigHashPrefixAll(tx: Transaction): Uint8Array;
+/**
+ * Compute the signature hash for input `idx` of `tx` under `hashType`, with
+ * `subScript` as the script being satisfied (the prevout pkScript for P2PKH, or
+ * the redeem script for P2SH). Returns the 32-byte hash to be signed.
+ *
+ * `cachedPrefix` is an optional pre-computed prefix hash from
+ * {@link sigHashPrefixAll}, honoured only for `SigHashAll` without
+ * `AnyOneCanPay` — the one case where the prefix half is input-independent. It is
+ * ignored for every other hash type rather than trusted, so it is safe to pass
+ * for *any hash type*.
+ *
+ * It is **not** checked against `tx`, because a 32-byte hash carries nothing to
+ * check it with: it must be this transaction's current prefix hash. Passing a
+ * stale one — taken before the prefix was changed, or from a different
+ * transaction — silently produces a signature over the wrong message. Take it
+ * from the transaction you are about to sign, after the prefix is final, or use
+ * {@link signP2PKHInputs}, which does that for you.
+ */
+declare function calcSignatureHash(subScript: Uint8Array, hashType: SigHashType | number, tx: Transaction, idx: number, cachedPrefix?: Uint8Array): Uint8Array;
+
+/** DER-encode a deterministic low-S ECDSA signature over a 32-byte hash. */
+declare function signHash(hash: Uint8Array, privateKey: Uint8Array): Uint8Array;
+/**
+ * Verify a **DER** signature over a 32-byte hash against a public key.
+ *
+ * Strictly DER, and low-S. `@noble`'s `verify` falls back to the 64-byte compact
+ * `r ‖ s` encoding when DER parsing fails, so without parsing the DER ourselves
+ * first this would accept a signature encoding dcrd's script engine rejects — a
+ * co-signer or hardware device emitting compact signatures would pass local
+ * validation and then fail consensus.
+ */
+declare function verifyHash(hash: Uint8Array, derSignature: Uint8Array, publicKey: Uint8Array): boolean;
+/**
+ * Produce the raw signature for input `idx`: the DER signature over the Decred
+ * signature hash with the one-byte hash type appended (as it appears in a
+ * signature script and in a signature stack element).
+ */
+declare function rawTxInSignature(tx: Transaction, idx: number, subScript: Uint8Array, hashType: SigHashType | number, privateKey: Uint8Array, cachedPrefix?: Uint8Array): Uint8Array;
+/**
+ * Build the full P2PKH signature script for input `idx`:
+ * `push(<DER-sig ‖ hashType>) push(<pubkey>)`.
+ */
+declare function signatureScript(tx: Transaction, idx: number, subScript: Uint8Array, hashType: SigHashType | number, privateKey: Uint8Array, compressed?: boolean, cachedPrefix?: Uint8Array): Uint8Array;
+/**
+ * Sign input `idx` in place: compute and assign its P2PKH signature script.
+ * Returns the signed transaction for chaining.
+ *
+ * For a transaction with several inputs prefer {@link signP2PKHInputs}, which
+ * reuses one prefix hash instead of recomputing it per input.
+ */
+declare function signP2PKHInput(tx: Transaction, idx: number, subScript: Uint8Array, privateKey: Uint8Array, hashType?: SigHashType | number, compressed?: boolean): Transaction;
+/** One input to sign, for {@link signP2PKHInputs}. */
+interface P2PKHInputToSign {
+    /** Index into `tx.inputs`. */
+    idx: number;
+    /** The script being satisfied — the prevout pkScript for P2PKH. */
+    subScript: Uint8Array;
+    privateKey: Uint8Array;
+    /** Serialize the public key compressed (the default). */
+    compressed?: boolean;
+}
+/**
+ * Sign several P2PKH inputs in place, reusing one prefix hash.
+ *
+ * `calcSignatureHash` re-serializes and re-hashes the whole transaction prefix on
+ * every call — every outpoint and every output script — which is the dominant
+ * cost for a transaction with many inputs. Under `SigHashAll` without
+ * `AnyOneCanPay` that half is input-independent, so it is computed once here and
+ * reused, which is what dcrd's `cachedPrefix` parameter is for.
+ *
+ * This lowers the constant, not the exponent: the witness half still walks every
+ * input per call, so signing stays O(N²). On the hashing alone it measured 12x at
+ * 50 inputs and 26x at 500; end to end the gain is smaller (1.7x at 250) because
+ * ECDSA dominates.
+ *
+ * The prefix hash is taken **before** any signature script is assigned, which is
+ * also why this is correct: the prefix commits to no witness data, so writing
+ * signature scripts cannot invalidate it. For other hash types the cache is
+ * ignored and each input is hashed independently, so passing one is always safe.
+ */
+declare function signP2PKHInputs(tx: Transaction, toSign: readonly P2PKHInputToSign[], hashType?: SigHashType | number): Transaction;
+
+/** Atoms in one DCR. */
+declare const ATOMS_PER_COIN = 100000000n;
+/** Decimal places in a DCR amount. */
+declare const COIN_DECIMALS = 8;
+/**
+ * Parse a decimal DCR string (e.g. "1.5", "-0.00000001") into atoms.
+ * Accepts up to 8 fractional digits; more is an error.
+ */
+declare function dcrToAtoms(dcr: string): bigint;
+/**
+ * Format atoms as a fixed 8-decimal DCR string (e.g. 150000000n → "1.50000000").
+ */
+declare function atomsToDcr(atoms: bigint): string;
+
+export { ATOMS_PER_COIN, type AddressKind, BLAKE256_BLOCK_LENGTH, BLAKE256_DIGEST_LENGTH, Blake256, COIN_DECIMALS, CURVE_ORDER, DEFAULT_TX_VERSION, DcrError, type DcrErrorCode, type DecodedAddress, type DecodedWif, ExtendedKey, HARDENED_OFFSET, type HashAddressKind, MAX_ADDRESS_LENGTH, MAX_EXTENDED_KEY_LENGTH, MAX_SCRIPT_ELEMENT_SIZE, MAX_SEQUENCE, MAX_WIF_LENGTH, NULL_BLOCK_HEIGHT, NULL_BLOCK_INDEX, NULL_VALUE_IN, type Network, type NetworkName, OP, type OutPoint, type P2PKHInputToSign, type PubKeyAddressKind, Reader, type ScriptKind, SigHashType, SignatureType, Transaction, type TxInput, type TxOutput, TxSerializeType, TxTree, type Wordlist, Writer, addressFromPubKey, addressFromScript, addressToScript, assertCompressedPubKey, assertPrivateKey, assertPubKey, assertSignableSigHashType, atomsToDcr, base58Decode, base58Encode, blake256, calcSignatureHash, checkDecode, checkEncode, classifyScript, copyOf, dcrToAtoms, decodeAddress, decodeWif, encodeWif, englishWordlist, entropyToMnemonic, extractHash160, generateMnemonic, hardened, hasErrorCode, hash160, hash256, isDcrError, isPayToPubKeyHash, isPayToScriptHash, isSignableSigHashType, isValidAddress, isValidEd25519PublicKey, isValidPrivateKey, isValidPublicKey, mainnet, maxBase58Length, mnemonicToEntropy, mnemonicToMasterKey, mnemonicToSeed, networks, outPointFromTxid, payToPubKeyAltScript, payToPubKeyHashAltScript, payToPubKeyHashScript, payToPubKeyScript, payToScriptHashScript, pubKeyAddress, pubKeyEd25519Address, pubKeyHashAddress, pubKeyHashEd25519Address, pubKeyHashSchnorrAddress, pubKeySchnorrAddress, publicKeyFromPrivate, pushData, rawTxInSignature, regnet, scriptHashAddress, scriptParses, sigHashPrefixAll, signHash, signP2PKHInput, signP2PKHInputs, signatureScript, simnet, testnet3, validateMnemonic, verifyHash };