@exodus/bytes 1.9.0 → 1.10.0

package/multi-byte.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Decode / encode the legacy multi-byte encodings according to the
+ * [Encoding standard](https://encoding.spec.whatwg.org/)
+ * ([§10](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(simplified)-encodings),
+ * [§11](https://encoding.spec.whatwg.org/#legacy-multi-byte-chinese-(traditional)-encodings),
+ * [§12](https://encoding.spec.whatwg.org/#legacy-multi-byte-japanese-encodings),
+ * [§13](https://encoding.spec.whatwg.org/#legacy-multi-byte-korean-encodings)).
+ *
+ * ```js
+ * import { createMultibyteDecoder, createMultibyteEncoder } from '@exodus/bytes/multi-byte.js'
+ * ```
+ *
+ * Supports all legacy multi-byte encodings listed in the WHATWG Encoding standard:
+ * `gbk`, `gb18030`, `big5`, `euc-jp`, `iso-2022-jp`, `shift_jis`, `euc-kr`.
+ *
+ * @module @exodus/bytes/multi-byte.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * Create a decoder for a supported legacy multi-byte `encoding`, given its lowercased name `encoding`.
+ *
+ * Returns a function `decode(arr, stream = false)` that decodes bytes to a string.
+ *
+ * The returned function will maintain internal state while `stream = true` is used, allowing it to
+ * handle incomplete multi-byte sequences across multiple calls.
+ * State is reset when `stream = false` or when the function is called without the `stream` parameter.
+ *
+ * @param encoding - The encoding name (e.g., 'gbk', 'gb18030', 'big5', 'euc-jp', 'iso-2022-jp', 'shift_jis', 'euc-kr')
+ * @param loose - If true, replaces unmapped bytes with replacement character instead of throwing (default: false)
+ * @returns A function that decodes bytes to string, with optional streaming support
+ */
+export function createMultibyteDecoder(
+  encoding: string,
+  loose?: boolean
+): (arr: Uint8Array, stream?: boolean) => string;
+
+/**
+ * Create an encoder for a supported legacy multi-byte `encoding`, given its lowercased name `encoding`.
+ *
+ * Returns a function `encode(string)` that encodes a string to bytes.
+ *
+ * In `'fatal'` mode (default), will throw on non well-formed strings or any codepoints which could
+ * not be encoded in the target encoding.
+ *
+ * @param encoding - The encoding name (e.g., 'gbk', 'gb18030', 'big5', 'euc-jp', 'iso-2022-jp', 'shift_jis', 'euc-kr')
+ * @param options - Encoding options
+ * @param options.mode - Encoding mode (default: 'fatal'). Currently, only 'fatal' mode is supported.
+ * @returns A function that encodes string to bytes
+ */
+export function createMultibyteEncoder(
+  encoding: string,
+  options?: { mode?: 'fatal' }
+): (string: string) => Uint8ArrayBuffer;

package/package.json

@@ -1,7 +1,23 @@
 {
   "name": "@exodus/bytes",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Various operations on Uint8Array data",
+  "keywords": [
+    "encoding",
+    "uint8array",
+    "textdecoder",
+    "textencoder",
+    "utf8",
+    "utf16",
+    "hex",
+    "base64",
+    "base32",
+    "base58",
+    "base58check",
+    "bech32",
+    "bech32m",
+    "wif"
+  ],
   "scripts": {
     "lint": "eslint .",
     "test:javascriptcore": "npm run test:jsc --",
@@ -38,7 +54,7 @@
   "bugs": {
     "url": "https://github.com/ExodusOSS/bytes/issues"
   },
-  "homepage": "https://github.com/ExodusOSS/bytes#readme",
+  "homepage": "https://github.com/ExodusOSS/bytes",
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
   },
@@ -66,13 +82,18 @@
     "/array.d.ts",
     "/assert.js",
     "/base32.js",
+    "/base32.d.ts",
     "/base58.js",
+    "/base58.d.ts",
     "/base58check.js",
+    "/base58check.d.ts",
     "/base58check.node.js",
     "/base64.js",
     "/base64.d.ts",
     "/bech32.js",
+    "/bech32.d.ts",
     "/bigint.js",
+    "/bigint.d.ts",
     "/encoding-browser.js",
     "/encoding-browser.browser.js",
     "/encoding-browser.native.js",
@@ -87,15 +108,19 @@
     "/index.js",
     "/index.d.ts",
     "/multi-byte.js",
+    "/multi-byte.d.ts",
     "/multi-byte.node.js",
     "/single-byte.js",
+    "/single-byte.d.ts",
     "/single-byte.node.js",
     "/utf16.js",
+    "/utf16.d.ts",
     "/utf16.node.js",
     "/utf8.js",
     "/utf8.d.ts",
     "/utf8.node.js",
-    "/wif.js"
+    "/wif.js",
+    "/wif.d.ts"
   ],
   "main": "index.js",
   "module": "index.js",
@@ -109,9 +134,16 @@
       "types": "./array.d.ts",
       "default": "./array.js"
     },
-    "./base32.js": "./base32.js",
-    "./base58.js": "./base58.js",
+    "./base32.js": {
+      "types": "./base32.d.ts",
+      "default": "./base32.js"
+    },
+    "./base58.js": {
+      "types": "./base58.d.ts",
+      "default": "./base58.js"
+    },
     "./base58check.js": {
+      "types": "./base58check.d.ts",
       "node": "./base58check.node.js",
       "default": "./base58check.js"
     },
@@ -119,18 +151,26 @@
       "types": "./base64.d.ts",
       "default": "./base64.js"
     },
-    "./bech32.js": "./bech32.js",
-    "./bigint.js": "./bigint.js",
+    "./bech32.js": {
+      "types": "./bech32.d.ts",
+      "default": "./bech32.js"
+    },
+    "./bigint.js": {
+      "types": "./bigint.d.ts",
+      "default": "./bigint.js"
+    },
     "./hex.js": {
       "types": "./hex.d.ts",
       "node": "./hex.node.js",
       "default": "./hex.js"
     },
     "./multi-byte.js": {
+      "types": "./multi-byte.d.ts",
       "node": "./multi-byte.node.js",
       "default": "./multi-byte.js"
     },
     "./single-byte.js": {
+      "types": "./single-byte.d.ts",
       "node": "./single-byte.node.js",
       "default": "./single-byte.js"
     },
@@ -150,6 +190,7 @@
       "default": "./encoding-browser.js"
     },
     "./utf16.js": {
+      "types": "./utf16.d.ts",
       "node": "./utf16.node.js",
       "default": "./utf16.js"
     },
@@ -158,7 +199,10 @@
       "node": "./utf8.node.js",
       "default": "./utf8.js"
     },
-    "./wif.js": "./wif.js"
+    "./wif.js": {
+      "types": "./wif.d.ts",
+      "default": "./wif.js"
+    }
   },
   "react-native": {
     "./encoding-browser.js": "./encoding-browser.native.js"

package/single-byte.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Decode / encode the legacy single-byte encodings according to the
+ * [Encoding standard](https://encoding.spec.whatwg.org/)
+ * ([§9](https://encoding.spec.whatwg.org/#legacy-single-byte-encodings),
+ * [§14.5](https://encoding.spec.whatwg.org/#x-user-defined)),
+ * and [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859) `iso-8859-*` mappings.
+ *
+ * ```js
+ * import { createSinglebyteDecoder, createSinglebyteEncoder } from '@exodus/bytes/single-byte.js'
+ * import { windows1252toString, windows1252fromString } from '@exodus/bytes/single-byte.js'
+ * import { latin1toString, latin1fromString } from '@exodus/bytes/single-byte.js'
+ * ```
+ *
+ * Supports all single-byte encodings listed in the WHATWG Encoding standard:
+ * `ibm866`, `iso-8859-2`, `iso-8859-3`, `iso-8859-4`, `iso-8859-5`, `iso-8859-6`, `iso-8859-7`, `iso-8859-8`,
+ * `iso-8859-8-i`, `iso-8859-10`, `iso-8859-13`, `iso-8859-14`, `iso-8859-15`, `iso-8859-16`, `koi8-r`, `koi8-u`,
+ * `macintosh`, `windows-874`, `windows-1250`, `windows-1251`, `windows-1252`, `windows-1253`, `windows-1254`,
+ * `windows-1255`, `windows-1256`, `windows-1257`, `windows-1258`, `x-mac-cyrillic` and `x-user-defined`.
+ *
+ * Also supports `iso-8859-1`, `iso-8859-9`, `iso-8859-11` as defined at
+ * [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859)
+ * (and all other `iso-8859-*` encodings there as they match WHATWG).
+ *
+ * > [!NOTE]
+ * > While all `iso-8859-*` encodings supported by the [WHATWG Encoding standard](https://encoding.spec.whatwg.org/) match
+ * > [unicode.org](https://unicode.org/Public/MAPPINGS/ISO8859), the WHATWG Encoding spec doesn't support
+ * > `iso-8859-1`, `iso-8859-9`, `iso-8859-11`, and instead maps them as labels to `windows-1252`, `windows-1254`, `windows-874`.\
+ * > `createSinglebyteDecoder()` (unlike `TextDecoder` or `legacyHookDecode()`) does not do such mapping,
+ * > so its results will differ from `TextDecoder` for those encoding names.
+ *
+ * ```js
+ * > new TextDecoder('iso-8859-1').encoding
+ * 'windows-1252'
+ * > new TextDecoder('iso-8859-9').encoding
+ * 'windows-1254'
+ * > new TextDecoder('iso-8859-11').encoding
+ * 'windows-874'
+ * > new TextDecoder('iso-8859-9').decode(Uint8Array.of(0x80, 0x81, 0xd0))
+ * '€\x81Ğ' // this is actually decoded according to windows-1254 per TextDecoder spec
+ * > createSinglebyteDecoder('iso-8859-9')(Uint8Array.of(0x80, 0x81, 0xd0))
+ * '\x80\x81Ğ' // this is iso-8859-9 as defined at https://unicode.org/Public/MAPPINGS/ISO8859/8859-9.txt
+ * ```
+ *
+ * All WHATWG Encoding spec [`windows-*` encodings](https://encoding.spec.whatwg.org/#windows-874) are supersets of
+ * corresponding [unicode.org encodings](https://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/), meaning that
+ * they encode/decode all the old valid (non-replacement) strings / byte sequences identically, but can also support
+ * a wider range of inputs.
+ *
+ * @module @exodus/bytes/single-byte.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * Create a decoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
+ *
+ * Returns a function `decode(arr)` that decodes bytes to a string.
+ *
+ * @param encoding - The encoding name (e.g., 'iso-8859-1', 'windows-1252')
+ * @param loose - If true, replaces unmapped bytes with replacement character instead of throwing (default: false)
+ * @returns A function that decodes bytes to string
+ */
+export function createSinglebyteDecoder(
+  encoding: string,
+  loose?: boolean
+): (arr: Uint8Array) => string;
+
+/**
+ * Create an encoder for a supported one-byte `encoding`, given its lowercased name `encoding`.
+ *
+ * Returns a function `encode(string)` that encodes a string to bytes.
+ *
+ * In `'fatal'` mode (default), will throw on non well-formed strings or any codepoints which could
+ * not be encoded in the target encoding.
+ *
+ * @param encoding - The encoding name (e.g., 'iso-8859-1', 'windows-1252')
+ * @param options - Encoding options
+ * @param options.mode - Encoding mode (default: 'fatal'). Currently, only 'fatal' mode is supported.
+ * @returns A function that encodes string to bytes
+ */
+export function createSinglebyteEncoder(
+  encoding: string,
+  options?: { mode?: 'fatal' }
+): (string: string) => Uint8ArrayBuffer;
+
+/**
+ * Decode `iso-8859-1` bytes to a string.
+ *
+ * There is no loose variant for this encoding, all bytes can be decoded.
+ *
+ * Same as:
+ * ```js
+ * const latin1toString = createSinglebyteDecoder('iso-8859-1')
+ * ```
+ *
+ * Note: this is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as
+ * those alias to `new TextDecoder('windows-1252')`.
+ *
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function latin1toString(arr: Uint8Array): string;
+
+/**
+ * Encode a string to `iso-8859-1` bytes.
+ *
+ * Throws on non well-formed strings or any codepoints which could not be encoded in `iso-8859-1`.
+ *
+ * Same as:
+ * ```js
+ * const latin1fromString = createSinglebyteEncoder('iso-8859-1', { mode: 'fatal' })
+ * ```
+ *
+ * @param string - The string to encode
+ * @returns The encoded bytes
+ */
+export function latin1fromString(string: string): Uint8ArrayBuffer;
+
+/**
+ * Decode `windows-1252` bytes to a string.
+ *
+ * There is no loose variant for this encoding, all bytes can be decoded.
+ *
+ * Same as:
+ * ```js
+ * const windows1252toString = createSinglebyteDecoder('windows-1252')
+ * ```
+ *
+ * @param arr - The bytes to decode
+ * @returns The decoded string
+ */
+export function windows1252toString(arr: Uint8Array): string;
+
+/**
+ * Encode a string to `windows-1252` bytes.
+ *
+ * Throws on non well-formed strings or any codepoints which could not be encoded in `windows-1252`.
+ *
+ * Same as:
+ * ```js
+ * const windows1252fromString = createSinglebyteEncoder('windows-1252', { mode: 'fatal' })
+ * ```
+ *
+ * @param string - The string to encode
+ * @returns The encoded bytes
+ */
+export function windows1252fromString(string: string): Uint8ArrayBuffer;

package/utf16.d.ts

@@ -0,0 +1,92 @@
+/**
+ * UTF-16 encoding/decoding
+ *
+ * ```js
+ * import { utf16fromString, utf16toString } from '@exodus/bytes/utf16.js'
+ *
+ * // loose
+ * import { utf16fromStringLoose, utf16toStringLoose } from '@exodus/bytes/utf16.js'
+ * ```
+ *
+ * _These methods by design encode/decode BOM (codepoint `U+FEFF` Byte Order Mark) as-is._\
+ * _If you need BOM handling or detection, use `@exodus/bytes/encoding.js`_
+ *
+ * @module @exodus/bytes/utf16.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer, Uint16ArrayBuffer } from './array.js';
+
+/**
+ * Output format for UTF-16 encoding
+ */
+export type Utf16Format = 'uint16' | 'uint8-le' | 'uint8-be';
+
+/**
+ * Encode a string to UTF-16 bytes (strict mode)
+ *
+ * Throws on invalid Unicode (unpaired surrogates)
+ *
+ * @param string - The string to encode
+ * @param format - Output format (default: 'uint16')
+ * @returns The encoded bytes
+ */
+export function utf16fromString(string: string, format?: 'uint16'): Uint16ArrayBuffer;
+export function utf16fromString(string: string, format: 'uint8-le'): Uint8ArrayBuffer;
+export function utf16fromString(string: string, format: 'uint8-be'): Uint8ArrayBuffer;
+export function utf16fromString(string: string, format?: Utf16Format): Uint16ArrayBuffer | Uint8ArrayBuffer;
+
+/**
+ * Encode a string to UTF-16 bytes (loose mode)
+ *
+ * Replaces invalid Unicode (unpaired surrogates) with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversible and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * @param string - The string to encode
+ * @param format - Output format (default: 'uint16')
+ * @returns The encoded bytes
+ */
+export function utf16fromStringLoose(string: string, format?: 'uint16'): Uint16ArrayBuffer;
+export function utf16fromStringLoose(string: string, format: 'uint8-le'): Uint8ArrayBuffer;
+export function utf16fromStringLoose(string: string, format: 'uint8-be'): Uint8ArrayBuffer;
+export function utf16fromStringLoose(string: string, format?: Utf16Format): Uint16ArrayBuffer | Uint8ArrayBuffer;
+
+/**
+ * Decode UTF-16 bytes to a string (strict mode)
+ *
+ * Throws on invalid UTF-16 byte sequences
+ *
+ * Throws on non-even byte length.
+ *
+ * @param arr - The bytes to decode
+ * @param format - Input format (default: 'uint16')
+ * @returns The decoded string
+ */
+export function utf16toString(arr: Uint16Array, format?: 'uint16'): string;
+export function utf16toString(arr: Uint8Array, format: 'uint8-le'): string;
+export function utf16toString(arr: Uint8Array, format: 'uint8-be'): string;
+export function utf16toString(arr: Uint16Array | Uint8Array, format?: Utf16Format): string;
+
+/**
+ * Decode UTF-16 bytes to a string (loose mode)
+ *
+ * Replaces invalid UTF-16 byte sequences with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversible and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * Throws on non-even byte length.
+ *
+ * @param arr - The bytes to decode
+ * @param format - Input format (default: 'uint16')
+ * @returns The decoded string
+ */
+export function utf16toStringLoose(arr: Uint16Array, format?: 'uint16'): string;
+export function utf16toStringLoose(arr: Uint8Array, format: 'uint8-le'): string;
+export function utf16toStringLoose(arr: Uint8Array, format: 'uint8-be'): string;
+export function utf16toStringLoose(arr: Uint16Array | Uint8Array, format?: Utf16Format): string;

package/utf8.d.ts

@@ -1,42 +1,76 @@
+/**
+ * UTF-8 encoding/decoding
+ *
+ * ```js
+ * import { utf8fromString, utf8toString } from '@exodus/bytes/utf8.js'
+ *
+ * // loose
+ * import { utf8fromStringLoose, utf8toStringLoose } from '@exodus/bytes/utf8.js'
+ * ```
+ *
+ * _These methods by design encode/decode BOM (codepoint `U+FEFF` Byte Order Mark) as-is._\
+ * _If you need BOM handling or detection, use `@exodus/bytes/encoding.js`_
+ *
+ * @module @exodus/bytes/utf8.js
+ */
+
 /// <reference types="node" />
 
 import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
 
 /**
- * Encodes a string to UTF-8 bytes (strict mode)
+ * Encode a string to UTF-8 bytes (strict mode)
+ *
  * Throws on invalid Unicode (unpaired surrogates)
- * @param str - The string to encode
+ *
+ * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
  */
-export function utf8fromString(str: string, format?: 'uint8'): Uint8ArrayBuffer;
-export function utf8fromString(str: string, format: 'buffer'): Buffer;
-export function utf8fromString(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+export function utf8fromString(string: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromString(string: string, format: 'buffer'): Buffer;
+export function utf8fromString(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
 
 /**
- * Encodes a string to UTF-8 bytes (loose mode)
- * Replaces invalid Unicode with replacement character
- * @param str - The string to encode
+ * Encode a string to UTF-8 bytes (loose mode)
+ *
+ * Replaces invalid Unicode (unpaired surrogates) with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversable and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
+ * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
  */
-export function utf8fromStringLoose(str: string, format?: 'uint8'): Uint8ArrayBuffer;
-export function utf8fromStringLoose(str: string, format: 'buffer'): Buffer;
-export function utf8fromStringLoose(str: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
+export function utf8fromStringLoose(string: string, format?: 'uint8'): Uint8ArrayBuffer;
+export function utf8fromStringLoose(string: string, format: 'buffer'): Buffer;
+export function utf8fromStringLoose(
+  string: string,
+  format?: OutputFormat
+): Uint8ArrayBuffer | Buffer;
 
 /**
- * Decodes UTF-8 bytes to a string (strict mode)
- * Throws on invalid UTF-8 sequences
+ * Decode UTF-8 bytes to a string (strict mode)
+ *
+ * Throws on invalid UTF-8 byte sequences
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
-export function utf8toString(arr: Uint8ArrayBuffer): string;
+export function utf8toString(arr: Uint8Array): string;
 
 /**
- * Decodes UTF-8 bytes to a string (loose mode)
- * Replaces invalid sequences with replacement character
+ * Decode UTF-8 bytes to a string (loose mode)
+ *
+ * Replaces invalid UTF-8 byte sequences with replacement codepoints `U+FFFD`
+ * per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
+ *
+ * _Such replacement is a non-injective function, is irreversable and causes collisions.\
+ * Prefer using strict throwing methods for cryptography applications._
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
-export function utf8toStringLoose(arr: Uint8ArrayBuffer): string;
-
+export function utf8toStringLoose(arr: Uint8Array): string;

package/utf8.js

@@ -35,8 +35,13 @@ function deLoose(str, loose, res) {
     start = pos + 1
     if (res[pos + 1] === 0xbf && res[pos + 2] === 0xbd) {
       // Found a replacement char in output, need to recheck if we encoded the input correctly
-      if (str !== decode(res)) throw new TypeError(E_STRICT_UNICODE)
-      return res
+      if (!nativeDecoder && str.length < 1e7) {
+        // This is ~2x faster than decode in Hermes
+        try {
+          if (encodeURI(str) !== null) return res // guard against optimizing out
+        } catch {}
+      } else if (str === decode(res)) return res
+      throw new TypeError(E_STRICT_UNICODE)
     }
   }
 

package/utf8.node.js

@@ -9,7 +9,7 @@ if (Buffer.TYPED_ARRAY_SUPPORT) throw new Error('Unexpected Buffer polyfill')
 let decoderFatal
 const decoderLoose = new TextDecoder('utf-8', { ignoreBOM: true })
 const { isWellFormed } = String.prototype
-const isDeno = Boolean(globalThis.Deno)
+const isDeno = !!globalThis.Deno
 
 try {
   decoderFatal = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true })

package/wif.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Wallet Import Format (WIF) encoding and decoding.
+ *
+ * ```js
+ * import { fromWifString, toWifString } from '@exodus/bytes/wif.js'
+ * import { fromWifStringSync, toWifStringSync } from '@exodus/bytes/wif.js'
+ * ```
+ *
+ * On non-Node.js, requires peer dependency [@noble/hashes](https://www.npmjs.com/package/@noble/hashes) to be installed.
+ *
+ * @module @exodus/bytes/wif.js
+ */
+
+/// <reference types="node" />
+
+import type { Uint8ArrayBuffer } from './array.js';
+
+/**
+ * WIF (Wallet Import Format) data structure
+ */
+export interface Wif {
+  /** Network version byte */
+  version: number;
+  /** 32-byte private key */
+  privateKey: Uint8ArrayBuffer;
+  /** Whether the key is compressed */
+  compressed: boolean;
+}
+
+/**
+ * Decode a WIF string to WIF data
+ *
+ * Returns a promise that resolves to an object with `{ version, privateKey, compressed }`.
+ *
+ * The optional `version` parameter validates the version byte.
+ *
+ * Throws if the WIF string is invalid or version doesn't match.
+ *
+ * @param string - The WIF encoded string
+ * @param version - Optional expected version byte to validate against
+ * @returns The decoded WIF data
+ * @throws Error if the WIF string is invalid or version doesn't match
+ */
+export function fromWifString(string: string, version?: number): Promise<Wif>;
+
+/**
+ * Decode a WIF string to WIF data (synchronous)
+ *
+ * Returns an object with `{ version, privateKey, compressed }`.
+ *
+ * The optional `version` parameter validates the version byte.
+ *
+ * Throws if the WIF string is invalid or version doesn't match.
+ *
+ * @param string - The WIF encoded string
+ * @param version - Optional expected version byte to validate against
+ * @returns The decoded WIF data
+ * @throws Error if the WIF string is invalid or version doesn't match
+ */
+export function fromWifStringSync(string: string, version?: number): Wif;
+
+/**
+ * Encode WIF data to a WIF string
+ *
+ * @param wif - The WIF data to encode
+ * @returns The WIF encoded string
+ */
+export function toWifString(wif: Wif): Promise<string>;
+
+/**
+ * Encode WIF data to a WIF string (synchronous)
+ *
+ * @param wif - The WIF data to encode
+ * @returns The WIF encoded string
+ */
+export function toWifStringSync(wif: Wif): string;