ox 0.14.28 → 1.0.0-beta.0

package/src/core/Log.ts

@@ -0,0 +1,250 @@
+import type * as Address from './Address.js'
+import type * as Errors from './Errors.js'
+import type * as Hex from './Hex.js'
+import * as Quantity from './internal/quantity.js'
+import type { Compute } from './internal/types.js'
+
+/** A Log as defined in the [Execution API specification](https://github.com/ethereum/execution-apis/blob/main/src/schemas/receipt.yaml). */
+export type Log<
+  pending extends boolean = false,
+  bigintType = bigint,
+  numberType = number,
+> = Compute<{
+  /** The address from which this log originated */
+  address: Address.Address
+  /** Hash of block containing this log or `null` if pending */
+  blockHash: pending extends true ? null : Hex.Hex
+  /** Number of block containing this log or `null` if pending */
+  blockNumber: pending extends true ? null : bigintType
+  /** Timestamp of block containing this log or `null` if pending */
+  blockTimestamp?: (pending extends true ? null : bigintType) | undefined
+  /** Contains the non-integered arguments of the log */
+  data: Hex.Hex
+  /** Index of this log within its block or `null` if pending */
+  logIndex: pending extends true ? null : numberType
+  /** List of topics associated with this log */
+  topics: [Hex.Hex, ...(readonly Hex.Hex[])]
+  /** Hash of the transaction that created this log or `null` if pending */
+  transactionHash: pending extends true ? null : Hex.Hex
+  /** Index of the transaction that created this log or `null` if pending */
+  transactionIndex: pending extends true ? null : numberType
+  /** `true` if this filter has been destroyed and is invalid */
+  removed: boolean
+}>
+
+/** An RPC Log as defined in the [Execution API specification](https://github.com/ethereum/execution-apis/blob/main/src/schemas/receipt.yaml). */
+export type Rpc<pending extends boolean = false> = Log<
+  pending,
+  Hex.Hex,
+  Hex.Hex
+>
+
+/**
+ * Converts a {@link ox#Log.Rpc} to an {@link ox#Log.Log}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Log } from 'ox'
+ *
+ * const log = Log.fromRpc({
+ *   address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ *   topics: [
+ *     '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+ *     '0x0000000000000000000000000000000000000000000000000000000000000000',
+ *     '0x0000000000000000000000000c04d9e9278ec5e4d424476d3ebec70cb5d648d1',
+ *     '0x000000000000000000000000000000000000000000000000000000000000025b'
+ *   ],
+ *   data: '0x',
+ *   blockHash:
+ *     '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4',
+ *   blockNumber: '0x12d846c',
+ *   transactionHash:
+ *     '0xcfa52db0bc2cb5bdcb2c5bd8816df7a2f018a0e3964ab1ef4d794cf327966e93',
+ *   transactionIndex: '0x91',
+ *   logIndex: '0x10f',
+ *   removed: false
+ * })
+ * // @log: {
+ * // @log:   address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ * // @log:   blockHash: '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4',
+ * // @log:   blockNumber: 19760236n,
+ * // @log:   data: '0x',
+ * // @log:   logIndex: 271,
+ * // @log:   removed: false,
+ * // @log:   topics: [
+ * // @log:     "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+ * // @log:     "0x0000000000000000000000000000000000000000000000000000000000000000",
+ * // @log:     "0x0000000000000000000000000c04d9e9278ec5e4d424476d3ebec70cb5d648d1",
+ * // @log:     "0x000000000000000000000000000000000000000000000000000000000000025b",
+ * // @log:   transactionHash:
+ * // @log:     '0xcfa52db0bc2cb5bdcb2c5bd8816df7a2f018a0e3964ab1ef4d794cf327966e93',
+ * // @log:   transactionIndex: 145,
+ * // @log: }
+ * ```
+ *
+ * @example
+ * ### End-to-end
+ *
+ * Below is an example of how to use `Log.fromRpc` to instantiate a {@link ox#Log.Log} from an RPC log.
+ *
+ * ```ts twoslash
+ * import 'ox/window'
+ * import { AbiEvent, Hex, Log } from 'ox'
+ *
+ * const transfer = AbiEvent.from(
+ *   'event Transfer(address indexed from, address indexed to, uint256 indexed value)'
+ * )
+ *
+ * const { topics } = AbiEvent.encode(transfer)
+ *
+ * const logs = await window.ethereum!.request({
+ *   method: 'eth_getLogs',
+ *   params: [
+ *     {
+ *       address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ *       fromBlock: Hex.fromNumber(19760235n),
+ *       toBlock: Hex.fromNumber(19760240n),
+ *       topics
+ *     }
+ *   ]
+ * })
+ *
+ * const log = Log.fromRpc(logs[0]) // [!code focus]
+ * // @log: {
+ * // @log:   address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ * // @log:   blockHash: '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4',
+ * // @log:   blockNumber: 19760236n,
+ * // @log:   data: '0x',
+ * // @log:   logIndex: 271,
+ * // @log:   removed: false,
+ * // @log:   topics: [
+ * // @log:     "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+ * // @log:     "0x0000000000000000000000000000000000000000000000000000000000000000",
+ * // @log:     "0x0000000000000000000000000c04d9e9278ec5e4d424476d3ebec70cb5d648d1",
+ * // @log:     "0x000000000000000000000000000000000000000000000000000000000000025b",
+ * // @log:   transactionHash:
+ * // @log:     '0xcfa52db0bc2cb5bdcb2c5bd8816df7a2f018a0e3964ab1ef4d794cf327966e93',
+ * // @log:   transactionIndex: 145,
+ * // @log: }
+ * ```
+ *
+ * :::note
+ *
+ * For simplicity, the above example uses `window.ethereum.request`, but you can use any
+ * type of JSON-RPC interface.
+ *
+ * :::
+ *
+ * @param log - The RPC log to convert.
+ * @returns An instantiated {@link ox#Log.Log}.
+ */
+export function fromRpc<
+  const log extends Rpc<boolean>,
+  pending extends boolean = false,
+>(
+  log: log | Rpc<boolean>,
+  _options: fromRpc.Options<pending> = {},
+): Log<pending> {
+  return {
+    ...log,
+    blockNumber: Quantity.toBigInt(log.blockNumber) ?? null,
+    ...('blockTimestamp' in log
+      ? {
+          blockTimestamp:
+            log.blockTimestamp === null
+              ? null
+              : Quantity.toBigInt(log.blockTimestamp),
+        }
+      : {}),
+    logIndex: Quantity.toNumber(log.logIndex) ?? null,
+    transactionIndex: Quantity.toNumber(log.transactionIndex) ?? null,
+  } as Log<pending>
+}
+
+export declare namespace fromRpc {
+  type Options<pending extends boolean = false> = {
+    pending?: pending | boolean | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Converts a {@link ox#Log.Log} to a {@link ox#Log.Rpc}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Log } from 'ox'
+ *
+ * const log = Log.toRpc({
+ *   address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ *   blockHash:
+ *     '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4',
+ *   blockNumber: 19760236n,
+ *   data: '0x',
+ *   logIndex: 271,
+ *   removed: false,
+ *   topics: [
+ *     '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+ *     '0x0000000000000000000000000000000000000000000000000000000000000000',
+ *     '0x0000000000000000000000000c04d9e9278ec5e4d424476d3ebec70cb5d648d1',
+ *     '0x000000000000000000000000000000000000000000000000000000000000025b'
+ *   ],
+ *   transactionHash:
+ *     '0xcfa52db0bc2cb5bdcb2c5bd8816df7a2f018a0e3964ab1ef4d794cf327966e93',
+ *   transactionIndex: 145
+ * })
+ * // @log: {
+ * // @log:   address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
+ * // @log:   blockHash: '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4',
+ * // @log:   blockNumber: '0x012d846c',
+ * // @log:   data: '0x',
+ * // @log:   logIndex: '0x010f',
+ * // @log:   removed: false,
+ * // @log:   topics: [
+ * // @log:     '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+ * // @log:     '0x0000000000000000000000000000000000000000000000000000000000000000',
+ * // @log:     '0x0000000000000000000000000c04d9e9278ec5e4d424476d3ebec70cb5d648d1',
+ * // @log:     '0x000000000000000000000000000000000000000000000000000000000000025b',
+ * // @log:   ],
+ * // @log:   transactionHash:
+ * // @log:     '0xcfa52db0bc2cb5bdcb2c5bd8816df7a2f018a0e3964ab1ef4d794cf327966e93',
+ * // @log:   transactionIndex: '0x91',
+ * // @log: }
+ * ```
+ *
+ * @param log - The log to convert.
+ * @returns An RPC log.
+ */
+export function toRpc<
+  const log extends Log<boolean>,
+  pending extends boolean = false,
+>(log: log, _options: toRpc.Options<pending> = {}): Rpc<pending> {
+  return {
+    address: log.address,
+    blockHash: log.blockHash,
+    blockNumber: Quantity.fromBigInt(log.blockNumber) ?? null,
+    ...('blockTimestamp' in log
+      ? {
+          blockTimestamp:
+            log.blockTimestamp === null
+              ? null
+              : Quantity.fromBigInt(log.blockTimestamp),
+        }
+      : {}),
+    data: log.data,
+    logIndex: Quantity.fromNumber(log.logIndex) ?? null,
+    topics: log.topics,
+    transactionHash: log.transactionHash,
+    transactionIndex: Quantity.fromNumber(log.transactionIndex) ?? null,
+    removed: log.removed,
+  } as Rpc as never
+}
+
+export declare namespace toRpc {
+  type Options<pending extends boolean = false> = {
+    pending?: pending | boolean | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}

package/src/core/Mnemonic.bench.ts

@@ -0,0 +1,16 @@
+import { bench, describe } from 'vp/test'
+import * as Mnemonic from './Mnemonic.js'
+
+const mnemonic = Mnemonic.random(Mnemonic.english)
+
+describe('Mnemonic.toSeed', () => {
+  bench('toSeed (sync, PBKDF2-HMAC-SHA512 x 2048)', () => {
+    Mnemonic.toSeed(mnemonic)
+  })
+})
+
+describe('Mnemonic.toPrivateKey', () => {
+  bench('toPrivateKey (default path)', () => {
+    Mnemonic.toPrivateKey(mnemonic)
+  })
+})

package/src/core/Mnemonic.ts

@@ -0,0 +1,231 @@
+import {
+  generateMnemonic,
+  mnemonicToSeedSync,
+  validateMnemonic,
+} from '@scure/bip39'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as HdKey from './HdKey.js'
+import type * as Hex from './Hex.js'
+
+export { path } from './HdKey.js'
+
+export {
+  czech,
+  english,
+  french,
+  italian,
+  japanese,
+  korean,
+  portuguese,
+  simplifiedChinese,
+  spanish,
+  traditionalChinese,
+} from './internal/mnemonic/wordlists.js'
+
+/**
+ * Generates a random mnemonic.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * // @log: 'buyer zoo end danger ice capable shrug naive twist relief mass bonus'
+ * ```
+ *
+ * @param wordlist - The wordlist to use.
+ * @param options - Generation options.
+ * @returns The mnemonic.
+ */
+export function random(
+  wordlist: string[],
+  options: random.Options = {},
+): string {
+  const { strength = 128 } = options
+  return generateMnemonic(wordlist, strength)
+}
+
+export declare namespace random {
+  type Options = {
+    /**
+     * The strength of the mnemonic to generate, in bits.
+     * @default 128
+     */
+    strength?: number | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Converts a mnemonic to a HD Key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * const hdKey = Mnemonic.toHdKey(mnemonic)
+ * ```
+ *
+ * @example
+ * ### Path Derivation
+ *
+ * You can derive a HD Key at a specific path using `derive`:
+ *
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * const hdKey = Mnemonic.toHdKey(mnemonic).derive(
+ *   Mnemonic.path({ index: 1 })
+ * )
+ * ```
+ *
+ * @param mnemonic - The mnemonic to convert.
+ * @param options - Conversion options.
+ * @returns The HD Key.
+ */
+export function toHdKey(
+  mnemonic: string,
+  options: toHdKey.Options = {},
+): HdKey.HdKey {
+  const { passphrase } = options
+  const seed = toSeed(mnemonic, { passphrase })
+  return HdKey.fromSeed(seed)
+}
+
+export declare namespace toHdKey {
+  type Options = {
+    /** An optional passphrase for additional protection to the seed. */
+    passphrase?: string | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Converts a mnemonic to a private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * const privateKey = Mnemonic.toPrivateKey(mnemonic)
+ * // @log: '0x...'
+ * ```
+ *
+ * @example
+ * ### Paths
+ *
+ * You can derive a private key at a specific path using the `path` option.
+ *
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * const privateKey = Mnemonic.toPrivateKey(mnemonic, {
+ *   path: Mnemonic.path({ index: 1 }) // 'm/44'/60'/0'/0/1' // [!code focus]
+ * })
+ * // @log: '0x...'
+ * ```
+ *
+ * @param mnemonic - The mnemonic to convert.
+ * @param options - Conversion options.
+ * @returns The private key.
+ */
+export function toPrivateKey<as extends 'Bytes' | 'Hex' = 'Bytes'>(
+  mnemonic: string,
+  options: toPrivateKey.Options<as> = {},
+): toPrivateKey.ReturnType<as> {
+  const { as = 'Bytes', path = HdKey.path(), passphrase } = options
+  const hdKey = toHdKey(mnemonic, { passphrase }).derive(path)
+  if (as === 'Hex') return hdKey.privateKey as never
+  return Bytes.from(hdKey.privateKey) as never
+}
+
+export declare namespace toPrivateKey {
+  type Options<as extends 'Bytes' | 'Hex' = 'Bytes'> = {
+    /** The output format. @default 'Bytes' */
+    as?: as | 'Bytes' | 'Hex' | undefined
+    /** An optional path to derive the private key from. @default `m/44'/60'/0'/0/0` */
+    path?: string | undefined
+    /** An optional passphrase for additional protection to the seed. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Bytes' | 'Hex' = 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Converts a mnemonic to a master seed.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.random(Mnemonic.english)
+ * const seed = Mnemonic.toSeed(mnemonic)
+ * // @log: Uint8Array [...64 bytes]
+ * ```
+ *
+ * @param mnemonic - The mnemonic to convert.
+ * @param options - Conversion options.
+ * @returns The master seed.
+ */
+export function toSeed<as extends 'Bytes' | 'Hex' = 'Bytes'>(
+  mnemonic: string,
+  options: toSeed.Options<as> = {},
+): toSeed.ReturnType<as> {
+  const { passphrase } = options
+  const seed = mnemonicToSeedSync(mnemonic, passphrase)
+  if (options.as === 'Hex') return Bytes.toHex(seed) as never
+  return seed as never
+}
+
+export declare namespace toSeed {
+  type Options<as extends 'Bytes' | 'Hex' = 'Bytes'> = {
+    /** The output format. @default 'Bytes' */
+    as?: as | 'Bytes' | 'Hex' | undefined
+    /** An optional passphrase for additional protection to the seed. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Bytes' | 'Hex' = 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Checks if a mnemonic is valid, given a wordlist.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Mnemonic } from 'ox'
+ *
+ * const mnemonic = Mnemonic.validate(
+ *   'buyer zoo end danger ice capable shrug naive twist relief mass bonus',
+ *   Mnemonic.english
+ * )
+ * // @log: true
+ * ```
+ *
+ * @param mnemonic - The mnemonic to validate.
+ * @param wordlist - The wordlist to use.
+ * @returns Whether the mnemonic is valid.
+ */
+export function validate(mnemonic: string, wordlist: string[]): boolean {
+  return validateMnemonic(mnemonic, wordlist)
+}
+
+export declare namespace validate {
+  type ErrorType = Errors.GlobalErrorType
+}