ox 0.0.1 → 0.1.0

package/Hash.ts

@@ -0,0 +1,210 @@
+import { ripemd160 as noble_ripemd160 } from '@noble/hashes/ripemd160'
+import { keccak_256 as noble_keccak256 } from '@noble/hashes/sha3'
+import { sha256 as noble_sha256 } from '@noble/hashes/sha256'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+
+/**
+ * Calculates the [Keccak256](https://en.wikipedia.org/wiki/SHA-3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * This function is a re-export of `keccak_256` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.keccak256('0xdeadbeef')
+ * // @log: '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1'
+ * ```
+ *
+ * @example
+ * ### Calculate Hash of a String
+ *
+ * ```ts twoslash
+ * import { Hash, Hex } from 'ox'
+ *
+ * Hash.keccak256(Hex.fromString('hello world'))
+ * // @log: '0x3ea2f1d0abf3fc66cf29eebb70cbd4e7fe762ef8a09bcc06c8edf641230afec0'
+ * ```
+ *
+ * @example
+ * ### Configure Return Type
+ *
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.keccak256('0xdeadbeef', { as: 'Bytes' })
+ * // @log: Uint8Array [...]
+ * ```
+ *
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns Keccak256 hash.
+ */
+export function keccak256<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: keccak256.Options<as> = {},
+): keccak256.ReturnType<as> {
+  const { as = typeof value === 'string' ? 'Hex' : 'Bytes' } = options
+  const bytes = noble_keccak256(Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace keccak256 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+keccak256.parseError = (error: unknown) => error as keccak256.ErrorType
+
+/**
+ * Calculates the [Ripemd160](https://en.wikipedia.org/wiki/RIPEMD) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * This function is a re-export of `ripemd160` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.ripemd160('0xdeadbeef')
+ * // '0x226821c2f5423e11fe9af68bd285c249db2e4b5a'
+ * ```
+ *
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns Ripemd160 hash.
+ */
+export function ripemd160<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: ripemd160.Options<as> = {},
+): ripemd160.ReturnType<as> {
+  const { as = typeof value === 'string' ? 'Hex' : 'Bytes' } = options
+  const bytes = noble_ripemd160(Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace ripemd160 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+ripemd160.parseError = (error: unknown) => error as ripemd160.ErrorType
+
+/**
+ * Calculates the [Sha256](https://en.wikipedia.org/wiki/SHA-256) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * This function is a re-export of `sha256` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.sha256('0xdeadbeef')
+ * // '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953'
+ * ```
+ *
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns Sha256 hash.
+ */
+export function sha256<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: sha256.Options<as> = {},
+): sha256.ReturnType<as> {
+  const { as = typeof value === 'string' ? 'Hex' : 'Bytes' } = options
+  const bytes = noble_sha256(Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace sha256 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+sha256.parseError = (error: unknown) => error as sha256.ErrorType
+
+/**
+ * Checks if a string is a valid hash value.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.validate('0x')
+ * // @log: false
+ *
+ * Hash.validate('0x3ea2f1d0abf3fc66cf29eebb70cbd4e7fe762ef8a09bcc06c8edf641230afec0')
+ * // @log: true
+ * ```
+ *
+ * @param value - Value to check.
+ * @returns Whether the value is a valid hash.
+ */
+export function validate(value: string): value is Hex.Hex {
+  return Hex.validate(value) && Hex.size(value) === 32
+}
+
+export declare namespace validate {
+  type ErrorType =
+    | Hex.validate.ErrorType
+    | Hex.size.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+validate.parseError = (error: unknown) => error as validate.ErrorType

package/HdKey/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/HdKey.d.ts",
+  "main": "../_cjs/HdKey.js",
+  "module": "../_esm/HdKey.js"
+}

package/HdKey.ts

@@ -0,0 +1,175 @@
+import { HDKey, type Versions } from '@scure/bip32'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import type * as Hex from './Hex.js'
+import type * as PublicKey from './PublicKey.js'
+import * as internal from './internal/hdKey.js'
+
+/** Root type for a Hierarchical Deterministic (HD) Key. */
+export type HdKey = {
+  derive: (path: string) => HdKey
+  depth: number
+  index: number
+  identifier: Hex.Hex
+  privateKey: Hex.Hex
+  privateExtendedKey: string
+  publicKey: PublicKey.PublicKey<false>
+  publicExtendedKey: string
+  versions: Versions
+}
+
+/**
+ * Creates a HD Key from an extended private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { HdKey } from 'ox'
+ *
+ * const hdKey = HdKey.fromExtendedKey('...')
+ *
+ * console.log(hdKey.privateKey)
+ * // @log: '0x...'
+ * ```
+ *
+ * @param extendedKey - The extended private key.
+ * @returns The HD Key.
+ */
+export function fromExtendedKey(extendedKey: string): HdKey {
+  const key = HDKey.fromExtendedKey(extendedKey)
+  return internal.fromScure(key)
+}
+
+export declare namespace fromExtendedKey {
+  type ErrorType = internal.fromScure.ErrorType | Errors.GlobalErrorType
+}
+
+fromExtendedKey.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as fromExtendedKey.ErrorType
+
+/**
+ * Creates a HD Key from a JSON object containing an extended private key (`xpriv`).
+ *
+ * @example
+ * ```ts twoslash
+ * import { HdKey } from 'ox'
+ *
+ * const hdKey = HdKey.fromJson({ xpriv: '...' })
+ *
+ * console.log(hdKey.privateKey)
+ * // @log: '0x...'
+ * ```
+ *
+ * @param json - The JSON object containing an extended private key (`xpriv`).
+ * @returns The HD Key.
+ */
+export function fromJson(json: { xpriv: string }): HdKey {
+  return internal.fromScure(HDKey.fromJSON(json))
+}
+
+export declare namespace fromJson {
+  type ErrorType = internal.fromScure.ErrorType | Errors.GlobalErrorType
+}
+
+fromJson.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as fromJson.ErrorType
+
+/**
+ * Creates a HD Key from a master seed.
+ *
+ * @example
+ * ```ts twoslash
+ * import { HdKey, Mnemonic } from 'ox'
+ *
+ * const seed = Mnemonic.toSeed('test test test test test test test test test test test junk')
+ * const hdKey = HdKey.fromSeed(seed)
+ * ```
+ *
+ * @example
+ * ### Path Derivation
+ *
+ * You can derive a HD Key at a specific path using `derive`.
+ *
+ * ```ts twoslash
+ * import { HdKey, Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.toSeed('test test test test test test test test test test test junk')
+ * const hdKey = HdKey.fromSeed(mnemonic).derive(HdKey.path())
+ *
+ * console.log(hdKey.privateKey)
+ * // @log: '0x...'
+ * ```
+ *
+ * @param seed - The master seed to create the HD Key from.
+ * @param options - Creation options.
+ * @returns The HD Key.
+ */
+export function fromSeed(
+  seed: Hex.Hex | Bytes.Bytes,
+  options: fromSeed.Options = {},
+): HdKey {
+  const { versions } = options
+  const key = HDKey.fromMasterSeed(Bytes.from(seed), versions)
+  return internal.fromScure(key)
+}
+
+export declare namespace fromSeed {
+  type Options = {
+    /** The versions to use for the HD Key. */
+    versions?: Versions | undefined
+  }
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | internal.fromScure.ErrorType
+    | Errors.GlobalErrorType
+}
+
+fromSeed.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as fromSeed.ErrorType
+
+/**
+ * Creates an Ethereum-based BIP-44 HD path.
+ *
+ * @example
+ * ```ts twoslash
+ * import { HdKey } from 'ox'
+ *
+ * const path = HdKey.path({ account: 1, index: 2 })
+ * // @log: "m/44'/60'/1'/0/2"
+ * ```
+ *
+ * @param options - Path options.
+ * @returns The path.
+ */
+export function path(options: path.Options = {}): string {
+  const { account = 0, change = 0, index = 0 } = options
+  return `m/44'/60'/${account}'/${change}/${index}`
+}
+
+export declare namespace path {
+  type Options = {
+    /**
+     * The account.
+     * @default 0
+     */
+    account?: number | undefined
+    /**
+     * The change.
+     * @default 0
+     */
+    change?: number | undefined
+    /**
+     * The address index.
+     * @default 0
+     */
+    index?: number | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+path.parseError = (error: unknown) => error as path.ErrorType

package/Hex/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/Hex.d.ts",
+  "main": "../_cjs/Hex.js",
+  "module": "../_esm/Hex.js"
+}